@skdx/react 0.26.0

package/dist/autocomplete/AutocompleteInput.d.cts

@@ -0,0 +1,31 @@
+import * as React from 'react';
+import type { AutocompleteInputProps } from './types.cjs';
+/**
+ * The free-text field an {@link Autocomplete} is built around. Keeps real DOM
+ * focus for the whole interaction and doubles as the popper anchor the popup
+ * positions against. Renders an `<input type="text" role="combobox">` with
+ * `aria-expanded`, `aria-controls` pointing at `AutocompleteList`,
+ * `aria-autocomplete="list"`, `aria-activedescendant` tracking the
+ * virtually-focused suggestion, `autoComplete="off"`, and
+ * `aria-invalid`/`aria-readonly` plus their `data-*` twins from the root.
+ *
+ * Keyboard, in full:
+ *
+ * | Key | Effect |
+ * | --- | --- |
+ * | Arrow Down / Up | opens the popup, or moves the highlight — **DOM focus never moves** |
+ * | Enter | commits the highlighted suggestion; with nothing highlighted, commits the raw text (when `allowCustomValue`) |
+ * | Escape | closes and puts the last committed text back |
+ * | Tab | commits the raw text and moves on — the free-text escape hatch |
+ *
+ * Blur commits the raw text too, which is the behaviour that separates this
+ * family from `Combobox`: typing "foo" and clicking elsewhere keeps "foo".
+ * Give it an accessible name — `aria-label`, `aria-labelledby`, or a `Label`
+ * pointing at it.
+ *
+ * @example
+ * ```tsx
+ * <AutocompleteInput aria-label="City" placeholder="Where to?" />
+ * ```
+ */
+export declare const AutocompleteInput: React.ForwardRefExoticComponent<Omit<AutocompleteInputProps, "ref"> & React.RefAttributes<HTMLInputElement>>;

package/dist/autocomplete/AutocompleteInput.d.ts

@@ -0,0 +1,31 @@
+import * as React from 'react';
+import type { AutocompleteInputProps } from './types.js';
+/**
+ * The free-text field an {@link Autocomplete} is built around. Keeps real DOM
+ * focus for the whole interaction and doubles as the popper anchor the popup
+ * positions against. Renders an `<input type="text" role="combobox">` with
+ * `aria-expanded`, `aria-controls` pointing at `AutocompleteList`,
+ * `aria-autocomplete="list"`, `aria-activedescendant` tracking the
+ * virtually-focused suggestion, `autoComplete="off"`, and
+ * `aria-invalid`/`aria-readonly` plus their `data-*` twins from the root.
+ *
+ * Keyboard, in full:
+ *
+ * | Key | Effect |
+ * | --- | --- |
+ * | Arrow Down / Up | opens the popup, or moves the highlight — **DOM focus never moves** |
+ * | Enter | commits the highlighted suggestion; with nothing highlighted, commits the raw text (when `allowCustomValue`) |
+ * | Escape | closes and puts the last committed text back |
+ * | Tab | commits the raw text and moves on — the free-text escape hatch |
+ *
+ * Blur commits the raw text too, which is the behaviour that separates this
+ * family from `Combobox`: typing "foo" and clicking elsewhere keeps "foo".
+ * Give it an accessible name — `aria-label`, `aria-labelledby`, or a `Label`
+ * pointing at it.
+ *
+ * @example
+ * ```tsx
+ * <AutocompleteInput aria-label="City" placeholder="Where to?" />
+ * ```
+ */
+export declare const AutocompleteInput: React.ForwardRefExoticComponent<Omit<AutocompleteInputProps, "ref"> & React.RefAttributes<HTMLInputElement>>;

package/dist/autocomplete/AutocompleteItem.d.cts

@@ -0,0 +1,28 @@
+import * as React from 'react';
+import type { AutocompleteItemProps } from './types.cjs';
+/**
+ * One suggestion inside {@link AutocompleteList}. Renders a
+ * `<div role="option">` with `data-value`, `aria-selected` (true only for the
+ * suggestion matching the *committed* value), `data-state`
+ * (`"checked" | "unchecked"`), `data-highlighted` for virtual focus — the
+ * attribute the brand layer styles the "keyboard cursor" from, since real DOM
+ * focus stays on the input — and `data-disabled`.
+ *
+ * Registers itself, and its text, with the root: that is how
+ * {@link AutocompleteEmpty} knows the list is empty, how the suggestion-count
+ * announcement gets its number, and how Enter knows what the highlighted
+ * option commits to. Click commits the suggestion, writes its text into the
+ * input, closes the popup and returns focus to the input. Pointer hover moves
+ * the highlight onto it.
+ *
+ * With a `filter` predicate on the root, a rejected item renders **nothing at
+ * all** and unregisters itself — it is absent from the DOM rather than hidden,
+ * because a hidden option is still reachable through `aria-activedescendant`
+ * and would still be counted as a suggestion.
+ *
+ * @example
+ * ```tsx
+ * <AutocompleteItem value="Oslo">Oslo</AutocompleteItem>
+ * ```
+ */
+export declare const AutocompleteItem: React.ForwardRefExoticComponent<Omit<AutocompleteItemProps, "ref"> & React.RefAttributes<HTMLDivElement>>;

package/dist/autocomplete/AutocompleteItem.d.ts

@@ -0,0 +1,28 @@
+import * as React from 'react';
+import type { AutocompleteItemProps } from './types.js';
+/**
+ * One suggestion inside {@link AutocompleteList}. Renders a
+ * `<div role="option">` with `data-value`, `aria-selected` (true only for the
+ * suggestion matching the *committed* value), `data-state`
+ * (`"checked" | "unchecked"`), `data-highlighted` for virtual focus — the
+ * attribute the brand layer styles the "keyboard cursor" from, since real DOM
+ * focus stays on the input — and `data-disabled`.
+ *
+ * Registers itself, and its text, with the root: that is how
+ * {@link AutocompleteEmpty} knows the list is empty, how the suggestion-count
+ * announcement gets its number, and how Enter knows what the highlighted
+ * option commits to. Click commits the suggestion, writes its text into the
+ * input, closes the popup and returns focus to the input. Pointer hover moves
+ * the highlight onto it.
+ *
+ * With a `filter` predicate on the root, a rejected item renders **nothing at
+ * all** and unregisters itself — it is absent from the DOM rather than hidden,
+ * because a hidden option is still reachable through `aria-activedescendant`
+ * and would still be counted as a suggestion.
+ *
+ * @example
+ * ```tsx
+ * <AutocompleteItem value="Oslo">Oslo</AutocompleteItem>
+ * ```
+ */
+export declare const AutocompleteItem: React.ForwardRefExoticComponent<Omit<AutocompleteItemProps, "ref"> & React.RefAttributes<HTMLDivElement>>;

package/dist/autocomplete/AutocompleteList.d.cts

@@ -0,0 +1,24 @@
+import * as React from 'react';
+import type { AutocompleteListProps } from './types.cjs';
+/**
+ * The `role="listbox"` holding an {@link Autocomplete}'s suggestions. Carries
+ * the id the input's `aria-controls` points at, so it must be rendered
+ * whenever the popup is — a dangling `aria-controls` is an axe violation.
+ *
+ * Split out from {@link AutocompleteContent} rather than merged into it so the
+ * popup can also hold things that are *not* options — a heading, a "showing 10
+ * of 400" footer, an {@link AutocompleteEmpty} — without those becoming
+ * children of a listbox, where a screen reader would report them as broken
+ * options.
+ *
+ * `role="listbox"` has no implicit accessible name: pass `aria-label` or
+ * `aria-labelledby` saying what the list is *of*.
+ *
+ * @example
+ * ```tsx
+ * <AutocompleteList aria-label="Cities">
+ *   <AutocompleteItem value="Oslo">Oslo</AutocompleteItem>
+ * </AutocompleteList>
+ * ```
+ */
+export declare const AutocompleteList: React.ForwardRefExoticComponent<Omit<AutocompleteListProps, "ref"> & React.RefAttributes<HTMLDivElement>>;

package/dist/autocomplete/AutocompleteList.d.ts

@@ -0,0 +1,24 @@
+import * as React from 'react';
+import type { AutocompleteListProps } from './types.js';
+/**
+ * The `role="listbox"` holding an {@link Autocomplete}'s suggestions. Carries
+ * the id the input's `aria-controls` points at, so it must be rendered
+ * whenever the popup is — a dangling `aria-controls` is an axe violation.
+ *
+ * Split out from {@link AutocompleteContent} rather than merged into it so the
+ * popup can also hold things that are *not* options — a heading, a "showing 10
+ * of 400" footer, an {@link AutocompleteEmpty} — without those becoming
+ * children of a listbox, where a screen reader would report them as broken
+ * options.
+ *
+ * `role="listbox"` has no implicit accessible name: pass `aria-label` or
+ * `aria-labelledby` saying what the list is *of*.
+ *
+ * @example
+ * ```tsx
+ * <AutocompleteList aria-label="Cities">
+ *   <AutocompleteItem value="Oslo">Oslo</AutocompleteItem>
+ * </AutocompleteList>
+ * ```
+ */
+export declare const AutocompleteList: React.ForwardRefExoticComponent<Omit<AutocompleteListProps, "ref"> & React.RefAttributes<HTMLDivElement>>;

package/dist/autocomplete/AutocompletePortal.d.cts

@@ -0,0 +1,21 @@
+import type { AutocompletePortalProps } from './types.cjs';
+/**
+ * Teleports its children (typically {@link AutocompleteContent}) to
+ * `document.body` — or to `container`, via `PortalProps` — while the
+ * {@link Autocomplete}'s popup is open, so the suggestions escape clipping and
+ * `overflow: hidden` from ancestors. Renders nothing while closed unless
+ * `forceMount` is set.
+ *
+ * @example
+ * ```tsx
+ * <AutocompletePortal>
+ *   <AutocompleteContent>
+ *     <AutocompleteList aria-label="Cities">…</AutocompleteList>
+ *   </AutocompleteContent>
+ * </AutocompletePortal>
+ * ```
+ */
+export declare const AutocompletePortal: {
+    ({ forceMount, children, ...props }: AutocompletePortalProps): import("react").JSX.Element | null;
+    displayName: string;
+};

package/dist/autocomplete/AutocompletePortal.d.ts

@@ -0,0 +1,21 @@
+import type { AutocompletePortalProps } from './types.js';
+/**
+ * Teleports its children (typically {@link AutocompleteContent}) to
+ * `document.body` — or to `container`, via `PortalProps` — while the
+ * {@link Autocomplete}'s popup is open, so the suggestions escape clipping and
+ * `overflow: hidden` from ancestors. Renders nothing while closed unless
+ * `forceMount` is set.
+ *
+ * @example
+ * ```tsx
+ * <AutocompletePortal>
+ *   <AutocompleteContent>
+ *     <AutocompleteList aria-label="Cities">…</AutocompleteList>
+ *   </AutocompleteContent>
+ * </AutocompletePortal>
+ * ```
+ */
+export declare const AutocompletePortal: {
+    ({ forceMount, children, ...props }: AutocompletePortalProps): import("react").JSX.Element | null;
+    displayName: string;
+};

package/dist/autocomplete/AutocompleteTrigger.d.cts

@@ -0,0 +1,20 @@
+import * as React from 'react';
+import type { AutocompleteTriggerProps } from './types.cjs';
+/**
+ * Optional button that toggles an {@link Autocomplete}'s suggestion popup —
+ * the "▾" affordance that tells a pointer user there is a list at all, since
+ * a plain text field looks like a plain text field.
+ *
+ * Renders a `<button type="button">` with `aria-expanded`, `aria-controls`
+ * pointing at `AutocompleteList`, and `data-state="open" | "closed"`. It is
+ * deliberately **not** a Tab stop: the input is the widget, and the keyboard
+ * path to the list is Arrow Down on the input, so a second stop here would
+ * make every autocomplete cost two Tab presses to skip. Give it an
+ * `aria-label` — a chevron glyph is not an accessible name.
+ *
+ * @example
+ * ```tsx
+ * <AutocompleteTrigger aria-label="Show suggestions">▾</AutocompleteTrigger>
+ * ```
+ */
+export declare const AutocompleteTrigger: React.ForwardRefExoticComponent<Omit<AutocompleteTriggerProps, "ref"> & React.RefAttributes<HTMLButtonElement>>;

package/dist/autocomplete/AutocompleteTrigger.d.ts

@@ -0,0 +1,20 @@
+import * as React from 'react';
+import type { AutocompleteTriggerProps } from './types.js';
+/**
+ * Optional button that toggles an {@link Autocomplete}'s suggestion popup —
+ * the "▾" affordance that tells a pointer user there is a list at all, since
+ * a plain text field looks like a plain text field.
+ *
+ * Renders a `<button type="button">` with `aria-expanded`, `aria-controls`
+ * pointing at `AutocompleteList`, and `data-state="open" | "closed"`. It is
+ * deliberately **not** a Tab stop: the input is the widget, and the keyboard
+ * path to the list is Arrow Down on the input, so a second stop here would
+ * make every autocomplete cost two Tab presses to skip. Give it an
+ * `aria-label` — a chevron glyph is not an accessible name.
+ *
+ * @example
+ * ```tsx
+ * <AutocompleteTrigger aria-label="Show suggestions">▾</AutocompleteTrigger>
+ * ```
+ */
+export declare const AutocompleteTrigger: React.ForwardRefExoticComponent<Omit<AutocompleteTriggerProps, "ref"> & React.RefAttributes<HTMLButtonElement>>;

package/dist/autocomplete/index.d.cts

@@ -0,0 +1,9 @@
+export * from './Autocomplete.cjs';
+export { AutocompleteInput } from './AutocompleteInput.cjs';
+export { AutocompleteTrigger } from './AutocompleteTrigger.cjs';
+export { AutocompletePortal } from './AutocompletePortal.cjs';
+export { AutocompleteContent } from './AutocompleteContent.cjs';
+export { AutocompleteList } from './AutocompleteList.cjs';
+export { AutocompleteItem } from './AutocompleteItem.cjs';
+export { AutocompleteEmpty } from './AutocompleteEmpty.cjs';
+export type { AutocompleteFilter, AutocompleteProps, AutocompleteInputProps, AutocompleteTriggerProps, AutocompletePortalProps, AutocompleteContentProps, AutocompleteListProps, AutocompleteItemProps, AutocompleteEmptyProps, } from './types.cjs';

package/dist/autocomplete/index.d.ts

@@ -0,0 +1,9 @@
+export * from './Autocomplete.js';
+export { AutocompleteInput } from './AutocompleteInput.js';
+export { AutocompleteTrigger } from './AutocompleteTrigger.js';
+export { AutocompletePortal } from './AutocompletePortal.js';
+export { AutocompleteContent } from './AutocompleteContent.js';
+export { AutocompleteList } from './AutocompleteList.js';
+export { AutocompleteItem } from './AutocompleteItem.js';
+export { AutocompleteEmpty } from './AutocompleteEmpty.js';
+export type { AutocompleteFilter, AutocompleteProps, AutocompleteInputProps, AutocompleteTriggerProps, AutocompletePortalProps, AutocompleteContentProps, AutocompleteListProps, AutocompleteItemProps, AutocompleteEmptyProps, } from './types.js';

package/dist/autocomplete/types.d.cts

@@ -0,0 +1,250 @@
+import type * as React from 'react';
+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';
+import type { OptionEntry } from '../utils/useOptionCollection.cjs';
+/**
+ * Decides which `AutocompleteItem`s survive the current draft text.
+ * `undefined` filters nothing — the consumer renders only the suggestions that
+ * match, which is what an async or server-side search needs.
+ */
+export type AutocompleteFilter = (itemText: string, inputValue: string) => boolean;
+/** @internal Shared state distributed from {@link Autocomplete} to its parts via context. Not part of the public API. */
+export interface AutocompleteContextValue {
+    inputRef: React.RefObject<HTMLInputElement | null>;
+    /** The optional `AutocompleteTrigger`, if one is mounted. Part of the layer for dismissal purposes: it toggles on *click*, so a pointer-down on it must not be reported as an outside interaction and close the popup the click is about to reopen. */
+    triggerRef: React.RefObject<HTMLButtonElement | null>;
+    contentRef: React.RefObject<HTMLDivElement | null>;
+    /** Id of `AutocompleteList`, referenced by the input's `aria-controls`. */
+    listId: string;
+    /** The committed value — the answer the form takes, which need not be one of the suggestions. */
+    value: string;
+    /** Whether an option value is the committed one, for `aria-selected`. */
+    isSelected: (value: string) => boolean;
+    /** The draft text currently in the input. */
+    inputValue: string;
+    onInputValueChange: (value: string) => void;
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    activeId: string | null;
+    setActiveId: (id: string | null) => void;
+    moveActive: (direction: 1 | -1) => void;
+    openWithHighlight: (edge: 'first' | 'last') => void;
+    itemCount: number;
+    registerItem: (id: string, entry: OptionEntry) => void;
+    unregisterItem: (id: string) => void;
+    getItem: (id: string) => OptionEntry | undefined;
+    /** Whether an item with this text survives the current `filter` and draft text. */
+    matchesFilter: (itemText: string) => boolean;
+    /** Commits a suggestion: writes its text into the input, its value into `value`, and closes. */
+    commitItem: (value: string, text: string) => void;
+    /** Commits the raw draft text as the value (Tab, blur) — or restores the last committed text when `allowCustomValue` is off. */
+    commitInputValue: () => void;
+    /** Closes and puts the last committed text back in the input (Escape). */
+    revert: () => void;
+    allowCustomValue: boolean;
+    openOnFocus: boolean;
+    disabled: boolean;
+    readOnly: boolean;
+    invalid: boolean;
+}
+/** Props for the {@link Autocomplete} root. */
+export interface AutocompleteProps {
+    /**
+     * The `AutocompleteInput`/`AutocompletePortal` parts, rendered as children —
+     * `Autocomplete` itself renders no DOM.
+     * @default undefined — renders nothing without children.
+     */
+    children?: React.ReactNode;
+    /**
+     * The committed value, for controlled usage. Pair with `onValueChange`. This
+     * is a *separate* state from `inputValue`: the draft text moves on every
+     * keystroke, the value only when something is committed.
+     * @default undefined — uncontrolled, tracks its own committed value internally.
+     */
+    value?: string;
+    /**
+     * Initial committed value, for uncontrolled usage. Also seeds
+     * `defaultInputValue`, so an autocomplete restored from saved state shows
+     * the text it committed rather than an empty field.
+     * @default '' — nothing committed, so blurring an untouched field commits nothing.
+     */
+    defaultValue?: string;
+    /**
+     * Fires with the new committed value — on Enter, on a suggestion click, on
+     * Tab, and on blur. Never on a keystroke.
+     * @default undefined — no-op if omitted.
+     */
+    onValueChange?: (value: string) => void;
+    /**
+     * The draft text in the input, for controlled usage. Pair with
+     * `onInputValueChange` — typically used to drive filtering of the suggestion
+     * list, since filtering is the consumer's job unless `filter` is supplied.
+     * @default undefined — uncontrolled, tracks its own draft text internally.
+     */
+    inputValue?: string;
+    /**
+     * Initial draft text, for uncontrolled usage.
+     * @default defaultValue — the field opens showing whatever value it starts committed to.
+     */
+    defaultInputValue?: string;
+    /**
+     * Fires with the new draft text on every keystroke, and whenever a commit or
+     * a revert rewrites the field.
+     * @default undefined — no-op if omitted.
+     */
+    onInputValueChange?: (inputValue: string) => void;
+    /**
+     * Whether the suggestion popup is open, for controlled usage. Pair with `onOpenChange`.
+     * @default undefined — uncontrolled, tracks its own open state internally.
+     */
+    open?: boolean;
+    /**
+     * Initial open state, for uncontrolled usage.
+     * @default false
+     */
+    defaultOpen?: boolean;
+    /**
+     * Fires with the new open state whenever it changes, controlled or not.
+     * @default undefined — no-op if omitted.
+     */
+    onOpenChange?: (open: boolean) => void;
+    /**
+     * Fires with the new open state once the change has finished on screen —
+     * after `AutocompleteContent`'s enter or exit animation ends, or as soon as it
+     * has settled when the popup declares no animation. Use it for work that must
+     * not race the transition; use `onOpenChange` for work that must not wait for it.
+     * @default undefined — no-op if omitted.
+     */
+    onOpenChangeComplete?: (open: boolean) => void;
+    /**
+     * Lets the committed value be text that is not in the suggestion list — Tab,
+     * Enter with nothing highlighted, and blur all commit the raw draft. This is
+     * the whole point of the family: an autocomplete *suggests*, it does not
+     * constrain. Turn it off and an unmatched draft is discarded on blur and the
+     * last committed text is put back, which makes this a
+     * `Combobox` with extra steps — reach for that instead.
+     * @default true
+     */
+    allowCustomValue?: boolean;
+    /**
+     * Opens the suggestion popup as soon as the input takes focus, instead of
+     * waiting for the first keystroke. Off by default: an empty field usually
+     * means an unfiltered list, and dropping the entire dataset over the page on
+     * focus is rarely what the user asked for.
+     * @default false
+     */
+    openOnFocus?: boolean;
+    /**
+     * Predicate deciding which `AutocompleteItem`s survive the current draft
+     * text. Every item is measured (its `textValue`, or its rendered text) and
+     * the rejected ones render nothing at all, so they leave the suggestion
+     * count, the highlight order, and `AutocompleteEmpty` exactly as if the
+     * consumer had removed them.
+     * @default undefined — nothing is filtered; the consumer renders only the matching items, which is what an async or server-side search needs.
+     */
+    filter?: AutocompleteFilter;
+    /**
+     * Blocks all interaction: the input is natively `disabled`, so it is not
+     * focusable and the popup can never open.
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Shows the committed text but blocks any change to it — the input is
+     * natively `readOnly` and still focusable (unlike `disabled`), and no
+     * keystroke, Tab or blur commits anything.
+     * @default false
+     */
+    readOnly?: boolean;
+    /**
+     * Marks the field as invalid, exposed as `aria-invalid`/`data-invalid` on
+     * `AutocompleteInput`.
+     * @default false
+     */
+    invalid?: boolean;
+    /**
+     * Formats the message announced (through the shared `LiveAnnouncer`) each
+     * time the number of rendered suggestions changes while the popup is open.
+     * Filtering changes nothing `aria-expanded` or `aria-activedescendant`
+     * reports, so this count is the only signal a screen-reader user gets that
+     * typing narrowed anything. Return an empty string to announce nothing.
+     * @default defaultGetSuggestionCountLabel — e.g. `"3 suggestions available"`
+     */
+    getSuggestionCountLabel?: (count: number) => string;
+}
+/** Props for {@link AutocompleteInput}, the free-text field that owns real DOM focus for the whole interaction. */
+export interface AutocompleteInputProps extends Omit<PrimitivePropsWithRef<'input'>, 'value' | 'defaultValue'> {
+}
+/** Props for {@link AutocompleteTrigger}, the optional button that toggles the suggestion popup. */
+export interface AutocompleteTriggerProps extends PrimitivePropsWithRef<'button'> {
+}
+/** Props for {@link AutocompletePortal}, which teleports its content to `document.body` while the popup is open. */
+export interface AutocompletePortalProps extends PortalProps {
+    /**
+     * Render (and mount `AutocompleteContent`) even while closed, instead of
+     * unmounting. Useful for animation libraries that need the outgoing content
+     * present in the DOM during an exit transition.
+     * @default false
+     */
+    forceMount?: boolean;
+}
+/**
+ * Props for {@link AutocompleteContent}, the popup shell. Extends
+ * {@link PopperContentProps} (`side`, `align`, `sideOffset`, `alignOffset`,
+ * `avoidCollisions`, `collisionPadding`) for floating-ui positioning relative
+ * to the input — note `AutocompleteContent` defaults `side` to `'bottom'`,
+ * `align` to `'start'` and `sideOffset` to `4`, instead of the popper base
+ * defaults (`'bottom'` / `'center'` / `0`).
+ */
+export interface AutocompleteContentProps extends PopperContentProps {
+    /**
+     * Keep this popup mounted even while closed, instead of unmounting it.
+     * @default false
+     */
+    forceMount?: boolean;
+    /**
+     * Fires when Escape is pressed while the popup is open. Call `event.preventDefault()` to stop it from closing — which also leaves the draft text alone, since Escape's default here is "revert to the last committed value and close".
+     * @default undefined — no-op if omitted.
+     */
+    onEscapeKeyDown?: (event: KeyboardEvent) => void;
+    /**
+     * Fires on pointer-down outside the popup and the input. Call `event.preventDefault()` to stop the popup from closing.
+     * @default undefined — no-op if omitted.
+     */
+    onPointerDownOutside?: (event: PointerEvent) => void;
+    /**
+     * Fires when focus moves to an element outside the popup and the input. Call `event.preventDefault()` to stop the popup 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.
+     */
+    onFocusOutside?: (event: FocusOutsideEvent) => void;
+    /**
+     * 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.
+     */
+    onInteractOutside?: (event: InteractOutsideEvent) => void;
+}
+/** Props for {@link AutocompleteList}, the `role="listbox"` the suggestions live in. */
+export interface AutocompleteListProps extends PrimitivePropsWithRef<'div'> {
+}
+/** Props for a single {@link AutocompleteItem} suggestion within `AutocompleteList`. */
+export interface AutocompleteItemProps extends PrimitivePropsWithRef<'div'> {
+    /** Value committed to the autocomplete root when this suggestion is chosen. */
+    value: string;
+    /**
+     * Excludes this suggestion from selection and pointer highlight.
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Text the root's `filter` predicate matches against, and the text a
+     * commit writes back into `AutocompleteInput`. 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.
+     */
+    textValue?: string;
+}
+/** Props for {@link AutocompleteEmpty}, shown in place of the suggestion list when no items are rendered. */
+export interface AutocompleteEmptyProps extends PrimitivePropsWithRef<'div'> {
+}