Listbox

"use client";

import {
  createContext,
  use,
  useCallback,
  useEffect,
  useId,
  useLayoutEffect,
  useMemo,
  useReducer,
  useRef,
  useState,
  useSyncExternalStore,
} from "react";
import type {
  ComponentProps,
  KeyboardEvent,
  MouseEvent,
  PointerEvent,
  ReactElement,
  ReactNode,
  RefObject,
} from "react";
import { flushSync } from "react-dom";
import { cn } from "../../lib/utils.ts";
import { composeEventHandlers } from "../../lib/compose-event-handlers.ts";
import { focusRingClassName } from "../../lib/focus-class.ts";
import { mergeRefs } from "../../lib/merge-refs.ts";
import { isCommandKey } from "../../lib/platform.ts";
import {
  closestItemElement,
  collectionItemProps,
  duplicateKeys,
  focusItem,
  getCollection,
  getCollectionItem,
} from "../../primitives/collection.ts";
import type { CollectionItem } from "../../primitives/collection.ts";
import { moveForKey, pageStep, step } from "../../primitives/navigation.ts";
import type { Extent, Orientation } from "../../primitives/navigation.ts";
import {
  applyIntent,
  autoScrollSpeed,
  inOrder,
  itemAt,
  pointerIntent,
  sameSelection,
  selectAll,
  tapActs,
} from "../../primitives/selection.ts";
import type { SelectionBehavior, SelectionIntent, SelectionState } from "../../primitives/selection.ts";
import { useControllableState } from "../../primitives/use-controllable-state.ts";
import { matchTypeahead, useTypeahead } from "../../primitives/typeahead.ts";

interface SingleSelection {
  selectionMode?: "single";
  value?: string | null;
  defaultValue?: string | null;
  onValueChange?: (value: string | null) => void;
}

interface MultipleSelection {
  selectionMode: "multiple";
  value?: readonly string[];
  defaultValue?: readonly string[];
  onValueChange?: (value: string[]) => void;
}

export type ListboxProps = Omit<ComponentProps<"div">, "defaultValue" | "onChange"> &
  (SingleSelection | MultipleSelection) & {
    selectionBehavior?: SelectionBehavior;
    /** Keep at least one item selected once something is. */
    disallowEmptySelection?: boolean;
    orientation?: Orientation;
    /**
     * An item's primary action: Enter, or a double click. By touch, a tap where
     * selecting would change nothing; see `tapActs` in primitives/selection.ts.
     */
    onAction?: (value: string) => void;
    /**
     * Behave as a list in a popup does: the option under the pointer is
     * highlighted, releasing on an option chooses it — so a press that opened
     * the popup can be carried to an option — and the chosen option is marked
     * rather than filled, leaving the fill to the highlight.
     */
    focusFollowsPointer?: boolean;
    /**
     * Shown in place of the options when there are none, and read out as the
     * list's description. Words, not controls: it is not itself reachable.
     */
    emptyState?: ReactNode;
  };

type Value = string | null | readonly string[];

/** What a press may still become: a long press, or a drag across options. */
interface Press {
  readonly pointerId: number;
  readonly pointerType: string;
  readonly key: string;
  readonly element: HTMLElement;
  readonly x: number;
  readonly y: number;
  /**
   * Whether a drag from here draws a range. From an option that was already
   * selected it does not: that drag is the selection's own, to be carried.
   */
  readonly drawsRange: boolean;
  /** The selection before the press, which a gesture the platform takes back returns to. */
  readonly before: { readonly value: Value; readonly range: Pick<SelectionState, "anchor" | "base"> };
  timer: ReturnType<typeof setTimeout> | undefined;
  longPressed: boolean;
  drag: Drag | null;
}

interface Drag {
  x: number;
  y: number;
  /** How far past the list's edge the pointer is, signed; 0 inside. */
  out: number;
  /** The options as last read, and the count of changes then: one reading serves until they change. */
  reading: Reading | null;
  readAt: number;
  reached: string | null;
  frame: number;
  time: number;
  /** Scrolling owed but less than a pixel: some engines scroll by whole pixels only. */
  carry: number;
  readonly rtl: boolean;
}

interface Reading {
  readonly all: readonly CollectionItem[];
  readonly enabled: readonly CollectionItem[];
}

/** Pixels a pointer travels before its press is a drag. */
const DRAG_THRESHOLD = 4;
/** Pixels a finger may wander and still be holding still. */
const TOUCH_SLOP = 10;
/** As long as the platforms take to call a press long. */
const LONG_PRESS = 500;

const SELECTED = 1;
const TAB_STOP = 2;
const NO_TAB_STOP = 1;
const EMPTY = 2;

/**
 * What each option draws from — whether it is selected, whether it is the tab
 * stop — held outside React's tree, with each option listening for its own key.
 * Through context, every focus move re-rendered every option; this way a change
 * reaches the options it changes and no others, and the attributes stay
 * React's to write.
 */
function createListStore(initial: ReadonlySet<string>, onItemsChange: () => void) {
  const listeners = new Map<string, Set<() => void>>();
  const rootListeners = new Set<() => void>();
  const notify = (key: string | null): void => {
    if (key !== null) listeners.get(key)?.forEach((listener) => listener());
  };
  const notifyRoot = (): void => rootListeners.forEach((listener) => listener());

  const store = {
    selected: initial,
    tabStop: null as string | null,
    /** The option focus was last on. */
    focused: null as string | null,
    empty: false,
    /** Options have come, gone or changed since the collection was last read. */
    stale: true,
    /** Focus was on an option that has gone: it is owed to the one that takes its place. */
    focusOwed: false,
    /** The shared values last warned of, so that each is said once. */
    reported: "",
    /** Counts the times options have changed: a reading is good while this stands still. */
    changes: 0,

    subscribe(key: string, listener: () => void): () => void {
      let set = listeners.get(key);
      if (set === undefined) listeners.set(key, (set = new Set()));
      set.add(listener);
      return () => {
        set.delete(listener);
        if (set.size === 0 && listeners.get(key) === set) listeners.delete(key);
      };
    },
    subscribeRoot(listener: () => void): () => void {
      rootListeners.add(listener);
      return () => rootListeners.delete(listener);
    },
    itemState: (key: string): number =>
      (store.selected.has(key) ? SELECTED : 0) | (store.tabStop === key ? TAB_STOP : 0),
    rootState: (): number => (store.tabStop === null ? NO_TAB_STOP : 0) | (store.empty ? EMPTY : 0),

    setSelected(next: ReadonlySet<string>): void {
      const previous = store.selected;
      if (previous === next) return;
      store.selected = next;
      for (const key of previous) if (!next.has(key)) notify(key);
      for (const key of next) if (!previous.has(key)) notify(key);
    },
    setTabStop(next: string | null): void {
      const previous = store.tabStop;
      if (previous === next) return;
      store.tabStop = next;
      notify(previous);
      notify(next);
      if ((previous === null) !== (next === null)) notifyRoot();
    },
    setEmpty(next: boolean): void {
      if (store.empty === next) return;
      store.empty = next;
      notifyRoot();
    },
    focus(key: string): void {
      store.focused = key;
      store.setTabStop(key);
    },
    forgetFocus(): void {
      store.focused = null;
    },
    /** Whether these shared values are news: each set of them is said once. */
    report(values: string): boolean {
      if (store.reported === values) return false;
      store.reported = values;
      return values !== "";
    },
    markRead(): void {
      store.stale = false;
    },
    oweFocus(): void {
      store.focusOwed = true;
    },
    payFocus(): void {
      store.focusOwed = false;
    },
    /** Items call this as they mount, unmount or change; one render answers however many did. */
    invalidate(): void {
      store.changes += 1;
      if (store.stale) return;
      store.stale = true;
      onItemsChange();
    },
  };
  return store;
}

type ListStore = ReturnType<typeof createListStore>;

interface ItemHandlers {
  /** Whether the pointer has moved since it was last heard: a list scrolling under a resting pointer has not. */
  readonly pointerMoved: (event: PointerEvent) => boolean;
  readonly onItemPointerDown: (event: PointerEvent<HTMLElement>, key: string) => void;
  readonly onItemPointerUp: (event: PointerEvent, key: string) => void;
  readonly onItemClick: (event: MouseEvent, key: string) => void;
  readonly onItemDoubleClick: (key: string) => void;
}

interface ListboxContextValue {
  readonly scope: string;
  readonly store: ListStore;
  readonly focusFollowsPointer: boolean;
  /** As of the last render. Read when an event arrives, so the context — and every option — stays as it is. */
  readonly handlers: RefObject<ItemHandlers | null>;
}

const ListboxContext = createContext<ListboxContextValue | null>(null);

function useListboxContext(): ListboxContextValue {
  const context = use(ListboxContext);
  if (context === null) throw new Error("ListboxItem must be rendered inside a Listbox.");
  return context;
}

/** A value read in the list's mode: one that allows a single option holds the first of several. */
function toSet(value: Value, multiple: boolean): ReadonlySet<string> {
  if (value === null) return new Set();
  if (typeof value === "string") return new Set([value]);
  return new Set(multiple ? value : value.slice(0, 1));
}

/** Where an option lies along the list, in an order that grows with the options. */
function extentOf(element: HTMLElement, horizontal: boolean, rtl: boolean): Extent {
  const box = element.getBoundingClientRect();
  if (!horizontal) return { start: box.top, end: box.bottom };
  return rtl ? { start: -box.right, end: -box.left } : { start: box.left, end: box.right };
}

export function Listbox({
  selectionMode = "single",
  value,
  defaultValue,
  onValueChange,
  selectionBehavior = "replace",
  disallowEmptySelection = false,
  orientation = "vertical",
  onAction,
  focusFollowsPointer = false,
  emptyState,
  className,
  children,
  ref,
  onKeyDown,
  onFocus,
  onBlur,
  onPointerDownCapture,
  onPointerMove,
  onPointerUp,
  onPointerCancel,
  onLostPointerCapture,
  onContextMenu,
  "aria-describedby": describedBy,
  ...props
}: ListboxProps): ReactElement {
  const scope = useId();
  const emptyId = useId();
  const rootRef = useRef<HTMLDivElement>(null);
  const mergedRef = useMemo(() => mergeRefs(rootRef, ref), [ref]);
  const multiple = selectionMode === "multiple";
  const horizontal = orientation === "horizontal";

  const [rawValue, setRawValue] = useControllableState<Value>(
    value,
    defaultValue ?? (multiple ? [] : null),
    onValueChange as ((value: Value) => void) | undefined,
  );
  const selected = useMemo(() => toSet(rawValue, multiple), [rawValue, multiple]);

  // The mode changed under a value in the other mode's form: it is given back in this one's.
  useLayoutEffect(() => {
    if (multiple === Array.isArray(rawValue)) return;
    if (typeof rawValue === "string") setRawValue([rawValue]);
    else setRawValue(rawValue === null ? [] : (rawValue[0] ?? null));
  }, [multiple, rawValue, setRawValue]);

  // Where a range starts and what it adds to; see primitives/selection.ts.
  const range = useRef<Pick<SelectionState, "anchor" | "base">>({ anchor: null, base: new Set() });
  const [itemsVersion, onItemsChange] = useReducer((version: number) => version + 1, 0);
  const [store] = useState(() => createListStore(selected, onItemsChange));
  const rootState = useSyncExternalStore(store.subscribeRoot, store.rootState, store.rootState);
  const empty = (rootState & EMPTY) !== 0;

  /** The options as the document has them now. One reading serves an interaction. */
  function read(): Reading {
    const all = getCollection(rootRef.current, scope);
    return { all, enabled: all.filter((item) => !item.disabled) };
  }

  /**
   * One option is the tab stop: the one last focused, else the first selected,
   * else the first. Which one depends on the order, which only the document has.
   */
  const resolveTabStop = useCallback(() => {
    const all = getCollection(rootRef.current, scope);
    const enabled = all.filter((item) => !item.disabled);
    store.setEmpty(all.length === 0);
    if (process.env.NODE_ENV !== "production" && store.stale) {
      const values = duplicateKeys(all)
        .map((key) => JSON.stringify(key))
        .join(", ");
      if (store.report(values)) {
        console.warn(
          `Listbox: more than one option has the value ${values}. ` +
            "Options that share a value are selected together; give each its own.",
        );
      }
    }
    let next = enabled.find((item) => item.key === store.focused);
    if (next === undefined) {
      store.forgetFocus();
      next = enabled.find((item) => store.selected.has(item.key)) ?? enabled[0];
    }
    store.setTabStop(next?.key ?? null);
    if (store.focusOwed) {
      store.payFocus();
      (next?.element ?? rootRef.current)?.focus({ preventScroll: true });
    }
  }, [scope, store]);

  const resolvedFor = useRef<ReadonlySet<string> | null>(null);
  useLayoutEffect(() => {
    store.setSelected(selected);
    // While focus is on an option the tab stop is that option, and focus keeps it
    // so: the collection is read again only when it changed, or — with focus
    // elsewhere — when the selection the tab stop follows did.
    const unfocused = store.focused === null && resolvedFor.current !== selected;
    resolvedFor.current = selected;
    if (!store.stale && !unfocused) return;
    resolveTabStop();
    store.markRead();
    // `itemsVersion` is not read: it is the signal that items mounted or unmounted,
    // or that a selection was shown ahead of its value.
    // oxlint-disable-next-line react/exhaustive-effect-dependencies
  }, [store, selected, itemsVersion, resolveTabStop]);

  /**
   * Every key a selection may hold, in the order to report them: the options as
   * they stand, then whatever is selected but not among them — an option that is
   * unavailable or not drawn stays selected until the person deselects it.
   */
  function reportOrder({ all }: Reading): string[] {
    const keys = all.map((item) => item.key);
    const present = new Set(keys);
    for (const key of selected) if (!present.has(key)) keys.push(key);
    return keys;
  }

  function select(intent: SelectionIntent, key: string, reading: Reading = read()): void {
    const next = applyIntent({ selected, ...range.current }, intent, key, {
      mode: selectionMode,
      order: reading.enabled.map((item) => item.key),
      disallowEmpty: disallowEmptySelection,
    });
    range.current = { anchor: next.anchor, base: next.base };
    if (sameSelection(next.selected, selected)) return;
    // Shown at once, so the options it changes are drawn in the same pass as
    // everything else this interaction changed; with so many options a second
    // pass is felt. The render asked for here puts back what an owner refuses.
    store.setSelected(next.selected);
    onItemsChange();
    setRawValue(multiple ? inOrder(next.selected, reportOrder(reading)) : ([...next.selected][0] ?? null));
  }

  /** The option that has focus, among those read: the element, since a value may not be one option's own. */
  function focusedItem(enabled: readonly CollectionItem[]): CollectionItem | null {
    const root = rootRef.current;
    const element = root === null ? null : closestItemElement(document.activeElement, root, scope);
    return (
      enabled.find((item) => (element === null ? item.key === store.focused : item.element === element)) ??
      null
    );
  }

  function onQuery(query: string): void {
    const reading = read();
    const match = matchTypeahead(
      reading.enabled.map((item) => ({
        key: item.key,
        // Read as the search reaches it, and no further than its match.
        get text() {
          return item.textValue;
        },
      })),
      query,
      store.focused,
    );
    const item = match === null ? undefined : reading.enabled.find((candidate) => candidate.key === match);
    if (item === undefined) return;
    focusItem(item.element);
    if (selectionBehavior === "replace") select("replace", item.key, reading);
  }

  const typeahead = useTypeahead(onQuery);

  function handleKeyDown(event: KeyboardEvent<HTMLDivElement>): void {
    if (typeahead(event)) {
      // A character of a query is nobody else's key: not a popup's that closes on Space.
      event.preventDefault();
      event.stopPropagation();
      return;
    }
    const command = event.metaKey || event.ctrlKey;
    const rtl = getComputedStyle(event.currentTarget).direction === "rtl";
    const move = moveForKey(event.key, orientation, rtl ? "rtl" : "ltr");
    const page = event.key === "PageDown" ? 1 : event.key === "PageUp" ? -1 : 0;

    if (move !== null || page !== 0) {
      event.preventDefault();
      const reading = read();
      const { enabled } = reading;
      const from = focusedItem(enabled);
      const target =
        move !== null
          ? step(enabled, from, move)
          : (enabled[
              pageStep(
                enabled.length,
                from === null ? -1 : enabled.indexOf(from),
                page as 1 | -1,
                (index) => extentOf(enabled[index]!.element, horizontal, rtl),
                horizontal ? event.currentTarget.clientWidth : event.currentTarget.clientHeight,
              )
            ] ?? null);
      if (target === null) return;
      const focused = store.focused;
      focusItem(target.element);
      if (command && !event.shiftKey) return;
      // A selection that no gesture began — given as a value — extends from where focus was.
      if (multiple && event.shiftKey && range.current.anchor === null && focused !== null) {
        range.current = { anchor: focused, base: new Set(selected) };
      }
      if (multiple && event.shiftKey) select("extend", target.key, reading);
      else if (selectionBehavior === "replace") select("replace", target.key, reading);
      return;
    }

    const focused = store.focused;
    if (focused === null) return;
    if (event.key === " ") {
      event.preventDefault();
      if (multiple) select(event.shiftKey ? "extend" : "toggle", focused);
      else select(command ? "toggle" : "replace", focused);
    } else if (event.key === "Enter" && onAction !== undefined) {
      event.preventDefault();
      // A key held down acts once.
      if (!event.repeat) onAction(focused);
    } else if (command && event.key.toLowerCase() === "a") {
      // In a list of one choice there is nothing to select all of — least of all the page's text.
      event.preventDefault();
      if (!multiple) return;
      const reading = read();
      const next = selectAll(
        { selected, ...range.current },
        reading.enabled.map((item) => item.key),
      );
      const all = new Set([...selected, ...next.selected]);
      if (!sameSelection(all, selected)) setRawValue(inOrder(all, reportOrder(reading)));
    }
  }

  // A pointer type is only known on pointerdown, and a touch selects on click so a
  // scroll that starts on an item does not select it.
  const pointerType = useRef("mouse");
  // A press on one of several selected options: it becomes the only one when the
  // press ends as a click, so that a drag can begin from it with them all.
  const deferred = useRef<string | null>(null);
  // Focus that a press brings must not scroll the list from under the pointer.
  const pressed = useRef(false);
  const pointerAt = useRef({ x: Number.NaN, y: Number.NaN });
  const press = useRef<Press | null>(null);
  // The click that ends a drag or a long press is the end of that gesture, not a click.
  const gestured = useRef(false);

  function intentOf(event: PointerEvent | MouseEvent, type: string): SelectionIntent {
    return pointerIntent(
      { shiftKey: event.shiftKey, commandKey: isCommandKey(event), pointerType: type },
      selectionMode,
      selectionBehavior,
    );
  }

  /** In a popup, an option is chosen: its action if the list has one, else its selection. */
  function choose(event: PointerEvent | MouseEvent, key: string): void {
    if (onAction !== undefined) onAction(key);
    else select(intentOf(event, pointerType.current), key);
  }

  function endPress(cancelled = false): void {
    const ended = press.current;
    if (ended === null) return;
    press.current = null;
    clearTimeout(ended.timer);
    if (ended.drag === null) return;
    cancelAnimationFrame(ended.drag.frame);
    const root = rootRef.current;
    if (root?.hasPointerCapture(ended.pointerId)) root.releasePointerCapture(ended.pointerId);
    // A drag the platform took back — to scroll with a pen, say — selected nothing.
    if (cancelled) {
      range.current = ended.before.range;
      setRawValue(ended.before.value);
    }
  }

  function beginDrag(from: Press, event: PointerEvent): void {
    const root = rootRef.current;
    if (root === null) return;
    // Held by the list, the drag goes on wherever the pointer does.
    root.setPointerCapture(from.pointerId);
    gestured.current = true;
    // A pen selects nothing as it presses, since its press may yet be a scroll.
    if (from.pointerType === "pen") flushSync(() => select("toggle", from.key));
    from.drag = {
      x: event.clientX,
      y: event.clientY,
      out: 0,
      reading: null,
      readAt: 0,
      reached: from.key,
      frame: 0,
      time: 0,
      carry: 0,
      rtl: getComputedStyle(root).direction === "rtl",
    };
  }

  /** Extend the range to the option the pointer is at, and keep the list scrolling while it is past an edge. */
  function dragStep(current: Press, now: number): void {
    const root = rootRef.current;
    const drag = current.drag;
    if (root === null || drag === null) return;
    if (drag.reading === null || drag.readAt !== store.changes) {
      drag.reading = read();
      drag.readAt = store.changes;
    }
    const { reading } = drag;
    const { enabled } = reading;
    const box = root.getBoundingClientRect();
    const low = horizontal ? box.left + root.clientLeft : box.top + root.clientTop;
    const high = low + (horizontal ? root.clientWidth : root.clientHeight);
    const at = horizontal ? drag.x : drag.y;
    drag.out = at < low ? at - low : at > high ? at - high : 0;
    // Past an edge, the range reaches the option at that edge.
    const within = Math.min(Math.max(at, low), high - 1);
    const sign = horizontal && drag.rtl ? -1 : 1;
    const target =
      enabled[
        itemAt(
          enabled.length,
          (index) => extentOf(enabled[index]!.element, horizontal, drag.rtl),
          sign * within,
        )
      ];
    if (target !== undefined && target.key !== drag.reached) {
      drag.reached = target.key;
      // At once: the next frame works from the selection this one made.
      flushSync(() => select("extend", target.key, reading));
      target.element.focus({ preventScroll: true });
    }
    if (drag.out !== 0 && drag.frame === 0) {
      drag.time = now;
      drag.frame = requestAnimationFrame((time) => latest.current?.dragFrame(time));
    }
  }

  function dragFrame(now: number): void {
    const current = press.current;
    const root = rootRef.current;
    const drag = current?.drag;
    if (current === null || root === null || !drag) return;
    drag.frame = 0;
    if (drag.out === 0) return;
    const elapsed = Math.min(Math.max(now - drag.time, 0), 64) / 1000;
    drag.carry += Math.sign(drag.out) * autoScrollSpeed(Math.abs(drag.out)) * elapsed;
    const whole = Math.trunc(drag.carry);
    drag.carry -= whole;
    if (horizontal) root.scrollLeft += whole;
    else root.scrollTop += whole;
    dragStep(current, now);
  }

  function handlePointerMove(event: PointerEvent<HTMLDivElement>): void {
    const current = press.current;
    if (current === null || current.pointerId !== event.pointerId) return;
    // Let go where the list could not hear it.
    if (event.buttons === 0) {
      endPress();
      return;
    }
    if (current.drag === null) {
      const distance = Math.hypot(event.clientX - current.x, event.clientY - current.y);
      if (current.pointerType === "touch" && !current.longPressed) {
        // A finger that moves before a long press is scrolling.
        if (distance > TOUCH_SLOP) clearTimeout(current.timer);
        return;
      }
      if (distance < DRAG_THRESHOLD || !current.drawsRange) return;
      beginDrag(current, event);
    }
    if (current.drag === null) return;
    current.drag.x = event.clientX;
    current.drag.y = event.clientY;
    dragStep(current, performance.now());
  }

  /**
   * A long press by touch, heard as the platform's `contextmenu` — which the
   * list raises itself where the platform does not. In a single selection it is
   * a secondary press: the option is selected, and a menu may open on it. In a
   * multiple selection it begins selecting: the option is added and, while the
   * finger stays down, a range follows it.
   */
  function handleContextMenu(event: MouseEvent<HTMLDivElement>): void {
    const current = press.current;
    if (current === null || current.pointerType !== "touch" || current.longPressed) return;
    current.longPressed = true;
    clearTimeout(current.timer);
    gestured.current = true;
    current.element.focus({ preventScroll: true });
    if (!multiple) {
      if (!selected.has(current.key)) select("replace", current.key);
      return;
    }
    // Kept from the platform, whose own menu would end the press the range needs.
    event.preventDefault();
    if (current.drawsRange) select("toggle", current.key);
  }

  const handlers: ItemHandlers = {
    pointerMoved(event) {
      const moved = event.clientX !== pointerAt.current.x || event.clientY !== pointerAt.current.y;
      pointerAt.current = { x: event.clientX, y: event.clientY };
      return moved;
    },
    onItemPointerDown(event, key) {
      endPress();
      pointerType.current = event.pointerType;
      deferred.current = null;
      gestured.current = false;
      const mouse = event.pointerType === "mouse";
      // A secondary press — on a Mac, Ctrl-click too — is for a context menu: it
      // selects what it lands on only if that is outside the selection.
      if (mouse && (event.button === 2 || (event.button === 0 && event.ctrlKey && !isCommandKey(event)))) {
        if (!selected.has(key)) select("replace", key);
        return;
      }
      // In a popup, the release chooses.
      if (event.button !== 0 || focusFollowsPointer) return;
      const began: Press = {
        pointerId: event.pointerId,
        pointerType: event.pointerType,
        key,
        element: event.currentTarget,
        x: event.clientX,
        y: event.clientY,
        drawsRange: multiple && !selected.has(key),
        before: { value: rawValue, range: range.current },
        timer: undefined,
        longPressed: false,
        drag: null,
      };
      press.current = began;
      if (event.pointerType === "touch") {
        began.timer = setTimeout(() => {
          if (press.current !== began || began.longPressed) return;
          began.element.dispatchEvent(
            new globalThis.MouseEvent("contextmenu", {
              bubbles: true,
              cancelable: true,
              clientX: began.x,
              clientY: began.y,
            }),
          );
        }, LONG_PRESS);
      }
      // A finger or a pen selects on click: its press may yet be a scroll.
      if (!mouse) return;
      const intent = intentOf(event, "mouse");
      if (intent === "replace" && multiple && selected.size > 1 && selected.has(key)) {
        deferred.current = key;
        return;
      }
      select(intent, key);
    },
    onItemPointerUp(event, key) {
      if (focusFollowsPointer && event.pointerType === "mouse" && event.button === 0) choose(event, key);
    },
    onItemClick(event, key) {
      // A click that no press came before is a key's, or assistive technology's.
      if (event.detail === 0) {
        if (focusFollowsPointer && onAction !== undefined) onAction(key);
        else select(multiple ? "toggle" : "replace", key);
        return;
      }
      if (gestured.current) return;
      if (pointerType.current === "mouse") {
        if (deferred.current === key) select("replace", key);
        deferred.current = null;
        return;
      }
      if (focusFollowsPointer) choose(event, key);
      else if (
        onAction !== undefined &&
        !event.shiftKey &&
        !isCommandKey(event) &&
        tapActs(selected, key, selectionMode, selectionBehavior)
      ) {
        onAction(key);
      } else select(intentOf(event, pointerType.current), key);
    },
    onItemDoubleClick(key) {
      // Two taps have each been heard as a tap.
      if (pointerType.current === "mouse") onAction?.(key);
    },
  };

  const latest = useRef<(ItemHandlers & { dragFrame: typeof dragFrame }) | null>(null);
  useLayoutEffect(() => {
    latest.current = { ...handlers, dragFrame };
  });

  useEffect(() => {
    const root = rootRef.current;
    if (root === null || focusFollowsPointer) return;
    const abort = new AbortController();
    // A long press the list has already raised is not raised again by the platform.
    root.addEventListener(
      "contextmenu",
      (event) => {
        if (!event.isTrusted || press.current?.longPressed !== true) return;
        event.preventDefault();
        event.stopPropagation();
      },
      { capture: true, signal: abort.signal },
    );
    if (multiple) {
      // After a long press the finger draws a range, and the list must not scroll under it.
      root.addEventListener(
        "touchmove",
        (event) => {
          if (press.current?.longPressed === true && event.cancelable) event.preventDefault();
        },
        { passive: false, signal: abort.signal },
      );
    }
    return () => abort.abort();
  }, [multiple, focusFollowsPointer]);

  useEffect(
    () => () => {
      clearTimeout(press.current?.timer);
      cancelAnimationFrame(press.current?.drag?.frame ?? 0);
    },
    [],
  );

  const context = useMemo<ListboxContextValue>(
    () => ({ scope, store, focusFollowsPointer, handlers: latest }),
    [scope, store, focusFollowsPointer],
  );

  const showEmpty = empty && emptyState !== undefined && emptyState !== null;

  return (
    <ListboxContext value={context}>
      <div
        ref={mergedRef}
        role="listbox"
        aria-multiselectable={multiple || undefined}
        aria-orientation={orientation}
        aria-describedby={showEmpty ? [describedBy, emptyId].filter(Boolean).join(" ") : describedBy}
        // Focusable itself only until it has an item to hand focus to.
        tabIndex={(rootState & NO_TAB_STOP) !== 0 ? 0 : -1}
        data-orientation={orientation}
        data-popup={focusFollowsPointer ? "" : undefined}
        data-empty={empty ? "" : undefined}
        onKeyDown={(event) => {
          onKeyDown?.(event);
          pressed.current = false;
          if (!event.defaultPrevented) handleKeyDown(event);
        }}
        onPointerDownCapture={(event) => {
          onPointerDownCapture?.(event);
          pressed.current = true;
        }}
        onPointerMove={(event) => {
          onPointerMove?.(event);
          if (!event.defaultPrevented) handlePointerMove(event);
        }}
        onPointerUp={(event) => {
          onPointerUp?.(event);
          if (press.current?.pointerId === event.pointerId) endPress();
        }}
        onPointerCancel={(event) => {
          onPointerCancel?.(event);
          if (press.current?.pointerId === event.pointerId) endPress(true);
        }}
        onLostPointerCapture={(event) => {
          onLostPointerCapture?.(event);
          // The list's own capture: a finger's capture passing from the option to the list is not its end.
          if (event.target !== event.currentTarget) return;
          if (press.current?.pointerId === event.pointerId && press.current.drag !== null) endPress();
        }}
        onContextMenu={(event) => {
          onContextMenu?.(event);
          handleContextMenu(event);
        }}
        onFocus={(event) => {
          onFocus?.(event);
          if (event.defaultPrevented || event.target !== event.currentTarget) return;
          const item =
            store.tabStop === null ? null : getCollectionItem(event.currentTarget, scope, store.tabStop);
          if (item === null) return;
          if (pressed.current) item.element.focus({ preventScroll: true });
          else focusItem(item.element);
        }}
        onBlur={(event) => {
          onBlur?.(event);
          if (event.currentTarget.contains(event.relatedTarget)) return;
          // What is typed on return is a new query.
          typeahead.reset();
          // A popup opens each time on what is chosen, not on what was last pointed at.
          if (focusFollowsPointer) {
            store.forgetFocus();
            resolveTabStop();
          }
        }}
        className={cn(
          "group/listbox flex flex-col overflow-auto overscroll-contain rounded-lg border border-border-muted bg-surface p-1 select-none",
          // A long press is the list's own: not the platform's callout over the text.
          "[-webkit-touch-callout:none]",
          "data-[orientation=horizontal]:flex-row",
          focusRingClassName,
          className,
        )}
        {...props}
      >
        {children}
        {showEmpty && (
          // Read out as the list's description; as content, a list may hold only options.
          <div id={emptyId} aria-hidden className="px-2 py-1 text-sm text-fg-muted">
            {emptyState}
          </div>
        )}
      </div>
    </ListboxContext>
  );
}

export type ListboxItemProps = ComponentProps<"div"> & {
  value: string;
  disabled?: boolean;
  /** What typeahead matches, when the item's text is not the right answer. */
  textValue?: string;
};

export function ListboxItem({
  value,
  disabled = false,
  textValue,
  className,
  onFocus,
  onPointerMove,
  onPointerDown,
  onPointerUp,
  onClick,
  onDoubleClick,
  children,
  ref,
  ...props
}: ListboxItemProps): ReactElement {
  const { scope, store, handlers, focusFollowsPointer: popup } = useListboxContext();
  const subscribe = useCallback((listener: () => void) => store.subscribe(value, listener), [store, value]);
  const snapshot = (): number => store.itemState(value);
  const state = useSyncExternalStore(subscribe, snapshot, snapshot);
  const selected = (state & SELECTED) !== 0;
  const element = useRef<HTMLDivElement>(null);
  const mergedRef = useMemo(() => mergeRefs(element, ref), [ref]);

  // Told while the element still holds focus: before it is taken out, or as it
  // becomes unavailable.
  useLayoutEffect(() => {
    const node = element.current;
    const owe = (): void => {
      if (document.activeElement === node) store.oweFocus();
    };
    if (disabled) owe();
    return owe;
  }, [disabled, store]);

  // Changing `value` or `disabled` changes which item can be the tab stop.
  useLayoutEffect(() => {
    store.invalidate();
    return store.invalidate;
    // oxlint-disable-next-line react/exhaustive-effect-dependencies
  }, [store, value, disabled]);

  return (
    // Keys are handled by the listbox, which owns focus movement for every option.
    // oxlint-disable-next-line jsx-a11y/click-events-have-key-events
    <div
      ref={mergedRef}
      role="option"
      aria-selected={selected}
      aria-disabled={disabled || undefined}
      tabIndex={disabled ? undefined : (state & TAB_STOP) !== 0 ? 0 : -1}
      {...collectionItemProps(scope, value, { disabled, textValue })}
      data-selected={selected ? "" : undefined}
      onFocus={composeEventHandlers(onFocus, () => store.focus(value))}
      onPointerMove={composeEventHandlers(onPointerMove, (event) => {
        if (!popup || disabled || event.pointerType === "touch" || !handlers.current?.pointerMoved(event))
          return;
        if (document.activeElement !== event.currentTarget)
          event.currentTarget.focus({ preventScroll: true });
      })}
      onPointerDown={composeEventHandlers(onPointerDown, (event) => {
        if (!disabled) handlers.current?.onItemPointerDown(event, value);
      })}
      onPointerUp={composeEventHandlers(onPointerUp, (event) => {
        if (!disabled) handlers.current?.onItemPointerUp(event, value);
      })}
      onClick={composeEventHandlers(onClick, (event) => {
        if (!disabled) handlers.current?.onItemClick(event, value);
      })}
      onDoubleClick={composeEventHandlers(onDoubleClick, () => {
        if (!disabled) handlers.current?.onItemDoubleClick(value);
      })}
      className={cn(
        "relative flex min-h-8 cursor-default items-center gap-2 rounded-md px-2 py-1 text-sm text-fg outline-none",
        "[-webkit-tap-highlight-color:transparent] forced-colors:forced-color-adjust-none",
        // A finger needs a larger target than a pointer; the list grows rather than the text.
        "pointer-coarse:min-h-11",
        popup
          ? // In a popup the fill is the highlight, which follows focus; the choice is the mark.
            "ps-7 focus:bg-selected focus:text-on-selected forced-colors:focus:bg-[Highlight] forced-colors:focus:text-[HighlightText]"
          : [
              "hover:bg-surface-muted",
              // A selection reads as the list's accent only while the list has focus.
              "data-selected:bg-surface-strong data-selected:text-fg-strong",
              "group-focus-within/listbox:data-selected:bg-selected group-focus-within/listbox:data-selected:text-on-selected",
              // Adjacent selected items join into one block, along the way the list runs.
              "group-data-[orientation=vertical]/listbox:[&[data-selected]:has(+[data-selected])]:rounded-b-none group-data-[orientation=vertical]/listbox:[[data-selected]+&[data-selected]]:rounded-t-none",
              "group-data-[orientation=horizontal]/listbox:[&[data-selected]:has(+[data-selected])]:rounded-e-none group-data-[orientation=horizontal]/listbox:[[data-selected]+&[data-selected]]:rounded-s-none",
              "forced-colors:data-selected:bg-[Highlight] forced-colors:data-selected:text-[HighlightText]",
              "focus-visible:outline-2 focus-visible:-outline-offset-2 focus-visible:outline-focus-ring focus-visible:outline-solid",
              // On the accent, the ring is the colour of the text there.
              "group-focus-within/listbox:data-selected:focus-visible:outline-on-selected",
              // Selected, yet not to be had: neither the accent nor the look of a choice on offer.
              "data-disabled:data-selected:bg-surface-strong data-disabled:data-selected:text-fg-muted",
            ],
        "data-disabled:text-fg-disabled data-disabled:hover:bg-transparent forced-colors:data-disabled:text-[GrayText]",
        "pointer-coarse:text-base",
        className,
      )}
      {...props}
    >
      {popup && selected && (
        <svg
          aria-hidden
          viewBox="0 0 16 16"
          className="absolute start-2 size-3.5"
          fill="none"
          stroke="currentColor"
          strokeWidth="2"
        >
          <path d="M3.5 8.5 6.5 11.5 12.5 4.5" strokeLinecap="round" strokeLinejoin="round" />
        </svg>
      )}
      {children}
    </div>
  );
}

export type ListboxGroupProps = Omit<ComponentProps<"div">, "children"> & {
  label: ReactNode;
  children?: ReactNode;
};

export function ListboxGroup({ label, className, children, ...props }: ListboxGroupProps): ReactElement {
  const labelId = useId();
  return (
    <div role="group" aria-labelledby={labelId} className={cn("flex flex-col", className)} {...props}>
      <div id={labelId} role="presentation" className="px-2 pt-2 pb-1 text-xs font-medium text-fg-muted">
        {label}
      </div>
      {children}
    </div>
  );
}