@codapet/design-system 0.8.5 → 0.8.6

package/AGENTS.md

@@ -15,6 +15,45 @@ This is a **shadcn/ui-style** library (Radix primitives + cva variants + Tailwin
 - ESM-only. If a consumer uses Jest, add the package to `transformIgnorePatterns` (or use Vitest, which handles it).
 - Single entry: `from '@codapet/design-system'`. There are **no subpath component imports** — only `'@codapet/design-system'` and `'@codapet/design-system/styles'` exist.
 
+## Finding exact props: read the shipped types
+
+`dist/index.d.mts` is the authoritative API reference, and it ships inside the
+package with every JSDoc comment intact. When you need a component's exact
+props, defaults, or union values, **read it instead of guessing**:
+
+```
+node_modules/@codapet/design-system/dist/index.d.mts
+```
+
+Grep it for the type you want — `interface SearchInputProps`,
+`interface AsyncAutocompleteProps` — and you get every prop with its
+documentation. It is regenerated from source on every release, so it cannot go
+stale.
+
+**One trap when reading the types.** Many components take props that never
+appear in their interface body, because they come from a cva:
+
+```ts
+interface BadgeNumberProps
+  extends React.ComponentProps<'span'>,
+    VariantProps<typeof badgeNumberVariants> { value: number }
+```
+
+Grepping `interface BadgeNumberProps` suggests `value` is the only prop, but
+`state` (`'active' | 'disabled' | 'resting'`, default `'active'`) is real — it
+lives in `badgeNumberVariants`. Whenever an interface extends
+`VariantProps<typeof xVariants>`, read the `declare const xVariants` entry just
+above it for the remaining props. `variant`, `size`, `state` and `colorScheme`
+almost always arrive this way.
+
+Division of labour: **this guide covers what is surprising** (defaults that
+differ from shadcn, which component to reach for, gotchas). **The `.d.mts`
+covers what is exhaustive.** Read this file first to pick the right component,
+then the types to get its props right.
+
+The docs app in this repo also has a live example page per component, and the
+richer ones (`SmartDialog*`, `AsyncAutocomplete`) carry a full props table.
+
 ## Required setup in a consumer (Tailwind v4)
 
 In the app's global CSS:
@@ -107,6 +146,7 @@ These don't exist in shadcn — reach for them instead of building your own:
 | `SearchableSelect` | Combobox-style select with search; supports `mode="single"` or `"multiple"` + `maxCount` for tag overflow. |
 | `MultiSelectFreeText` | Tag input where users can type free text **and** pick from suggestions. |
 | `SearchInput` | Search field with `variant="icon"` or `"button"`, suggestions dropdown, and clear button. Don't compose this from `Input` + a Search icon. |
+| `AsyncAutocomplete` | Type-ahead over an **async** source — a Places lookup, a REST search. You own fetching and debouncing; it renders `options` verbatim, never filtering. Full ARIA combobox with keyboard nav, portaled panel, and it dismisses the moment the user scrolls. `mobileVariant="sheet"` makes it a full-screen takeover under 768px. Restyle any part through the `classNames` slot object. For a **static** list reach for `SearchableSelect` instead. |
 | `DateInput` / `DateRangeInput` | Text input + Calendar popover. Controlled via `date`/`setDate` (or `dateRange`/`setDateRange`). Configurable `dateFormat` (15 options including `'MMM D, YYYY'`, `'DD/MM/YYYY'`, etc.). Prefer over a bare `Calendar`. |
 | `TimeInput` | Time picker with `timeFormat` = `'12h' \| '24h' \| 'h:mm a' \| 'h:mm A'`. Value is `{ hours, minutes }`, not a `Date`. |
 | `AutoResizeTextarea` | Textarea that grows with content; `maxHeight` enables scroll. Handles RHF `setValue`/`reset` correctly. |
@@ -115,6 +155,138 @@ These don't exist in shadcn — reach for them instead of building your own:
 | `Typography`: `DisplayHeading`, `HeadingXL` … `HeadingXXS` (+ `*Medium` variants), `Body` | Use these instead of raw `<h1>`/`<p>` to inherit the right tokens (`font-serif italic` for display, `text-vibrant-text-heading` for headings, `text-vibrant-text-body` for body). Sizes are responsive (md: breakpoint baked in). |
 | `ThemeToggle` | Drop-in light/dark toggle. |
 
+## Choosing the right component
+
+The most common agent mistake here is not a wrong prop, it is reaching for the
+wrong component. Work from the task:
+
+| The task | Use | Not |
+|---|---|---|
+| Type-ahead whose results come from an API | `AsyncAutocomplete` | `SearchInput`, whose suggestions are a static prop and whose dropdown pushes page content down |
+| Pick one/many from a **static** list, with search | `SearchableSelect` | `AsyncAutocomplete`, which never filters — it renders `options` verbatim |
+| Pick one from a short static list, no search | `DropdownSelect` | `Select` (heavier; still fine when you need native-select semantics) |
+| Free-text entry **plus** suggestions, many values | `MultiSelectFreeText` | a hand-rolled `Input` + chips |
+| A search field with a visible Search button | `SearchInput` | `Input` + a magnifier icon |
+| Command palette / fuzzy launcher | `Command*` | `SearchableSelect` |
+| Modal that should bottom-sheet on phones | `SmartDialog*` | `Dialog*` |
+| Modal that is a dialog at every size | `Dialog*` | `SmartDialog*` |
+| Panel sliding from a screen edge | `Sheet*` | `Drawer*` |
+| Bottom sheet with drag-to-dismiss at every size | `Drawer*` | `Sheet*` |
+| Destructive confirm | `AlertDialog*` | `Dialog*` |
+| Inline, page-level notice | `AlertBanner` | `Alert` (the shadcn-equivalent, quieter) |
+| Transient notification | `toast` + `Toaster` | `AlertBanner` |
+| Date, or date range | `DateInput` / `DateRangeInput` | a bare `Calendar` |
+| Time of day | `TimeInput` (value is `{ hours, minutes }`, not a `Date`) | `Input type="time"` |
+| Any heading or body copy | `DisplayHeading` / `Heading*` / `Body` | raw `<h1>`/`<p>`, which miss the tokens |
+| Textarea that grows with content | `AutoResizeTextarea` | `Textarea` + manual resize |
+| Selectable card with a radio/checkbox | `OptionCard` | `Card` + a `Checkbox` |
+| Step or count pill | `BadgeNumber` | `Badge` |
+| Clickable filter chip | `BadgeActionable` | `Button variant="outline"` |
+| Read-only metadata pill | `BadgeInformative` | `Badge` |
+
+## Dialogs, drawers and sheets — read this before writing one
+
+Four families, and they are the most common source of broken code here. Each
+has its own React context, so **parts are never interchangeable**: a
+`DialogContent` inside a `SmartDialog` throws on mobile, because the root
+rendered a vaul `Drawer` and the child asked for a Radix Dialog context that
+does not exist. Pick a family and use only its parts.
+
+| Family | Parts | Renders as |
+|---|---|---|
+| `Dialog*` | Root, Trigger, Content, Header, Footer, Title, Description, Close, Overlay, Portal | Centred modal at every size |
+| `SmartDialog*` | Root, Trigger, Content, Header, Footer, Title, Description, Close — **8 parts, no Overlay/Portal/Body** | `Dialog` above 600px, `Drawer` at/below |
+| `Drawer*` | Root, Trigger, Content, Header, Footer, Title, Description, Close, Overlay, Portal | vaul sheet, draggable, `max-h-[80vh]` |
+| `Sheet*` | Root, Trigger, Content, Header, Footer, Title, Description, Close | Edge panel, `w-3/4 sm:max-w-sm` |
+
+### Never wrap `*Content` in a Portal or Overlay
+
+`DialogContent`, `DrawerContent` and `SheetContent` **already render their own
+Portal and Overlay internally.** Stock shadcn composes them by hand, so a copied
+example produces two stacked backdrops (visibly double-dimmed) and two portals:
+
+```tsx
+// ❌ copied from shadcn — double overlay
+<Dialog>
+  <DialogPortal>
+    <DialogOverlay />
+    <DialogContent>…</DialogContent>
+  </DialogPortal>
+</Dialog>
+
+// ✅ here
+<Dialog>
+  <DialogTrigger asChild><Button>Open</Button></DialogTrigger>
+  <DialogContent>
+    <DialogHeader>
+      <DialogTitle>Confirm</DialogTitle>
+      <DialogDescription>This cannot be undone.</DialogDescription>
+    </DialogHeader>
+    <DialogFooter>
+      <DialogClose asChild><Button variant="ghost">Cancel</Button></DialogClose>
+      <Button variant="destructive">Delete</Button>
+    </DialogFooter>
+  </DialogContent>
+</Dialog>
+```
+
+`DialogPortal` / `DialogOverlay` / `DrawerPortal` / `DrawerOverlay` are exported
+only because shadcn exports them. **You almost never need them.** To restyle the
+backdrop, pass `overlayClassName` to `DialogContent` / `DrawerContent` /
+`SmartDialogContent` — `SheetContent` and `AlertDialogContent` do not accept it.
+
+### `withCloseButton` is the drag handle, not the close button
+
+On `DrawerContent` and `SmartDialogContent`:
+
+- `showCloseButton` (default `true`) — the round **X** in the top-right.
+- `withCloseButton` (default `true`) — the small grey **drag pill**, and only for
+  `direction="bottom"`. The name is misleading; it has nothing to do with the X.
+
+So `withCloseButton={false}` still leaves the X. To remove the X, pass
+`showCloseButton={false}`. `SmartDialogContent` forwards `showCloseButton` to
+both variants, so the X stays consistent across the breakpoint.
+
+### `direction` goes on both the root and the content
+
+vaul needs it on the root for gesture handling; the content needs it for its own
+edge/rounding classes. Setting only one gives a drawer that animates from one
+edge and is styled for another:
+
+```tsx
+<Drawer direction="right">
+  <DrawerContent direction="right">…</DrawerContent>
+</Drawer>
+```
+
+`Sheet` uses `side` instead (`'top' | 'right' | 'bottom' | 'left'`, default
+`'right'`), on `SheetContent` only.
+
+### `SmartDialog` specifics
+
+- The breakpoint is **600px**, not the 768px `useIsMobile` uses. That is
+  deliberate — see the note further down.
+- **The first client render is always the Dialog variant**, then it settles to
+  the real one. The server has no viewport, so `useMediaQuery` returns the server
+  snapshot during hydration; rendering the true value there would be a hydration
+  mismatch. Do not measure the DOM or branch on the variant during first paint.
+- Props are a union of Dialog's and Drawer's, so drawer-only props
+  (`direction`, `dismissible`) are accepted and silently ignored above 600px.
+- `Drawer` hardcodes `repositionInputs={false}`, which `SmartDialog` inherits —
+  relevant if you put a focused input inside on iOS.
+
+### Always give it a title
+
+All four families are Radix-Dialog-based and warn without a `Title`. If the
+design has no visible heading, keep the element and hide it:
+
+```tsx
+<DialogTitle className="sr-only">Edit profile</DialogTitle>
+```
+
+Pass `aria-describedby={undefined}` on the content when there is genuinely no
+`Description`, rather than leaving the warning in the console.
+
 ## Color tokens (don't reach for raw Tailwind colors)
 
 The brand palette lives in CSS variables exposed as Tailwind colors. Use these, not `bg-blue-600`, `text-gray-500`, `border-red-300`, etc. — raw colors won't dark-mode correctly.
@@ -141,12 +313,65 @@ Source of truth: `src/styles.css` in this package. If a token is missing, propos
 - `useTheme()` — re-exported from `next-themes`.
 - `buttonVariants`, `badgeVariants`, etc. — exported `cva` instances. Use them when you need the same look on a non-button element (e.g. an `<a>` styled like a button) instead of reimplementing the styles.
 
+## Complete export index
+
+Everything below is imported from the single entry `'@codapet/design-system'`.
+A `Foo*` glob means the whole compound family — `Dialog*` is `Dialog`,
+`DialogTrigger`, `DialogContent`, `DialogHeader`, `DialogFooter`, `DialogTitle`,
+`DialogDescription`, `DialogClose`, `DialogOverlay`, `DialogPortal`. Families
+follow the standard shadcn part names; when unsure, grep the `.d.mts`.
+
+**If a name is not in this list, it does not exist — do not import it.**
+
+| Area | Exports |
+|---|---|
+| Layout & structure | `AspectRatio`, `Card*`, `Separator`, `ScrollArea`, `ScrollBar`, `Resizable*`, `Sidebar*`, `useSidebar`, `Table*`, `Skeleton` |
+| Typography | `DisplayHeading`, `HeadingXL`, `HeadingL`, `HeadingM`, `HeadingS`, `HeadingXS`, `HeadingXXS` (each with a `*Medium` twin, e.g. `HeadingLMedium`), `Body` |
+| Buttons & badges | `Button`, `Badge`, `BadgeActionable`, `BadgeInformative`, `BadgeInformativeGroup`, `BadgeInformativeItem`, `BadgeNumber`, `Toggle`, `ToggleGroup`, `ToggleGroupItem` |
+| Form fields | `Input`, `Textarea`, `AutoResizeTextarea`, `Label`, `Checkbox`, `RadioGroup`, `RadioGroupItem`, `Switch`, `Slider`, `InputOTP*`, `Form*`, `useFormField`, `OptionCard` |
+| Selection & search | `AsyncAutocomplete*`, `SearchableSelect*`, `SearchInput`, `MultiSelectFreeText`, `DropdownSelect*`, `Select*`, `Command*` |
+| Date & time | `Calendar`, `CalendarDayButton`, `DateInput`, `DateRangeInput`, `TimeInput` |
+| Overlays & menus | `Dialog*`, `AlertDialog*`, `Drawer*`, `Sheet*`, `SmartDialog*`, `Popover*`, `HoverCard*`, `Tooltip*`, `RichTooltip*`, `DropdownMenu*`, `ContextMenu*`, `Menubar*` |
+| Feedback | `Alert`, `AlertTitle`, `AlertDescription`, `AlertBanner`, `Toaster`, `toast`, `Progress`, `ProgressBar` |
+| Navigation | `Tabs*`, `Breadcrumb*`, `Pagination*`, `NavigationMenu*` |
+| Content & data | `Accordion*`, `Collapsible*`, `Avatar*`, `Carousel*`, `Chart*` |
+| Theming & utilities | `ThemeProvider*`, `ThemeToggle`, `cn`, `useIsMobile` |
+
+**cva style objects** — use these to give a non-button element a button's look
+rather than reimplementing the classes: `buttonVariants`, `badgeVariants`,
+`badgeActionableVariants`, `badgeInformativeVariants`, `badgeNumberVariants`,
+`alertBannerVariants`, `inputVariants`, `labelTextVariants`, `optionCardVariants`,
+`progressBarVariants`, `tabsTriggerVariants`, `toggleVariants`,
+`bodyTextVariants`, `displayTextVariants`, `navigationMenuTriggerStyle`.
+
+**Exported types** — import with `import type`: `InputProps`, `TextareaProps`,
+`SearchInputProps`, `SearchSuggestion`, `AlertBannerProps`,
+`BadgeActionableProps`, `BadgeInformativeProps`, `BadgeNumberProps`,
+`OptionCardProps`, `ProgressBarProps`, `TabsTriggerProps`, `TooltipContentProps`,
+`RichTooltipContentProps`, `RichTooltipVariant`, `DateFormat`, `DateInputProps`,
+`DateRangeInputProps`, `DateRange` (re-exported from `react-day-picker`:
+`{ from?: Date; to?: Date }` — the value type for `DateRangeInput`),
+`TimeFormat`, `TimeValue`, `TimeInputProps`,
+`SearchableSelectOption`, `SearchableSelectProps`, `MultiSelectFreeTextOption`,
+`MultiSelectFreeTextProps`, `DropdownSelectProps`, `DropdownSelectLabelProps`,
+`DropdownSelectTriggerProps`, `DropdownSelectContentProps`,
+`DropdownSelectOptionProps`, `AsyncAutocompleteProps`,
+`AsyncAutocompleteOption`, `AsyncAutocompleteOptionState`,
+`AsyncAutocompleteClassNames`, `AsyncAutocompleteInputProps`, `CarouselApi`,
+`ChartConfig`, `ThemeProviderProps`.
+
+There are no other public exports, and no subpath imports: only
+`'@codapet/design-system'` and `'@codapet/design-system/styles'` resolve.
+
 ## Common gotchas
 
 - **Unstyled components** → missing `@source` glob for `node_modules/@codapet/design-system/dist/**` in the consumer's CSS.
 - **Wrong default Button look** → you forgot `variant="primary"`/`size="md"` are not the same as shadcn's defaults; passing nothing gives you `primary` + `lg`.
 - **Toast looks generic** → you imported `toast` from `'sonner'` instead of from `@codapet/design-system`.
 - **Modal doesn't bottom-sheet on mobile** → you used `Dialog` instead of `SmartDialog`.
+- **`AsyncAutocomplete` fires a request per keystroke** → it deliberately does not debounce. Debounce in your fetch layer (`usePlacesService({ debounce: 300 })`, your own hook) so cancellation and out-of-order responses stay with the code that owns them.
+- **`AsyncAutocomplete` shows results that don't match what you typed** → it renders `options` verbatim by design, because the server already filtered. If your list is static, use `SearchableSelect`/`DropdownSelect`, which filter client-side.
+- **Styling `AsyncAutocomplete`** → it does **not** follow the flat `*ClassName` convention that `DateInput`/`TimeInput` use, because it has twenty-odd stylable slots. `className` is the root wrapper; everything else lives in one `classNames` object: `field`, `input`, `leftIcon`, `clearButton`, `content`, `listbox`, `option`, `optionHighlighted`, `optionDisabled`, `optionIcon`, `optionLabel`, `optionDescription`, `loading`, `loadingSpinner`, `empty`, plus `sheetOverlay`, `sheetContent`, `sheetHeader`, `sheetCloseButton`, `sheetInput`, `sheetList`. All merge through `cn`, so `{ content: 'max-h-[420px]' }` replaces the built-in max-height rather than stacking with it. A single row can also carry its own `className` via the option object, and rows expose `data-highlighted` / `data-disabled` for parent-level selectors. Use `renderOption` to change row *structure*, `classNames` to change its *look*.
 - **Headings look wrong** → you used a raw `<h1>` instead of `HeadingXL` / `DisplayHeading`. The serif-italic display style only comes from `DisplayHeading`.
 - **Dark mode broken** → you used raw Tailwind colors (`bg-gray-100`, `text-zinc-700`) instead of brand tokens; or you forgot to wrap in `ThemeProvider`.
 - **"Module not found" in tests** → Jest can't parse ESM; add `'@codapet/design-system'` to `transformIgnorePatterns` or switch the test file to Vitest.

package/dist/index.d.mts

@@ -87,6 +87,201 @@ declare function AlertDialogCancel({ className, ...props }: React$1.ComponentPro
 
 declare function AspectRatio({ ...props }: React.ComponentProps<typeof AspectRatioPrimitive.Root>): react_jsx_runtime.JSX.Element;
 
+interface AsyncAutocompleteOption<TData = unknown> {
+    /** Stable unique key. Doubles as the DOM id suffix — a `place_id`, slug, … */
+    id: string;
+    /** Primary line. */
+    label: string;
+    /** Secondary line, rendered dimmed after the label. */
+    description?: string;
+    /** Leading icon/avatar for this row. Falls back to `optionIcon`. */
+    icon?: React$1.ReactNode;
+    /** Rendered dimmed, and skipped by keyboard navigation and clicks. */
+    disabled?: boolean;
+    /**
+     * Merged onto this row only, after `classNames.option` — so a single row can
+     * be styled differently from its siblings (a "use my location" entry, a
+     * promoted result).
+     */
+    className?: string;
+    /**
+     * Arbitrary consumer payload handed straight back by `onSelect` — a raw
+     * Google `AutocompletePrediction`, a REST row, a whole domain object. The
+     * design system never inspects it.
+     */
+    data?: TData;
+}
+/** Row state passed to `renderOption`. */
+interface AsyncAutocompleteOptionState {
+    /** Position in `options`. Matches the `-suggestion-N` DOM id. */
+    index: number;
+    /** True when keyboard- or hover-highlighted (`aria-activedescendant`). */
+    highlighted: boolean;
+    /** Current input text, for match highlighting. */
+    query: string;
+}
+/**
+ * Long-tail `<input>` props forwarded to the text field. The props
+ * `AsyncAutocomplete` owns are excluded; `onFocus`, `onKeyDown` and
+ * `onPointerDown` are chained after the component's own handlers rather than
+ * replacing them.
+ */
+type AsyncAutocompleteInputProps = Omit<React$1.ComponentPropsWithoutRef<'input'>, 'value' | 'defaultValue' | 'onChange' | 'size' | 'disabled' | 'placeholder' | 'id' | 'type' | 'role' | 'readOnly'>;
+/**
+ * Per-slot class overrides. Every entry is merged with `cn`, so
+ * tailwind-merge lets a caller class replace a conflicting default rather than
+ * fight it — `{ content: 'max-h-[420px]' }` really does replace the built-in
+ * max-height.
+ *
+ * `DateInput`/`TimeInput` expose two or three flat `*ClassName` props;
+ * `AsyncAutocomplete` has twenty-odd stylable slots, so they live in one
+ * object here instead of twenty top-level props burying `onSearch`/`onSelect`.
+ */
+interface AsyncAutocompleteClassNames {
+    /** Wrapper around the input — also the popover's anchor. */
+    field?: string;
+    /** The text input itself. */
+    input?: string;
+    /** Left icon wrapper inside the input. */
+    leftIcon?: string;
+    /** The clear ("X") button. */
+    clearButton?: string;
+    /** The popover surface holding the results. */
+    content?: string;
+    /** The `role="listbox"` container, in both popover and sheet. */
+    listbox?: string;
+    /** Every option row. */
+    option?: string;
+    /** Added to the highlighted row, on top of `option`. */
+    optionHighlighted?: string;
+    /** Added to a disabled row, on top of `option`. */
+    optionDisabled?: string;
+    /** Icon wrapper inside a default row. Not applied when `renderOption` is used. */
+    optionIcon?: string;
+    /** Primary text span in a default row. Not applied when `renderOption` is used. */
+    optionLabel?: string;
+    /** Secondary text span in a default row. Not applied when `renderOption` is used. */
+    optionDescription?: string;
+    /** The loading row. */
+    loading?: string;
+    /** The spinner inside the loading row. */
+    loadingSpinner?: string;
+    /** The empty ("no results") row. Not applied when `emptyState` is used. */
+    empty?: string;
+    /** The sheet's backdrop. */
+    sheetOverlay?: string;
+    /** The sheet panel. */
+    sheetContent?: string;
+    /** The sheet's pinned header row. */
+    sheetHeader?: string;
+    /** The sheet's close/back button. */
+    sheetCloseButton?: string;
+    /** The sheet's own text input. */
+    sheetInput?: string;
+    /** The sheet's scrollable results area. */
+    sheetList?: string;
+}
+interface AsyncAutocompleteProps<TData = unknown> {
+    /**
+     * Current result set, rendered **verbatim**. `AsyncAutocomplete` never
+     * filters, sorts or caches — map your API response to options yourself.
+     */
+    options: AsyncAutocompleteOption<TData>[];
+    /**
+     * Fired on every keystroke with the raw input text, plus `''` when the
+     * clear button is pressed. **Not debounced** — debounce in your fetch layer
+     * (`usePlacesService({ debounce: 300 })`, a `setTimeout` hook, …) so
+     * request cancellation and out-of-order responses stay with the code that
+     * owns them.
+     */
+    onSearch: (query: string) => void;
+    /**
+     * Fired when an option is committed by click, tap or Enter. Closes the
+     * panel. Deliberately does **not** write the label into the input: call
+     * sites resolve their own display text (a `getDetails` lookup, a
+     * `formatted_address`) or clear the field. Drive `value` yourself.
+     */
+    onSelect: (option: AsyncAutocompleteOption<TData>) => void;
+    /** In-flight request. Replaces the rows with a spinner. */
+    loading?: boolean;
+    /** Controlled input text. */
+    value?: string;
+    /** Initial input text when uncontrolled. */
+    defaultValue?: string;
+    /** Fired on every input change and on clear. */
+    onValueChange?: (value: string) => void;
+    /**
+     * Fired only when the clear (X) button is pressed, after
+     * `onValueChange('')` and `onSearch('')`. Use it to drop the selected
+     * entity. Focus is returned to the input automatically.
+     */
+    onClear?: () => void;
+    placeholder?: string;
+    /** Decorative leading icon — `<MapPin />`, `<Stethoscope />`, … */
+    leftIcon?: React$1.ReactNode;
+    /** Fixed height: `sm` 40px · `md` 48px (default) · `lg` 56px. */
+    size?: 'sm' | 'md' | 'lg';
+    /** Error color scheme on the input. Also sets `aria-invalid`. */
+    error?: boolean;
+    disabled?: boolean;
+    /** Forwarded to the underlying `<input>` for imperative focus. */
+    inputRef?: React$1.Ref<HTMLInputElement>;
+    /** Escape hatch for `name`, `enterKeyHint`, `inputMode`, `autoFocus`, … */
+    inputProps?: AsyncAutocompleteInputProps;
+    /**
+     * `'popover'` (default) always anchors a portaled popover under the field
+     * and dismisses it as soon as the user scrolls. `'sheet'` keeps that
+     * behavior above 768px but turns the search into a full-screen takeover on
+     * phones, where the page behind is scroll-locked.
+     */
+    mobileVariant?: 'popover' | 'sheet';
+    /**
+     * Replace a whole row. The default renders `label` plus a dimmed
+     * `, description` on one truncated line with a leading icon. Reach for this
+     * for stacked two-line rows, avatars, or bold match highlighting — the
+     * wrapper, `role="option"`, ids, highlight background and click/keyboard
+     * wiring stay with the component.
+     */
+    renderOption?: (option: AsyncAutocompleteOption<TData>, state: AsyncAutocompleteOptionState) => React$1.ReactNode;
+    /** Default leading icon for rows without their own `option.icon`. */
+    optionIcon?: React$1.ReactNode;
+    /** "No results" copy. Ignored when `emptyState` is provided. */
+    emptyMessage?: string;
+    /** Full replacement for the empty row — an illustration, a CTA, … */
+    emptyState?: React$1.ReactNode;
+    /** Copy beside the loading spinner. */
+    loadingMessage?: string;
+    /** Replaces the clear button's `X` glyph. */
+    clearIcon?: React$1.ReactNode;
+    /** Accessible name for the clear button. */
+    clearLabel?: string;
+    /** Accessible name for the `mobileVariant="sheet"` takeover. */
+    sheetTitle?: string;
+    /** Replaces the sheet's back-arrow glyph. */
+    sheetCloseIcon?: React$1.ReactNode;
+    /** Accessible name for the sheet's close button. */
+    sheetCloseLabel?: string;
+    /** Controlled open state. Prefer `defaultOpen` unless you truly need this. */
+    open?: boolean;
+    /** Start open — for fields mounted lazily on focus. */
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    /**
+     * Prefix for stable DOM ids, so analytics autocapture keeps working:
+     * `{idPrefix}-input`, `{idPrefix}-clear`, `{idPrefix}-listbox`,
+     * `{idPrefix}-suggestion-{index}`, and in sheet mode also
+     * `{idPrefix}-sheet-input` and `{idPrefix}-sheet-clear`. Falls back to a
+     * `useId()` value, which is fine for ARIA wiring but not usable as a CSS
+     * selector.
+     */
+    idPrefix?: string;
+    /** Merged onto the root wrapper. */
+    className?: string;
+    /** Per-slot class overrides. See `AsyncAutocompleteClassNames`. */
+    classNames?: AsyncAutocompleteClassNames;
+}
+declare function AsyncAutocomplete<TData = unknown>({ options, onSearch, onSelect, loading, value: valueProp, defaultValue, onValueChange, onClear, placeholder, leftIcon, size, error, disabled, inputRef, inputProps, mobileVariant, renderOption, optionIcon, emptyMessage, emptyState, loadingMessage, clearIcon, clearLabel, sheetTitle, sheetCloseIcon, sheetCloseLabel, open: openProp, defaultOpen, onOpenChange, idPrefix, className, classNames }: AsyncAutocompleteProps<TData>): react_jsx_runtime.JSX.Element;
+
 interface TextareaProps extends Omit<React$1.ComponentProps<'textarea'>, 'size'> {
     error?: boolean;
 }
@@ -959,4 +1154,4 @@ declare function cn(...inputs: ClassValue[]): string;
 
 declare function useIsMobile(): boolean;
 
-export { Accordion, AccordionContent, AccordionItem, AccordionTrigger, Alert, AlertBanner, type AlertBannerProps, AlertDescription, AlertDialog, AlertDialogAction, AlertDialogCancel, AlertDialogContent, AlertDialogDescription, AlertDialogFooter, AlertDialogHeader, AlertDialogOverlay, AlertDialogPortal, AlertDialogTitle, AlertDialogTrigger, AlertTitle, AspectRatio, AutoResizeTextarea, Avatar, AvatarFallback, AvatarImage, Badge, BadgeActionable, type BadgeActionableProps, BadgeInformative, BadgeInformativeGroup, BadgeInformativeItem, type BadgeInformativeProps, BadgeNumber, type BadgeNumberProps, Body, Breadcrumb, BreadcrumbEllipsis, BreadcrumbItem, BreadcrumbLink, BreadcrumbList, BreadcrumbPage, BreadcrumbSeparator, Button, Calendar, CalendarDayButton, Card, CardAction, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, Carousel, type CarouselApi, CarouselContent, CarouselItem, CarouselNext, CarouselPrevious, type ChartConfig, ChartContainer, ChartLegend, ChartLegendContent, ChartStyle, ChartTooltip, ChartTooltipContent, Checkbox, Collapsible, CollapsibleContent, CollapsibleTrigger, Command, CommandDialog, CommandEmpty, CommandGroup, CommandInput, CommandItem, CommandList, CommandSeparator, CommandShortcut, ContextMenu, ContextMenuCheckboxItem, ContextMenuContent, ContextMenuGroup, ContextMenuItem, ContextMenuLabel, ContextMenuPortal, ContextMenuRadioGroup, ContextMenuRadioItem, ContextMenuSeparator, ContextMenuShortcut, ContextMenuSub, ContextMenuSubContent, ContextMenuSubTrigger, ContextMenuTrigger, type DateFormat, DateInput, type DateInputProps, DateRangeInput, type DateRangeInputProps, Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger, DisplayHeading, Drawer, DrawerClose, DrawerContent, DrawerDescription, DrawerFooter, DrawerHeader, DrawerOverlay, DrawerPortal, DrawerTitle, DrawerTrigger, DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, DropdownSelect, DropdownSelectContent, type DropdownSelectContentProps, DropdownSelectLabel, type DropdownSelectLabelProps, DropdownSelectOption, type DropdownSelectOptionProps, type DropdownSelectProps, DropdownSelectTrigger, type DropdownSelectTriggerProps, Form, FormControl, FormDescription, FormField, FormItem, FormLabel, FormMessage, HeadingL, HeadingLMedium, HeadingM, HeadingMMedium, HeadingS, HeadingSMedium, HeadingXL, HeadingXLMedium, HeadingXS, HeadingXSMedium, HeadingXXS, HeadingXXSMedium, HoverCard, HoverCardContent, HoverCardTrigger, Input, InputOTP, InputOTPGroup, InputOTPSeparator, InputOTPSlot, Label, Menubar, MenubarCheckboxItem, MenubarContent, MenubarGroup, MenubarItem, MenubarLabel, MenubarMenu, MenubarPortal, MenubarRadioGroup, MenubarRadioItem, MenubarSeparator, MenubarShortcut, MenubarSub, MenubarSubContent, MenubarSubTrigger, MenubarTrigger, MultiSelectFreeText, type MultiSelectFreeTextOption, type MultiSelectFreeTextProps, NavigationMenu, NavigationMenuContent, NavigationMenuIndicator, NavigationMenuItem, NavigationMenuLink, NavigationMenuList, NavigationMenuTrigger, NavigationMenuViewport, OptionCard, type OptionCardProps, Pagination, PaginationContent, PaginationEllipsis, PaginationItem, PaginationLink, PaginationNext, PaginationPrevious, Popover, PopoverAnchor, PopoverContent, PopoverTrigger, Progress, ProgressBar, type ProgressBarProps, RadioGroup, RadioGroupItem, ResizableHandle, ResizablePanel, ResizablePanelGroup, RichTooltipContent, type RichTooltipContentProps, type RichTooltipVariant, ScrollArea, ScrollBar, SearchInput, type SearchInputProps, type SearchSuggestion, SearchableSelect, SearchableSelectContent, SearchableSelectEmpty, SearchableSelectGroup, SearchableSelectItem, type SearchableSelectOption, type SearchableSelectProps, SearchableSelectTrigger, Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectScrollDownButton, SelectScrollUpButton, SelectSeparator, SelectTrigger, SelectValue, Separator, Sheet, SheetClose, SheetContent, SheetDescription, SheetFooter, SheetHeader, SheetTitle, SheetTrigger, Sidebar, SidebarContent, SidebarFooter, SidebarGroup, SidebarGroupAction, SidebarGroupContent, SidebarGroupLabel, SidebarHeader, SidebarInput, SidebarInset, SidebarMenu, SidebarMenuAction, SidebarMenuBadge, SidebarMenuButton, SidebarMenuItem, SidebarMenuSkeleton, SidebarMenuSub, SidebarMenuSubButton, SidebarMenuSubItem, SidebarProvider, SidebarRail, SidebarSeparator, SidebarTrigger, Skeleton, Slider, SmartDialog, SmartDialogClose, SmartDialogContent, SmartDialogDescription, SmartDialogFooter, SmartDialogHeader, SmartDialogTitle, SmartDialogTrigger, Switch, Table, TableBody, TableCaption, TableCell, TableFooter, TableHead, TableHeader, TableRow, Tabs, TabsContent, TabsList, TabsTrigger, type TabsTriggerProps, Textarea, type TextareaProps, ThemeProvider, ThemeToggle, type TimeFormat, TimeInput, type TimeInputProps, type TimeValue, Toaster, Toggle, ToggleGroup, ToggleGroupItem, Tooltip, TooltipContent, type TooltipContentProps, TooltipProvider, TooltipTrigger, alertBannerVariants, badgeActionableVariants, badgeInformativeVariants, badgeNumberVariants, badgeVariants, bodyTextVariants, buttonVariants, cn, displayTextVariants, inputVariants, labelTextVariants, navigationMenuTriggerStyle, optionCardVariants, progressBarVariants, tabsTriggerVariants, toggleVariants, useFormField, useIsMobile, useSidebar };
+export { Accordion, AccordionContent, AccordionItem, AccordionTrigger, Alert, AlertBanner, type AlertBannerProps, AlertDescription, AlertDialog, AlertDialogAction, AlertDialogCancel, AlertDialogContent, AlertDialogDescription, AlertDialogFooter, AlertDialogHeader, AlertDialogOverlay, AlertDialogPortal, AlertDialogTitle, AlertDialogTrigger, AlertTitle, AspectRatio, AsyncAutocomplete, type AsyncAutocompleteClassNames, type AsyncAutocompleteInputProps, type AsyncAutocompleteOption, type AsyncAutocompleteOptionState, type AsyncAutocompleteProps, AutoResizeTextarea, Avatar, AvatarFallback, AvatarImage, Badge, BadgeActionable, type BadgeActionableProps, BadgeInformative, BadgeInformativeGroup, BadgeInformativeItem, type BadgeInformativeProps, BadgeNumber, type BadgeNumberProps, Body, Breadcrumb, BreadcrumbEllipsis, BreadcrumbItem, BreadcrumbLink, BreadcrumbList, BreadcrumbPage, BreadcrumbSeparator, Button, Calendar, CalendarDayButton, Card, CardAction, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, Carousel, type CarouselApi, CarouselContent, CarouselItem, CarouselNext, CarouselPrevious, type ChartConfig, ChartContainer, ChartLegend, ChartLegendContent, ChartStyle, ChartTooltip, ChartTooltipContent, Checkbox, Collapsible, CollapsibleContent, CollapsibleTrigger, Command, CommandDialog, CommandEmpty, CommandGroup, CommandInput, CommandItem, CommandList, CommandSeparator, CommandShortcut, ContextMenu, ContextMenuCheckboxItem, ContextMenuContent, ContextMenuGroup, ContextMenuItem, ContextMenuLabel, ContextMenuPortal, ContextMenuRadioGroup, ContextMenuRadioItem, ContextMenuSeparator, ContextMenuShortcut, ContextMenuSub, ContextMenuSubContent, ContextMenuSubTrigger, ContextMenuTrigger, type DateFormat, DateInput, type DateInputProps, DateRangeInput, type DateRangeInputProps, Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger, DisplayHeading, Drawer, DrawerClose, DrawerContent, DrawerDescription, DrawerFooter, DrawerHeader, DrawerOverlay, DrawerPortal, DrawerTitle, DrawerTrigger, DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, DropdownSelect, DropdownSelectContent, type DropdownSelectContentProps, DropdownSelectLabel, type DropdownSelectLabelProps, DropdownSelectOption, type DropdownSelectOptionProps, type DropdownSelectProps, DropdownSelectTrigger, type DropdownSelectTriggerProps, Form, FormControl, FormDescription, FormField, FormItem, FormLabel, FormMessage, HeadingL, HeadingLMedium, HeadingM, HeadingMMedium, HeadingS, HeadingSMedium, HeadingXL, HeadingXLMedium, HeadingXS, HeadingXSMedium, HeadingXXS, HeadingXXSMedium, HoverCard, HoverCardContent, HoverCardTrigger, Input, InputOTP, InputOTPGroup, InputOTPSeparator, InputOTPSlot, type InputProps, Label, Menubar, MenubarCheckboxItem, MenubarContent, MenubarGroup, MenubarItem, MenubarLabel, MenubarMenu, MenubarPortal, MenubarRadioGroup, MenubarRadioItem, MenubarSeparator, MenubarShortcut, MenubarSub, MenubarSubContent, MenubarSubTrigger, MenubarTrigger, MultiSelectFreeText, type MultiSelectFreeTextOption, type MultiSelectFreeTextProps, NavigationMenu, NavigationMenuContent, NavigationMenuIndicator, NavigationMenuItem, NavigationMenuLink, NavigationMenuList, NavigationMenuTrigger, NavigationMenuViewport, OptionCard, type OptionCardProps, Pagination, PaginationContent, PaginationEllipsis, PaginationItem, PaginationLink, PaginationNext, PaginationPrevious, Popover, PopoverAnchor, PopoverContent, PopoverTrigger, Progress, ProgressBar, type ProgressBarProps, RadioGroup, RadioGroupItem, ResizableHandle, ResizablePanel, ResizablePanelGroup, RichTooltipContent, type RichTooltipContentProps, type RichTooltipVariant, ScrollArea, ScrollBar, SearchInput, type SearchInputProps, type SearchSuggestion, SearchableSelect, SearchableSelectContent, SearchableSelectEmpty, SearchableSelectGroup, SearchableSelectItem, type SearchableSelectOption, type SearchableSelectProps, SearchableSelectTrigger, Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectScrollDownButton, SelectScrollUpButton, SelectSeparator, SelectTrigger, SelectValue, Separator, Sheet, SheetClose, SheetContent, SheetDescription, SheetFooter, SheetHeader, SheetTitle, SheetTrigger, Sidebar, SidebarContent, SidebarFooter, SidebarGroup, SidebarGroupAction, SidebarGroupContent, SidebarGroupLabel, SidebarHeader, SidebarInput, SidebarInset, SidebarMenu, SidebarMenuAction, SidebarMenuBadge, SidebarMenuButton, SidebarMenuItem, SidebarMenuSkeleton, SidebarMenuSub, SidebarMenuSubButton, SidebarMenuSubItem, SidebarProvider, SidebarRail, SidebarSeparator, SidebarTrigger, Skeleton, Slider, SmartDialog, SmartDialogClose, SmartDialogContent, SmartDialogDescription, SmartDialogFooter, SmartDialogHeader, SmartDialogTitle, SmartDialogTrigger, Switch, Table, TableBody, TableCaption, TableCell, TableFooter, TableHead, TableHeader, TableRow, Tabs, TabsContent, TabsList, TabsTrigger, type TabsTriggerProps, Textarea, type TextareaProps, ThemeProvider, ThemeToggle, type TimeFormat, TimeInput, type TimeInputProps, type TimeValue, Toaster, Toggle, ToggleGroup, ToggleGroupItem, Tooltip, TooltipContent, type TooltipContentProps, TooltipProvider, TooltipTrigger, alertBannerVariants, badgeActionableVariants, badgeInformativeVariants, badgeNumberVariants, badgeVariants, bodyTextVariants, buttonVariants, cn, displayTextVariants, inputVariants, labelTextVariants, navigationMenuTriggerStyle, optionCardVariants, progressBarVariants, tabsTriggerVariants, toggleVariants, useFormField, useIsMobile, useSidebar };