Combobox

1"use client";
2 
3import { AnimatePresence, motion, useReducedMotion } from "framer-motion";
4import * as React from "react";
5 
6export type ComboboxOption = {
7  label: string;
8  value: string;
9  description?: string;
10};
11 
12/** A non-option affordance rendered inside the listbox (e.g. a pinned top row or
13 *  an empty-state CTA). `onSelect` receives the current (trimmed) query. */
14export type ComboboxAction = {
15  label: React.ReactNode;
16  onSelect: (query: string) => void;
17};
18 
19export type ComboboxProps = Omit<
20  React.HTMLAttributes<HTMLDivElement>,
21  "onChange" | "defaultValue" | "onToggle"
22> & {
23  /** Static option list. Ignored when `onSearch` is provided. */
24  options?: ComboboxOption[];
25  /** Async resolver. Return options for a query. */
26  onSearch?: (query: string) => Promise<ComboboxOption[]>;
27  value?: string;
28  defaultValue?: string;
29  placeholder?: string;
30  emptyMessage?: string;
31  /** Disable the input and prevent opening the listbox. */
32  disabled?: boolean;
33  onChange?: (value: string, option: ComboboxOption) => void;
34  /** Multi-select mode: chosen options render as chips in the control and
35   *  picking one keeps the list open. Drive it with `values` + `onToggle`. */
36  multiple?: boolean;
37  /** Selected values (multi-select). */
38  values?: string[];
39  /** Toggle handler (multi-select). */
40  onToggle?: (value: string, option: ComboboxOption) => void;
41  /** Offer the typed value as an "Add …" row when it isn't already an option, so
42   *  free entry works alongside the suggestions. Implies a searchable input. */
43  creatable?: boolean;
44  /** Persist a newly-typed value instead of committing a synthetic option.
45   *  Receives the trimmed label. */
46  onCreate?: (label: string) => void | Promise<void>;
47  /** Spinner + disabled state on the create row while a create is in flight. */
48  creating?: boolean;
49  /** When false, render a plain click-to-open dropdown (no type-ahead filtering)
50   *  — a drop-in for a fixed-enum `<select>`. Defaults smart: searchable once the
51   *  option count exceeds `searchableThreshold`. Ignored when a feature that needs
52   *  a text query is on (`onSearch`, `creatable`, `emptyAction`, `multiple`). */
53  searchable?: boolean;
54  /** Option count above which search auto-enables when `searchable` is unset.
55   *  Defaults to `COMBOBOX_SEARCHABLE_THRESHOLD` (5). */
56  searchableThreshold?: number;
57  /** A persistent row shown at the top of the list — a place for a "manage" or
58// … truncated