@primitiv-ui/react 0.1.29 → 0.1.31

package/src/Drawer/Drawer.tsx

@@ -26,7 +26,7 @@ import type {
  * @example Uncontrolled
  * ```tsx
  * <Drawer.Root defaultOpen>
- *   <Drawer.Content>…</Drawer.Content>
+ *   <Drawer.Content>...</Drawer.Content>
  * </Drawer.Root>
  * ```
  *
@@ -38,7 +38,7 @@ import type {
  *   <Drawer.Trigger>Open</Drawer.Trigger>
  *   <Drawer.Portal>
  *     <Drawer.Overlay />
- *     <Drawer.Content side="right">…</Drawer.Content>
+ *     <Drawer.Content side="right">...</Drawer.Content>
  *   </Drawer.Portal>
  * </Drawer.Root>
  * ```
@@ -92,7 +92,7 @@ DrawerTrigger.displayName = "DrawerTrigger";
  * ```tsx
  * <Drawer.Portal container={document.getElementById("drawer-root")!}>
  *   <Drawer.Overlay />
- *   <Drawer.Content>…</Drawer.Content>
+ *   <Drawer.Content>...</Drawer.Content>
  * </Drawer.Portal>
  * ```
  */
@@ -159,12 +159,12 @@ DrawerOverlay.displayName = "DrawerOverlay";
  *
  * @example Right-hand drawer (default)
  * ```tsx
- * <Drawer.Content>…</Drawer.Content>
+ * <Drawer.Content>...</Drawer.Content>
  * ```
  *
  * @example Bottom sheet
  * ```tsx
- * <Drawer.Content side="bottom">…</Drawer.Content>
+ * <Drawer.Content side="bottom">...</Drawer.Content>
  * ```
  */
 function DrawerContent({

package/src/Drawer/README.md

@@ -61,8 +61,8 @@ and changes no behaviour, focus, or ARIA — it exists purely so the styling lay
 can position and animate the panel against the right edge:
 
 ```tsx
-<Drawer.Content side="bottom">…</Drawer.Content>
-// → <dialog data-side="bottom" data-state="open" …>
+<Drawer.Content side="bottom">...</Drawer.Content>
+// → <dialog data-side="bottom" data-state="open" ...>
 ```
 
 ```css

package/src/Dropdown/Dropdown.tsx

@@ -81,7 +81,7 @@ import { MENUITEM_SELECTOR } from "./constants";
  * const [open, setOpen] = useState(false);
  *
  * <Dropdown.Root open={open} onOpenChange={setOpen}>
- *   …
+ *   ...
  * </Dropdown.Root>
  * ```
  */
@@ -960,7 +960,7 @@ export type TDropdownCompound = typeof DropdownRoot & {
  * styles ship.
  *
  * The default export is the `Root`; sub-components are attached as static
- * properties (`Dropdown.Trigger`, `Dropdown.Content`, …).
+ * properties (`Dropdown.Trigger`, `Dropdown.Content`, ...).
  */
 const DropdownCompound: TDropdownCompound = Object.assign(DropdownRoot, {
   Root: DropdownRoot,

package/src/Dropdown/README.md

@@ -213,7 +213,7 @@ submenu, which is unfocusable. While focus lives inside an open
   <Dropdown.Group>
     <Dropdown.Label>File</Dropdown.Label>
     <Dropdown.Item>New</Dropdown.Item>
-    <Dropdown.Item>Open…</Dropdown.Item>
+    <Dropdown.Item>Open...</Dropdown.Item>
   </Dropdown.Group>
   <Dropdown.Separator />
   <Dropdown.Group>
@@ -249,7 +249,7 @@ the component's):
 
 ```css
 /* Open state on the menu panel */
-[role="menu"][data-popover-open] {
+[role="menu"]:popover-open {
   animation: fade-in var(--primitiv-motion-duration-control) var(--primitiv-motion-easing-enter);
 }
 
@@ -274,9 +274,11 @@ the component's):
 }
 ```
 
-The native popover API adds `data-popover-open` on the element while the
-popover is showing; combine it with the standard ARIA attributes for
-state-driven styling.
+The popover API exposes the open state as the **`:popover-open` pseudo-class**,
+not as an attribute — combine it with the standard ARIA attributes for
+state-driven styling. (`data-popover-open` appears in this package's tests
+because the jsdom popover polyfill mirrors the state to an attribute; no browser
+sets it, so do not style against it.)
 
 `data-highlighted` is present on `Item`, `CheckboxItem`, `RadioItem`, and
 `SubTrigger` while the item has pointer focus (mouseenter). On `SubTrigger`

package/src/EmptyState/README.md

@@ -69,7 +69,7 @@ For an empty state that is part of the initial, static page — and so has
 nothing to announce — opt out of the live region:
 
 ```tsx
-<EmptyState.Root role={undefined}>…</EmptyState.Root>
+<EmptyState.Root role={undefined}>...</EmptyState.Root>
 ```
 
 ## Media
@@ -106,7 +106,7 @@ instead of the default, merging in the sub-component's props (and, for
 
 ```tsx
 <EmptyState.Root asChild>
-  <section>…</section>
+  <section>...</section>
 </EmptyState.Root>
 ```
 

package/src/Field/README.md

@@ -21,7 +21,7 @@ import { Field, Input } from "@primitiv-ui/react";
 | --------------------------- | ------------------------ | ------------------------------------- |
 | `Field` / `Field.Root`      | `<div>`                  | `data-field=""`                       |
 | `Field.Label`               | `<label>` (`htmlFor=id`) | n/a                                   |
-| `Field.Description`         | `<div id=…-description>` | n/a                                   |
+| `Field.Description`         | `<div id=...-description>` | n/a                                   |
 | `Field.ErrorText`           | `<div role="alert">`     | n/a (only renders when invalid)       |
 
 Plus three state-driven hooks on the root: `data-field-invalid`,

package/src/Field/hooks/useFieldProps.ts

@@ -19,7 +19,7 @@ type FieldAwareProps = {
 /**
  * Merges consumer-supplied props with any {@link FieldContext} available
  * higher in the tree. Use it inside form controls (Input, Textarea,
- * Select, …) so they automatically inherit the field's id, aria
+ * Select, ...) so they automatically inherit the field's id, aria
  * wiring, and `disabled` / `required` cascade when nested inside
  * `<Field.Root>`.
  *

package/src/Fieldset/Fieldset.tsx

@@ -28,7 +28,7 @@ import { FieldsetLegendProps, FieldsetProps } from "./types";
  *
  * ```tsx
  * const ref = useRef<HTMLFieldSetElement>(null);
- * <Fieldset.Root ref={ref}>…</Fieldset.Root>
+ * <Fieldset.Root ref={ref}>...</Fieldset.Root>
  * ```
  *
  * @extends HTMLFieldSetElement
@@ -46,7 +46,7 @@ import { FieldsetLegendProps, FieldsetProps } from "./types";
  * ```tsx
  * <Fieldset.Root disabled>
  *   <Fieldset.Legend>Billing</Fieldset.Legend>
- *   …every nested control is disabled…
+ *   ...every nested control is disabled...
  * </Fieldset.Root>
  * ```
  */
@@ -138,7 +138,7 @@ export type FieldsetCompound = typeof FieldsetRoot & {
  * ```tsx
  * <Fieldset.Root disabled>
  *   <Fieldset.Legend>Billing</Fieldset.Legend>
- *   …every nested control is disabled…
+ *   ...every nested control is disabled...
  * </Fieldset.Root>
  * ```
  *

package/src/Fieldset/README.md

@@ -48,7 +48,7 @@ within the group.
 ```tsx
 <Fieldset.Root>
   <Fieldset.Legend>Shipping address</Fieldset.Legend>
-  …
+  ...
 </Fieldset.Root>
 ```
 
@@ -63,7 +63,7 @@ directly:
 ```tsx
 <Fieldset.Root disabled>
   <Fieldset.Legend>Billing</Fieldset.Legend>
-  …every nested control is disabled…
+  ...every nested control is disabled...
 </Fieldset.Root>
 ```
 

package/src/Input/Input.tsx

@@ -11,7 +11,7 @@ import { InputProps } from "./types";
  *
  * **Default type.** `type="text"` is set by default. Override with the
  * `type` prop for any native variant (`"email"`, `"password"`,
- * `"number"`, `"search"`, `"tel"`, `"url"`, `"date"`, …). Future
+ * `"number"`, `"search"`, `"tel"`, `"url"`, `"date"`, ...). Future
  * composite primitives (`PasswordInput`, `NumberInput`, `DatePicker`)
  * will layer richer interaction on top of those types.
  *

package/src/Input/README.md

@@ -14,11 +14,11 @@ import { Input } from "@primitiv-ui/react";
 
 | Prop       | Type                       | Default  | Notes                                                          |
 | ---------- | -------------------------- | -------- | -------------------------------------------------------------- |
-| `type`     | `string`                   | `"text"` | Any native `<input>` type (`"email"`, `"password"`, …)         |
+| `type`     | `string`                   | `"text"` | Any native `<input>` type (`"email"`, `"password"`, ...)         |
 | `disabled` | `boolean`                  | —        | Native `disabled` + `data-disabled=""` styling hook            |
 | `asChild`  | `boolean`                  | `false`  | Delegate rendering to the child element via Slot               |
 | `ref`      | `Ref<HTMLInputElement>`    | —        | Forwarded to the underlying input element                      |
-| `...rest`  | `ComponentProps<"input">`  | —        | All other `<input>` props (`value`, `placeholder`, `aria-*`, …) |
+| `...rest`  | `ComponentProps<"input">`  | —        | All other `<input>` props (`value`, `placeholder`, `aria-*`, ...) |
 
 ## Default type
 

package/src/Listbox/Listbox.tsx

@@ -0,0 +1,475 @@
+import {
+  useEffect,
+  useId,
+  useMemo,
+  useRef,
+  useState,
+  type ReactElement,
+} from "react";
+
+import { useDirection } from "../DirectionProvider/index.ts";
+import { Slot, composeEventHandlers, composeRefs } from "../Slot/index.ts";
+
+import {
+  ListboxGroupProvider,
+  ListboxProvider,
+  useListboxContext,
+  useListboxGroupContext,
+} from "./ListboxContext";
+import { useListboxRoot } from "./hooks/index.ts";
+import type {
+  ListboxGroupLabelProps,
+  ListboxGroupProps,
+  ListboxOptionProps,
+  ListboxRootProps,
+} from "./types";
+
+/**
+ * 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
+}: ListboxRootProps): ReactElement {
+  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" as const,
+    tabIndex: 0,
+    "aria-multiselectable": type === "multiple" ? true : undefined,
+    "aria-orientation":
+      orientation === "horizontal" ? ("horizontal" as const) : undefined,
+    "data-orientation": orientation,
+    "aria-activedescendant":
+      activeValue === undefined ? undefined : getOptionId(activeValue),
+    onFocus: composeEventHandlers(onFocus, seedActiveValue),
+    onBlur: composeEventHandlers(onBlur, clearActiveValue),
+    onKeyDown: composeEventHandlers(onKeyDown, handleKeyDown),
+  };
+
+  return (
+    <ListboxProvider value={contextValue}>
+      {asChild ? (
+        <Slot {...rootProps}>{children}</Slot>
+      ) : (
+        <div {...rootProps}>{children}</div>
+      )}
+    </ListboxProvider>
+  );
+}
+
+/** @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
+}: ListboxOptionProps): ReactElement {
+  const {
+    selectedValues,
+    select,
+    activeValue,
+    registerOption,
+    getOptionId,
+    moveCursor,
+  } = useListboxContext();
+  const selected = selectedValues.includes(value);
+
+  const localRef = useRef<HTMLDivElement | null>(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" as const,
+    "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 ? (
+    <Slot {...optionProps}>{children}</Slot>
+  ) : (
+    <div {...optionProps}>{children}</div>
+  );
+}
+
+/** @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
+}: ListboxGroupProps): ReactElement {
+  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" as const,
+    // 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 (
+    <ListboxGroupProvider value={contextValue}>
+      {asChild ? (
+        <Slot {...groupProps}>{children}</Slot>
+      ) : (
+        <div {...groupProps}>{children}</div>
+      )}
+    </ListboxGroupProvider>
+  );
+}
+
+/** @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
+}: ListboxGroupLabelProps): ReactElement {
+  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" as const,
+  };
+
+  return asChild ? (
+    <Slot {...labelProps}>{children}</Slot>
+  ) : (
+    <div {...labelProps}>{children}</div>
+  );
+}
+
+/** @internal */
+// Stryker disable next-line StringLiteral: equivalent — a DevTools label, asserted by no behaviour.
+ListboxGroupLabel.displayName = "ListboxGroupLabel";
+
+/**
+ * The shape of the exported `Listbox` value — callable as `Listbox.Root` and
+ * carrying `Root`, `Option` and `Group` as static properties.
+ */
+export type TListboxCompound = typeof ListboxRoot & {
+  Root: typeof ListboxRoot;
+  Option: typeof ListboxOption;
+  Group: typeof ListboxGroup;
+  GroupLabel: typeof 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: TListboxCompound = 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 };