@skdx/react 0.26.0 → 0.28.0

package/dist/autocomplete/AutocompleteList.d.cts

@@ -1,18 +1,9 @@
 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.
+ * `role="listbox"` for {@link Autocomplete} suggestions. Split from content so popup can hold non-options (headings, footers, empty state).
  *
- * 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*.
+ * `role="listbox"` has no implicit name; pass `aria-label` or `aria-labelledby`.
  *
  * @example
  * ```tsx

package/dist/autocomplete/AutocompleteList.d.ts

@@ -1,18 +1,9 @@
 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.
+ * `role="listbox"` for {@link Autocomplete} suggestions. Split from content so popup can hold non-options (headings, footers, empty state).
  *
- * 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*.
+ * `role="listbox"` has no implicit name; pass `aria-label` or `aria-labelledby`.
  *
  * @example
  * ```tsx

package/dist/autocomplete/AutocompletePortal.d.cts

@@ -1,10 +1,8 @@
 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.
+ * `document.body` or `container`, escaping clipping and `overflow: hidden`.
+ * Renders nothing while closed unless `forceMount` is set.
  *
  * @example
  * ```tsx

package/dist/autocomplete/AutocompletePortal.d.ts

@@ -1,10 +1,8 @@
 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.
+ * `document.body` or `container`, escaping clipping and `overflow: hidden`.
+ * Renders nothing while closed unless `forceMount` is set.
  *
  * @example
  * ```tsx

package/dist/autocomplete/AutocompleteTrigger.d.cts

@@ -1,16 +1,8 @@
 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.
+ * Optional toggle button for suggestions ("▾" affordance). Not a Tab stop —
+ * the input is the widget; Arrow Down opens the list. Requires an `aria-label`.
  *
  * @example
  * ```tsx

package/dist/autocomplete/AutocompleteTrigger.d.ts

@@ -1,16 +1,8 @@
 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.
+ * Optional toggle button for suggestions ("▾" affordance). Not a Tab stop —
+ * the input is the widget; Arrow Down opens the list. Requires an `aria-label`.
  *
  * @example
  * ```tsx

package/dist/autocomplete/index.d.cts

@@ -1,9 +1,3 @@
 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';
+export type { AutocompleteFilter, AutocompleteOption, AutocompleteOptionGroup, AutocompleteOptionOrGroup, AutocompleteValueChangeDetail, AutocompleteValueChangeReason, AutocompleteProps, AutocompleteHandle, } from './types.cjs';
+export { defaultOptionsFilter } from './AutocompleteAnatomy.cjs';

package/dist/autocomplete/index.d.ts

@@ -1,9 +1,3 @@
 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';
+export type { AutocompleteFilter, AutocompleteOption, AutocompleteOptionGroup, AutocompleteOptionOrGroup, AutocompleteValueChangeDetail, AutocompleteValueChangeReason, AutocompleteProps, AutocompleteHandle, } from './types.js';
+export { defaultOptionsFilter } from './AutocompleteAnatomy.js';

package/dist/autocomplete/primitives.d.cts

@@ -0,0 +1,32 @@
+/**
+ * Primitives for `Autocomplete` — manual composition escape hatch.
+ *
+ * @example
+ * ```tsx
+ * import { Autocomplete, AutocompleteInput, AutocompletePortal, AutocompleteContent, AutocompleteList, AutocompleteItem, AutocompleteEmpty } from '@skdx/react/primitives/autocomplete';
+ *
+ * <Autocomplete>
+ *   <AutocompleteInput aria-label="City" placeholder="Where to?" />
+ *   <AutocompletePortal>
+ *     <AutocompleteContent>
+ *       <AutocompleteList aria-label="Cities">
+ *         <AutocompleteItem value="oslo">Oslo</AutocompleteItem>
+ *       </AutocompleteList>
+ *       <AutocompleteEmpty>No matches — your text is still accepted</AutocompleteEmpty>
+ *     </AutocompleteContent>
+ *   </AutocompletePortal>
+ * </Autocomplete>
+ * ```
+ */
+export { Autocomplete } from './Autocomplete.cjs';
+export { AutocompleteInput } from './AutocompleteInput.cjs';
+export { AutocompleteTrigger } from './AutocompleteTrigger.cjs';
+export { AutocompleteClear } from './AutocompleteClear.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 { AutocompleteGroup } from './AutocompleteGroup.cjs';
+export { AutocompleteGroupLabel } from './AutocompleteGroupLabel.cjs';
+export type { AutocompleteProps, AutocompleteInputProps, AutocompleteTriggerProps, AutocompleteClearProps, AutocompletePortalProps, AutocompleteContentProps, AutocompleteListProps, AutocompleteItemProps, AutocompleteEmptyProps, AutocompleteGroupProps, AutocompleteGroupLabelProps, } from './types.cjs';

package/dist/autocomplete/primitives.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Primitives for `Autocomplete` — manual composition escape hatch.
+ *
+ * @example
+ * ```tsx
+ * import { Autocomplete, AutocompleteInput, AutocompletePortal, AutocompleteContent, AutocompleteList, AutocompleteItem, AutocompleteEmpty } from '@skdx/react/primitives/autocomplete';
+ *
+ * <Autocomplete>
+ *   <AutocompleteInput aria-label="City" placeholder="Where to?" />
+ *   <AutocompletePortal>
+ *     <AutocompleteContent>
+ *       <AutocompleteList aria-label="Cities">
+ *         <AutocompleteItem value="oslo">Oslo</AutocompleteItem>
+ *       </AutocompleteList>
+ *       <AutocompleteEmpty>No matches — your text is still accepted</AutocompleteEmpty>
+ *     </AutocompleteContent>
+ *   </AutocompletePortal>
+ * </Autocomplete>
+ * ```
+ */
+export { Autocomplete } from './Autocomplete.js';
+export { AutocompleteInput } from './AutocompleteInput.js';
+export { AutocompleteTrigger } from './AutocompleteTrigger.js';
+export { AutocompleteClear } from './AutocompleteClear.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 { AutocompleteGroup } from './AutocompleteGroup.js';
+export { AutocompleteGroupLabel } from './AutocompleteGroupLabel.js';
+export type { AutocompleteProps, AutocompleteInputProps, AutocompleteTriggerProps, AutocompleteClearProps, AutocompletePortalProps, AutocompleteContentProps, AutocompleteListProps, AutocompleteItemProps, AutocompleteEmptyProps, AutocompleteGroupProps, AutocompleteGroupLabelProps, } from './types.js';

package/dist/autocomplete/types.d.cts

@@ -1,178 +1,254 @@
 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';
 import type { OptionEntry } from '../utils/useOptionCollection.cjs';
+/** One suggestion for the {@link AutocompleteProps.options} recipe prop — a flat entry rendered as an `AutocompleteItem`. */
+export interface AutocompleteOption {
+    /** Value committed to the field when this suggestion is chosen. */
+    value: string;
+    /**
+     * Text matched by `filter` and written to the Input on selection.
+     * @default undefined — falls back to `value`.
+     */
+    label?: string;
+    /**
+     * Excludes this suggestion from selection and pointer highlight.
+     * @default false
+     */
+    disabled?: boolean;
+}
+/** A labeled group of {@link AutocompleteOption}s for {@link AutocompleteProps.options} — grouping is data, never a wrapper component. */
+export interface AutocompleteOptionGroup {
+    /** Heading rendered as an `AutocompleteGroupLabel` above this group's suggestions. */
+    label: string;
+    /** The suggestions belonging to this group. */
+    options: AutocompleteOption[];
+}
+/** One entry of {@link AutocompleteProps.options}: a flat suggestion, or a labeled group of them. */
+export type AutocompleteOptionOrGroup = AutocompleteOption | AutocompleteOptionGroup;
+/**
+ * Filters and ranks Items against the draft text: `'manual'` filters nothing,
+ * a predicate filters, and a number ranks (0 excludes, positive keeps and
+ * orders by score descending).
+ */
+export type AutocompleteFilter = 'manual' | ((itemText: string, inputValue: string) => boolean | number);
+/** What drove an {@link Autocomplete} value change. */
+export type AutocompleteValueChangeReason = 'keyboard' | 'pointer' | 'programmatic';
 /**
- * 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.
+ * The payload `onValueChange` receives; `created` is `true` when the commit
+ * was the draft text itself rather than an existing suggestion.
  */
-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 AutocompleteValueChangeDetail {
+    /** The new committed value. */
+    value: string;
+    /** Previous value, or `null` when there was none. */
+    previousValue: string | null;
+    /** What drove the change. */
+    reason: AutocompleteValueChangeReason;
+    /** True when the commit was the draft text rather than a suggestion. */
+    created: boolean;
+}
+/** @internal Shared state distributed from {@link Autocomplete} to its parts via context. */
 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. */
+    /** Excluded from outside-interaction detection so its click can't close the popup it just opened. */
     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. */
+    /** The committed value, which need not match any suggestion. */
     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;
+    /** CSS `order` for score-ranked Items when `filter` ranks; null leaves order untouched. */
+    itemOrder: ReadonlyMap<string, number> | null;
     setActiveId: (id: string | null) => void;
-    moveActive: (direction: 1 | -1) => void;
+    moveActive: (direction: 1 | -1) => string | null;
+    /** Moves the highlight to the first/last Item, only while open (Home/End). */
+    moveActiveToEdge: (edge: 'first' | 'last') => string | null;
     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. */
+    /** Whether an item's 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). */
+    /** Commits a suggestion — writes its text and value, closes, and tags the change with `reason`. */
+    commitItem: (value: string, text: string, reason: AutocompleteValueChangeReason) => void;
+    /** Commits the raw draft (Tab, blur) or restores the last committed text when `allowCustomValue` is off. */
+    commitInputValue: (reason: AutocompleteValueChangeReason) => void;
+    /** Closes and restores the last committed text (Escape). */
     revert: () => void;
+    /** Empties draft, value, and the remembered committed text so blur can't restore what was cleared. */
+    clear: () => void;
     allowCustomValue: boolean;
     openOnFocus: boolean;
     disabled: boolean;
     readOnly: boolean;
     invalid: boolean;
+    /** Whether suggestions are in flight, exposed as `aria-busy`/`data-loading`, suppressing count announcement. */
+    loading: boolean;
+    /** Form field name, stamped on the real `<input>` the Input part renders. */
+    name: string | undefined;
+    /** Id of the `<form>` the field submits into, stamped on the real `<input>` the Input part renders. */
+    form: string | undefined;
 }
-/** Props for the {@link Autocomplete} root. */
-export interface AutocompleteProps {
+/**
+ * Constraint-validation handle for {@link Autocomplete}'s ref; delegates to
+ * the Input's real `<input>`, or reports valid when none is mounted.
+ */
+export type AutocompleteHandle = FormValidityHandle;
+/**
+ * Props for the {@link Autocomplete} root. Standard attributes land on
+ * the derived Input (`role="combobox"`).
+ */
+export interface AutocompleteProps extends PassThroughProps {
     /**
-     * The `AutocompleteInput`/`AutocompletePortal` parts, rendered as children —
-     * `Autocomplete` itself renders no DOM.
+     * The `AutocompleteInput`/`AutocompletePortal` parts — `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.
+     * The committed value, for controlled usage, distinct from the draft `inputValue`.
      * @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.
+     * Initial committed value; also seeds `defaultInputValue`.
      * @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.
+     * Fires with the new committed value on Enter, a suggestion click, Tab, or blur — never on a keystroke.
      * @default undefined — no-op if omitted.
      */
-    onValueChange?: (value: string) => void;
+    onValueChange?: (detail: AutocompleteValueChangeDetail) => 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.
+     * Controlled draft text; with no `filter` set, this prop is the filtering mechanism itself.
      * @default undefined — uncontrolled, tracks its own draft text internally.
      */
     inputValue?: string;
     /**
-     * Initial draft text, for uncontrolled usage.
+     * Initial draft text, falls back to defaultValue if unset.
      * @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.
+     * Fires with the new draft text on every keystroke, commit, or revert.
      * @default undefined — no-op if omitted.
      */
     onInputValueChange?: (inputValue: string) => void;
     /**
-     * Whether the suggestion popup is open, for controlled usage. Pair with `onOpenChange`.
+     * Whether the suggestion popup is open, for controlled usage.
      * @default undefined — uncontrolled, tracks its own open state internally.
      */
     open?: boolean;
     /**
-     * Initial open state, for uncontrolled usage.
+     * Initial open state; popup waits for keystroke or trigger if false.
      * @default false
      */
     defaultOpen?: boolean;
     /**
-     * Fires with the new open state whenever it changes, controlled or not.
+     * Fires with the new open state whenever it changes.
      * @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.
+     * Fires after the open-state animation completes; use for work that must not race the transition.
      * @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.
+     * Lets the committed value be text outside the suggestion list; off, an unmatched draft reverts to the last committed text on blur.
      * @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.
+     * Opens the suggestion popup on focus instead of waiting for the first keystroke.
      * @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.
+     * Keeps the first suggestion highlighted as the filtered list changes while open, so Enter always has a target.
+     * @default false
+     */
+    autoHighlight?: boolean;
+    /**
+     * Wraps arrow navigation around list ends; set `false` to clamp. Home/End always jump to an end regardless.
+     * @default true
+     */
+    loop?: boolean;
+    /**
+     * Filters and ranks Items: `'manual'` filters nothing (default), a predicate filters and ranks by score.
      * @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.
+     * Blocks all interaction; the input is natively disabled and the popup can't 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.
+     * Shows the committed text but blocks changes, while remaining focusable, unlike `disabled`.
      * @default false
      */
     readOnly?: boolean;
     /**
-     * Marks the field as invalid, exposed as `aria-invalid`/`data-invalid` on
-     * `AutocompleteInput`.
+     * Marks the field as invalid, exposed as `aria-invalid`/`data-invalid` on the Input.
      * @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.
+     * Marks suggestions as in flight; suppresses the suggestion-count announcement that would race an in-progress fetch.
+     * @default false
+     */
+    loading?: boolean;
+    /**
+     * Form field name; needed on the root since a shadow-root input can't associate with the ancestor form.
+     * @default undefined — the field submits nothing at all.
+     */
+    name?: string;
+    /**
+     * Id of the `<form>` the field submits into; requires `name` to have any effect.
+     * @default undefined — associates with the nearest ancestor `<form>`.
+     */
+    form?: string;
+    /**
+     * Formats the polite announcement when the rendered suggestion count changes while open; return an empty string to announce nothing.
      * @default defaultGetSuggestionCountLabel — e.g. `"3 suggestions available"`
      */
-    getSuggestionCountLabel?: (count: number) => string;
+    getResultCountLabel?: (count: number) => string;
+    /**
+     * Flat or grouped suggestion data; when present, derives the Input, Portal, and List instead of using children.
+     * @default undefined — nothing is derived; compose the parts yourself via `children`.
+     */
+    options?: AutocompleteOptionOrGroup[];
+    /**
+     * Customises how a derived suggestion renders; only read while `options` derives the anatomy.
+     * @default undefined — renders `option.label ?? option.value`.
+     */
+    renderOption?: (option: AutocompleteOption, state: {
+        selected: boolean;
+    }) => React.ReactNode;
+    /**
+     * Placeholder for the derived Input; only read while `options` derives the anatomy.
+     * @default undefined
+     */
+    placeholder?: string;
+    /**
+     * Accessible name for the derived input and list; only read while `options` derives the anatomy.
+     * @default undefined — falls back to `placeholder`; with neither, no attribute is emitted.
+     */
+    'aria-label'?: 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'> {
@@ -191,12 +267,9 @@ export interface AutocompletePortalProps extends PortalProps {
     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`).
+ * Props for {@link AutocompleteContent}, extending {@link PopperContentProps}
+ * for floating-ui positioning; defaults `side` to `'bottom'`, `align` to
+ * `'start'`, and `sideOffset` to `4`.
  */
 export interface AutocompleteContentProps extends PopperContentProps {
     /**
@@ -205,22 +278,22 @@ export interface AutocompleteContentProps extends PopperContentProps {
      */
     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".
+     * Fires on Escape while open; call `event.preventDefault()` to keep the popup open and the draft text unchanged.
      * @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.
+     * Fires on pointer-down outside the popup and the input; call `event.preventDefault()` to keep the popup open.
      * @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.
+     * Fires when focus leaves the popup and the input, via a cancelable stand-in since native `focusin` cannot itself 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.
+     * Fires before either outside handler above, with the same event, so one `event.preventDefault()` here vetoes dismissal from either trigger.
      * @default undefined — no-op if omitted.
      */
     onInteractOutside?: (event: InteractOutsideEvent) => void;
@@ -238,9 +311,7 @@ export interface AutocompleteItemProps extends PrimitivePropsWithRef<'div'> {
      */
     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).
+     * Text matched by `filter` and written to the Input on commit; needed only when the item renders more than its label.
      * @default undefined — falls back to the item's rendered text content.
      */
     textValue?: string;
@@ -248,3 +319,17 @@ export interface AutocompleteItemProps extends PrimitivePropsWithRef<'div'> {
 /** Props for {@link AutocompleteEmpty}, shown in place of the suggestion list when no items are rendered. */
 export interface AutocompleteEmptyProps extends PrimitivePropsWithRef<'div'> {
 }
+/** Props for {@link AutocompleteClear}, the optional button that empties the draft text and the committed value. */
+export interface AutocompleteClearProps extends PrimitivePropsWithRef<'button'> {
+}
+/** Props for {@link AutocompleteGroup}, a named section of related suggestions inside `AutocompleteList`. */
+export interface AutocompleteGroupProps extends PrimitivePropsWithRef<'div'> {
+}
+/** Props for {@link AutocompleteGroupLabel}, the heading that names its enclosing `AutocompleteGroup`. */
+export interface AutocompleteGroupLabelProps extends PrimitivePropsWithRef<'div'> {
+}
+/** @internal What an {@link AutocompleteGroup} publishes to the `AutocompleteGroupLabel` inside it. */
+export interface AutocompleteGroupContextValue {
+    /** The id the group points `aria-labelledby` at, which its label claims. */
+    labelId: string;
+}