@primitiv-ui/react 0.1.38 → 0.1.40

package/dist/InputGroup/InputGroup.d.ts

@@ -0,0 +1,176 @@
+import type { ReactElement } from "react";
+import { InputGroupAdornmentProps, InputGroupRootProps } from "./types.js";
+/**
+ * The root of an InputGroup — a stateless `<div>` wrapper that frames a
+ * single form control alongside optional leading and trailing adornments.
+ *
+ * `InputGroup` is intentionally **layout-and-anatomy only**. It owns no
+ * state, provides no context, and does not know which control sits
+ * inside it. Use CSS `:focus-within` and `:has(input:disabled)` /
+ * `:has(input[aria-invalid="true"])` to style the frame in response to
+ * the inner control's state — no JS coordination required.
+ *
+ * **Styling hook.** `data-input-group=""` on the root.
+ *
+ * **`asChild` composition.** Pass `asChild` to render the consumer's
+ * element instead of `<div>` — e.g. a `<label>` so a click anywhere on
+ * the frame focuses the wrapped input.
+ *
+ * @extends HTMLDivElement
+ *
+ * @example Basic frame with no adornments
+ * ```tsx
+ * <InputGroup>
+ *   <Input aria-label="Search" type="search" />
+ * </InputGroup>
+ * ```
+ *
+ * @example Frame rendered as a <label> so the whole frame is clickable
+ * ```tsx
+ * <InputGroup asChild>
+ *   <label>
+ *     <InputGroup.LeadingAdornment><SearchIcon /></InputGroup.LeadingAdornment>
+ *     <Input type="search" />
+ *   </label>
+ * </InputGroup>
+ * ```
+ */
+export declare function InputGroupRoot({ asChild, children, ref, ...rest }: InputGroupRootProps): ReactElement;
+export declare namespace InputGroupRoot {
+    var displayName: string;
+}
+/**
+ * A leading adornment slot — a `<span>` positioned at the start of the
+ * frame for icons, currency symbols, prefix text, or interactive
+ * buttons.
+ *
+ * **Styling hook.** `data-input-group-adornment="leading"` on the
+ * adornment element.
+ *
+ * **Accessibility.** No `aria-hidden` is set automatically — the
+ * adornment is just a positioned slot. Mark decorative icons
+ * `aria-hidden="true"` yourself (or wrap with `AccessibleIcon`), and
+ * give interactive children a proper accessible name.
+ *
+ * **`asChild` composition.** Pass `asChild` to render an interactive
+ * element such as `<button>` — for a clickable icon that triggers a
+ * search, opens a colour picker, or any other action. Event handlers
+ * compose (child runs first); refs forward to the consumer element.
+ *
+ * @extends HTMLSpanElement
+ *
+ * @example Decorative leading icon
+ * ```tsx
+ * <InputGroup.LeadingAdornment>
+ *   <SearchIcon aria-hidden="true" />
+ * </InputGroup.LeadingAdornment>
+ * ```
+ *
+ * @example Interactive leading button via asChild
+ * ```tsx
+ * <InputGroup.LeadingAdornment asChild>
+ *   <button type="button" aria-label="Open colour picker" onClick={open}>
+ *     <ColourSwatch />
+ *   </button>
+ * </InputGroup.LeadingAdornment>
+ * ```
+ */
+export declare function InputGroupLeadingAdornment({ asChild, children, ref, ...rest }: InputGroupAdornmentProps): ReactElement;
+export declare namespace InputGroupLeadingAdornment {
+    var displayName: string;
+}
+/**
+ * A trailing adornment slot — a `<span>` positioned at the end of the
+ * frame for icons, suffix text, clear buttons, or password-reveal
+ * toggles.
+ *
+ * **Styling hook.** `data-input-group-adornment="trailing"` on the
+ * adornment element.
+ *
+ * **Accessibility.** No `aria-hidden` is set automatically — the
+ * adornment is just a positioned slot. Mark decorative icons
+ * `aria-hidden="true"` yourself (or wrap with `AccessibleIcon`), and
+ * give interactive children a proper accessible name.
+ *
+ * **`asChild` composition.** Pass `asChild` to render an interactive
+ * element such as `<button>`. Event handlers compose (child runs
+ * first); refs forward to the consumer element.
+ *
+ * @extends HTMLSpanElement
+ *
+ * @example Trailing clear button via asChild
+ * ```tsx
+ * <InputGroup.TrailingAdornment asChild>
+ *   <button type="button" aria-label="Clear" onClick={clear}>
+ *     <XIcon aria-hidden="true" />
+ *   </button>
+ * </InputGroup.TrailingAdornment>
+ * ```
+ */
+export declare function InputGroupTrailingAdornment({ asChild, children, ref, ...rest }: InputGroupAdornmentProps): ReactElement;
+export declare namespace InputGroupTrailingAdornment {
+    var displayName: string;
+}
+/** Type of the {@link InputGroup} compound: the root callable plus its attached sub-components. */
+export type TInputGroupCompound = typeof InputGroupRoot & {
+    Root: typeof InputGroupRoot;
+    LeadingAdornment: typeof InputGroupLeadingAdornment;
+    TrailingAdornment: typeof InputGroupTrailingAdornment;
+};
+/**
+ * Headless, accessible **InputGroup** — a stateless compound that frames
+ * a single form control alongside optional leading and trailing
+ * adornments. Zero styles ship.
+ *
+ * `InputGroup` is intentionally **not** input-specific. It maps directly
+ * to the `framed-control/*` design-token anatomy (height,
+ * padding-inline, gap, icon-size, radius) and works just as well around
+ * a `<Textarea>`, a future `NumberInput.Control`, or any other framed
+ * control — the only thing tying it to `<Input>` is the name.
+ *
+ * `InputGroup` is both callable (an alias of `InputGroup.Root`) and
+ * carries its sub-components as static properties:
+ *
+ * - {@link InputGroupRoot | `InputGroup.Root`} — the wrapping `<div>`,
+ *   `data-input-group=""` styling hook.
+ * - {@link InputGroupLeadingAdornment | `InputGroup.LeadingAdornment`} —
+ *   leading slot, `data-input-group-adornment="leading"`.
+ * - {@link InputGroupTrailingAdornment | `InputGroup.TrailingAdornment`} —
+ *   trailing slot, `data-input-group-adornment="trailing"`.
+ *
+ * **State coordination.** None. CSS handles disabled / invalid /
+ * focus-within styling via `:has()` and `:focus-within`. {@link Field}
+ * sits *outside* `InputGroup` and owns the label / error / description
+ * wiring, so the two compose without `InputGroup` needing to know about
+ * it — wrap the `Input` in an `InputGroup` inside a `Field.Root`.
+ *
+ * @example Leading search icon
+ * ```tsx
+ * import { InputGroup, Input } from "@primitiv-ui/react";
+ *
+ * <InputGroup>
+ *   <InputGroup.LeadingAdornment>
+ *     <SearchIcon aria-hidden="true" />
+ *   </InputGroup.LeadingAdornment>
+ *   <Input aria-label="Search" type="search" />
+ * </InputGroup>
+ * ```
+ *
+ * @example Trailing clear button
+ * ```tsx
+ * <InputGroup>
+ *   <Input value={q} onChange={onChange} aria-label="Search" />
+ *   <InputGroup.TrailingAdornment asChild>
+ *     <button type="button" aria-label="Clear" onClick={clear}>
+ *       <XIcon aria-hidden="true" />
+ *     </button>
+ *   </InputGroup.TrailingAdornment>
+ * </InputGroup>
+ * ```
+ *
+ * @see {@link InputGroupRoot} for frame anatomy and `asChild` on Root.
+ * @see {@link InputGroupLeadingAdornment} for leading-slot semantics.
+ * @see {@link InputGroupTrailingAdornment} for trailing-slot semantics.
+ */
+declare const InputGroupCompound: TInputGroupCompound;
+export { InputGroupCompound as InputGroup };

package/dist/InputGroup/InputGroup.js

@@ -0,0 +1,205 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Slot } from "../Slot/index.js";
+/**
+ * The root of an InputGroup — a stateless `<div>` wrapper that frames a
+ * single form control alongside optional leading and trailing adornments.
+ *
+ * `InputGroup` is intentionally **layout-and-anatomy only**. It owns no
+ * state, provides no context, and does not know which control sits
+ * inside it. Use CSS `:focus-within` and `:has(input:disabled)` /
+ * `:has(input[aria-invalid="true"])` to style the frame in response to
+ * the inner control's state — no JS coordination required.
+ *
+ * **Styling hook.** `data-input-group=""` on the root.
+ *
+ * **`asChild` composition.** Pass `asChild` to render the consumer's
+ * element instead of `<div>` — e.g. a `<label>` so a click anywhere on
+ * the frame focuses the wrapped input.
+ *
+ * @extends HTMLDivElement
+ *
+ * @example Basic frame with no adornments
+ * ```tsx
+ * <InputGroup>
+ *   <Input aria-label="Search" type="search" />
+ * </InputGroup>
+ * ```
+ *
+ * @example Frame rendered as a <label> so the whole frame is clickable
+ * ```tsx
+ * <InputGroup asChild>
+ *   <label>
+ *     <InputGroup.LeadingAdornment><SearchIcon /></InputGroup.LeadingAdornment>
+ *     <Input type="search" />
+ *   </label>
+ * </InputGroup>
+ * ```
+ */
+export function InputGroupRoot({ asChild = false, children, ref, ...rest }) {
+    const rootProps = {
+        ...rest,
+        ref,
+        "data-input-group": "",
+    };
+    if (asChild) {
+        return _jsx(Slot, { ...rootProps, children: children });
+    }
+    return _jsx("div", { ...rootProps, children: children });
+}
+/** @internal */
+// Stryker disable next-line StringLiteral: overwritten by the compound alias — an equivalent mutant.
+InputGroupRoot.displayName = "InputGroupRoot";
+/**
+ * A leading adornment slot — a `<span>` positioned at the start of the
+ * frame for icons, currency symbols, prefix text, or interactive
+ * buttons.
+ *
+ * **Styling hook.** `data-input-group-adornment="leading"` on the
+ * adornment element.
+ *
+ * **Accessibility.** No `aria-hidden` is set automatically — the
+ * adornment is just a positioned slot. Mark decorative icons
+ * `aria-hidden="true"` yourself (or wrap with `AccessibleIcon`), and
+ * give interactive children a proper accessible name.
+ *
+ * **`asChild` composition.** Pass `asChild` to render an interactive
+ * element such as `<button>` — for a clickable icon that triggers a
+ * search, opens a colour picker, or any other action. Event handlers
+ * compose (child runs first); refs forward to the consumer element.
+ *
+ * @extends HTMLSpanElement
+ *
+ * @example Decorative leading icon
+ * ```tsx
+ * <InputGroup.LeadingAdornment>
+ *   <SearchIcon aria-hidden="true" />
+ * </InputGroup.LeadingAdornment>
+ * ```
+ *
+ * @example Interactive leading button via asChild
+ * ```tsx
+ * <InputGroup.LeadingAdornment asChild>
+ *   <button type="button" aria-label="Open colour picker" onClick={open}>
+ *     <ColourSwatch />
+ *   </button>
+ * </InputGroup.LeadingAdornment>
+ * ```
+ */
+export function InputGroupLeadingAdornment({ asChild = false, children, ref, ...rest }) {
+    const adornmentProps = {
+        ...rest,
+        ref,
+        "data-input-group-adornment": "leading",
+    };
+    if (asChild) {
+        return _jsx(Slot, { ...adornmentProps, children: children });
+    }
+    return _jsx("span", { ...adornmentProps, children: children });
+}
+/** @internal */
+InputGroupLeadingAdornment.displayName = "InputGroupLeadingAdornment";
+/**
+ * A trailing adornment slot — a `<span>` positioned at the end of the
+ * frame for icons, suffix text, clear buttons, or password-reveal
+ * toggles.
+ *
+ * **Styling hook.** `data-input-group-adornment="trailing"` on the
+ * adornment element.
+ *
+ * **Accessibility.** No `aria-hidden` is set automatically — the
+ * adornment is just a positioned slot. Mark decorative icons
+ * `aria-hidden="true"` yourself (or wrap with `AccessibleIcon`), and
+ * give interactive children a proper accessible name.
+ *
+ * **`asChild` composition.** Pass `asChild` to render an interactive
+ * element such as `<button>`. Event handlers compose (child runs
+ * first); refs forward to the consumer element.
+ *
+ * @extends HTMLSpanElement
+ *
+ * @example Trailing clear button via asChild
+ * ```tsx
+ * <InputGroup.TrailingAdornment asChild>
+ *   <button type="button" aria-label="Clear" onClick={clear}>
+ *     <XIcon aria-hidden="true" />
+ *   </button>
+ * </InputGroup.TrailingAdornment>
+ * ```
+ */
+export function InputGroupTrailingAdornment({ asChild = false, children, ref, ...rest }) {
+    const adornmentProps = {
+        ...rest,
+        ref,
+        "data-input-group-adornment": "trailing",
+    };
+    if (asChild) {
+        return _jsx(Slot, { ...adornmentProps, children: children });
+    }
+    return _jsx("span", { ...adornmentProps, children: children });
+}
+/** @internal */
+InputGroupTrailingAdornment.displayName = "InputGroupTrailingAdornment";
+/**
+ * Headless, accessible **InputGroup** — a stateless compound that frames
+ * a single form control alongside optional leading and trailing
+ * adornments. Zero styles ship.
+ *
+ * `InputGroup` is intentionally **not** input-specific. It maps directly
+ * to the `framed-control/*` design-token anatomy (height,
+ * padding-inline, gap, icon-size, radius) and works just as well around
+ * a `<Textarea>`, a future `NumberInput.Control`, or any other framed
+ * control — the only thing tying it to `<Input>` is the name.
+ *
+ * `InputGroup` is both callable (an alias of `InputGroup.Root`) and
+ * carries its sub-components as static properties:
+ *
+ * - {@link InputGroupRoot | `InputGroup.Root`} — the wrapping `<div>`,
+ *   `data-input-group=""` styling hook.
+ * - {@link InputGroupLeadingAdornment | `InputGroup.LeadingAdornment`} —
+ *   leading slot, `data-input-group-adornment="leading"`.
+ * - {@link InputGroupTrailingAdornment | `InputGroup.TrailingAdornment`} —
+ *   trailing slot, `data-input-group-adornment="trailing"`.
+ *
+ * **State coordination.** None. CSS handles disabled / invalid /
+ * focus-within styling via `:has()` and `:focus-within`. {@link Field}
+ * sits *outside* `InputGroup` and owns the label / error / description
+ * wiring, so the two compose without `InputGroup` needing to know about
+ * it — wrap the `Input` in an `InputGroup` inside a `Field.Root`.
+ *
+ * @example Leading search icon
+ * ```tsx
+ * import { InputGroup, Input } from "@primitiv-ui/react";
+ *
+ * <InputGroup>
+ *   <InputGroup.LeadingAdornment>
+ *     <SearchIcon aria-hidden="true" />
+ *   </InputGroup.LeadingAdornment>
+ *   <Input aria-label="Search" type="search" />
+ * </InputGroup>
+ * ```
+ *
+ * @example Trailing clear button
+ * ```tsx
+ * <InputGroup>
+ *   <Input value={q} onChange={onChange} aria-label="Search" />
+ *   <InputGroup.TrailingAdornment asChild>
+ *     <button type="button" aria-label="Clear" onClick={clear}>
+ *       <XIcon aria-hidden="true" />
+ *     </button>
+ *   </InputGroup.TrailingAdornment>
+ * </InputGroup>
+ * ```
+ *
+ * @see {@link InputGroupRoot} for frame anatomy and `asChild` on Root.
+ * @see {@link InputGroupLeadingAdornment} for leading-slot semantics.
+ * @see {@link InputGroupTrailingAdornment} for trailing-slot semantics.
+ */
+const InputGroupCompound = Object.assign(InputGroupRoot, {
+    Root: InputGroupRoot,
+    LeadingAdornment: InputGroupLeadingAdornment,
+    TrailingAdornment: InputGroupTrailingAdornment,
+});
+/** @internal */
+InputGroupCompound.displayName = "InputGroup";
+export { InputGroupCompound as InputGroup };

package/dist/InputGroup/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./InputGroup.js";
+export * from "./types.js";

package/dist/InputGroup/index.js

@@ -0,0 +1,2 @@
+export * from "./InputGroup.js";
+export * from "./types.js";

package/dist/InputGroup/types.d.ts

@@ -0,0 +1,41 @@
+import { ComponentProps, ReactNode, Ref } from "react";
+/**
+ * Props for {@link InputGroupRoot | `InputGroup.Root`} — the frame
+ * wrapper. Extends the native `<div>` attributes plus the `asChild`
+ * escape hatch and a typed `ref`.
+ */
+export type InputGroupRootProps = ComponentProps<"div"> & {
+    /** Render the consumer's element instead of `<div>` via the
+     * {@link Slot} pattern — e.g. a `<label>` so the whole frame is
+     * clickable. The `data-input-group` hook is preserved.
+     * @default false */
+    asChild?: boolean;
+    /** Forwarded to the underlying `HTMLDivElement` (or the `asChild`
+     * element). */
+    ref?: Ref<HTMLDivElement>;
+    /** The wrapped control and its optional leading / trailing
+     * adornments. */
+    children?: ReactNode;
+};
+/**
+ * Props shared by
+ * {@link InputGroupLeadingAdornment | `InputGroup.LeadingAdornment`} and
+ * {@link InputGroupTrailingAdornment | `InputGroup.TrailingAdornment`} —
+ * the positioned adornment slots. Extends the native `<span>` attributes
+ * plus the `asChild` escape hatch and a typed `ref`.
+ */
+export type InputGroupAdornmentProps = ComponentProps<"span"> & {
+    /** Render the consumer's element instead of `<span>` via the
+     * {@link Slot} pattern — e.g. an interactive `<button>`. Event
+     * handlers compose (child runs first) and the `data-input-group-adornment`
+     * hook is preserved.
+     * @default false */
+    asChild?: boolean;
+    /** Forwarded to the underlying `HTMLSpanElement` (or the `asChild`
+     * element). */
+    ref?: Ref<HTMLSpanElement>;
+    /** The adornment content — a decorative icon (mark it
+     * `aria-hidden="true"`), suffix text, or an interactive control with an
+     * accessible name. */
+    children?: ReactNode;
+};

package/dist/InputGroup/types.js

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

package/dist/Listbox/Listbox.d.ts

@@ -0,0 +1,231 @@
+import { type ReactElement } from "react";
+import type { ListboxGroupLabelProps, ListboxGroupProps, ListboxOptionProps, ListboxRootProps } from "./types.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 declare function ListboxRoot({ type, defaultValue, value: controlledValue, onValueChange, selectionFollowsFocus, orientation, dir, asChild, onFocus, onBlur, onKeyDown, children, ref, ...rest }: ListboxRootProps): ReactElement;
+export declare namespace ListboxRoot {
+    var displayName: string;
+}
+/**
+ * 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 declare function ListboxOption({ value, disabled, asChild, onClick, children, ref, ...rest }: ListboxOptionProps): ReactElement;
+export declare namespace ListboxOption {
+    var displayName: string;
+}
+/**
+ * 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 declare function ListboxGroup({ label, asChild, children, ref, ...rest }: ListboxGroupProps): ReactElement;
+export declare namespace ListboxGroup {
+    var displayName: string;
+}
+/**
+ * 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 declare function ListboxGroupLabel({ asChild, children, ref, ...rest }: ListboxGroupLabelProps): ReactElement;
+export declare namespace ListboxGroupLabel {
+    var displayName: string;
+}
+/**
+ * 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.
+ */
+declare const ListboxCompound: TListboxCompound;
+export { ListboxCompound as Listbox };