@skdx/react 0.27.0 → 0.29.0

package/dist/combobox/types.d.cts

@@ -1,15 +1,62 @@
 import type * as React from 'react';
 import type { FormValidityHandle } from '../utils/formControl.cjs';
+import type { PassThroughProps } from '../utils/passThrough.cjs';
 import type { PopperContentProps } from '../utils/popper.cjs';
 import type { PortalProps } from '../utils/portal.cjs';
 import type { PrimitivePropsWithRef } from '../utils/primitive.cjs';
 import type { FocusOutsideEvent, InteractOutsideEvent } from '../utils/useDismiss.cjs';
-/**
- * How a {@link Combobox} decides which Items to show. `'manual'` filters
- * nothing — the consumer renders only the matches, which is what async or
- * server-side search needs. A predicate moves filtering inside the component.
- */
-export type ComboboxFilter = 'manual' | ((itemText: string, inputValue: string) => boolean);
+/** Flat option for ComboboxProps.options recipe prop. */
+export interface ComboboxOption {
+    /** Value committed when option is chosen. */
+    value: string;
+    /**
+     * Text shown for option; matched by filter, written back on selection.
+     * @default undefined
+     */
+    label?: string | undefined;
+    /**
+     * Excludes option from selection and pointer highlight.
+     * @default false
+     */
+    disabled?: boolean | undefined;
+}
+/** Labeled group of options for ComboboxProps.options. */
+export interface ComboboxOptionGroup {
+    /** Heading for the group. */
+    label: string;
+    /** Options in this group. */
+    options: ComboboxOption[];
+}
+/** One entry of {@link ComboboxProps.options}: a flat option, or a labeled group of them. */
+export type ComboboxOptionOrGroup = ComboboxOption | ComboboxOptionGroup;
+/** Filtering strategy: 'manual' for consumer control or predicate for component filtering; numbers rank. */
+export type ComboboxFilter = 'manual' | ((itemText: string, inputValue: string) => boolean | number);
+/** What drove a {@link Combobox} value change — the shared three-value vocabulary from `@skdx/shared`'s `change-reason` contract. */
+export type ComboboxValueChangeReason = 'keyboard' | 'pointer' | 'programmatic';
+/** Payload for the `onValueChange` event. */
+export interface ComboboxValueChangeDetail {
+    /** New selection (always array). */
+    value: string[];
+    /** Previous selection, empty when there was none. */
+    previousValue: string[];
+    /** What drove the change. */
+    reason: ComboboxValueChangeReason;
+    /** First selected value, or null when nothing is. */
+    selectedValue: string | null;
+}
+/** Gesture to open listbox: 'type', 'click', or 'focus'. */
+export type ComboboxOpenOn = 'type' | 'click' | 'focus';
+/** What moved highlight: 'keyboard', 'pointer', or 'auto'. */
+export type ComboboxHighlightReason = 'keyboard' | 'pointer' | 'auto';
+/** Payload for the `onHighlightChange` event. */
+export interface ComboboxHighlightChangeDetail {
+    /** Option value now highlighted, or null if none. */
+    value: string | null;
+    /** Previously highlighted option value, or null. */
+    previousValue: string | null;
+    /** What moved it. */
+    reason: ComboboxHighlightReason;
+}
 /** @internal What one registered {@link ComboboxItem} contributes to the root's collection. */
 export interface ComboboxItemEntry {
     /** Identifier committed to the root's value when this option is chosen. */
@@ -17,9 +64,11 @@ export interface ComboboxItemEntry {
     /** The item's `textValue`, or its rendered text — matched by `filter` and written back into the input. */
     text: string;
 }
-/** @internal Shared state distributed from {@link Combobox} to its parts via context. Not part of the public API. */
+/** @internal Shared state distributed from {@link Combobox} to its parts via context. */
 export interface ComboboxContextValue {
     inputRef: React.RefObject<HTMLInputElement | null>;
+    /** Optional trigger button ref for dismissal layer. */
+    triggerRef: React.RefObject<HTMLButtonElement | null>;
     contentRef: React.RefObject<HTMLDivElement | null>;
     contentId: string;
     /** Whether more than one option can be selected. */
@@ -28,248 +77,292 @@ export interface ComboboxContextValue {
     selectedValues: string[];
     /** Whether one option value is currently selected. */
     isSelected: (value: string) => boolean;
-    /**
-     * Commits an option: replaces the selection, writes `text` into the input
-     * and closes — or, when `multiple`, toggles it within the selection, clears
-     * the draft text, and leaves the listbox open.
-     */
-    selectItem: (value: string, text: string) => void;
+    /** Commits option: replaces selection or toggles in multi-select mode. */
+    selectItem: (value: string, text: string, reason: ComboboxValueChangeReason) => void;
+    /** Empties selection and draft text. */
+    clear: () => void;
     inputValue: string;
     onInputValueChange: (value: string) => void;
     open: boolean;
     onOpenChange: (open: boolean) => void;
     activeId: string | null;
-    setActiveId: (id: string | null) => void;
-    /** Opens the listbox and, once its items are mounted, highlights the first (or last) one. */
+    /** Rank each currently-visible item's CSS `order` should carry when `filter` also scores it; `null` leaves order untouched. */
+    itemOrder: ReadonlyMap<string, number> | null;
+    /** Moves virtual highlight and tags with reason. */
+    setActiveId: (id: string | null, reason?: ComboboxHighlightReason) => void;
+    /** Opens listbox and highlights first or last option. */
     openWithHighlight: (edge: 'first' | 'last') => void;
+    /** Whether arrow navigation wraps around the ends of the option list. */
+    loop: boolean;
+    /** Which pointer/focus gesture opens the listbox, on top of the keyboard ones. */
+    openOn: ComboboxOpenOn;
+    /** Replaces draft text with selected option's text when focus lost and `allowCustomValue` is off. */
+    reconcileDraftText: () => void;
     itemCount: number;
     registerItem: (id: string, entry: ComboboxItemEntry) => void;
     unregisterItem: (id: string) => void;
-    /** The registered entry behind an option id, for committing the virtually-focused option. */
+    /** Gets registered entry for option id. */
     getItem: (id: string) => ComboboxItemEntry | undefined;
-    /** Whether an item with this text survives the current `filter` and draft text. */
+    /** Checks if item text matches filter and draft. */
     matchesFilter: (itemText: string) => boolean;
     invalid: boolean;
     readOnly: boolean;
+    disabled: boolean;
     loading: boolean;
     allowCustomValue: boolean;
     required: boolean;
 }
+/** Forwarded ref for constraint-validation methods. */
+export type ComboboxHandle = FormValidityHandle;
 /**
- * What {@link Combobox}'s forwarded ref carries. The root renders no DOM of
- * its own, so the ref is these two constraint-validation methods and nothing
- * else — `React.useRef<ComboboxHandle>(null)`.
+ * Props for the {@link Combobox} root. Standard attributes ({@link
+ * PassThroughProps}) land on the derived `ComboboxInput` (the `role="combobox"`).
  */
-export type ComboboxHandle = FormValidityHandle;
-/** Props for the {@link Combobox} root. */
-export interface ComboboxProps {
+export interface ComboboxProps extends PassThroughProps {
     /**
-     * The `ComboboxInput`/`ComboboxPortal` parts, rendered as children — `Combobox` itself renders no DOM.
-     * @default undefined — renders nothing without children.
+     * The `ComboboxInput` and `ComboboxPortal` parts children to render.
+     * @default undefined
      */
-    children?: React.ReactNode;
+    children?: React.ReactNode | undefined;
     /**
-     * Selected option's value, for controlled usage — a `string[]` when
-     * `multiple`, a `string` otherwise. Pair with `onValueChange`.
-     * @default undefined — uncontrolled, tracks its own selected value internally.
+     * Selected value for controlled usage; pair with `onValueChange`.
+     * @default undefined
      */
-    value?: string | string[];
+    value?: string | string[] | undefined;
     /**
-     * Initially selected option's value, for uncontrolled usage. Same shape as
-     * `value`: a `string[]` when `multiple`.
-     * @default undefined — no option selected initially.
+     * Initially selected value for uncontrolled usage.
+     * @default undefined
      */
-    defaultValue?: string | string[];
+    defaultValue?: string | string[] | undefined;
     /**
-     * Fires with the new value whenever an option is chosen, controlled or not —
-     * the whole `string[]` when `multiple`, not the toggled option.
-     * @default undefined — no-op if omitted.
+     * Fires when the selected value changes in the combobox.
+     * @default undefined
      */
-    onValueChange?: (value: string | string[]) => void;
+    onValueChange?: ((detail: ComboboxValueChangeDetail) => void) | undefined;
     /**
-     * Allows more than one option to be selected: `value` becomes a `string[]`,
-     * the listbox gets `aria-multiselectable`, and committing an option toggles
-     * it, clears the draft text, and leaves the listbox open.
+     * Allows multiple options selected; toggles instead of replacing.
      * @default false
      */
-    multiple?: boolean;
+    multiple?: boolean | undefined;
     /**
-     * Lets Enter commit the draft text itself when no option is highlighted, so
-     * the combobox can create values that aren't in the list. Off by default —
-     * a combobox that silently accepts unmatched text is the wrong control for a
-     * closed set of options.
+     * Lets Enter commit unmatched draft text as a value ("creatable").
      * @default false
      */
-    allowCustomValue?: boolean;
+    allowCustomValue?: boolean | undefined;
     /**
-     * How `ComboboxItem`s are filtered against the draft text. `'manual'` filters
-     * nothing: the consumer renders only the matching items, which is what async
-     * or server-side search needs. A predicate moves filtering inside the
-     * component — every item is measured (its `textValue`, or its rendered text)
-     * and the rejected ones render nothing at all, so they leave the option
-     * count, the highlight order, and `ComboboxEmpty` exactly as if the consumer
-     * had removed them.
+     * How items are filtered; 'manual' filters nothing, predicate filters and ranks.
      * @default 'manual'
      */
-    filter?: ComboboxFilter;
+    filter?: ComboboxFilter | undefined;
     /**
-     * Keeps the first option highlighted whenever the (filtered) list changes
-     * while open, so Enter always has an obvious target. Off by default: it
-     * makes Enter commit something the user never pointed at, which is wrong
-     * when the draft text is itself a valid answer.
+     * Keeps first option highlighted when list changes while open.
      * @default false
      */
-    autoHighlight?: boolean;
+    autoHighlight?: boolean | undefined;
+    /**
+     * Wraps arrow navigation around list ends.
+     * @default true
+     */
+    loop?: boolean | undefined;
+    /**
+     * Fires when virtual focus changes; read-only, no controlled counterpart.
+     * @default undefined
+     */
+    onHighlightChange?: ((detail: ComboboxHighlightChangeDetail) => void) | undefined;
+    /**
+     * Which pointer/focus gesture opens listbox on top of keyboard ones.
+     * @default 'type'
+     */
+    openOn?: ComboboxOpenOn | undefined;
     /**
-     * Marks results as in flight: `aria-busy`/`data-loading` on `ComboboxInput`
-     * and `ComboboxContent`, and no result-count announcement (a count measured
-     * mid-fetch would announce "0 results available" for every request).
+     * Marks results as in flight: aria-busy and data-loading.
      * @default false
      */
-    loading?: boolean;
+    loading?: boolean | undefined;
     /**
-     * The text field's draft text, for controlled usage. Pair with
-     * `onInputValueChange` — typically used to drive filtering of the
-     * `ComboboxItem` list, since filtering itself is left to the consumer.
-     * @default undefined — uncontrolled, tracks its own draft text internally.
+     * Draft text for controlled usage; pair with `onInputValueChange`.
+     * @default undefined
      */
-    inputValue?: string;
+    inputValue?: string | undefined;
     /**
-     * Initial draft text, for uncontrolled usage.
+     * Initial draft text for uncontrolled usage.
      * @default ''
      */
-    defaultInputValue?: string;
+    defaultInputValue?: string | undefined;
     /**
-     * Fires with the new draft text as the user types, or when a selection updates it, controlled or not.
-     * @default undefined — no-op if omitted.
+     * Fires with new draft text on keystroke or when selection updates it.
+     * @default undefined
      */
-    onInputValueChange?: (value: string) => void;
+    onInputValueChange?: ((value: string) => void) | undefined;
     /**
-     * Whether the listbox popup is open, for controlled usage. Pair with `onOpenChange`.
-     * @default undefined — uncontrolled, tracks its own open state internally.
+     * Whether listbox is open for controlled usage; pair with `onOpenChange`.
+     * @default undefined
      */
-    open?: boolean;
+    open?: boolean | undefined;
     /**
-     * Initial open state, for uncontrolled usage.
+     * Initial open state for uncontrolled usage.
      * @default false
      */
-    defaultOpen?: boolean;
+    defaultOpen?: boolean | undefined;
     /**
-     * Fires with the new open state whenever it changes, controlled or not.
-     * @default undefined — no-op if omitted.
+     * Fires with the new open state when it changes.
+     * @default undefined
      */
-    onOpenChange?: (open: boolean) => void;
+    onOpenChange?: ((open: boolean) => void) | undefined;
     /**
-     * Fires with the new open state once the change has finished on screen —
-     * after `ComboboxContent`'s enter or exit animation ends, or as soon as it
-     * has settled when the listbox declares no animation. Use it for work that
-     * must not race the transition (measuring the panel, tearing down an
-     * expensive child); use `onOpenChange` for work that must not wait for it.
-     * @default undefined — no-op if omitted.
+     * Fires once the open/close animation completes.
+     * @default undefined
+     */
+    onOpenChangeComplete?: ((open: boolean) => void) | undefined;
+    /**
+     * Marks combobox invalid: aria-invalid and data-invalid.
+     * @default false
      */
-    onOpenChangeComplete?: (open: boolean) => void;
+    invalid?: boolean | undefined;
     /**
-     * Marks the combobox as invalid, exposed as `aria-invalid`/`data-invalid`
-     * on the `ComboboxInput`.
+     * Makes input read-only: aria-readonly and data-readonly.
      * @default false
      */
-    invalid?: boolean;
+    readOnly?: boolean | undefined;
     /**
-     * Makes the `ComboboxInput` read-only, exposed as the native `readOnly`
-     * attribute plus `aria-readonly`/`data-readonly`.
+     * Disables combobox: disabled attribute and data-disabled.
      * @default false
      */
-    readOnly?: boolean;
+    disabled?: boolean | undefined;
     /**
-     * Formats the message announced (through the shared `LiveAnnouncer`) each
-     * time the number of rendered `ComboboxItem`s changes while the listbox is
-     * open — filtering is silent for screen-reader users otherwise. Return an
-     * empty string to announce nothing.
-     * @default defaultGetResultCountLabel — e.g. `"3 results available"`
+     * Formats the match count announcement for screen readers.
+     * @default defaultGetResultCountLabel
      */
-    getResultCountLabel?: (count: number) => string;
+    getResultCountLabel?: ((count: number) => string) | undefined;
     /**
-     * Form field name. With it, visually-hidden native inputs mirror the
-     * *selected* value — never the draft `inputValue` — so the combobox
-     * participates in native form submission, reset and validation. A `multiple`
-     * combobox mirrors one control per selected value under the same `name`, the
-     * way a native `<select multiple>` submits repeated entries.
-     * @default undefined — submits nothing.
+     * Form field name; mirrors selected value for form submission.
+     * @default undefined
      */
-    name?: string;
+    name?: string | undefined;
     /**
-     * Marks the combobox required: `aria-required` on `ComboboxInput`, and —
-     * with `name` — native `valueMissing` while nothing is selected, reported
-     * through `checkValidity()`/`reportValidity()`.
+     * Id of the form this combobox submits into.
+     * @default undefined
+     */
+    form?: string | undefined;
+    /**
+     * Marks combobox required; valueMissing when nothing selected.
      * @default false
      */
-    required?: boolean;
+    required?: boolean | undefined;
+    /**
+     * Option data (flat or grouped) to render automatically.
+     * @default undefined
+     */
+    options?: ComboboxOptionOrGroup[] | undefined;
+    /**
+     * Custom rendering function for each option in the options list.
+     * @default undefined
+     */
+    renderOption?: ((option: ComboboxOption, state: {
+        selected: boolean;
+    }) => React.ReactNode) | undefined;
+    /**
+     * Placeholder text shown in the input when no value is selected.
+     * @default undefined
+     */
+    placeholder?: string | undefined;
+    /**
+     * Accessible name for derived input and listbox.
+     * @default undefined
+     */
+    'aria-label'?: string | undefined;
+    /**
+     * Corner rung the skin rounds the field by, fed to the derived `ComboboxInput`.
+     * @default undefined — the skin's own default corner.
+     */
+    shape?: 'rounded' | 'square' | (string & {}) | undefined;
+    /**
+     * Size rung the skin scales the field by, fed to the derived `ComboboxInput`.
+     * @default undefined — the skin's own default size.
+     */
+    size?: 'md' | 'sm' | 'lg' | (string & {}) | undefined;
 }
-/** Props for {@link ComboboxInput}, the text field that drives filtering and keeps real DOM focus while the listbox is open. */
-export interface ComboboxInputProps extends Omit<PrimitivePropsWithRef<'input'>, 'value' | 'defaultValue'> {
+/** Props for {@link ComboboxInput}, the text field with real DOM focus. */
+export interface ComboboxInputProps extends Omit<PrimitivePropsWithRef<'input'>, 'value' | 'defaultValue' | 'size'> {
+    /**
+     * Corner rung the skin rounds the input by, mirrored to `data-shape`.
+     * @default undefined — the skin's own default corner.
+     */
+    shape?: 'rounded' | 'square' | (string & {}) | undefined;
+    /**
+     * Size rung the skin scales the input by, mirrored to `data-size`.
+     * @default undefined — the skin's own default size.
+     */
+    size?: 'md' | 'sm' | 'lg' | (string & {}) | undefined;
 }
-/** Props for {@link ComboboxPortal}, which teleports its content to `document.body` while the listbox is open. */
+/** Props for ComboboxPortal, which teleports content to document.body. */
 export interface ComboboxPortalProps extends PortalProps {
     /**
-     * Render (and mount `ComboboxContent`) even while closed, instead of
-     * unmounting. Useful for animation libraries that need the outgoing
-     * content present in the DOM during an exit transition.
+     * Mounts listbox content to the DOM even when closed, enabling exit animations.
      * @default false
      */
-    forceMount?: boolean;
+    forceMount?: boolean | undefined;
 }
-/**
- * Props for {@link ComboboxContent}, the listbox popup. Extends
- * {@link PopperContentProps} (`side`, `align`, `sideOffset`, `alignOffset`,
- * `avoidCollisions`, `collisionPadding`) for floating-ui positioning relative
- * to the input — note `ComboboxContent` defaults `side` to `'bottom'`,
- * `align` to `'start'`, and `sideOffset` to `4`, instead of the popper base
- * defaults (`'bottom'` / `'center'` / `0`).
- */
+/** Props for the ComboboxContent listbox popup. */
 export interface ComboboxContentProps extends PopperContentProps {
     /**
-     * Keep this listbox mounted even while closed, instead of unmounting it.
+     * Mounts the listbox DOM even when closed, enabling exit animations.
      * @default false
      */
-    forceMount?: boolean;
+    forceMount?: boolean | undefined;
     /**
-     * Fires when Escape is pressed while the listbox is open. Call `event.preventDefault()` to stop it from closing.
-     * @default undefined — no-op if omitted.
+     * Fires when the Escape key is pressed while the listbox is open.
+     * @default undefined
      */
-    onEscapeKeyDown?: (event: KeyboardEvent) => void;
+    onEscapeKeyDown?: ((event: KeyboardEvent) => void) | undefined;
     /**
-     * Fires on pointer-down outside the listbox and the input. Call `event.preventDefault()` to stop the listbox from closing.
-     * @default undefined — no-op if omitted.
+     * Fires on pointer-down outside listbox and input.
+     * @default undefined
      */
-    onPointerDownOutside?: (event: PointerEvent) => void;
+    onPointerDownOutside?: ((event: PointerEvent) => void) | undefined;
     /**
-     * Fires when focus moves to an element outside the listbox and the input. Call `event.preventDefault()` to stop the listbox from closing. Receives a cancelable stand-in carrying the original `focusin` as its `detail`, since `focusin` itself cannot be canceled.
-     * @default undefined — no-op if omitted.
+     * Fires when focus moves outside listbox and input.
+     * @default undefined
      */
-    onFocusOutside?: (event: FocusOutsideEvent) => void;
+    onFocusOutside?: ((event: FocusOutsideEvent) => void) | undefined;
     /**
-     * Fires for either kind of outside interaction — pointer-down or focus — immediately before the specific handler above and with the same event, so one `event.preventDefault()` here vetoes the dismissal whichever way it was triggered.
-     * @default undefined — no-op if omitted.
+     * Fires when any interaction occurs outside the listbox and input.
+     * @default undefined
      */
-    onInteractOutside?: (event: InteractOutsideEvent) => void;
+    onInteractOutside?: ((event: InteractOutsideEvent) => void) | undefined;
 }
-/** Props for a single {@link ComboboxItem} option within `ComboboxContent`. */
+/** Props for single ComboboxItem option. */
 export interface ComboboxItemProps extends PrimitivePropsWithRef<'div'> {
-    /** Unique identifier committed to the combobox root's value when this option is chosen. */
+    /** Value committed when option is chosen. */
     value: string;
     /**
-     * Excludes this option from selection and pointer highlight.
+     * Excludes option from selection and pointer highlight.
      * @default false
      */
-    disabled?: boolean;
+    disabled?: boolean | undefined;
     /**
-     * Text the root's `filter` predicate matches against, and the text a
-     * selection writes back into `ComboboxInput`. Only needed when the item
-     * renders more than its label (an icon, a secondary line).
-     * @default undefined — falls back to the item's rendered text content.
+     * Text for filter matching and selection write-back to input.
+     * @default undefined
      */
-    textValue?: string;
+    textValue?: string | undefined;
 }
-/** Props for {@link ComboboxEmpty}, shown in place of the item list when no `ComboboxItem`s are rendered (because the consumer, or `filter`, removed them all). */
+/** Props for ComboboxEmpty, shown when no items are rendered. */
 export interface ComboboxEmptyProps extends PrimitivePropsWithRef<'div'> {
 }
+/** Props for ComboboxTrigger, optional button that toggles listbox. */
+export interface ComboboxTriggerProps extends PrimitivePropsWithRef<'button'> {
+}
+/** Props for ComboboxClear, optional button that empties selection. */
+export interface ComboboxClearProps extends PrimitivePropsWithRef<'button'> {
+}
+/** Props for ComboboxGroup, named section of related options. */
+export interface ComboboxGroupProps extends PrimitivePropsWithRef<'div'> {
+}
+/** Props for ComboboxGroupLabel, heading for enclosing ComboboxGroup. */
+export interface ComboboxGroupLabelProps extends PrimitivePropsWithRef<'div'> {
+}
+/** @internal What ComboboxGroup publishes to ComboboxGroupLabel inside it. */
+export interface ComboboxGroupContextValue {
+    /** Id group points aria-labelledby at. */
+    labelId: string;
+}