@primitiv-ui/react 0.1.37 → 0.1.39

package/dist/Listbox/Listbox.js

@@ -0,0 +1,339 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useId, useMemo, useRef, useState, } from "react";
+import { useDirection } from "../DirectionProvider/index.js";
+import { Slot, composeEventHandlers, composeRefs } from "../Slot/index.js";
+import { ListboxGroupProvider, ListboxProvider, useListboxContext, useListboxGroupContext, } from "./ListboxContext.js";
+import { useListboxRoot } from "./hooks/index.js";
+/**
+ * The root of a Listbox — a `<div role="listbox">` that owns the selection,
+ * holds the single tab stop, and provides {@link ListboxContext} to its
+ * descendant {@link ListboxOption | `Listbox.Option`}s.
+ *
+ * **Virtual focus, not roving tabindex.** This is the distinguishing choice.
+ * Real DOM focus stays on the root; the visually-focused option is published
+ * as `aria-activedescendant` and marked `data-highlighted`. Options are never
+ * given a `tabIndex` and are never `focus()`ed. That is what lets a text input
+ * elsewhere keep DOM focus while driving this list — the combobox / command
+ * palette case — which a roving tabstop cannot do. Per APG, the cursor is
+ * seeded when the root takes focus (onto the first selected option, or the
+ * first enabled one) and the active option is scrolled into view as it moves.
+ *
+ * Two type modes, statically discriminated at the type level:
+ *
+ * - **`type="single"`** — at most one option selected. Re-selecting the current
+ *   option is a no-op, not a deselect. Controlled via `value: string` +
+ *   `onValueChange: (value: string) => void`.
+ * - **`type="multiple"`** — options toggle independently, and the root carries
+ *   `aria-multiselectable`. Controlled via `value: string[]` +
+ *   `onValueChange: (value: string[]) => void`.
+ *
+ * Each mode supports **uncontrolled** (`defaultValue`, or omit for an empty
+ * selection) and **controlled** (`value` + `onValueChange`) shapes.
+ *
+ * **Keyboard.** Arrow keys move the cursor along the
+ * {@link ListboxRootBaseProps.orientation | orientation} axis, wrapping at
+ * both ends; Home/End jump to the first/last option; Enter and Space select
+ * (single) or toggle (multiple) the cursor option; printable characters run a
+ * prefix typeahead. Selection is manual by default — set
+ * {@link ListboxRootBaseProps.selectionFollowsFocus | `selectionFollowsFocus`}
+ * for the APG example's select-as-you-arrow behaviour.
+ *
+ * In `type="multiple"`, APG's optional modifier shortcuts are implemented too:
+ * `Shift+Arrow` moves the cursor and selects what it lands on (without
+ * wrapping), `Ctrl`/`Cmd`+`Shift`+`Home`/`End` sweeps the selection to that
+ * edge, and `Ctrl`/`Cmd`+`A` selects every enabled option or clears the
+ * selection when all are already selected. Every **other** chorded shortcut is
+ * deliberately left alone — `Alt+Arrow` and unclaimed `Ctrl`/`Cmd` combinations
+ * reach your own `onKeyDown` and the browser untouched, so a toolbar can bind
+ * them.
+ *
+ * **Reordering.** Navigation order is read from the live DOM on each
+ * interaction rather than from mount order, so moving an option in place is
+ * picked up immediately.
+ *
+ * **ARIA.** `role="listbox"` on the root, plus `aria-activedescendant`,
+ * `aria-multiselectable` (multiple mode only) and `aria-orientation`
+ * (horizontal only — vertical is the ARIA default). The root needs an
+ * accessible name: pass `aria-label` or `aria-labelledby`.
+ *
+ * **Styling hooks.** `data-orientation="horizontal" | "vertical"` on the root.
+ *
+ * @extends HTMLDivElement
+ *
+ * @example Single selection
+ * ```tsx
+ * <Listbox.Root type="single" defaultValue="apple" aria-label="Fruit">
+ *   <Listbox.Option value="apple">Apple</Listbox.Option>
+ *   <Listbox.Option value="banana">Banana</Listbox.Option>
+ * </Listbox.Root>
+ * ```
+ *
+ * @example Multiple selection, controlled
+ * ```tsx
+ * const [value, setValue] = useState<string[]>([]);
+ *
+ * <Listbox.Root type="multiple" value={value} onValueChange={setValue} aria-label="Toppings">
+ *   <Listbox.Option value="cheese">Cheese</Listbox.Option>
+ *   <Listbox.Option value="olives">Olives</Listbox.Option>
+ * </Listbox.Root>
+ * ```
+ *
+ * @example As a semantic list
+ * ```tsx
+ * <Listbox.Root type="single" asChild aria-label="Fruit">
+ *   <ul>
+ *     <Listbox.Option value="apple" asChild>
+ *       <li>Apple</li>
+ *     </Listbox.Option>
+ *   </ul>
+ * </Listbox.Root>
+ * ```
+ */
+export function ListboxRoot({ type, defaultValue, value: controlledValue, onValueChange, selectionFollowsFocus = false, orientation = "vertical", dir, asChild = false, onFocus, onBlur, onKeyDown, children, ref, ...rest }) {
+    const resolvedDir = dir ?? useDirection();
+    const { selectedValues, select, activeValue, registerOption, getOptionId, seedActiveValue, clearActiveValue, handleKeyDown, moveCursor, } = useListboxRoot({
+        type,
+        defaultValue,
+        value: controlledValue,
+        onValueChange,
+        selectionFollowsFocus,
+        orientation,
+        dir: resolvedDir,
+    });
+    const contextValue = useMemo(() => ({
+        selectedValues,
+        select,
+        activeValue,
+        registerOption,
+        getOptionId,
+        moveCursor,
+    }), [
+        selectedValues,
+        select,
+        activeValue,
+        registerOption,
+        getOptionId,
+        moveCursor,
+    ]);
+    const rootProps = {
+        ...rest,
+        ref,
+        role: "listbox",
+        tabIndex: 0,
+        "aria-multiselectable": type === "multiple" ? true : undefined,
+        "aria-orientation": orientation === "horizontal" ? "horizontal" : undefined,
+        "data-orientation": orientation,
+        "aria-activedescendant": activeValue === undefined ? undefined : getOptionId(activeValue),
+        onFocus: composeEventHandlers(onFocus, seedActiveValue),
+        onBlur: composeEventHandlers(onBlur, clearActiveValue),
+        onKeyDown: composeEventHandlers(onKeyDown, handleKeyDown),
+    };
+    return (_jsx(ListboxProvider, { value: contextValue, children: asChild ? (_jsx(Slot, { ...rootProps, children: children })) : (_jsx("div", { ...rootProps, children: children })) }));
+}
+/** @internal */
+// Stryker disable next-line StringLiteral: overwritten by the compound alias — an equivalent mutant.
+ListboxRoot.displayName = "ListboxRoot";
+/**
+ * A single choice inside a Listbox — a `<div role="option">` reporting its own
+ * selected and highlighted state.
+ *
+ * **No tab stop, no DOM focus.** The option is never focusable; the root owns
+ * focus and points at this element with `aria-activedescendant` when the
+ * cursor reaches it. Style the cursor from `data-highlighted`, not `:focus`.
+ *
+ * **Selection.** Clicking an option selects it (single) or toggles it
+ * (multiple), as does Enter / Space while the cursor is on it. A click also
+ * moves the cursor onto the clicked option, so a following arrow key resumes
+ * from there — APG treats the clicked option as the focused one.
+ *
+ * **Hover does nothing.** Unlike `Select`'s popup listbox, pointing at an
+ * option does not move the cursor: a mouse resting over the list would
+ * otherwise steal it mid-keystroke. Give hover its own weaker treatment in
+ * CSS, distinct from `data-highlighted`.
+ *
+ * **Disabled.** `disabled` sets `aria-disabled` and removes the option from
+ * cursor navigation, focus seeding, and typeahead — it stays in the
+ * accessibility tree and in the DOM. This is a house extension: APG's listbox
+ * pattern does not itself specify disabled options.
+ *
+ * **Typeahead matching** reads the option's rendered text, so keep the label
+ * in `children`.
+ *
+ * **Styling hooks.** `data-highlighted=""` when the cursor is on it,
+ * `data-disabled=""` when disabled. Selection is read from `aria-selected`.
+ *
+ * @throws if rendered outside a `Listbox.Root`.
+ *
+ * @extends HTMLDivElement
+ *
+ * @example
+ * ```tsx
+ * <Listbox.Option value="apple">Apple</Listbox.Option>
+ * <Listbox.Option value="durian" disabled>Durian (out of stock)</Listbox.Option>
+ * ```
+ */
+export function ListboxOption({ value, disabled = false, asChild = false, onClick, children, ref, ...rest }) {
+    const { selectedValues, select, activeValue, registerOption, getOptionId, moveCursor, } = useListboxContext();
+    const selected = selectedValues.includes(value);
+    const localRef = useRef(null);
+    // Stryker disable next-line ArrayDeclaration: equivalent — localRef is a stable RefObject, so the composed ref behaves identically however the deps are spelled.
+    const setRef = useMemo(() => composeRefs(localRef, ref), [ref]);
+    useEffect(() => {
+        registerOption(value, localRef.current, disabled);
+        return () => registerOption(value, null);
+    }, [value, disabled, registerOption]);
+    const optionProps = {
+        ...rest,
+        ref: setRef,
+        id: getOptionId(value),
+        role: "option",
+        "aria-selected": selected,
+        "aria-disabled": disabled || undefined,
+        "data-disabled": disabled ? "" : undefined,
+        "data-highlighted": activeValue === value ? "" : undefined,
+        onClick: composeEventHandlers(onClick, () => {
+            if (disabled)
+                return;
+            select(value);
+            // A click is a deliberate act of choosing, so it also becomes the
+            // cursor's position — APG treats the clicked option as the focused one.
+            // Without this the two ways of choosing disagree about where you are in
+            // the list: focus (which fires first) seeds the cursor onto the
+            // previously-selected option, and the next arrow key would resume from
+            // there rather than from the row just clicked. Deliberately not
+            // `navigateTo`, which would re-apply selectionFollowsFocus and, in
+            // multiple mode, toggle the option straight back off.
+            moveCursor(value);
+        }),
+    };
+    return asChild ? (_jsx(Slot, { ...optionProps, children: children })) : (_jsx("div", { ...optionProps, children: children }));
+}
+/** @internal */
+// Stryker disable next-line StringLiteral: equivalent — a DevTools label, asserted by no behaviour.
+ListboxOption.displayName = "ListboxOption";
+/**
+ * A titled cluster of options — a `<div role="group">` carrying the accessible
+ * name APG requires on every option group.
+ *
+ * Grouping is presentational only: the cursor still walks every option in DOM
+ * order, crossing group boundaries without stopping, and typeahead searches
+ * the whole list.
+ *
+ * @extends HTMLDivElement
+ *
+ * @example
+ * ```tsx
+ * <Listbox.Root type="single" aria-label="Fruit">
+ *   <Listbox.Group label="Citrus">
+ *     <Listbox.Option value="lemon">Lemon</Listbox.Option>
+ *   </Listbox.Group>
+ *   <Listbox.Group label="Berries">
+ *     <Listbox.Option value="fig">Fig</Listbox.Option>
+ *   </Listbox.Group>
+ * </Listbox.Root>
+ * ```
+ */
+export function ListboxGroup({ label, asChild = false, children, ref, ...rest }) {
+    const labelId = useId();
+    const [hasLabel, setHasLabel] = useState(false);
+    const contextValue = useMemo(() => ({ labelId, registerLabel: setHasLabel }), 
+    // Stryker disable next-line ArrayDeclaration: equivalent — labelId is a useId() constant and setHasLabel is a stable setState, so an empty dep array memoises identically.
+    [labelId]);
+    const groupProps = {
+        ...rest,
+        ref,
+        role: "group",
+        // A rendered GroupLabel wins: aria-labelledby outranks aria-label in the
+        // accessible-name algorithm, so emitting both would be misleading.
+        "aria-labelledby": hasLabel ? labelId : undefined,
+        "aria-label": hasLabel ? undefined : label,
+    };
+    return (_jsx(ListboxGroupProvider, { value: contextValue, children: asChild ? (_jsx(Slot, { ...groupProps, children: children })) : (_jsx("div", { ...groupProps, children: children })) }));
+}
+/** @internal */
+// Stryker disable next-line StringLiteral: equivalent — a DevTools label, asserted by no behaviour.
+ListboxGroup.displayName = "ListboxGroup";
+/**
+ * The visible heading that names its enclosing
+ * {@link ListboxGroup | `Listbox.Group`} — APG's grouped-options example
+ * labels each group this way rather than with an invisible `aria-label`.
+ *
+ * Renders `role="presentation"` so the heading is not exposed as an option
+ * (only `role="option"` elements may sit inside a listbox), while still being
+ * referenceable: the Group points `aria-labelledby` at this element's id,
+ * which is derived and wired automatically.
+ *
+ * @throws if rendered outside a `Listbox.Group`.
+ *
+ * @extends HTMLDivElement
+ *
+ * @example
+ * ```tsx
+ * <Listbox.Group>
+ *   <Listbox.GroupLabel>Land</Listbox.GroupLabel>
+ *   <Listbox.Option value="cat">Cat</Listbox.Option>
+ * </Listbox.Group>
+ * ```
+ */
+export function ListboxGroupLabel({ asChild = false, children, ref, ...rest }) {
+    const { labelId, registerLabel } = useListboxGroupContext();
+    useEffect(() => {
+        registerLabel(true);
+        return () => registerLabel(false);
+    }, 
+    // Stryker disable next-line ArrayDeclaration: equivalent — registerLabel is a stable setState from the Group above.
+    [registerLabel]);
+    const labelProps = {
+        ...rest,
+        ref,
+        id: labelId,
+        role: "presentation",
+    };
+    return asChild ? (_jsx(Slot, { ...labelProps, children: children })) : (_jsx("div", { ...labelProps, children: children }));
+}
+/** @internal */
+// Stryker disable next-line StringLiteral: equivalent — a DevTools label, asserted by no behaviour.
+ListboxGroupLabel.displayName = "ListboxGroupLabel";
+/**
+ * Headless, accessible **Listbox** — a persistently-visible list of options
+ * implementing the WAI-ARIA APG listbox pattern with a virtual-focus cursor.
+ *
+ * Unlike `Select`, nothing here opens or closes: there is no trigger and no
+ * popup layer. And unlike every roving-tabindex collection in this library,
+ * DOM focus never moves to an option — the root keeps it and publishes
+ * `aria-activedescendant`, so an external control (a search input, a command
+ * palette) can hold focus and drive the list.
+ *
+ * `Listbox` is both callable (an alias of {@link ListboxRoot | `Listbox.Root`})
+ * and carries its sub-components as static properties.
+ *
+ * - {@link ListboxRoot | `Listbox.Root`} — state owner, context provider, tab
+ *   stop, `<div role="listbox">` wrapper.
+ * - {@link ListboxOption | `Listbox.Option`} — one selectable choice.
+ * - {@link ListboxGroup | `Listbox.Group`} — a named cluster of options.
+ * - {@link ListboxGroupLabel | `Listbox.GroupLabel`} — a group's visible heading.
+ *
+ * @example
+ * ```tsx
+ * import { Listbox } from "@primitiv-ui/react";
+ *
+ * <Listbox.Root type="single" defaultValue="apple" aria-label="Fruit">
+ *   <Listbox.Option value="apple">Apple</Listbox.Option>
+ *   <Listbox.Option value="banana">Banana</Listbox.Option>
+ * </Listbox.Root>;
+ * ```
+ *
+ * @see {@link ListboxRoot} for selection modes, keyboard, and ARIA.
+ * @see {@link ListboxOption} for per-option state and disabling.
+ * @see {@link ListboxGroup} for grouping.
+ */
+const ListboxCompound = Object.assign(ListboxRoot, {
+    Root: ListboxRoot,
+    Option: ListboxOption,
+    Group: ListboxGroup,
+    GroupLabel: ListboxGroupLabel,
+});
+// Stryker disable next-line StringLiteral: equivalent — a DevTools label, asserted by no behaviour.
+ListboxCompound.displayName = "Listbox";
+export { ListboxCompound as Listbox };

package/dist/Listbox/ListboxContext.d.ts

@@ -0,0 +1,19 @@
+import type { Context, Provider } from "react";
+import type { ListboxContextValue, ListboxGroupContextValue } from "./types.js";
+/** Strict React context carrying the {@link ListboxContextValue} from
+ * `Listbox.Root` to its options. `null` outside a Root. */
+export declare const ListboxContext: Context<ListboxContextValue | null>;
+/** Reads the {@link ListboxContextValue}; throws outside a `Listbox.Root`. */
+export declare const useListboxContext: () => ListboxContextValue;
+/** Provider for {@link ListboxContext}, used by `Listbox.Root`. */
+declare const ListboxProvider: Provider<ListboxContextValue | null>;
+export { ListboxProvider };
+/** Strict React context carrying the {@link ListboxGroupContextValue} from
+ * `Listbox.Group` to its label. `null` outside a Group. */
+export declare const ListboxGroupContext: Context<ListboxGroupContextValue | null>;
+/** Reads the {@link ListboxGroupContextValue}; throws outside a
+ * `Listbox.Group`. */
+export declare const useListboxGroupContext: () => ListboxGroupContextValue;
+/** Provider for {@link ListboxGroupContext}, used by `Listbox.Group`. */
+declare const ListboxGroupProvider: Provider<ListboxGroupContextValue | null>;
+export { ListboxGroupProvider };

package/dist/Listbox/ListboxContext.js

@@ -0,0 +1,25 @@
+"use client";
+import { createStrictContext } from "../utils/index.js";
+const listboxContextPair = createStrictContext("Listbox.Option must be rendered as a child of Listbox.Root", 
+// Stryker disable next-line StringLiteral: equivalent — a DevTools label, asserted by no behaviour.
+"ListboxContext");
+/** Strict React context carrying the {@link ListboxContextValue} from
+ * `Listbox.Root` to its options. `null` outside a Root. */
+export const ListboxContext = listboxContextPair[0];
+/** Reads the {@link ListboxContextValue}; throws outside a `Listbox.Root`. */
+export const useListboxContext = listboxContextPair[1];
+/** Provider for {@link ListboxContext}, used by `Listbox.Root`. */
+const ListboxProvider = ListboxContext.Provider;
+export { ListboxProvider };
+const listboxGroupContextPair = createStrictContext("Listbox.GroupLabel must be rendered as a child of Listbox.Group", 
+// Stryker disable next-line StringLiteral: equivalent — a DevTools label, asserted by no behaviour.
+"ListboxGroupContext");
+/** Strict React context carrying the {@link ListboxGroupContextValue} from
+ * `Listbox.Group` to its label. `null` outside a Group. */
+export const ListboxGroupContext = listboxGroupContextPair[0];
+/** Reads the {@link ListboxGroupContextValue}; throws outside a
+ * `Listbox.Group`. */
+export const useListboxGroupContext = listboxGroupContextPair[1];
+/** Provider for {@link ListboxGroupContext}, used by `Listbox.Group`. */
+const ListboxGroupProvider = ListboxGroupContext.Provider;
+export { ListboxGroupProvider };

package/dist/Listbox/constants.d.ts

@@ -0,0 +1,2 @@
+/** Typeahead accumulation window, in milliseconds. */
+export declare const TYPEAHEAD_RESET_MS: number;

package/dist/Listbox/constants.js

@@ -0,0 +1,3 @@
+"use client";
+/** Typeahead accumulation window, in milliseconds. */
+export const TYPEAHEAD_RESET_MS = 500;

package/dist/Listbox/hooks/index.d.ts

@@ -0,0 +1 @@
+export * from "./useListboxRoot.js";

package/dist/Listbox/hooks/index.js

@@ -0,0 +1 @@
+export * from "./useListboxRoot.js";

package/dist/Listbox/hooks/useListboxRoot.d.ts

@@ -0,0 +1,39 @@
+import { type KeyboardEvent } from "react";
+type UseListboxRootArgs = {
+    type: "single" | "multiple";
+    defaultValue: string | string[] | undefined;
+    value: string | string[] | undefined;
+    onValueChange: ((value: string) => void) | ((value: string[]) => void) | undefined;
+    selectionFollowsFocus: boolean;
+    orientation: "horizontal" | "vertical";
+    dir: "ltr" | "rtl";
+};
+/**
+ * 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 declare function useListboxRoot({ type, defaultValue, value: controlledValue, onValueChange, selectionFollowsFocus, orientation, dir, }: UseListboxRootArgs): {
+    selectedValues: string[];
+    select: (optionValue: string) => void;
+    activeValue: string | undefined;
+    registerOption: (optionValue: string, element: HTMLElement | null, disabled?: boolean) => void;
+    getOptionId: (optionValue: string) => string;
+    seedActiveValue: () => void;
+    clearActiveValue: () => void;
+    handleKeyDown: (event: KeyboardEvent<HTMLElement>) => void;
+    moveCursor: (optionValue: string) => void;
+};
+export {};