@reapit/elements 5.0.0-beta.60 → 5.0.0-beta.62

package/dist/types/utils/listbox/get-select-id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-select-id.d.ts","sourceRoot":"/","sources":["utils/listbox/get-select-id.ts"],"names":[],"mappings":"AAAA,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAE5D"}

package/dist/types/utils/listbox/index.d.ts

@@ -0,0 +1,11 @@
+export * from './context';
+export * from './dom-helpers';
+export * from './get-select-id';
+export * from './listbox';
+export * from './optgroup';
+export * from './option';
+export * from './render-context';
+export * from './use-focus-management';
+export * from './use-listbox-selection-observer';
+export * from './use-listbox-state';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/utils/listbox/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"/","sources":["utils/listbox/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAA;AACzB,cAAc,eAAe,CAAA;AAC7B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,WAAW,CAAA;AACzB,cAAc,YAAY,CAAA;AAC1B,cAAc,UAAU,CAAA;AACxB,cAAc,kBAAkB,CAAA;AAChC,cAAc,wBAAwB,CAAA;AACtC,cAAc,kCAAkC,CAAA;AAChD,cAAc,qBAAqB,CAAA"}

package/dist/types/utils/listbox/listbox.d.ts

@@ -0,0 +1,141 @@
+import { clearListboxValue, getListboxSelectedOptions, getListboxValue, setListboxOptionSelectedState } from './dom-helpers';
+import { Divider } from '#src/core/divider';
+import { ListboxContext, useListboxContext } from './context';
+import { ListboxOption } from './option';
+import { ListboxOptgroup } from './optgroup';
+import { ListboxRenderContext, useListboxRenderContext } from './render-context';
+import { ListboxSelect } from './select';
+import { useListboxSelectionObserver } from './use-listbox-selection-observer';
+import type { ChangeEventHandler, ComponentPropsWithoutRef, ElementType, HTMLAttributes, ReactNode } from 'react';
+type AttributesToOmit = 'onChange';
+export declare namespace Listbox {
+    interface DividerProps extends Divider.Props {
+    }
+    interface OptionProps extends ListboxOption.BaseProps {
+    }
+    interface OptgroupProps extends ListboxOptgroup.BaseProps {
+    }
+    interface SelectProps extends ListboxSelect.Props {
+    }
+    interface BaseProps extends Omit<HTMLAttributes<HTMLDivElement>, AttributesToOmit> {
+        /** Whether the listbox and its options are disabled. */
+        'aria-disabled'?: boolean;
+        /**
+         * Allows multiple option selection in the listbox.
+         * When `true`, selects multiple options simultaneously.
+         * When `false` (default), selects only one option at a time.
+         */
+        'aria-multiselectable'?: boolean;
+        /**
+         * Defines the element's orientation as horizontal or vertical.
+         * Defaults to `'vertical'`. Set to `'horizontal'` only when the
+         * listbox renders its options horizontally.
+         */
+        'aria-orientation'?: 'horizontal' | 'vertical';
+        /** Whether the listbox is required. */
+        'aria-required'?: boolean;
+        /**
+         * Options and option groups to display. Use `Listbox.Option`, `Listbox.Optgroup`,
+         * or `Listbox.Divider` components. The underlying select element renders selected
+         * options automatically based on `value`.
+         */
+        children?: ReactNode;
+        /**
+         * Initially selected option values for uncontrolled mode.
+         * Always an array of strings, regardless of single- or multi-select mode.
+         * For single-select, uses only the first value.
+         */
+        defaultValue?: readonly string[];
+        /** The listbox element's ID. Generates automatically if omitted. */
+        id?: string;
+        /** The form control name for form submission. */
+        name?: string;
+        /** Change handler for the underlying select element. Fires when selection changes. */
+        onChange?: ChangeEventHandler<HTMLSelectElement>;
+        /**
+         * Placeholder text for the default empty option.
+         * Applies only to single-select listboxes (`aria-multiselectable` is `false`).
+         * Defaults to `'Select an option'`.
+         */
+        placeholder?: string;
+        /**
+         * Behavior when clicking an option.
+         * - `'auto'`: Selects for single-selects, toggles for multi-selects
+         * - `'select'`: Always selects the option (useful for single-select)
+         * - `'toggle'`: Toggles the option's selected state (useful for multi-select)
+         * Defaults to `'auto'`.
+         */
+        selectAction?: 'auto' | 'select' | 'toggle';
+        /**
+         * Whether selection follows focus during keyboard navigation.
+         * When `true`, arrow key navigation automatically selects the focused option.
+         * When `false`, press Enter/Space to select a focused option.
+         * Defaults to `true` for single-select, `false` for multi-select.
+         */
+        selectionFollowsFocus?: boolean;
+        /**
+         * Ref to the underlying HTMLSelectElement.
+         *
+         * We use `selectRef` instead of the standard `ref` prop to preserve TypeScript's type
+         * inference for the polymorphic `as` prop. Combining `forwardRef` with generic type
+         * parameters breaks this inference.
+         */
+        selectRef?: React.Ref<HTMLSelectElement>;
+        /**
+         * Selected option values for controlled mode.
+         * Always an array of strings, regardless of single- or multi-select mode.
+         * For single-select, uses only the first value.
+         */
+        value?: readonly string[];
+    }
+    /**
+     * Polymorphic props that merge BaseProps with any additional props from the `as` component.
+     * When a component with required props is passed via `as`, those props become required.
+     */
+    type Props<C extends ElementType = 'div'> = BaseProps & Omit<ComponentPropsWithoutRef<C>, keyof BaseProps> & {
+        /** Element type for the listbox container. Defaults to `'div'`. */
+        as?: C;
+    };
+}
+/**
+ * Provides a foundation for a listbox of options. Built on a native select element,
+ * it supports single- and multi-select behavior, keyboard navigation, and focus management
+ * out of the box.
+ *
+ * This component renders all children twice: once as descendants of a native select element
+ * and once in the custom listbox UI. Include only children that render to `<option>`,
+ * `<optgroup>`, and `<hr>` elements within the native select.
+ *
+ * Use these subcomponents:
+ * - `Listbox.Option` renders as `<option>` in the native select and as a custom button
+ * in the listbox UI
+ * - `Listbox.Optgroup` renders as `<optgroup>` in the native select and as a custom div
+ * in the listbox UI
+ * - `Listbox.Divider` always renders as `<hr>`
+ *
+ * @example
+ * // Integrate with React Hook Form
+ * const { ref, ...field } = register('myField')
+ * <Listbox selectRef={ref} {...field}>
+ *   <Listbox.Option value="1">Option 1</Listbox.Option>
+ *   <Listbox.Option value="2">Option 2</Listbox.Option>
+ * </Listbox>
+ */
+export declare function Listbox<C extends ElementType = 'div'>({ 'aria-disabled': disabled, 'aria-multiselectable': multiple, 'aria-orientation': ariaOrientation, 'aria-required': required, as, children, className, defaultValue, id, name, onBlur, onChange, onFocus, onKeyDown, placeholder, selectAction, selectRef, selectionFollowsFocus, style, value, ...rest }: Listbox.Props<C>): import("react/jsx-runtime").JSX.Element;
+export declare namespace Listbox {
+    var Divider: typeof import("#src/core/divider").Divider;
+    var Option: typeof ListboxOption;
+    var Optgroup: typeof ListboxOptgroup;
+    var Select: import("react").ForwardRefExoticComponent<ListboxSelect.Props & import("react").RefAttributes<HTMLSelectElement>>;
+    var useSelectionObserver: typeof useListboxSelectionObserver;
+    var Context: import("react").Context<ListboxContext.Value | null>;
+    var RenderContext: import("react").Context<ListboxRenderContext.Value | null>;
+    var useContext: typeof useListboxContext;
+    var useRenderContext: typeof useListboxRenderContext;
+    var clearValue: typeof clearListboxValue;
+    var getSelectedOptions: typeof getListboxSelectedOptions;
+    var getValue: typeof getListboxValue;
+    var setOptionSelectedState: typeof setListboxOptionSelectedState;
+}
+export {};
+//# sourceMappingURL=listbox.d.ts.map

package/dist/types/utils/listbox/listbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"listbox.d.ts","sourceRoot":"/","sources":["utils/listbox/listbox.tsx"],"names":[],"mappings":"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"}

package/dist/types/utils/listbox/listbox.stories.d.ts

@@ -0,0 +1,92 @@
+import { Listbox } from './listbox';
+import type { StoryObj } from '@storybook/react-vite';
+declare const meta: {
+    title: string;
+    component: typeof Listbox;
+    argTypes: {
+        children: {
+            control: false;
+        };
+        defaultValue: {
+            control: false;
+        };
+        value: {
+            control: false;
+        };
+    };
+    render: (args: Listbox.BaseProps & Omit<Omit<any, "ref">, keyof Listbox.BaseProps> & {
+        as?: import("react").ElementType | undefined;
+    }) => import("react/jsx-runtime").JSX.Element;
+};
+export default meta;
+type Story = StoryObj<typeof meta>;
+/**
+ * At its most basic, `ListboxBaseListbox` renders the options (and option groups) provided to it alongside
+ * a hidden `<select>` element. The hidden select allows the selected options to be submitted as part of
+ * a standard HTML form.
+ */
+export declare const Example: Story;
+/**
+ * Single-select behaviour is the default. When used as a single-select, the first option of the combobox
+ * will always be a special "placeholder" option that will be automatically selected by the native select
+ * element when no other specific option is selected.
+ */
+export declare const Single: Story;
+/**
+ * Multi-select behaviour can be achieved using `multiple`.
+ */
+export declare const Multiple: Story;
+/**
+ * Listbox options can be disabled.
+ */
+export declare const Disabled: Story;
+/**
+ * There are two behaviours available when selecting an option. By default, the select action will
+ * `toggle` the option's selected state. In some cases however, we may want clicks to only select the option,
+ * preferring deselection to occur through a separate UI element. This `select-only` behaviour is
+ * demonstrated here.
+ */
+export declare const SelectAction: Story;
+/**
+ * Options can be grouped using `Listbox.Optgroup` and `Listbox.Divider`.
+ */
+export declare const Groups: Story;
+/**
+ * Since we rely on a native select element, the selected state can be controlled in the same manner
+ * as any other native form control. However, when controlling the combobox's state, consumers become
+ * responsible for implementing the same behaviour as the combobox would facilitate if its state
+ * were uncontrolled. To assist with this when using controlled form state management libraries like
+ * Formik, the `Listbox.getValue` helper is provided.
+ *
+ * Whether single- or multi-select behaviour is desired, the controlled state must be an array of
+ * string values. The example here demonstrates a controlled usage of the `Listbox` via simple
+ * local component state (`useState`) and `Listbox.getValue`.
+ */
+export declare const Controlled: Story;
+/**
+ * Clearing the listbox's selection when it's value is controlled is trivial: the value can simply be
+ * set to an empty array. However, sometimes the controlled value's setter may not be available to the
+ * component trying to clear it and lifting the state higher in the component tree may not be desirable.
+ * Further, sometimes the value is uncontrolled and exists only in the DOM.
+ *
+ * In these cases, `Listbox.clearValue` can be used to clear the selection state of the listbox via the
+ * DOM. When used, it will ensure a change event is fired (technically, it will be an input event) on the
+ * underlying select element so that consumers can react appropriately to the change.
+ */
+export declare const ClearingState: Story;
+/**
+ * As with clearing state, observing the listboxes selection state is trivial when it is controlled and
+ * within scope. However, if the controlled state is not easily available, or the state is uncontrolled,
+ * it can be useful to observe the selection state via a MutationObserver.
+ *
+ * The `Listbox.useSelectionObserver` makes this simple to achieve. It observes the selected options in
+ * the listbox, calling the provided callback with the array of selected options (the actual button
+ * elements), allowing consumers to react to changes in the selection state as shown here.
+ */
+export declare const ObservingState: Story;
+/**
+ * Any selected options will be included in the form data during submission. The following example
+ * demonstrates this through a native HTML form.
+ */
+export declare const Forms: Story;
+//# sourceMappingURL=listbox.stories.d.ts.map

package/dist/types/utils/listbox/listbox.stories.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"listbox.stories.d.ts","sourceRoot":"/","sources":["utils/listbox/listbox.stories.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAInC,OAAO,KAAK,EAAQ,QAAQ,EAAE,MAAM,uBAAuB,CAAA;AAE3D,QAAA,MAAM,IAAI;;;;;;;;;;;;;;;;;CAsBsB,CAAA;AAEhC,eAAe,IAAI,CAAA;AACnB,KAAK,KAAK,GAAG,QAAQ,CAAC,OAAO,IAAI,CAAC,CAAA;AAElC;;;;GAIG;AACH,eAAO,MAAM,OAAO,EAAE,KAkBrB,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,MAAM,EAAE,KAMpB,CAAA;AAED;;GAEG;AACH,eAAO,MAAM,QAAQ,EAAE,KAOtB,CAAA;AAED;;GAEG;AACH,eAAO,MAAM,QAAQ,EAAE,KAKtB,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,YAAY,EAAE,KAO1B,CAAA;AAED;;GAEG;AACH,eAAO,MAAM,MAAM,EAAE,KA8BpB,CAAA;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,UAAU,EAAE,KAsBxB,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,aAAa,EAAE,KAiB3B,CAAA;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc,EAAE,KAyB5B,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,KAAK,EAAE,KAwBnB,CAAA"}

package/dist/types/utils/listbox/optgroup/__tests__/optgroup.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=optgroup.test.d.ts.map

package/dist/types/utils/listbox/optgroup/__tests__/optgroup.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"optgroup.test.d.ts","sourceRoot":"/","sources":["utils/listbox/optgroup/__tests__/optgroup.test.tsx"],"names":[],"mappings":""}

package/dist/types/utils/listbox/optgroup/index.d.ts

@@ -0,0 +1,2 @@
+export * from './optgroup';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/utils/listbox/optgroup/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"/","sources":["utils/listbox/optgroup/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAA"}

package/dist/types/utils/listbox/optgroup/optgroup.d.ts

@@ -0,0 +1,33 @@
+import type { ComponentType, HTMLAttributes } from 'react';
+export declare namespace ListboxOptgroup {
+    interface BaseProps extends HTMLAttributes<HTMLElement> {
+        /**
+         * The label text for the option group. Provides a visual and semantic label
+         * for the group of related options.
+         */
+        label?: string;
+    }
+    interface Props extends BaseProps {
+        /**
+         * The element type to render for the option group. Must accept a `label` prop.
+         * The component passed here should render the label text accessibly and forward
+         * all props to the underlying element.
+         */
+        as: ComponentType<BaseProps>;
+    }
+}
+/**
+ * A polymorphic component for grouping related options within a Listbox.
+ *
+ * This component provides a dual-rendering capability:
+ * - When in "display" context, renders as a custom element (specified by `as` prop)
+ * - When in "native" context, renders as a native `<optgroup>` element for the hidden select
+ *
+ * The option group helps organize options into logical sections, improving usability
+ * and accessibility when dealing with many options.
+ */
+export declare function ListboxOptgroup({ as: Element, children, label, ...rest }: ListboxOptgroup.Props): import("react/jsx-runtime").JSX.Element;
+export declare namespace ListboxOptgroup {
+    var displayName: string;
+}
+//# sourceMappingURL=optgroup.d.ts.map

package/dist/types/utils/listbox/optgroup/optgroup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"optgroup.d.ts","sourceRoot":"/","sources":["utils/listbox/optgroup/optgroup.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,OAAO,CAAA;AAE1D,yBAAiB,eAAe,CAAC;IAC/B,UAAiB,SAAU,SAAQ,cAAc,CAAC,WAAW,CAAC;QAC5D;;;WAGG;QACH,KAAK,CAAC,EAAE,MAAM,CAAA;KACf;IAED,UAAiB,KAAM,SAAQ,SAAS;QACtC;;;;WAIG;QACH,EAAE,EAAE,aAAa,CAAC,SAAS,CAAC,CAAA;KAC7B;CACF;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,GAAG,IAAI,EAAE,EAAE,eAAe,CAAC,KAAK,2CAe/F;yBAfe,eAAe"}

package/dist/types/utils/listbox/option/__tests__/option.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=option.test.d.ts.map

package/dist/types/utils/listbox/option/__tests__/option.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"option.test.d.ts","sourceRoot":"/","sources":["utils/listbox/option/__tests__/option.test.tsx"],"names":[],"mappings":""}

package/dist/types/utils/listbox/option/__tests__/update-option-selection.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=update-option-selection.test.d.ts.map

package/dist/types/utils/listbox/option/__tests__/update-option-selection.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-option-selection.test.d.ts","sourceRoot":"/","sources":["utils/listbox/option/__tests__/update-option-selection.test.tsx"],"names":[],"mappings":""}

package/dist/types/utils/listbox/option/index.d.ts

@@ -0,0 +1,2 @@
+export * from './option';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/utils/listbox/option/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"/","sources":["utils/listbox/option/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAA"}

package/dist/types/utils/listbox/option/option.d.ts

@@ -0,0 +1,39 @@
+import type { ButtonHTMLAttributes, ComponentPropsWithoutRef, ElementType } from 'react';
+export declare namespace ListboxOption {
+    interface BaseProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+        /** Option value used in form submission and selection tracking */
+        value: string;
+    }
+    type Props<C extends ElementType = 'button'> = BaseProps & Omit<ComponentPropsWithoutRef<C>, keyof BaseProps> & {
+        /**
+         * Element type to render for the option. Must be button-based.
+         * Forward all props to the underlying `<button>` element for proper accessibility
+         * and functionality.
+         */
+        as?: C;
+    };
+}
+/**
+ * A polymorphic component for options within a Listbox.
+ *
+ * Provides dual-rendering capability:
+ * - In "display" context, renders as a custom button element (specified by `as`)
+ * - In "native" context, renders as a native `<option>` element for the hidden select
+ *
+ * Manages selection state automatically based on the parent listbox, updating ARIA
+ * attributes and handling click interactions.
+ *
+ * **Selection State Indication:**
+ * - Multi-select listboxes: Uses `aria-checked="true"` for selected options
+ * - Single-select listboxes: Uses `aria-selected="true"` for selected options
+ *
+ * Follows the ARIA listbox pattern: https://www.w3.org/WAI/ARIA/apg/patterns/listbox
+ *
+ * **Important:** The `as` element type must be button-based and forward all props to the
+ * underlying button for proper functionality.
+ */
+export declare function ListboxOption<C extends ElementType = 'button'>({ as, children, disabled, onClick, value: optionValue, ...rest }: ListboxOption.Props<C>): import("react/jsx-runtime").JSX.Element | null;
+export declare namespace ListboxOption {
+    var displayName: string;
+}
+//# sourceMappingURL=option.d.ts.map

package/dist/types/utils/listbox/option/option.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"option.d.ts","sourceRoot":"/","sources":["utils/listbox/option/option.tsx"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,WAAW,EAAqB,MAAM,OAAO,CAAA;AAE3G,yBAAiB,aAAa,CAAC;IAC7B,UAAiB,SAAU,SAAQ,oBAAoB,CAAC,iBAAiB,CAAC;QACxE,kEAAkE;QAClE,KAAK,EAAE,MAAM,CAAA;KACd;IAED,KAAY,KAAK,CAAC,CAAC,SAAS,WAAW,GAAG,QAAQ,IAAI,SAAS,GAC7D,IAAI,CAAC,wBAAwB,CAAC,CAAC,CAAC,EAAE,MAAM,SAAS,CAAC,GAAG;QACnD;;;;WAIG;QACH,EAAE,CAAC,EAAE,CAAC,CAAA;KACP,CAAA;CACJ;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,WAAW,GAAG,QAAQ,EAAE,EAC9D,EAAE,EACF,QAAQ,EACR,QAAQ,EACR,OAAO,EACP,KAAK,EAAE,WAAW,EAClB,GAAG,IAAI,EACR,EAAE,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC,kDA+CxB;yBAtDe,aAAa"}

package/dist/types/utils/listbox/option/update-option-selection.d.ts

@@ -0,0 +1,24 @@
+import type { MouseEvent } from 'react';
+/**
+ * Valid selection action modes for listbox options.
+ *
+ * - 'auto': Toggles for multi-select, selects for single-select
+ * - 'toggle': Always toggles the selection state
+ * - 'select': Always selects the option
+ */
+export type SelectAction = 'auto' | 'toggle' | 'select';
+/**
+ * Updates the selection state of a listbox option based on the selectAction setting.
+ *
+ * Modes:
+ * - 'auto': Toggles for multi-select, selects for single-select
+ * - 'toggle': Always toggles the selection state
+ * - 'select': Always selects the option
+ *
+ * @param event - The mouse click event from the option button. The button must have:
+ *   - `data-listbox-id`: ID of the associated listbox (required)
+ *   - `data-select-action`: Selection mode ('auto', 'toggle', or 'select') (required)
+ *   - `value`: The option value (required)
+ */
+export declare function updateOptionSelection(event: MouseEvent<HTMLButtonElement>): void;
+//# sourceMappingURL=update-option-selection.d.ts.map

package/dist/types/utils/listbox/option/update-option-selection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-option-selection.d.ts","sourceRoot":"/","sources":["utils/listbox/option/update-option-selection.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,OAAO,CAAA;AAEvC;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,QAAQ,GAAG,QAAQ,CAAA;AAoBvD;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,UAAU,CAAC,iBAAiB,CAAC,QAczE"}

package/dist/types/utils/listbox/render-context.d.ts

@@ -0,0 +1,16 @@
+export declare namespace ListboxRenderContext {
+    /** How descendants render: as custom display elements or native select elements */
+    type Value = 'custom' | 'native';
+}
+/**
+ * Tells Listbox descendants whether to render as native select elements or
+ * custom display elements.
+ */
+export declare const ListboxRenderContext: import("react").Context<ListboxRenderContext.Value | null>;
+/**
+ * Returns the current ListboxRenderContext value.
+ * @returns The render context value ('display' or 'native')
+ * @throws {Error} when used outside a Listbox
+ */
+export declare function useListboxRenderContext(): ListboxRenderContext.Value;
+//# sourceMappingURL=render-context.d.ts.map

package/dist/types/utils/listbox/render-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-context.d.ts","sourceRoot":"/","sources":["utils/listbox/render-context.ts"],"names":[],"mappings":"AAEA,yBAAiB,oBAAoB,CAAC;IACpC,mFAAmF;IACnF,KAAY,KAAK,GAAG,QAAQ,GAAG,QAAQ,CAAA;CACxC;AAED;;;GAGG;AACH,eAAO,MAAM,oBAAoB,4DAAyD,CAAA;AAE1F;;;;GAIG;AACH,wBAAgB,uBAAuB,IAAI,oBAAoB,CAAC,KAAK,CAMpE"}

package/dist/types/utils/listbox/select/__tests__/select.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=select.test.d.ts.map

package/dist/types/utils/listbox/select/__tests__/select.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"select.test.d.ts","sourceRoot":"/","sources":["utils/listbox/select/__tests__/select.test.tsx"],"names":[],"mappings":""}

package/dist/types/utils/listbox/select/index.d.ts

@@ -0,0 +1,3 @@
+export * from './select';
+export * from './styles';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/utils/listbox/select/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"/","sources":["utils/listbox/select/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAA;AACxB,cAAc,UAAU,CAAA"}

package/dist/types/utils/listbox/select/select.d.ts

@@ -0,0 +1,28 @@
+import type { SelectHTMLAttributes } from 'react';
+export declare namespace ListboxSelect {
+    interface Props extends SelectHTMLAttributes<HTMLSelectElement> {
+        /** Placeholder text for the empty option in single-select mode */
+        placeholder?: string;
+        /** Selected option values */
+        value: readonly string[];
+    }
+}
+/**
+ * Internal select element that maintains form state for the listbox.
+ *
+ * Visually hidden, this component provides native select functionality for form submission
+ * and state management. It renders a native `<select>` element synchronized with the custom
+ * listbox UI.
+ *
+ * Key behaviors:
+ * - Adds a placeholder option as the first option in single-select listboxes
+ * - Renders selected options to maintain state even when display options are filtered
+ * - Wires both `onChange` and `onInput` handlers to catch manual input events
+ * - Renders children twice: once as native `<option>` elements, once as custom display elements
+ *
+ * Uses a render context to control how children render. Children wrapped in this component
+ * receive `value="native"` from ListboxRenderContext, rendering as native `<option>` or
+ * `<optgroup>` elements.
+ */
+export declare const ListboxSelect: import("react").ForwardRefExoticComponent<ListboxSelect.Props & import("react").RefAttributes<HTMLSelectElement>>;
+//# sourceMappingURL=select.d.ts.map

package/dist/types/utils/listbox/select/select.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"select.d.ts","sourceRoot":"/","sources":["utils/listbox/select/select.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,OAAO,CAAA;AAEjD,yBAAiB,aAAa,CAAC;IAC7B,UAAiB,KAAM,SAAQ,oBAAoB,CAAC,iBAAiB,CAAC;QACpE,kEAAkE;QAClE,WAAW,CAAC,EAAE,MAAM,CAAA;QACpB,6BAA6B;QAC7B,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;KACzB;CACF;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,aAAa,mHAiCxB,CAAA"}

package/dist/types/utils/listbox/select/styles.d.ts

@@ -0,0 +1,2 @@
+export declare const ElListboxSelect: import("@linaria/react").StyledComponent<import("react").ClassAttributes<HTMLSelectElement> & import("react").SelectHTMLAttributes<HTMLSelectElement> & Record<never, unknown>>;
+//# sourceMappingURL=styles.d.ts.map

package/dist/types/utils/listbox/select/styles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"styles.d.ts","sourceRoot":"/","sources":["utils/listbox/select/styles.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,eAAe,iLAK3B,CAAA"}

package/dist/types/utils/listbox/use-focus-management/__tests__/handle-blur-event.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=handle-blur-event.test.d.ts.map

package/dist/types/utils/listbox/use-focus-management/__tests__/handle-blur-event.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handle-blur-event.test.d.ts","sourceRoot":"/","sources":["utils/listbox/use-focus-management/__tests__/handle-blur-event.test.tsx"],"names":[],"mappings":""}

package/dist/types/utils/listbox/use-focus-management/__tests__/handle-focus-event.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=handle-focus-event.test.d.ts.map

package/dist/types/utils/listbox/use-focus-management/__tests__/handle-focus-event.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handle-focus-event.test.d.ts","sourceRoot":"/","sources":["utils/listbox/use-focus-management/__tests__/handle-focus-event.test.tsx"],"names":[],"mappings":""}

package/dist/types/utils/listbox/use-focus-management/__tests__/use-focus-management.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=use-focus-management.test.d.ts.map

package/dist/types/utils/listbox/use-focus-management/__tests__/use-focus-management.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-focus-management.test.d.ts","sourceRoot":"/","sources":["utils/listbox/use-focus-management/__tests__/use-focus-management.test.tsx"],"names":[],"mappings":""}

package/dist/types/utils/listbox/use-focus-management/handle-blur-event.d.ts

@@ -0,0 +1,18 @@
+import type { FocusEvent } from 'react';
+/**
+ * Handles blur events for a listbox element to manage tab sequence participation.
+ *
+ * This function works in combination with `handleFocusEvent` to implement the roving tabindex
+ * pattern for listbox keyboard navigation. When focus moves outside the listbox entirely,
+ * the listbox element is restored to the document's tab sequence (tabIndex set to 0).
+ *
+ * This ensures that when the user tabs away from the listbox and then tabs back, they can
+ * re-enter the listbox naturally. Without this behavior, the listbox would remain at
+ * tabIndex -1 and become unreachable via keyboard navigation.
+ *
+ * **Key Behavior:**
+ * - If focus is moving to a related target outside the listbox, restore tabIndex to 0
+ * - If focus is moving between elements within the listbox, do nothing (keep tabIndex at -1)
+ */
+export declare function handleBlurEvent(event: FocusEvent<HTMLElement>): void;
+//# sourceMappingURL=handle-blur-event.d.ts.map

package/dist/types/utils/listbox/use-focus-management/handle-blur-event.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handle-blur-event.d.ts","sourceRoot":"/","sources":["utils/listbox/use-focus-management/handle-blur-event.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,OAAO,CAAA;AAEvC;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,UAAU,CAAC,WAAW,CAAC,GAAG,IAAI,CAQpE"}

package/dist/types/utils/listbox/use-focus-management/handle-focus-event.d.ts

@@ -0,0 +1,24 @@
+import type { FocusEvent } from 'react';
+/**
+ * Handles focus events for a listbox element to manage keyboard navigation and selection behavior.
+ *
+ * This function implements the ARIA listbox focus management pattern, ensuring proper
+ * keyboard navigation and selection behavior. It handles two primary scenarios:
+ *
+ * **Behavior 1: Focus moving between options within the listbox**
+ * When focus moves from one option to another via keyboard navigation and `selectionFollowsFocus`
+ * is enabled, the newly focused option is automatically clicked to select it. This provides
+ * a more efficient keyboard navigation experience where users don't need to press Enter/Space
+ * to confirm their selection.
+ *
+ * **Behavior 2: Focus entering the listbox from outside**
+ * When focus enters the listbox from outside (e.g., via Tab key), the listbox is removed from
+ * the tab sequence (tabIndex set to -1) to implement roving tabindex. Focus is then moved to:
+ * 1. The first selected option (if any exists), OR
+ * 2. The first available option (if no selections exist)
+ *
+ * In case 2, if `selectionFollowsFocus` is enabled and focus was via keyboard, the first
+ * option is also automatically selected.
+ */
+export declare function handleFocusEvent(event: FocusEvent<HTMLElement>): void;
+//# sourceMappingURL=handle-focus-event.d.ts.map

package/dist/types/utils/listbox/use-focus-management/handle-focus-event.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handle-focus-event.d.ts","sourceRoot":"/","sources":["utils/listbox/use-focus-management/handle-focus-event.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,OAAO,CAAA;AAwBvC;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,UAAU,CAAC,WAAW,CAAC,GAAG,IAAI,CA8CrE"}

package/dist/types/utils/listbox/use-focus-management/index.d.ts

@@ -0,0 +1,2 @@
+export * from './use-focus-management';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/utils/listbox/use-focus-management/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"/","sources":["utils/listbox/use-focus-management/index.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAA"}

package/dist/types/utils/listbox/use-focus-management/use-focus-management.d.ts

@@ -0,0 +1,31 @@
+import type { FocusEventHandler, KeyboardEventHandler } from 'react';
+export declare namespace useFocusManagement {
+    interface Input {
+        /** Blur handler called before internal blur handling */
+        onBlur?: FocusEventHandler<HTMLDivElement>;
+        /** Focus handler called before internal focus handling */
+        onFocus?: FocusEventHandler<HTMLDivElement>;
+        /** Keydown handler called before internal keyboard navigation */
+        onKeyDown?: KeyboardEventHandler<HTMLDivElement>;
+    }
+    interface Output {
+        /** Manages tab index when focus leaves the listbox */
+        onBlur: FocusEventHandler<HTMLDivElement>;
+        /** Manages focus and selection when entering or moving within the listbox */
+        onFocus: FocusEventHandler<HTMLDivElement>;
+        /** Enables arrow key navigation between options */
+        onKeyDown: KeyboardEventHandler<HTMLDivElement>;
+    }
+}
+/**
+ * Manages focus behavior and keyboard navigation for a listbox.
+ * Provides event handlers implementing ARIA listbox keyboard interaction patterns.
+ *
+ * Orchestrates these focus-related behaviors:
+ * - Arrow key navigation between options
+ * - Focus management when entering/leaving the listbox
+ * - Selection following focus (when enabled)
+ * - Tab index management for roving tabindex pattern
+ */
+export declare function useFocusManagement({ onBlur, onFocus, onKeyDown, }: useFocusManagement.Input): useFocusManagement.Output;
+//# sourceMappingURL=use-focus-management.d.ts.map

package/dist/types/utils/listbox/use-focus-management/use-focus-management.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-focus-management.d.ts","sourceRoot":"/","sources":["utils/listbox/use-focus-management/use-focus-management.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,OAAO,CAAA;AAEpE,yBAAiB,kBAAkB,CAAC;IAClC,UAAiB,KAAK;QACpB,wDAAwD;QACxD,MAAM,CAAC,EAAE,iBAAiB,CAAC,cAAc,CAAC,CAAA;QAC1C,0DAA0D;QAC1D,OAAO,CAAC,EAAE,iBAAiB,CAAC,cAAc,CAAC,CAAA;QAC3C,iEAAiE;QACjE,SAAS,CAAC,EAAE,oBAAoB,CAAC,cAAc,CAAC,CAAA;KACjD;IAED,UAAiB,MAAM;QACrB,sDAAsD;QACtD,MAAM,EAAE,iBAAiB,CAAC,cAAc,CAAC,CAAA;QACzC,6EAA6E;QAC7E,OAAO,EAAE,iBAAiB,CAAC,cAAc,CAAC,CAAA;QAC1C,mDAAmD;QACnD,SAAS,EAAE,oBAAoB,CAAC,cAAc,CAAC,CAAA;KAChD;CACF;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,EACjC,MAAM,EACN,OAAO,EACP,SAAS,GACV,EAAE,kBAAkB,CAAC,KAAK,GAAG,kBAAkB,CAAC,MAAM,CAqBtD"}