@primitiv-ui/react 0.1.37 → 0.1.39

package/dist/Listbox/hooks/useListboxRoot.js

@@ -0,0 +1,299 @@
+"use client";
+import { useCallback, useId, useState } from "react";
+import { useCollection, useControllableState, useTypeahead, } from "../../hooks/index.js";
+import { deriveId, getKeyToActionMap } from "../../utils/index.js";
+import { TYPEAHEAD_RESET_MS } from "../constants.js";
+function toArray(value) {
+    if (value === undefined)
+        return [];
+    return typeof value === "string" ? [value] : value;
+}
+/**
+ * Owns the Listbox's selection state and its virtual-focus cursor.
+ *
+ * Selection is normalised into an array so options only ever ask "am I in
+ * the selected set?". The cursor (`activeValue`) is the option
+ * `aria-activedescendant` points at — real DOM focus stays on the root, so
+ * the cursor is seeded when the root takes focus and cleared when it loses
+ * it.
+ *
+ * No `tabIndex` is moved between options: the root is the single tab stop,
+ * and navigation just repoints the cursor.
+ *
+ * Navigation order is read from the **live DOM** on every interaction rather
+ * than from a memoised array. Reordering options in place (APG's rearrangeable
+ * example) keeps the same elements mounted with unchanged props, so nothing
+ * re-registers and any cached order would silently go stale.
+ */
+export function useListboxRoot({ type, defaultValue, value: controlledValue, onValueChange, selectionFollowsFocus, orientation, dir, }) {
+    const rootId = useId();
+    const [selectedValues, setSelectedValues] = useControllableState(controlledValue === undefined ? undefined : toArray(controlledValue), toArray(defaultValue));
+    const [activeValue, setActiveValue] = useState(undefined);
+    // `keys` is deliberately unused: navigation order comes from the DOM, not
+    // from registration order. The collection is still what keeps `itemsRef`
+    // populated and re-renders the Root as options mount and unmount.
+    const { register: registerBase, itemsRef } = useCollection();
+    const registerOption = useCallback(
+    // Stryker disable next-line BooleanLiteral: equivalent — the only caller that omits this argument is the unmount path, which passes a null element and so never reads it.
+    (optionValue, element, disabled = false) => {
+        registerBase(optionValue, element ? { element, disabled } : null);
+    }, 
+    // Stryker disable next-line ArrayDeclaration: equivalent — registerBase is a stable useCollection callback, so an empty dep array memoises identically.
+    [registerBase]);
+    // Disabled options stay in the DOM and in the a11y tree, but drop out of
+    // every navigable list: cursor movement and focus seeding both skip them.
+    //
+    // Sorted by document position, not registration order — see the note above.
+    const getNavigableValues = useCallback(() => {
+        const entries = Array.from(itemsRef.current.entries()).filter(([, meta]) => !meta.disabled);
+        entries.sort(([, a], [, b]) => a.element.compareDocumentPosition(b.element) &
+            Node.DOCUMENT_POSITION_FOLLOWING
+            ? -1
+            : 1);
+        return entries.map(([key]) => key);
+    }, 
+    // Stryker disable next-line ArrayDeclaration: equivalent — itemsRef is a stable RefObject.
+    [itemsRef]);
+    // Single mode replaces the selection outright — re-selecting the current
+    // option is a no-op re-select, not a deselect (a listbox is not a toggle).
+    // Multiple mode toggles the option in place, preserving the rest.
+    const select = useCallback((optionValue) => {
+        if (type === "single") {
+            setSelectedValues([optionValue]);
+            onValueChange?.(optionValue);
+            return;
+        }
+        const next = selectedValues.includes(optionValue)
+            ? selectedValues.filter((key) => key !== optionValue)
+            : [...selectedValues, optionValue];
+        setSelectedValues(next);
+        onValueChange?.(next);
+    }, [type, selectedValues, setSelectedValues, onValueChange]);
+    // Bulk selection writes. Multiple-mode only: single mode's onValueChange
+    // takes a string, and none of the range shortcuts apply to it.
+    const commitSelection = useCallback((next) => {
+        setSelectedValues(next);
+        onValueChange?.(next);
+    }, 
+    // Stryker disable next-line ArrayDeclaration: equivalent — both are stable for a given render pair; the value read is the ref/state itself.
+    [setSelectedValues, onValueChange]);
+    // APG: Ctrl+A selects all, or deselects if everything is already selected.
+    // Disabled options are not selectable, so they are not part of "all".
+    const toggleSelectAll = useCallback(() => {
+        const navigable = getNavigableValues();
+        const allSelected = 
+        // Stryker disable next-line ConditionalExpression,EqualityOperator: equivalent — with nothing navigable both arms commit the empty array.
+        navigable.length > 0 &&
+            navigable.every((key) => selectedValues.includes(key));
+        commitSelection(allSelected ? [] : navigable);
+    }, [getNavigableValues, selectedValues, commitSelection]);
+    const getOptionId = useCallback(
+    // Stryker disable next-line StringLiteral: equivalent — the suffix only has to be stable; every assertion compares against the element's own id.
+    (optionValue) => deriveId(rootId, "option", optionValue), 
+    // Stryker disable next-line ArrayDeclaration: equivalent — rootId is a useId() constant.
+    [rootId]);
+    // APG: when the referenced option is not fully visible, scroll it into view.
+    const moveCursor = useCallback((optionValue) => {
+        setActiveValue(optionValue);
+        // Stryker disable next-line OptionalChaining: unreachable — every value reaching moveCursor comes from getNavigableValues(), so the entry is always registered.
+        itemsRef.current
+            .get(optionValue)
+            ?.element.scrollIntoView({ block: "nearest" });
+    }, 
+    // Stryker disable next-line ArrayDeclaration: equivalent — itemsRef is a stable RefObject.
+    [itemsRef]);
+    // APG: when the listbox receives focus, the first selected option takes
+    // the cursor; with nothing selected, the first option does.
+    const seedActiveValue = useCallback(() => {
+        const navigable = getNavigableValues();
+        setActiveValue((current) => current ??
+            navigable.find((key) => selectedValues.includes(key)) ??
+            navigable[0]);
+    }, 
+    // Stryker disable next-line ArrayDeclaration: equivalent — the callback is rebuilt each render and reads both through its closure.
+    [getNavigableValues, selectedValues]);
+    // Stryker disable next-line ArrayDeclaration: equivalent — the dep array is already empty; adding a phantom entry cannot change a setState-only callback.
+    const clearActiveValue = useCallback(() => setActiveValue(undefined), []);
+    // One navigation path for both the arrow keymap and typeahead, so
+    // `selectionFollowsFocus` applies identically to each.
+    const navigateTo = useCallback((target) => {
+        moveCursor(target);
+        if (selectionFollowsFocus)
+            select(target);
+    }, 
+    // Stryker disable next-line ArrayDeclaration: equivalent — a stale closure here still calls the same setState and select.
+    [moveCursor, selectionFollowsFocus, select]);
+    // APG: Shift+Arrow "moves focus and selects" the option it lands on. Unlike
+    // the plain arrows this deliberately does not wrap — extending a range off
+    // the end and round to the top would select options never travelled past.
+    const extendSelection = useCallback((direction) => {
+        const navigable = getNavigableValues();
+        const currentIndex = 
+        // Stryker disable next-line ConditionalExpression: equivalent — indexOf(undefined) is itself -1, so both arms yield the same index.
+        activeValue === undefined ? -1 : navigable.indexOf(activeValue);
+        if (currentIndex === -1)
+            return;
+        const targetIndex = direction === "next" ? currentIndex + 1 : currentIndex - 1;
+        if (targetIndex < 0 || targetIndex >= navigable.length)
+            return;
+        const target = navigable[targetIndex];
+        moveCursor(target);
+        if (!selectedValues.includes(target)) {
+            commitSelection([...selectedValues, target]);
+        }
+    }, [
+        activeValue,
+        getNavigableValues,
+        moveCursor,
+        selectedValues,
+        commitSelection,
+    ]);
+    // APG: Ctrl+Shift+Home/End selects from the cursor through to the first or
+    // last option and moves the cursor to that edge. Selections outside the
+    // swept range are preserved.
+    const extendToEdge = useCallback((edge) => {
+        const navigable = getNavigableValues();
+        const currentIndex = 
+        // Stryker disable next-line ConditionalExpression: equivalent — indexOf(undefined) is itself -1, so both arms yield the same index.
+        activeValue === undefined ? -1 : navigable.indexOf(activeValue);
+        if (currentIndex === -1)
+            return;
+        const range = edge === "first"
+            ? navigable.slice(0, currentIndex + 1)
+            : navigable.slice(currentIndex);
+        const next = [...selectedValues];
+        for (const key of range) {
+            if (!next.includes(key))
+                next.push(key);
+        }
+        commitSelection(next);
+        moveCursor(edge === "first" ? navigable[0] : navigable[navigable.length - 1]);
+    }, [
+        activeValue,
+        getNavigableValues,
+        selectedValues,
+        commitSelection,
+        moveCursor,
+    ]);
+    // The arrow / Home / End / Enter-Space keymap. This mirrors what
+    // `useRovingTabindex` does, but resolves `navigable` at event time so a
+    // reorder is picked up; that hook takes its list at render time.
+    const handleNavigationKey = useCallback((event) => {
+        const action = getKeyToActionMap({
+            orientation,
+            dir,
+            homeEnd: true,
+            activate: true,
+        })[event.key];
+        if (!action)
+            return;
+        const navigable = getNavigableValues();
+        // Stryker disable next-line ConditionalExpression: equivalent — with no options every downstream index resolves to undefined, which moves the cursor nowhere.
+        if (navigable.length === 0)
+            return;
+        if (action === "activate") {
+            if (activeValue === undefined)
+                return;
+            event.preventDefault();
+            select(activeValue);
+            return;
+        }
+        const currentIndex = 
+        // Stryker disable next-line ConditionalExpression: equivalent — indexOf(undefined) is itself -1, so both arms yield the same index.
+        activeValue === undefined ? -1 : navigable.indexOf(activeValue);
+        let targetIndex;
+        if (action === "first") {
+            targetIndex = 0;
+        }
+        else if (action === "last") {
+            targetIndex = navigable.length - 1;
+        }
+        else if (currentIndex === -1) {
+            // No cursor yet — the options streamed in after the listbox took
+            // focus, so seeding never ran. Enter the list from the near end
+            // rather than swallowing the keystroke.
+            targetIndex = action === "next" ? 0 : navigable.length - 1;
+        }
+        else {
+            targetIndex =
+                action === "next"
+                    ? (currentIndex + 1) % navigable.length
+                    : (currentIndex - 1 + navigable.length) % navigable.length;
+        }
+        event.preventDefault();
+        navigateTo(navigable[targetIndex]);
+    }, [orientation, dir, getNavigableValues, activeValue, select, navigateTo]);
+    // `optionValue` is always drawn from `navigable` (the enabled subset of the
+    // registered keys), and useCollection writes `itemsRef` and the keys state
+    // together — so the entry, and an element with textContent, always exist.
+    const getLabel = useCallback((optionValue) => itemsRef.current.get(optionValue).element.textContent, 
+    // Stryker disable next-line ArrayDeclaration: equivalent — itemsRef is a stable RefObject.
+    [itemsRef]);
+    const { handleTypeahead } = useTypeahead({
+        getNavigable: getNavigableValues,
+        getLabel,
+        currentKey: activeValue,
+        onMatch: navigateTo,
+        resetMs: TYPEAHEAD_RESET_MS,
+    });
+    // The keymap gets first refusal: it calls preventDefault on every key it
+    // consumes, so a still-unhandled printable character falls through to
+    // typeahead (and Space, which activates, never does).
+    const handleKeyDown = useCallback((event) => {
+        const chord = event.ctrlKey || event.metaKey;
+        if (chord && !event.altKey && event.key.toLowerCase() === "a") {
+            if (type !== "multiple")
+                return;
+            event.preventDefault();
+            toggleSelectAll();
+            return;
+        }
+        if (chord &&
+            event.shiftKey &&
+            (event.key === "Home" || event.key === "End")) {
+            if (type !== "multiple")
+                return;
+            event.preventDefault();
+            // Stryker disable next-line StringLiteral: equivalent — extendToEdge branches on `edge === "first"`, so any non-"first" string selects the same path.
+            extendToEdge(event.key === "Home" ? "first" : "last");
+            return;
+        }
+        // Every other chorded shortcut belongs to the browser and the consumer —
+        // APG's rearrangeable example binds Alt+Arrow to its toolbar. Only Shift
+        // is ours, for range selection.
+        if (chord || event.altKey)
+            return;
+        if (event.shiftKey && type === "multiple") {
+            const action = getKeyToActionMap({ orientation, dir })[event.key];
+            if (action === "next" || action === "prev") {
+                event.preventDefault();
+                extendSelection(action);
+                return;
+            }
+        }
+        handleNavigationKey(event);
+        if (event.defaultPrevented)
+            return;
+        handleTypeahead(event);
+    }, [
+        type,
+        orientation,
+        dir,
+        toggleSelectAll,
+        extendSelection,
+        extendToEdge,
+        handleNavigationKey,
+        handleTypeahead,
+    ]);
+    return {
+        selectedValues,
+        select,
+        activeValue,
+        registerOption,
+        getOptionId,
+        seedActiveValue,
+        clearActiveValue,
+        handleKeyDown,
+        moveCursor,
+    };
+}

package/dist/Listbox/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./Listbox.js";
+export * from "./ListboxContext.js";
+export * from "./types.js";

package/dist/Listbox/index.js

@@ -0,0 +1,3 @@
+export * from "./Listbox.js";
+export * from "./ListboxContext.js";
+export * from "./types.js";

package/dist/Listbox/types.d.ts

@@ -0,0 +1,214 @@
+import type { HTMLAttributes, ReactNode, Ref } from "react";
+/**
+ * Mode-independent props shared by every `Listbox.Root` variant — orientation,
+ * direction, selection-follows-focus, `asChild`, children, and the ref.
+ * Combined with a mode-specific arm to form {@link ListboxRootProps}.
+ */
+export type ListboxRootBaseProps = Omit<HTMLAttributes<HTMLDivElement>, "defaultValue" | "dir"> & {
+    /** Layout axis for cursor navigation. `"vertical"` binds ArrowUp/ArrowDown;
+     * `"horizontal"` binds ArrowLeft/ArrowRight and additionally emits
+     * `aria-orientation="horizontal"` (vertical is the ARIA default, so it is
+     * left implicit). Surfaces as `data-orientation` for styling; it does not
+     * itself apply any layout.
+     * @default "vertical" */
+    orientation?: "horizontal" | "vertical";
+    /** Reading direction. In `"rtl"` the horizontal arrow pair is mirrored so
+     * the cursor follows visual order — meaningful only when
+     * {@link ListboxRootBaseProps.orientation} is `"horizontal"`. Inherited from
+     * the nearest {@link DirectionProvider} when omitted, falling back to
+     * `"ltr"`. */
+    dir?: "ltr" | "rtl";
+    /** When `true`, moving the cursor with the arrow / Home / End keys or via
+     * typeahead also selects the option it lands on — the behaviour of APG's
+     * single-select listbox example. Left `false`, arrowing only moves the
+     * highlight and the user commits with Enter or Space, which is what a
+     * command palette or search-suggestion list needs.
+     * @default false */
+    selectionFollowsFocus?: boolean;
+    /** Render a single consumer-supplied element in place of the native `<div>`,
+     * with the listbox's `role`, `tabIndex`, ARIA state, `data-orientation`, ref
+     * and keyboard handlers merged onto it via the {@link Slot} pattern.
+     * @default false */
+    asChild?: boolean;
+    /** The {@link ListboxOptionProps | `Listbox.Option`} and
+     * {@link ListboxGroupProps | `Listbox.Group`} elements that make up the
+     * list. */
+    children?: ReactNode;
+    /** Forwarded to the underlying `HTMLDivElement`. */
+    ref?: Ref<HTMLDivElement>;
+};
+/**
+ * Single-selection mode, uncontrolled — at most one option selected, with the
+ * initial choice supplied via `defaultValue`.
+ */
+export type ListboxSingleUncontrolledProps = {
+    /** Selects single-selection semantics: at most one option selected at a
+     * time, and re-selecting the current option is a no-op rather than a
+     * deselect. */
+    type: "single";
+    /** Value of the option selected on first render. Omit to start with nothing
+     * selected. */
+    defaultValue?: string;
+    /** Forbidden in uncontrolled mode — use
+     * {@link ListboxSingleUncontrolledProps.defaultValue}. */
+    value?: never;
+    /** Called with the newly selected option's value whenever the user commits a
+     * choice. */
+    onValueChange?: (value: string) => void;
+};
+/**
+ * Single-selection mode, controlled — the selected value is owned by the
+ * caller via `value` / `onValueChange`.
+ */
+export type ListboxSingleControlledProps = {
+    /** Selects single-selection semantics: at most one option selected at a
+     * time, and re-selecting the current option is a no-op rather than a
+     * deselect. */
+    type: "single";
+    /** The currently selected option's value. Must be kept in sync by the caller
+     * via {@link ListboxSingleControlledProps.onValueChange}. */
+    value: string;
+    /** Called with the value the user is asking to select. */
+    onValueChange?: (value: string) => void;
+    /** Forbidden in controlled mode — use
+     * {@link ListboxSingleControlledProps.value}. */
+    defaultValue?: never;
+};
+/**
+ * Multiple-selection mode, uncontrolled — options toggle independently, with
+ * the initial set supplied via `defaultValue`.
+ */
+export type ListboxMultipleUncontrolledProps = {
+    /** Selects multiple-selection semantics: any number of options can be
+     * selected and each toggles independently. Sets `aria-multiselectable` on
+     * the root. */
+    type: "multiple";
+    /** Values of the options selected on first render. Omit to start with
+     * nothing selected. */
+    defaultValue?: string[];
+    /** Forbidden in uncontrolled mode — use
+     * {@link ListboxMultipleUncontrolledProps.defaultValue}. */
+    value?: never;
+    /** Called with the complete next set of selected values whenever the user
+     * toggles any option. */
+    onValueChange?: (value: string[]) => void;
+};
+/**
+ * Multiple-selection mode, controlled — the set of selected values is owned by
+ * the caller via `value` / `onValueChange`.
+ */
+export type ListboxMultipleControlledProps = {
+    /** Selects multiple-selection semantics: any number of options can be
+     * selected and each toggles independently. Sets `aria-multiselectable` on
+     * the root. */
+    type: "multiple";
+    /** The full set of currently selected values. Must be kept in sync by the
+     * caller via {@link ListboxMultipleControlledProps.onValueChange}. */
+    value: string[];
+    /** Called with the complete next set of selected values whenever the user
+     * toggles any option. */
+    onValueChange?: (value: string[]) => void;
+    /** Forbidden in controlled mode — use
+     * {@link ListboxMultipleControlledProps.value}. */
+    defaultValue?: never;
+};
+/**
+ * Props for {@link ListboxRoot | `Listbox.Root`}. Combines the shared
+ * {@link ListboxRootBaseProps} with one mode-specific arm — single or
+ * multiple, controlled or uncontrolled — so the `value` / `defaultValue` /
+ * `onValueChange` shape is enforced per `type`.
+ */
+export type ListboxRootProps = ListboxRootBaseProps & (ListboxSingleUncontrolledProps | ListboxSingleControlledProps | ListboxMultipleUncontrolledProps | ListboxMultipleControlledProps);
+/**
+ * Props for {@link ListboxOption | `Listbox.Option`} — one selectable choice.
+ * `value` identifies it within the listbox; `children` supplies the label that
+ * typeahead matches against.
+ */
+export type ListboxOptionProps = HTMLAttributes<HTMLDivElement> & {
+    /** Identifies this option within the listbox. It is this string — not the
+     * visible label — that is compared against the root's selected `value` /
+     * `defaultValue`; use `children` for the label. */
+    value: string;
+    /** Removes the option from cursor navigation, focus seeding and typeahead,
+     * and makes it unselectable by click or key. The option stays in the DOM and
+     * in the accessibility tree, marked `aria-disabled`. Also sets
+     * `data-disabled=""` for CSS targeting.
+     * @default false */
+    disabled?: boolean;
+    /** Render a single consumer-supplied element in place of the native `<div>`,
+     * with the option's `role`, `id`, `aria-selected`, `data-highlighted` and
+     * click handler merged onto it via the {@link Slot} pattern. The child must
+     * accept a `ref`.
+     * @default false */
+    asChild?: boolean;
+    /** Forwarded to the underlying `HTMLDivElement`. */
+    ref?: Ref<HTMLDivElement>;
+};
+/**
+ * Props for {@link ListboxGroup | `Listbox.Group`} — a named cluster of
+ * options. Grouping is presentational; it does not partition navigation.
+ */
+export type ListboxGroupProps = HTMLAttributes<HTMLDivElement> & {
+    /** Accessible name for the group, applied as `aria-label`. APG requires
+     * every option group to carry a name — supply it either with this prop (an
+     * invisible name) or by rendering a
+     * {@link ListboxGroupLabelProps | `Listbox.GroupLabel`} heading inside the
+     * group, which names it via `aria-labelledby` instead. A rendered
+     * `GroupLabel` takes precedence. */
+    label?: string;
+    /** Render a single consumer-supplied element in place of the native `<div>`,
+     * with the group's `role` and `aria-label` merged onto it via the
+     * {@link Slot} pattern.
+     * @default false */
+    asChild?: boolean;
+    /** Forwarded to the underlying `HTMLDivElement`. */
+    ref?: Ref<HTMLDivElement>;
+};
+/**
+ * Props for {@link ListboxGroupLabel | `Listbox.GroupLabel`} — the visible
+ * heading that names its enclosing {@link ListboxGroup | `Listbox.Group`}.
+ */
+export type ListboxGroupLabelProps = HTMLAttributes<HTMLDivElement> & {
+    /** Render a single consumer-supplied element in place of the native
+     * `<div>`, with the heading's `id` and `role="presentation"` merged onto it
+     * via the {@link Slot} pattern.
+     * @default false */
+    asChild?: boolean;
+    /** Forwarded to the underlying `HTMLDivElement`. */
+    ref?: Ref<HTMLDivElement>;
+};
+/**
+ * Context shared from {@link ListboxGroup | `Listbox.Group`} to its label —
+ * the id the heading must adopt so the group can point `aria-labelledby` at
+ * it, and the registrar telling the group a heading is present.
+ */
+export type ListboxGroupContextValue = {
+    /** The DOM id the {@link ListboxGroupLabel} must render with. */
+    labelId: string;
+    /** Called by the label on mount/unmount so the group knows whether to emit
+     * `aria-labelledby`. */
+    registerLabel: (present: boolean) => void;
+};
+/**
+ * Context shared from {@link ListboxRoot | `Listbox.Root`} to its options —
+ * the selected set, the select action, the virtual-focus cursor, option
+ * registration, and the id derivation that wires `aria-activedescendant` to
+ * each option's `id`.
+ */
+export type ListboxContextValue = {
+    /** Every currently selected option value. Single mode holds at most one. */
+    selectedValues: string[];
+    /** Selects (single) or toggles (multiple) the given option. */
+    select: (optionValue: string) => void;
+    /** The option the cursor is on, or `undefined` before the root is focused. */
+    activeValue: string | undefined;
+    /** Moves the cursor onto the given option and scrolls it into view. Used by
+     * `Listbox.Option` so a click leaves the cursor where the user clicked. */
+    moveCursor: (optionValue: string) => void;
+    /** Registers a mounted option's element and disabled state; pass `null` as
+     * the element to unregister. */
+    registerOption: (optionValue: string, element: HTMLElement | null, disabled?: boolean) => void;
+    /** Derives the stable DOM `id` for an option, shared by the option itself
+     * and the root's `aria-activedescendant`. */
+    getOptionId: (optionValue: string) => string;
+};

package/dist/Listbox/types.js

@@ -0,0 +1 @@
+export {};