@krizaka/ui 2.2.0 → 2.4.0

package/registry/combobox.json

@@ -0,0 +1,475 @@
+{
+  "name": "combobox",
+  "type": "primitive",
+  "title": "Combobox",
+  "summary": "A text field that suggests and completes — one value or several as chips, from a static list or a server, with values created from what was typed.",
+  "description": "A text field that suggests and completes — one value or several as chips, from a static list or a server, with values created from what was typed.",
+  "status": "beta",
+  "category": "forms",
+  "platforms": "web",
+  "whenToUse": [
+    "To choose among many values the person knows by name: a creator, a country, a model, a playlist.",
+    "With `onSearch` when the values live on a server (debounced, the previous request aborted).",
+    "With `multiple` for several values (collaborators, categories), and `creatable` when a new one can be added."
+  ],
+  "whenNotToUse": [
+    {
+      "when": "For fewer than about seven options known in advance: radios or a select.",
+      "use": "radio-group"
+    },
+    {
+      "when": "For free words without a closed list (tags, keywords): a tag input.",
+      "use": "tag-input"
+    },
+    {
+      "when": "To run a search and show results: a search field.",
+      "use": "search-field"
+    }
+  ],
+  "bestPractices": [
+    "Write `label` as the question (“Collaborators”), the `placeholder` as an example (“Type a name”).",
+    "Return at most 20 options from `onSearch`; put the best match first.",
+    "Give options a `description` when names collide (two creators named Eric: their handles).",
+    "Set `maxSelected` when the product has a limit, and say it in `hint`."
+  ],
+  "accessibility": {
+    "keyboard": [
+      {
+        "keys": "Arrow Down / Arrow Up",
+        "action": "Open the list and move the active option."
+      },
+      {
+        "keys": "Home / End",
+        "action": "First or last option, when the list is open."
+      },
+      {
+        "keys": "Enter",
+        "action": "Choose the active option (or create the typed value)."
+      },
+      {
+        "keys": "Esc",
+        "action": "Close the list; for one value, restore its label."
+      },
+      {
+        "keys": "Backspace",
+        "action": "In an empty input, remove the last chip."
+      }
+    ],
+    "notes": [
+      "The ARIA 1.2 combobox pattern: the focus stays in the input, `aria-activedescendant` points at the active option of the `listbox`.",
+      "The number of results is announced in a polite live region (`labels.results`).",
+      "Chosen options carry `aria-selected`; each chip's remove button is named (“Remove Eric”).",
+      "The label is a real `<label>`; `hint` and `error` are wired with `aria-describedby`, `error` sets `aria-invalid`."
+    ]
+  },
+  "related": [
+    "tag-input",
+    "search-field",
+    "field",
+    "chip",
+    "command"
+  ],
+  "web": {
+    "entry": "@krizaka/ui/combobox",
+    "import": "import { Combobox } from \"@krizaka/ui/combobox\";",
+    "props": [
+      {
+        "component": "Combobox",
+        "description": "A text field that suggests, filters and completes: one value or several (chips), static or fetched, creatable.",
+        "props": [
+          {
+            "name": "label",
+            "type": "string",
+            "default": null,
+            "description": "The visible label of the field, passed translated (also its accessible name).",
+            "required": true
+          },
+          {
+            "name": "className",
+            "type": "string",
+            "default": null,
+            "description": "Classes merged on the root.",
+            "required": false
+          },
+          {
+            "name": "creatable",
+            "type": "boolean",
+            "default": null,
+            "description": "Offers to create the query as a new value when no option has that exact label.",
+            "required": false
+          },
+          {
+            "name": "debounce",
+            "type": "number",
+            "default": null,
+            "description": "The wait, in ms, between the last key and `onSearch`. Default 250.",
+            "required": false
+          },
+          {
+            "name": "defaultValue",
+            "type": "ComboboxOption | readonly ComboboxOption[] | null",
+            "default": null,
+            "description": "The chosen option at first, uncontrolled.\nThe chosen options at first, uncontrolled.",
+            "required": false
+          },
+          {
+            "name": "disabled",
+            "type": "boolean",
+            "default": null,
+            "description": "Not available.",
+            "required": false
+          },
+          {
+            "name": "error",
+            "type": "string",
+            "default": null,
+            "description": "An error under the field: marks it invalid and is read with it.",
+            "required": false
+          },
+          {
+            "name": "filter",
+            "type": "((option: ComboboxOption, query: string) => boolean)",
+            "default": null,
+            "description": "Whether an option matches a query. Default: its label contains the query, ignoring case and accents.",
+            "required": false
+          },
+          {
+            "name": "hideLabel",
+            "type": "boolean",
+            "default": null,
+            "description": "Hides the label visually, keeping it as the accessible name (a search bar with its own context).",
+            "required": false
+          },
+          {
+            "name": "hint",
+            "type": "string",
+            "default": null,
+            "description": "A help text under the field.",
+            "required": false
+          },
+          {
+            "name": "id",
+            "type": "string",
+            "default": null,
+            "description": "The id of the text input (default: generated).",
+            "required": false
+          },
+          {
+            "name": "labels",
+            "type": "Partial<ComboboxLabels>",
+            "default": null,
+            "description": "The words, passed translated; English by default.",
+            "required": false
+          },
+          {
+            "name": "maxSelected",
+            "type": "number",
+            "default": null,
+            "description": "Most options that can be chosen (several values only).\nMost options that can be chosen; the list stops offering more past it.",
+            "required": false
+          },
+          {
+            "name": "multiple",
+            "type": "boolean",
+            "default": null,
+            "description": "One value (default) or several.\nSeveral values, shown as chips.",
+            "required": false
+          },
+          {
+            "name": "name",
+            "type": "string",
+            "default": null,
+            "description": "The name of a hidden input holding the value(s), for a plain `<form>` post.",
+            "required": false
+          },
+          {
+            "name": "onCreate",
+            "type": "((query: string) => ComboboxOption)",
+            "default": null,
+            "description": "Turns a query into the created option (an id from the server…). Default `{ value: query, label: query }`.",
+            "required": false
+          },
+          {
+            "name": "onSearch",
+            "type": "((query: string, signal: AbortSignal) => Promise<readonly ComboboxOption[]>)",
+            "default": null,
+            "description": "Fetches the options for a query (debounced by `debounce`); the `signal` aborts when a newer query starts.",
+            "required": false
+          },
+          {
+            "name": "onValueChange",
+            "type": "((value: ComboboxOption | null) => void) | ((value: ComboboxOption[]) => void)",
+            "default": null,
+            "description": "Called with the chosen option, or `null` when it is cleared.\nCalled with every chosen option.",
+            "required": false
+          },
+          {
+            "name": "options",
+            "type": "readonly ComboboxOption[]",
+            "default": null,
+            "description": "The options, filtered as the person types (by `filter`).",
+            "required": false
+          },
+          {
+            "name": "placeholder",
+            "type": "string",
+            "default": null,
+            "description": "The input's placeholder, passed translated.",
+            "required": false
+          },
+          {
+            "name": "separators",
+            "type": "readonly string[]",
+            "default": null,
+            "description": "Keys that create the query at once, as Enter does (`[\",\"]` for tags); a paste is split on them too.",
+            "required": false
+          },
+          {
+            "name": "value",
+            "type": "ComboboxOption | readonly ComboboxOption[] | null",
+            "default": null,
+            "description": "The chosen option (controlled), `null` for none.\nThe chosen options (controlled).",
+            "required": false
+          }
+        ]
+      }
+    ],
+    "examples": [
+      {
+        "name": "async",
+        "title": "From a server",
+        "description": "`onSearch`: creators fetched as you type, debounced, the stale request aborted.",
+        "path": "examples/combobox/async.tsx",
+        "module": "@krizaka/ui/registry/examples/combobox/async",
+        "code": "\"use client\";\n\nimport { Combobox, type ComboboxOption } from \"@krizaka/ui/combobox\";\n\nconst CREATORS: ComboboxOption[] = [\n  { value: \"u1\", label: \"Eric Tremblay\", description: \"@eric.films\" },\n  { value: \"u2\", label: \"Erica Moreau\", description: \"@erica\" },\n  { value: \"u3\", label: \"Inès Haddad\", description: \"@ines.draws\" },\n  { value: \"u4\", label: \"Jonas Weber\", description: \"@jonas\" },\n];\n\n// Your API in place of this one: it receives the query and an AbortSignal.\nasync function searchCreators(query: string, signal: AbortSignal) {\n  await new Promise((resolve) => setTimeout(resolve, 300));\n  if (signal.aborted) return [];\n  const q = query.toLowerCase();\n  return CREATORS.filter((c) => c.label.toLowerCase().includes(q) || c.description?.includes(q));\n}\n\nexport default function ComboboxAsync() {\n  return <Combobox label=\"Creator\" placeholder=\"Type a name or a handle\" onSearch={searchCreators} />;\n}\n"
+      },
+      {
+        "name": "multiple",
+        "title": "Several values",
+        "description": "Collaborators as chips; Backspace removes the last one, at most three.",
+        "path": "examples/combobox/multiple.tsx",
+        "module": "@krizaka/ui/registry/examples/combobox/multiple",
+        "code": "\"use client\";\n\nimport { Combobox } from \"@krizaka/ui/combobox\";\n\nconst PEOPLE = [\n  { value: \"eric\", label: \"Eric\" },\n  { value: \"ines\", label: \"Inès\" },\n  { value: \"jonas\", label: \"Jonas\" },\n  { value: \"mia\", label: \"Mia\" },\n  { value: \"noah\", label: \"Noah\" },\n];\n\n// Several values as chips; Backspace in the empty input removes the last one.\nexport default function ComboboxMultiple() {\n  return (\n    <Combobox\n      multiple\n      label=\"Collaborators\"\n      placeholder=\"Add a collaborator\"\n      options={PEOPLE}\n      defaultValue={[PEOPLE[0]!, PEOPLE[1]!]}\n      maxSelected={3}\n      hint=\"Up to three collaborators share the revenue of this video.\"\n    />\n  );\n}\n"
+      },
+      {
+        "name": "creatable",
+        "title": "Create a value",
+        "description": "Pick a playlist or create one from what was typed.",
+        "path": "examples/combobox/creatable.tsx",
+        "module": "@krizaka/ui/registry/examples/combobox/creatable",
+        "code": "\"use client\";\n\nimport { Combobox, type ComboboxOption } from \"@krizaka/ui/combobox\";\nimport * as React from \"react\";\n\n// Pick a playlist, or type a new name and create it.\nexport default function ComboboxCreatable() {\n  const [playlists, setPlaylists] = React.useState<ComboboxOption[]>([\n    { value: \"p1\", label: \"Travel diaries\" },\n    { value: \"p2\", label: \"Studio sessions\" },\n  ]);\n  const [value, setValue] = React.useState<ComboboxOption | null>(playlists[1]!);\n  return (\n    <Combobox\n      label=\"Playlist\"\n      options={playlists}\n      value={value}\n      onValueChange={setValue}\n      creatable\n      onCreate={(name) => {\n        const created = { value: `p${playlists.length + 1}`, label: name };\n        setPlaylists((all) => [...all, created]);\n        return created;\n      }}\n      labels={{ create: (name) => `Create the playlist “${name}”` }}\n    />\n  );\n}\n"
+      },
+      {
+        "name": "invalid",
+        "title": "With an error",
+        "description": "A required choice left empty: the error is read with the field.",
+        "path": "examples/combobox/invalid.tsx",
+        "module": "@krizaka/ui/registry/examples/combobox/invalid",
+        "code": "import { Combobox } from \"@krizaka/ui/combobox\";\n\n// A required choice left empty: the error is shown and read with the field.\nexport default function ComboboxInvalid() {\n  return (\n    <Combobox\n      label=\"Country of residence\"\n      placeholder=\"Choose a country\"\n      options={[\n        { value: \"CA\", label: \"Canada\" },\n        { value: \"FR\", label: \"France\" },\n        { value: \"BE\", label: \"Belgium\" },\n      ]}\n      error=\"Choose your country to receive payouts.\"\n    />\n  );\n}\n"
+      }
+    ]
+  },
+  "native": null,
+  "files": [
+    {
+      "path": "combobox/combobox.tsx",
+      "content": "// Client. The ARIA 1.2 combobox (`../listbox`): a text input that filters a listbox, the focus never leaves the input\n// (`aria-activedescendant`), the number of results announced in a polite live region. Static options filtered here,\n// or `onSearch` (debounced, the previous request aborted) for a server's; one value or several (chips, Backspace\n// removes the last), and new values created from the query when `creatable`.\nimport * as React from \"react\";\nimport { tv } from \"tailwind-variants\";\n\nimport { Chip } from \"../chip\";\nimport { CheckGlyph, ChevronGlyph, CloseGlyph, PlusGlyph } from \"../glyphs\";\nimport { useListbox } from \"../listbox\";\nimport { useControllable, useDebouncedCallback } from \"../media\";\n\nexport const combobox = tv({\n  slots: {\n    root: \"relative flex w-full flex-col gap-1.5\",\n    label: \"text-xs font-semibold text-fg-secondary\",\n    control:\n      \"flex min-h-11 w-full flex-wrap items-center gap-1.5 rounded-lg border border-border-default bg-surface-2 py-1.5 pl-2 pr-1 text-sm text-fg \" +\n      \"transition-[border-color,box-shadow] focus-within:border-accent focus-within:ring-2 focus-within:ring-ring \" +\n      \"data-[invalid]:border-danger data-[disabled]:cursor-not-allowed data-[disabled]:opacity-50\",\n    input: \"h-8 min-w-24 flex-1 bg-transparent px-1 text-sm text-fg outline-hidden placeholder:text-fg-muted disabled:cursor-not-allowed\",\n    icon:\n      \"inline-flex h-8 w-8 shrink-0 items-center justify-center rounded-md text-fg-secondary hover:bg-surface-3 hover:text-fg \" +\n      \"focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-ring\",\n    list: \"absolute inset-x-0 top-full z-50 mt-1 max-h-64 overflow-y-auto rounded-lg border border-border-default bg-surface-2 p-1 shadow-lg\",\n    option:\n      \"flex cursor-pointer select-none items-center gap-2.5 rounded-md px-2.5 py-2 text-sm text-fg \" +\n      \"data-[active]:bg-surface-3 aria-disabled:cursor-not-allowed aria-disabled:opacity-40\",\n    check: \"h-4 w-4 shrink-0 text-fg-accent\",\n    description: \"block text-xs text-fg-secondary\",\n    status: \"px-2.5 py-3 text-sm text-fg-secondary\",\n    hint: \"text-xs text-fg-secondary\",\n    error: \"flex items-center gap-1.5 text-xs font-medium text-fg-danger before:h-1.5 before:w-1.5 before:shrink-0 before:rounded-full before:bg-danger\",\n  },\n});\n\nexport type ComboboxOption = {\n  /** What the app stores. */\n  value: string;\n  /** What the person reads, passed translated. */\n  label: string;\n  /** A second line under the label. */\n  description?: string;\n  /** Shown but not choosable. */\n  disabled?: boolean;\n};\n\nexport type ComboboxLabels = {\n  /** No option matches (\"No results\"). */\n  empty: string;\n  /** While `onSearch` runs (\"Searching…\"). */\n  loading: string;\n  /** `onSearch` failed (\"Search unavailable\"). */\n  error: string;\n  /** The option that creates a value: `(query) => \"Create “\" + query + \"”\"`. */\n  create: (query: string) => string;\n  /** A chip's remove button: `(label) => \"Remove \" + label`. */\n  remove: (label: string) => string;\n  /** The button that empties a single choice (\"Clear\"). */\n  clear: string;\n  /** The button that opens the list (\"Show options\"). */\n  toggle: string;\n  /** Announced when the results change: `(n) => n + \" results\"`. */\n  results: (count: number) => string;\n};\n\nexport const comboboxLabels: ComboboxLabels = {\n  empty: \"No results\",\n  loading: \"Searching…\",\n  error: \"Search unavailable\",\n  create: (query) => `Create “${query}”`,\n  remove: (label) => `Remove ${label}`,\n  clear: \"Clear\",\n  toggle: \"Show options\",\n  results: (count) => (count === 1 ? \"1 result\" : `${count} results`),\n};\n\ntype BaseProps = {\n  /** The visible label of the field, passed translated (also its accessible name). */\n  label: string;\n  /** Hides the label visually, keeping it as the accessible name (a search bar with its own context). */\n  hideLabel?: boolean;\n  /** The options, filtered as the person types (by `filter`). */\n  options?: readonly ComboboxOption[];\n  /** Fetches the options for a query (debounced by `debounce`); the `signal` aborts when a newer query starts. */\n  onSearch?: (query: string, signal: AbortSignal) => Promise<readonly ComboboxOption[]>;\n  /** The wait, in ms, between the last key and `onSearch`. Default 250. */\n  debounce?: number;\n  /** Whether an option matches a query. Default: its label contains the query, ignoring case and accents. */\n  filter?: (option: ComboboxOption, query: string) => boolean;\n  /** Offers to create the query as a new value when no option has that exact label. */\n  creatable?: boolean;\n  /** Turns a query into the created option (an id from the server…). Default `{ value: query, label: query }`. */\n  onCreate?: (query: string) => ComboboxOption;\n  /** Keys that create the query at once, as Enter does (`[\",\"]` for tags); a paste is split on them too. */\n  separators?: readonly string[];\n  /** The input's placeholder, passed translated. */\n  placeholder?: string;\n  /** A help text under the field. */\n  hint?: string;\n  /** An error under the field: marks it invalid and is read with it. */\n  error?: string;\n  /** Not available. */\n  disabled?: boolean;\n  /** The name of a hidden input holding the value(s), for a plain `<form>` post. */\n  name?: string;\n  /** The words, passed translated; English by default. */\n  labels?: Partial<ComboboxLabels>;\n  /** Classes merged on the root. */\n  className?: string;\n  /** The id of the text input (default: generated). */\n  id?: string;\n};\n\ntype SingleProps = BaseProps & {\n  /** One value (default) or several. */\n  multiple?: false;\n  /** The chosen option (controlled), `null` for none. */\n  value?: ComboboxOption | null;\n  /** The chosen option at first, uncontrolled. */\n  defaultValue?: ComboboxOption | null;\n  /** Called with the chosen option, or `null` when it is cleared. */\n  onValueChange?: (value: ComboboxOption | null) => void;\n  /** Most options that can be chosen (several values only). */\n  maxSelected?: never;\n};\n\ntype MultipleProps = BaseProps & {\n  /** Several values, shown as chips. */\n  multiple: true;\n  /** The chosen options (controlled). */\n  value?: readonly ComboboxOption[];\n  /** The chosen options at first, uncontrolled. */\n  defaultValue?: readonly ComboboxOption[];\n  /** Called with every chosen option. */\n  onValueChange?: (value: ComboboxOption[]) => void;\n  /** Most options that can be chosen; the list stops offering more past it. */\n  maxSelected?: number;\n};\n\nexport type ComboboxProps = SingleProps | MultipleProps;\n\nconst fold = (text: string) => text.normalize(\"NFD\").replace(/\\p{Diacritic}/gu, \"\").toLowerCase();\nconst defaultFilter = (option: ComboboxOption, query: string) => fold(option.label).includes(fold(query.trim()));\n\ntype Item = { kind: \"option\"; option: ComboboxOption } | { kind: \"create\"; query: string };\n\n/** A text field that suggests, filters and completes: one value or several (chips), static or fetched, creatable. */\nexport function Combobox(props: ComboboxProps) {\n  const {\n    label,\n    hideLabel,\n    options,\n    onSearch,\n    debounce = 250,\n    filter = defaultFilter,\n    creatable,\n    onCreate = (query: string) => ({ value: query, label: query }),\n    separators,\n    placeholder,\n    hint,\n    error,\n    disabled,\n    name,\n    labels: given,\n    className,\n    id: givenId,\n  } = props;\n  const labels = { ...comboboxLabels, ...given };\n  const s = combobox();\n  const autoId = React.useId();\n  const inputId = givenId ?? `${autoId}-input`;\n  const hintId = `${autoId}-hint`;\n  const errorId = `${autoId}-error`;\n  const multiple = props.multiple === true;\n\n  const [values, setValues] = useControllable<readonly ComboboxOption[]>(\n    props.value === undefined ? undefined : multiple ? (props.value as readonly ComboboxOption[]) : props.value ? [props.value as ComboboxOption] : [],\n    multiple ? ((props.defaultValue as readonly ComboboxOption[]) ?? []) : props.defaultValue ? [props.defaultValue as ComboboxOption] : [],\n    (next) => (multiple ? (props.onValueChange as ((v: ComboboxOption[]) => void) | undefined)?.([...next]) : (props.onValueChange as ((v: ComboboxOption | null) => void) | undefined)?.(next[0] ?? null)),\n  );\n  const single = multiple ? null : (values[0] ?? null);\n  const [query, setQuery] = React.useState(single?.label ?? \"\");\n  const [editing, setEditing] = React.useState(false);\n  const [open, setOpenState] = React.useState(false);\n  const [remote, setRemote] = React.useState<{ query: string; options: readonly ComboboxOption[]; state: \"idle\" | \"loading\" | \"error\" }>({ query: \"\", options: [], state: \"idle\" });\n  const request = React.useRef<AbortController | null>(null);\n  const inputRef = React.useRef<HTMLInputElement>(null);\n\n  // The single choice's label shows in the input while the person is not typing.\n  const shownQuery = !multiple && !editing ? (single?.label ?? \"\") : query;\n  const searchQuery = editing ? query : \"\";\n\n  const search = useDebouncedCallback((text: string) => {\n    if (!onSearch) return;\n    request.current?.abort();\n    const controller = new AbortController();\n    request.current = controller;\n    onSearch(text, controller.signal).then(\n      (found) => !controller.signal.aborted && setRemote({ query: text, options: found, state: \"idle\" }),\n      () => !controller.signal.aborted && setRemote({ query: text, options: [], state: \"error\" }),\n    );\n  }, debounce);\n  React.useEffect(() => () => request.current?.abort(), []);\n\n  const setOpen = (next: boolean) => {\n    if (next && onSearch && remote.state === \"idle\" && remote.query !== searchQuery) {\n      setRemote((r) => ({ ...r, state: \"loading\" }));\n      search(searchQuery);\n    }\n    setOpenState(next);\n  };\n\n  const chosen = new Set(values.map((v) => v.value));\n  const source = onSearch ? remote.options : (options ?? []).filter((o) => !searchQuery.trim() || filter(o, searchQuery));\n  const full = multiple && props.maxSelected !== undefined && values.length >= props.maxSelected;\n  const trimmed = searchQuery.trim();\n  const exact = [...source, ...values].some((o) => fold(o.label) === fold(trimmed));\n  const items: Item[] = [\n    ...source.map((option) => ({ kind: \"option\" as const, option })),\n    ...(creatable && trimmed && !exact && !full ? [{ kind: \"create\" as const, query: trimmed }] : []),\n  ];\n  const isDisabled = (i: number) => {\n    const item = items[i];\n    if (!item) return true;\n    if (item.kind === \"create\") return false;\n    return Boolean(item.option.disabled) || (full && !chosen.has(item.option.value));\n  };\n\n  const commit = (option: ComboboxOption) => {\n    if (multiple) {\n      setValues(chosen.has(option.value) ? values.filter((v) => v.value !== option.value) : [...values, option]);\n      setQuery(\"\");\n      listbox.setActive(-1);\n    } else {\n      setValues([option]);\n      setQuery(option.label);\n      setEditing(false);\n      setOpenState(false);\n    }\n  };\n  const create = (text: string) => {\n    const clean = text.trim();\n    if (!clean || full) return;\n    const existing = [...source, ...values].find((o) => fold(o.label) === fold(clean));\n    if (multiple && existing && chosen.has(existing.value)) {\n      setQuery(\"\");\n      return;\n    }\n    commit(existing ?? onCreate(clean));\n  };\n  const pick = (i: number) => {\n    const item = items[i];\n    if (!item) return;\n    if (item.kind === \"create\") create(item.query);\n    else commit(item.option);\n  };\n\n  const listbox = useListbox({ count: items.length, isDisabled, onPick: pick, open, setOpen });\n\n  const onChange = (text: string) => {\n    setQuery(text);\n    setEditing(true);\n    listbox.setActive(-1);\n    if (onSearch) {\n      setRemote((r) => ({ ...r, state: \"loading\" }));\n      search(text);\n    }\n    setOpenState(true);\n    if (!multiple && text === \"\" && single) setValues([]);\n  };\n\n  const onKeyDown = (event: React.KeyboardEvent<HTMLInputElement>) => {\n    if (separators?.includes(event.key) && query.trim()) {\n      event.preventDefault();\n      create(query);\n      return;\n    }\n    if (listbox.onKeyDown(event)) return;\n    if (event.key === \"Enter\" && creatable && query.trim()) {\n      event.preventDefault();\n      create(query);\n    } else if (event.key === \"Backspace\" && multiple && query === \"\" && values.length > 0) {\n      setValues(values.slice(0, -1));\n    } else if (event.key === \"Escape\" && !multiple && editing) {\n      setEditing(false);\n      setQuery(single?.label ?? \"\");\n    }\n  };\n\n  const onPaste = (event: React.ClipboardEvent<HTMLInputElement>) => {\n    if (!separators?.length || !multiple) return;\n    const text = event.clipboardData.getData(\"text\");\n    const parts = text.split(new RegExp(`[${separators.map((c) => c.replace(/[\\\\\\]^-]/g, \"\\\\$&\")).join(\"\")}\\\\n]`)).map((p) => p.trim()).filter(Boolean);\n    if (parts.length < 2) return;\n    event.preventDefault();\n    const next = [...values];\n    for (const part of parts) {\n      if (props.maxSelected !== undefined && next.length >= props.maxSelected) break;\n      if (next.some((v) => fold(v.label) === fold(part))) continue;\n      next.push((options ?? []).find((o) => fold(o.label) === fold(part)) ?? onCreate(part));\n    }\n    setValues(next);\n  };\n\n  const loading = Boolean(onSearch) && remote.state === \"loading\";\n  const failed = Boolean(onSearch) && remote.state === \"error\";\n  const describedBy = [hint ? hintId : null, error ? errorId : null].filter(Boolean).join(\" \") || undefined;\n\n  return (\n    <div\n      className={s.root({ className })}\n      onBlur={(event) => {\n        if (event.currentTarget.contains(event.relatedTarget as Node | null)) return;\n        setOpenState(false);\n        if (!multiple) {\n          setEditing(false);\n          setQuery(single?.label ?? \"\");\n        }\n      }}\n    >\n      <label htmlFor={inputId} className={hideLabel ? \"sr-only\" : s.label()}>\n        {label}\n      </label>\n      <div className={s.control()} data-invalid={error ? \"\" : undefined} data-disabled={disabled ? \"\" : undefined} onMouseDown={(event) => {\n        if (event.target === event.currentTarget) {\n          event.preventDefault();\n          inputRef.current?.focus();\n        }\n      }}>\n        {multiple &&\n          values.map((option) => (\n            <Chip key={option.value} size=\"sm\" removable removeLabel={labels.remove(option.label)} disabled={disabled} onRemove={() => setValues(values.filter((v) => v.value !== option.value))}>\n              {option.label}\n            </Chip>\n          ))}\n        <input\n          ref={inputRef}\n          id={inputId}\n          type=\"text\"\n          autoComplete=\"off\"\n          spellCheck={false}\n          {...listbox.inputProps}\n          aria-describedby={describedBy}\n          aria-invalid={error ? true : undefined}\n          aria-busy={loading || undefined}\n          value={shownQuery}\n          placeholder={multiple && values.length > 0 ? undefined : placeholder}\n          disabled={disabled}\n          className={s.input()}\n          onChange={(event) => onChange(event.target.value)}\n          onKeyDown={onKeyDown}\n          onPaste={onPaste}\n          onClick={() => !open && setOpen(true)}\n        />\n        {!multiple && single && !disabled ? (\n          <button type=\"button\" aria-label={labels.clear} className={s.icon()} onClick={() => {\n            setValues([]);\n            setQuery(\"\");\n            inputRef.current?.focus();\n          }}>\n            <CloseGlyph className=\"h-4 w-4\" />\n          </button>\n        ) : null}\n        <button type=\"button\" tabIndex={-1} aria-label={labels.toggle} aria-expanded={open} aria-controls={listbox.listId} disabled={disabled} className={s.icon()} onClick={() => {\n          setOpen(!open);\n          inputRef.current?.focus();\n        }}>\n          <ChevronGlyph direction={open ? \"up\" : \"down\"} className=\"h-4 w-4\" />\n        </button>\n      </div>\n      {name && values.map((v) => <input key={v.value} type=\"hidden\" name={name} value={v.value} />)}\n      <div id={listbox.listId} role=\"listbox\" aria-label={label} aria-multiselectable={multiple || undefined} hidden={!open || (items.length === 0 && !loading && !failed && !labels.empty)} className={s.list()}>\n        {open && loading && items.length === 0 ? <div className={s.status()}>{labels.loading}</div> : null}\n        {open && failed ? <div className={s.status()}>{labels.error}</div> : null}\n        {open && !loading && !failed && items.length === 0 && labels.empty ? <div className={s.status()}>{labels.empty}</div> : null}\n        {open &&\n          items.map((item, i) =>\n            item.kind === \"create\" ? (\n              <div key=\"__create\" {...listbox.optionProps(i, false)} className={s.option()}>\n                <PlusGlyph className={s.check()} />\n                {labels.create(item.query)}\n              </div>\n            ) : (\n              <div key={item.option.value} {...listbox.optionProps(i, chosen.has(item.option.value))} className={s.option()}>\n                <span className=\"flex h-4 w-4 shrink-0 items-center justify-center\">{chosen.has(item.option.value) ? <CheckGlyph className={s.check()} /> : null}</span>\n                <span className=\"min-w-0 flex-1\">\n                  {item.option.label}\n                  {item.option.description ? <span className={s.description()}>{item.option.description}</span> : null}\n                </span>\n              </div>\n            ),\n          )}\n      </div>\n      <span className=\"sr-only\" aria-live=\"polite\" aria-atomic>\n        {open && !loading ? labels.results(items.length) : \"\"}\n      </span>\n      {hint ? (\n        <p id={hintId} className={s.hint()}>\n          {hint}\n        </p>\n      ) : null}\n      {error ? (\n        <p id={errorId} className={s.error()}>\n          {error}\n        </p>\n      ) : null}\n    </div>\n  );\n}\n"
+    },
+    {
+      "path": "combobox/index.ts",
+      "content": "/** @krizaka/ui/combobox — `Combobox` (autocomplete: one value or several in chips, static or fetched, creatable), `combobox` (the slots). Client (\"use client\"). */\nexport { Combobox, combobox, type ComboboxLabels, comboboxLabels, type ComboboxOption, type ComboboxProps } from \"./combobox\";\n"
+    },
+    {
+      "path": "combobox/meta.ts",
+      "content": "import type { ComponentMeta } from \"../meta\";\n\nexport const meta = {\n  title: \"Combobox\",\n  summary: \"A text field that suggests and completes — one value or several as chips, from a static list or a server, with values created from what was typed.\",\n  status: \"beta\",\n  category: \"forms\",\n  platforms: \"web\",\n  whenToUse: [\n    \"To choose among many values the person knows by name: a creator, a country, a model, a playlist.\",\n    \"With `onSearch` when the values live on a server (debounced, the previous request aborted).\",\n    \"With `multiple` for several values (collaborators, categories), and `creatable` when a new one can be added.\",\n  ],\n  whenNotToUse: [\n    { when: \"For fewer than about seven options known in advance: radios or a select.\", use: \"radio-group\" },\n    { when: \"For free words without a closed list (tags, keywords): a tag input.\", use: \"tag-input\" },\n    { when: \"To run a search and show results: a search field.\", use: \"search-field\" },\n  ],\n  bestPractices: [\n    \"Write `label` as the question (“Collaborators”), the `placeholder` as an example (“Type a name”).\",\n    \"Return at most 20 options from `onSearch`; put the best match first.\",\n    \"Give options a `description` when names collide (two creators named Eric: their handles).\",\n    \"Set `maxSelected` when the product has a limit, and say it in `hint`.\",\n  ],\n  accessibility: {\n    keyboard: [\n      { keys: \"Arrow Down / Arrow Up\", action: \"Open the list and move the active option.\" },\n      { keys: \"Home / End\", action: \"First or last option, when the list is open.\" },\n      { keys: \"Enter\", action: \"Choose the active option (or create the typed value).\" },\n      { keys: \"Esc\", action: \"Close the list; for one value, restore its label.\" },\n      { keys: \"Backspace\", action: \"In an empty input, remove the last chip.\" },\n    ],\n    notes: [\n      \"The ARIA 1.2 combobox pattern: the focus stays in the input, `aria-activedescendant` points at the active option of the `listbox`.\",\n      \"The number of results is announced in a polite live region (`labels.results`).\",\n      \"Chosen options carry `aria-selected`; each chip's remove button is named (“Remove Eric”).\",\n      \"The label is a real `<label>`; `hint` and `error` are wired with `aria-describedby`, `error` sets `aria-invalid`.\",\n    ],\n  },\n  related: [\"tag-input\", \"search-field\", \"field\", \"chip\", \"command\"],\n  web: {\n    imports: [\"Combobox\"],\n    examples: [\n      { name: \"async\", title: \"From a server\", description: \"`onSearch`: creators fetched as you type, debounced, the stale request aborted.\" },\n      { name: \"multiple\", title: \"Several values\", description: \"Collaborators as chips; Backspace removes the last one, at most three.\" },\n      { name: \"creatable\", title: \"Create a value\", description: \"Pick a playlist or create one from what was typed.\" },\n      { name: \"invalid\", title: \"With an error\", description: \"A required choice left empty: the error is read with the field.\" },\n    ],\n  },\n} satisfies ComponentMeta;\n"
+    },
+    {
+      "path": "glyphs.tsx",
+      "content": "// The small line glyphs the data and media primitives draw (play, volume, search, chevrons…): decorative, 24-unit\n// box, `currentColor`, sized by the caller's class. Shared by the entries that need them; never exported on its own —\n// a product draws its own icons with @krizaka/icons.\nimport type * as React from \"react\";\n\ntype GlyphProps = { className?: string };\n\nfunction Glyph({ className = \"h-4 w-4\", fill, children }: GlyphProps & { fill?: boolean; children: React.ReactNode }) {\n  return (\n    <svg\n      viewBox=\"0 0 24 24\"\n      className={className}\n      fill={fill ? \"currentColor\" : \"none\"}\n      stroke={fill ? \"none\" : \"currentColor\"}\n      strokeWidth=\"2\"\n      strokeLinecap=\"round\"\n      strokeLinejoin=\"round\"\n      aria-hidden\n      focusable=\"false\"\n    >\n      {children}\n    </svg>\n  );\n}\n\nexport const PlayGlyph = (p: GlyphProps) => (\n  <Glyph {...p} fill>\n    <path d=\"M8 5.5v13a1 1 0 0 0 1.5.86l10.4-6.5a1 1 0 0 0 0-1.72L9.5 4.64A1 1 0 0 0 8 5.5Z\" />\n  </Glyph>\n);\nexport const PauseGlyph = (p: GlyphProps) => (\n  <Glyph {...p} fill>\n    <rect x=\"6\" y=\"5\" width=\"4\" height=\"14\" rx=\"1\" />\n    <rect x=\"14\" y=\"5\" width=\"4\" height=\"14\" rx=\"1\" />\n  </Glyph>\n);\nexport const VolumeGlyph = ({ muted, ...p }: GlyphProps & { muted?: boolean }) => (\n  <Glyph {...p}>\n    <path d=\"M11 5 6 9H3v6h3l5 4V5Z\" />\n    {muted ? <path d=\"m22 9-6 6m0-6 6 6\" /> : <path d=\"M15.5 8.5a5 5 0 0 1 0 7M18.5 5.5a9 9 0 0 1 0 13\" />}\n  </Glyph>\n);\nexport const FullscreenGlyph = ({ exit, ...p }: GlyphProps & { exit?: boolean }) => (\n  <Glyph {...p}>\n    {exit ? <path d=\"M9 4v5H4m11-5v5h5M9 20v-5H4m11 5v-5h5\" /> : <path d=\"M4 9V4h5m6 0h5v5M4 15v5h5m11-5v5h-5\" />}\n  </Glyph>\n);\nexport const CaptionsGlyph = (p: GlyphProps) => (\n  <Glyph {...p}>\n    <rect x=\"3\" y=\"5\" width=\"18\" height=\"14\" rx=\"2\" />\n    <path d=\"M10 10.5a2 2 0 1 0 0 3M17 10.5a2 2 0 1 0 0 3\" />\n  </Glyph>\n);\nexport const PipGlyph = (p: GlyphProps) => (\n  <Glyph {...p}>\n    <rect x=\"3\" y=\"5\" width=\"18\" height=\"14\" rx=\"2\" />\n    <rect x=\"12\" y=\"12\" width=\"6\" height=\"4\" rx=\"1\" />\n  </Glyph>\n);\nexport const SearchGlyph = (p: GlyphProps) => (\n  <Glyph {...p}>\n    <circle cx=\"11\" cy=\"11\" r=\"7\" />\n    <path d=\"m20 20-3.5-3.5\" />\n  </Glyph>\n);\nexport const CloseGlyph = (p: GlyphProps) => (\n  <Glyph {...p}>\n    <path d=\"M18 6 6 18M6 6l12 12\" />\n  </Glyph>\n);\nexport const ChevronGlyph = ({ direction = \"down\", ...p }: GlyphProps & { direction?: \"left\" | \"right\" | \"up\" | \"down\" }) => (\n  <Glyph {...p}>\n    <path d={{ left: \"m15 6-6 6 6 6\", right: \"m9 6 6 6-6 6\", up: \"m6 15 6-6 6 6\", down: \"m6 9 6 6 6-6\" }[direction]} />\n  </Glyph>\n);\nexport const CheckGlyph = (p: GlyphProps) => (\n  <Glyph {...p}>\n    <path d=\"M20 6 9 17l-5-5\" />\n  </Glyph>\n);\nexport const PlusGlyph = (p: GlyphProps) => (\n  <Glyph {...p}>\n    <path d=\"M12 5v14M5 12h14\" />\n  </Glyph>\n);\nexport const CalendarGlyph = (p: GlyphProps) => (\n  <Glyph {...p}>\n    <rect x=\"3\" y=\"5\" width=\"18\" height=\"16\" rx=\"2\" />\n    <path d=\"M3 10h18M8 3v4M16 3v4\" />\n  </Glyph>\n);\nexport const UploadGlyph = (p: GlyphProps) => (\n  <Glyph {...p}>\n    <path d=\"M12 16V4m0 0L7 9m5-5 5 5\" />\n    <path d=\"M4 16v2a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2v-2\" />\n  </Glyph>\n);\nexport const FileGlyph = (p: GlyphProps) => (\n  <Glyph {...p}>\n    <path d=\"M14 3H7a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h10a2 2 0 0 0 2-2V8l-5-5Z\" />\n    <path d=\"M14 3v5h5\" />\n  </Glyph>\n);\nexport const CameraGlyph = (p: GlyphProps) => (\n  <Glyph {...p}>\n    <path d=\"M4 8h3l2-3h6l2 3h3a1 1 0 0 1 1 1v10a1 1 0 0 1-1 1H4a1 1 0 0 1-1-1V9a1 1 0 0 1 1-1Z\" />\n    <circle cx=\"12\" cy=\"13.5\" r=\"3.5\" />\n  </Glyph>\n);\nexport const FlipGlyph = (p: GlyphProps) => (\n  <Glyph {...p}>\n    <path d=\"M4 12a8 8 0 0 1 14-5.3M20 12a8 8 0 0 1-14 5.3\" />\n    <path d=\"M18 3v4h-4M6 21v-4h4\" />\n  </Glyph>\n);\nexport const RetryGlyph = (p: GlyphProps) => (\n  <Glyph {...p}>\n    <path d=\"M4 12a8 8 0 1 0 2.3-5.7L4 8.5\" />\n    <path d=\"M4 4v4.5h4.5\" />\n  </Glyph>\n);\nexport const SortGlyph = ({ direction, ...p }: GlyphProps & { direction?: \"ascending\" | \"descending\" }) => (\n  <Glyph {...p}>\n    {direction === \"ascending\" ? <path d=\"m7 14 5-5 5 5\" /> : direction === \"descending\" ? <path d=\"m7 10 5 5 5-5\" /> : <path d=\"m8 9 4-4 4 4M8 15l4 4 4-4\" />}\n  </Glyph>\n);\n"
+    },
+    {
+      "path": "listbox.ts",
+      "content": "// The ARIA 1.2 combobox engine shared by `combobox`, `tag-input` and `search-field` (client): the focus stays in the\n// text input, the active option is pointed at by `aria-activedescendant`, the arrows walk the enabled options, Enter\n// picks, Escape closes. The caller renders the input and the options; this hook gives them their ARIA and keys.\nimport * as React from \"react\";\n\nexport type ListboxOptions = {\n  /** How many options are shown. */\n  count: number;\n  /** Whether option `i` can be picked. */\n  isDisabled?: (index: number) => boolean;\n  /** Called when option `i` is picked (Enter or a click). */\n  onPick: (index: number) => void;\n  /** Whether the list is shown. */\n  open: boolean;\n  /** Opens or closes the list. */\n  setOpen: (open: boolean) => void;\n};\n\nexport function useListbox({ count, isDisabled = () => false, onPick, open, setOpen }: ListboxOptions) {\n  const id = React.useId();\n  const listId = `${id}-list`;\n  const [chosen, setActive] = React.useState(-1);\n  // The active option is cleared when the list closes and stays inside it when it shrinks.\n  const active = open ? Math.min(chosen, count - 1) : -1;\n  const optionId = (index: number) => `${id}-opt-${index}`;\n\n  const step = (from: number, delta: 1 | -1) => {\n    for (let i = 1; i <= count; i += 1) {\n      const next = (from + delta * i + count * 2) % count;\n      if (!isDisabled(next)) return next;\n    }\n    return -1;\n  };\n  const first = () => step(-1, 1);\n  const last = () => step(count, -1);\n\n  /** Keys of the text input. Returns `true` when the key was handled (the caller then does nothing else with it). */\n  const onKeyDown = (event: React.KeyboardEvent): boolean => {\n    switch (event.key) {\n      case \"ArrowDown\":\n        event.preventDefault();\n        if (!open) {\n          setOpen(true);\n          setActive(event.altKey ? -1 : first());\n        } else setActive(active < 0 ? first() : step(active, 1));\n        return true;\n      case \"ArrowUp\":\n        event.preventDefault();\n        if (!open) {\n          setOpen(true);\n          setActive(last());\n        } else setActive(active < 0 ? last() : step(active, -1));\n        return true;\n      case \"Home\":\n      case \"End\":\n        if (!open || count === 0) return false;\n        event.preventDefault();\n        setActive(event.key === \"Home\" ? first() : last());\n        return true;\n      case \"Enter\":\n        if (!open || active < 0) return false;\n        event.preventDefault();\n        onPick(active);\n        return true;\n      case \"Escape\":\n        if (!open) return false;\n        event.preventDefault();\n        event.stopPropagation();\n        setOpen(false);\n        return true;\n      case \"Tab\":\n        if (open) setOpen(false);\n        return false;\n      default:\n        return false;\n    }\n  };\n\n  // Keeps the active option in view while the arrows walk a long list.\n  React.useEffect(() => {\n    if (active < 0 || typeof document === \"undefined\") return;\n    document.getElementById(`${id}-opt-${active}`)?.scrollIntoView?.({ block: \"nearest\" });\n  }, [active, id]);\n\n  return {\n    listId,\n    active,\n    setActive,\n    optionId,\n    onKeyDown,\n    /** The ARIA of the text input. */\n    inputProps: {\n      role: \"combobox\" as const,\n      \"aria-expanded\": open,\n      \"aria-controls\": listId,\n      \"aria-autocomplete\": \"list\" as const,\n      \"aria-activedescendant\": open && active >= 0 ? optionId(active) : undefined,\n    },\n    /** The ARIA and pointer handlers of option `i` (a mouse down keeps the focus in the input). */\n    optionProps: (index: number, selected: boolean) => ({\n      id: optionId(index),\n      role: \"option\" as const,\n      \"aria-selected\": selected,\n      \"aria-disabled\": isDisabled(index) || undefined,\n      \"data-active\": index === active ? \"\" : undefined,\n      onMouseDown: (event: React.MouseEvent) => event.preventDefault(),\n      onMouseMove: () => !isDisabled(index) && index !== active && setActive(index),\n      onClick: () => !isDisabled(index) && onPick(index),\n    }),\n  };\n}\n"
+    },
+    {
+      "path": "media.ts",
+      "content": "// Shared by the data and media primitives (client): the clock format, the reduced-motion preference, the\n// in-view observer, a debounced callback. Never an entry of its own.\nimport * as React from \"react\";\n\n/** Seconds as a clock: `75` → `1:15`, `3725` → `1:02:05`. Negative or unknown values read `0:00`. */\nexport function formatClock(seconds: number): string {\n  const s = Number.isFinite(seconds) && seconds > 0 ? Math.floor(seconds) : 0;\n  const h = Math.floor(s / 3600);\n  const m = Math.floor((s % 3600) / 60);\n  const rest = String(s % 60).padStart(2, \"0\");\n  return h > 0 ? `${h}:${String(m).padStart(2, \"0\")}:${rest}` : `${m}:${rest}`;\n}\n\n/** Clamps `value` between `min` and `max`. */\nexport const clamp = (value: number, min: number, max: number) => Math.min(max, Math.max(min, value));\n\nconst REDUCE = \"(prefers-reduced-motion: reduce)\";\nconst subscribeReduce = (notify: () => void) => {\n  if (typeof window === \"undefined\" || !window.matchMedia) return () => undefined;\n  const query = window.matchMedia(REDUCE);\n  query.addEventListener?.(\"change\", notify);\n  return () => query.removeEventListener?.(\"change\", notify);\n};\n\n/** `true` when the person asked for less motion (`prefers-reduced-motion: reduce`); follows a change of the setting. */\nexport function usePrefersReducedMotion(): boolean {\n  return React.useSyncExternalStore(\n    subscribeReduce,\n    () => (typeof window !== \"undefined\" && window.matchMedia ? window.matchMedia(REDUCE).matches : false),\n    () => false,\n  );\n}\n\n/** The latest value of a callback, for an effect or an event that must not re-subscribe when it changes. */\nexport function useLatest<T>(value: T) {\n  const ref = React.useRef(value);\n  React.useLayoutEffect(() => {\n    ref.current = value;\n  });\n  return ref;\n}\n\n/** Calls `onChange(visible)` when at least `threshold` of the element enters or leaves the viewport. */\nexport function useInView(ref: React.RefObject<Element | null>, onChange: (visible: boolean) => void, enabled = true, threshold = 0.25) {\n  const latest = useLatest(onChange);\n  React.useEffect(() => {\n    const element = ref.current;\n    if (!enabled || !element || typeof IntersectionObserver === \"undefined\") return;\n    const observer = new IntersectionObserver(([entry]) => entry && latest.current(entry.isIntersecting), { threshold });\n    observer.observe(element);\n    return () => observer.disconnect();\n  }, [ref, enabled, threshold, latest]);\n}\n\n/** A stable function that runs `callback` once `delay` ms have passed without a new call; `cancel()` drops the pending one. */\nexport function useDebouncedCallback<A extends unknown[]>(callback: (...args: A) => void, delay: number) {\n  const latest = useLatest(callback);\n  const [debounced] = React.useState(() => {\n    let timer: ReturnType<typeof setTimeout> | undefined;\n    let wait = delay;\n    const run = (...args: A) => {\n      clearTimeout(timer);\n      if (wait <= 0) latest.current(...args);\n      else timer = setTimeout(() => latest.current(...args), wait);\n    };\n    return Object.assign(run, {\n      cancel: () => clearTimeout(timer),\n      setDelay: (next: number) => {\n        wait = next;\n      },\n    });\n  });\n  React.useEffect(() => debounced.setDelay(delay), [debounced, delay]);\n  React.useEffect(() => () => debounced.cancel(), [debounced]);\n  return debounced;\n}\n\n/** A value controlled by a prop when it is given, held inside otherwise; `set` calls `onChange` either way. */\nexport function useControllable<T>(value: T | undefined, defaultValue: T, onChange?: (next: T) => void) {\n  const [inner, setInner] = React.useState(defaultValue);\n  const controlled = value !== undefined;\n  const current = controlled ? value : inner;\n  const set = React.useCallback(\n    (next: T) => {\n      if (!controlled) setInner(next);\n      onChange?.(next);\n    },\n    [controlled, onChange],\n  );\n  return [current, set] as const;\n}\n\n/** Starts a media element without an unhandled rejection (autoplay refused, the source replaced meanwhile). */\nexport function playSafely(media: HTMLMediaElement | null | undefined) {\n  try {\n    const started = media?.play() as Promise<void> | undefined;\n    started?.catch?.(() => undefined);\n  } catch {\n    // Not playable here (no media support): the controls stay as they are.\n  }\n}\n"
+    },
+    {
+      "path": "meta.ts",
+      "content": "// The documentation of a component, carried by its code: each primitive has a `meta.ts` beside its source\n// (`src/<name>/meta.ts`; a component that exists only in React Native: `src/native/meta/<name>.ts`). Never built into\n// the package: `scripts/build-registry.mjs` reads them into `registry/<name>.json`, which krizaka.com renders as\n// /docs/ui/<name>, and `scripts/registry.test.mjs` fails when one is missing or incomplete.\n//\n// Why a typed module and not JSDoc tags: the fields are lists and links (`related`, `whenNotToUse[].use`, examples),\n// which a type checks and a comment does not; the file is plain data (erasable TypeScript), so Node reads it without a\n// compiler, and an editor completes it.\n\n/** Every documented component: the web primitives (one entry of the package each) and the native-only ones. */\nexport type ComponentName =\n  | \"alert\"\n  | \"audio-player\"\n  | \"avatar\"\n  | \"badge\"\n  | \"button\"\n  | \"card\"\n  | \"checkbox\"\n  | \"chip\"\n  | \"chip-link\"\n  | \"cn\"\n  | \"combobox\"\n  | \"command\"\n  | \"confirm-button\"\n  | \"countdown\"\n  | \"data-table\"\n  | \"date-picker\"\n  | \"dialog\"\n  | \"dropdown-menu\"\n  | \"empty-state\"\n  | \"field\"\n  | \"file-upload\"\n  | \"filter-bar\"\n  | \"glow-card\"\n  | \"image-cropper\"\n  | \"iso\"\n  | \"kbd\"\n  | \"loader\"\n  | \"marquee\"\n  | \"mascots\"\n  | \"media-capture\"\n  | \"meter\"\n  | \"nav-bar\"\n  | \"number-ticker\"\n  | \"page-header\"\n  | \"pagination\"\n  | \"popover\"\n  | \"progress\"\n  | \"radio-group\"\n  | \"search-field\"\n  | \"section-backdrop\"\n  | \"segmented\"\n  | \"separator\"\n  | \"skeleton\"\n  | \"slider\"\n  | \"slot\"\n  | \"spinner\"\n  | \"stat\"\n  | \"stepper\"\n  | \"switch\"\n  | \"tabs\"\n  | \"tag-input\"\n  | \"theme\"\n  | \"toast\"\n  | \"tooltip\"\n  | \"txt\"\n  | \"video-player\"\n  | \"video-trimmer\";\n\n/** Where a component exists: `@krizaka/ui/<name>` (web), `@krizaka/ui/native` (React Native), or both. */\nexport type Platform = \"web\" | \"native\" | \"both\";\n\n/** `stable`: its API only changes in a major. `beta`: it may still change in a minor. */\nexport type Status = \"stable\" | \"beta\";\n\n/** The group of the catalogue. `media`: video, sound, camera, files, cropping. */\nexport type Category = \"actions\" | \"forms\" | \"navigation\" | \"overlays\" | \"feedback\" | \"data-display\" | \"media\" | \"layout\" | \"foundations\";\n\n/**\n * A named example: the file `registry/examples/<component>/<name>.tsx` (web) or\n * `registry/examples/<component>/native/<name>.tsx` (React Native) — at most 40 lines, imported by the stories and\n * shown (live, with its code) by the documentation.\n */\nexport interface Example {\n  /** The file name, kebab-case (`primary`, `icon-button`). */\n  readonly name: string;\n  /** A short title (`Primary`, `Icon button`). */\n  readonly title: string;\n  /** One or two sentences: when this variant is the right one. */\n  readonly description: string;\n}\n\n/** One platform's side of a component. */\nexport interface PlatformDocs {\n  /** The names to import (`[\"Button\", \"IconButton\"]`): from `@krizaka/ui/<name>` on the web, `@krizaka/ui/native` in React Native. */\n  readonly imports: readonly string[];\n  /** The examples, in reading order; the first one is the component's preview. */\n  readonly examples: readonly Example[];\n}\n\n/** The React Native side: the same concept, and what differs from the web API. */\nexport interface NativeDocs extends PlatformDocs {\n  /**\n   * The entry to import from when it is not `@krizaka/ui/native`: a component that needs an Expo module (an optional\n   * peer) has its own, `@krizaka/ui/native/<name>`, so an app that does not use it never installs the module.\n   */\n  readonly entry?: string;\n  /** What differs from the web API (`label` instead of children…); empty for a native-only component. */\n  readonly differences: readonly string[];\n}\n\nexport interface KeyboardInteraction {\n  /** The keys, as written on a keyboard: `Space`, `Enter`, `Arrow keys`, `Esc`, `Tab`. */\n  readonly keys: string;\n  /** What they do. */\n  readonly action: string;\n}\n\nexport interface ComponentMeta {\n  /** The display name: `Button`, `Dropdown menu`. */\n  readonly title: string;\n  /** One sentence: what it is. */\n  readonly summary: string;\n  readonly status: Status;\n  readonly category: Category;\n  /** Must match the sides below: `both` ⇔ `web` and `native`. */\n  readonly platforms: Platform;\n  /** When to reach for it: concrete situations, one per item. */\n  readonly whenToUse: readonly string[];\n  /** When not to — and what to use instead (`use`), when another component is the answer. */\n  readonly whenNotToUse: readonly { readonly when: string; readonly use?: ComponentName }[];\n  /** How to use it well: wording, placement, composition. */\n  readonly bestPractices: readonly string[];\n  readonly accessibility: {\n    /** The keyboard, when it does more than Tab and Enter. */\n    readonly keyboard: readonly KeyboardInteraction[];\n    /** Roles, names and announcements: what the component does, what the app must provide. */\n    readonly notes: readonly string[];\n  };\n  /** The components a reader of this page should know about. */\n  readonly related: readonly ComponentName[];\n  readonly web?: PlatformDocs;\n  readonly native?: NativeDocs;\n}\n"
+    }
+  ],
+  "dependencies": [
+    "tailwind-variants@^3.3.1"
+  ],
+  "registryDependencies": [
+    "chip"
+  ],
+  "demo": {
+    "path": "examples/combobox/async.tsx",
+    "content": "\"use client\";\n\nimport { Combobox, type ComboboxOption } from \"@krizaka/ui/combobox\";\n\nconst CREATORS: ComboboxOption[] = [\n  { value: \"u1\", label: \"Eric Tremblay\", description: \"@eric.films\" },\n  { value: \"u2\", label: \"Erica Moreau\", description: \"@erica\" },\n  { value: \"u3\", label: \"Inès Haddad\", description: \"@ines.draws\" },\n  { value: \"u4\", label: \"Jonas Weber\", description: \"@jonas\" },\n];\n\n// Your API in place of this one: it receives the query and an AbortSignal.\nasync function searchCreators(query: string, signal: AbortSignal) {\n  await new Promise((resolve) => setTimeout(resolve, 300));\n  if (signal.aborted) return [];\n  const q = query.toLowerCase();\n  return CREATORS.filter((c) => c.label.toLowerCase().includes(q) || c.description?.includes(q));\n}\n\nexport default function ComboboxAsync() {\n  return <Combobox label=\"Creator\" placeholder=\"Type a name or a handle\" onSearch={searchCreators} />;\n}\n"
+  },
+  "props": [
+    {
+      "component": "Combobox",
+      "description": "A text field that suggests, filters and completes: one value or several (chips), static or fetched, creatable.",
+      "props": [
+        {
+          "name": "label",
+          "type": "string",
+          "default": null,
+          "description": "The visible label of the field, passed translated (also its accessible name).",
+          "required": true
+        },
+        {
+          "name": "className",
+          "type": "string",
+          "default": null,
+          "description": "Classes merged on the root.",
+          "required": false
+        },
+        {
+          "name": "creatable",
+          "type": "boolean",
+          "default": null,
+          "description": "Offers to create the query as a new value when no option has that exact label.",
+          "required": false
+        },
+        {
+          "name": "debounce",
+          "type": "number",
+          "default": null,
+          "description": "The wait, in ms, between the last key and `onSearch`. Default 250.",
+          "required": false
+        },
+        {
+          "name": "defaultValue",
+          "type": "ComboboxOption | readonly ComboboxOption[] | null",
+          "default": null,
+          "description": "The chosen option at first, uncontrolled.\nThe chosen options at first, uncontrolled.",
+          "required": false
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "default": null,
+          "description": "Not available.",
+          "required": false
+        },
+        {
+          "name": "error",
+          "type": "string",
+          "default": null,
+          "description": "An error under the field: marks it invalid and is read with it.",
+          "required": false
+        },
+        {
+          "name": "filter",
+          "type": "((option: ComboboxOption, query: string) => boolean)",
+          "default": null,
+          "description": "Whether an option matches a query. Default: its label contains the query, ignoring case and accents.",
+          "required": false
+        },
+        {
+          "name": "hideLabel",
+          "type": "boolean",
+          "default": null,
+          "description": "Hides the label visually, keeping it as the accessible name (a search bar with its own context).",
+          "required": false
+        },
+        {
+          "name": "hint",
+          "type": "string",
+          "default": null,
+          "description": "A help text under the field.",
+          "required": false
+        },
+        {
+          "name": "id",
+          "type": "string",
+          "default": null,
+          "description": "The id of the text input (default: generated).",
+          "required": false
+        },
+        {
+          "name": "labels",
+          "type": "Partial<ComboboxLabels>",
+          "default": null,
+          "description": "The words, passed translated; English by default.",
+          "required": false
+        },
+        {
+          "name": "maxSelected",
+          "type": "number",
+          "default": null,
+          "description": "Most options that can be chosen (several values only).\nMost options that can be chosen; the list stops offering more past it.",
+          "required": false
+        },
+        {
+          "name": "multiple",
+          "type": "boolean",
+          "default": null,
+          "description": "One value (default) or several.\nSeveral values, shown as chips.",
+          "required": false
+        },
+        {
+          "name": "name",
+          "type": "string",
+          "default": null,
+          "description": "The name of a hidden input holding the value(s), for a plain `<form>` post.",
+          "required": false
+        },
+        {
+          "name": "onCreate",
+          "type": "((query: string) => ComboboxOption)",
+          "default": null,
+          "description": "Turns a query into the created option (an id from the server…). Default `{ value: query, label: query }`.",
+          "required": false
+        },
+        {
+          "name": "onSearch",
+          "type": "((query: string, signal: AbortSignal) => Promise<readonly ComboboxOption[]>)",
+          "default": null,
+          "description": "Fetches the options for a query (debounced by `debounce`); the `signal` aborts when a newer query starts.",
+          "required": false
+        },
+        {
+          "name": "onValueChange",
+          "type": "((value: ComboboxOption | null) => void) | ((value: ComboboxOption[]) => void)",
+          "default": null,
+          "description": "Called with the chosen option, or `null` when it is cleared.\nCalled with every chosen option.",
+          "required": false
+        },
+        {
+          "name": "options",
+          "type": "readonly ComboboxOption[]",
+          "default": null,
+          "description": "The options, filtered as the person types (by `filter`).",
+          "required": false
+        },
+        {
+          "name": "placeholder",
+          "type": "string",
+          "default": null,
+          "description": "The input's placeholder, passed translated.",
+          "required": false
+        },
+        {
+          "name": "separators",
+          "type": "readonly string[]",
+          "default": null,
+          "description": "Keys that create the query at once, as Enter does (`[\",\"]` for tags); a paste is split on them too.",
+          "required": false
+        },
+        {
+          "name": "value",
+          "type": "ComboboxOption | readonly ComboboxOption[] | null",
+          "default": null,
+          "description": "The chosen option (controlled), `null` for none.\nThe chosen options (controlled).",
+          "required": false
+        }
+      ]
+    }
+  ]
+}

package/registry/command.json

@@ -243,7 +243,7 @@
     },
     {
       "path": "meta.ts",
-      "content": "// The documentation of a component, carried by its code: each primitive has a `meta.ts` beside its source\n// (`src/<name>/meta.ts`; a component that exists only in React Native: `src/native/meta/<name>.ts`). Never built into\n// the package: `scripts/build-registry.mjs` reads them into `registry/<name>.json`, which krizaka.com renders as\n// /docs/ui/<name>, and `scripts/registry.test.mjs` fails when one is missing or incomplete.\n//\n// Why a typed module and not JSDoc tags: the fields are lists and links (`related`, `whenNotToUse[].use`, examples),\n// which a type checks and a comment does not; the file is plain data (erasable TypeScript), so Node reads it without a\n// compiler, and an editor completes it.\n\n/** Every documented component: the web primitives (one entry of the package each) and the native-only ones. */\nexport type ComponentName =\n  | \"alert\"\n  | \"avatar\"\n  | \"badge\"\n  | \"button\"\n  | \"card\"\n  | \"checkbox\"\n  | \"chip\"\n  | \"cn\"\n  | \"command\"\n  | \"confirm-button\"\n  | \"countdown\"\n  | \"dialog\"\n  | \"dropdown-menu\"\n  | \"empty-state\"\n  | \"field\"\n  | \"kbd\"\n  | \"mascots\"\n  | \"page-header\"\n  | \"popover\"\n  | \"progress\"\n  | \"radio-group\"\n  | \"section-backdrop\"\n  | \"segmented\"\n  | \"separator\"\n  | \"skeleton\"\n  | \"slider\"\n  | \"slot\"\n  | \"spinner\"\n  | \"stat\"\n  | \"switch\"\n  | \"tabs\"\n  | \"theme\"\n  | \"toast\"\n  | \"tooltip\"\n  | \"txt\";\n\n/** Where a component exists: `@krizaka/ui/<name>` (web), `@krizaka/ui/native` (React Native), or both. */\nexport type Platform = \"web\" | \"native\" | \"both\";\n\n/** `stable`: its API only changes in a major. `beta`: it may still change in a minor. */\nexport type Status = \"stable\" | \"beta\";\n\n/** The group of the catalogue. */\nexport type Category = \"actions\" | \"forms\" | \"navigation\" | \"overlays\" | \"feedback\" | \"data-display\" | \"layout\" | \"foundations\";\n\n/**\n * A named example: the file `registry/examples/<component>/<name>.tsx` (web) or\n * `registry/examples/<component>/native/<name>.tsx` (React Native) — at most 40 lines, imported by the stories and\n * shown (live, with its code) by the documentation.\n */\nexport interface Example {\n  /** The file name, kebab-case (`primary`, `icon-button`). */\n  readonly name: string;\n  /** A short title (`Primary`, `Icon button`). */\n  readonly title: string;\n  /** One or two sentences: when this variant is the right one. */\n  readonly description: string;\n}\n\n/** One platform's side of a component. */\nexport interface PlatformDocs {\n  /** The names to import (`[\"Button\", \"IconButton\"]`): from `@krizaka/ui/<name>` on the web, `@krizaka/ui/native` in React Native. */\n  readonly imports: readonly string[];\n  /** The examples, in reading order; the first one is the component's preview. */\n  readonly examples: readonly Example[];\n}\n\n/** The React Native side: the same concept, and what differs from the web API. */\nexport interface NativeDocs extends PlatformDocs {\n  /** What differs from the web API (`label` instead of children…); empty for a native-only component. */\n  readonly differences: readonly string[];\n}\n\nexport interface KeyboardInteraction {\n  /** The keys, as written on a keyboard: `Space`, `Enter`, `Arrow keys`, `Esc`, `Tab`. */\n  readonly keys: string;\n  /** What they do. */\n  readonly action: string;\n}\n\nexport interface ComponentMeta {\n  /** The display name: `Button`, `Dropdown menu`. */\n  readonly title: string;\n  /** One sentence: what it is. */\n  readonly summary: string;\n  readonly status: Status;\n  readonly category: Category;\n  /** Must match the sides below: `both` ⇔ `web` and `native`. */\n  readonly platforms: Platform;\n  /** When to reach for it: concrete situations, one per item. */\n  readonly whenToUse: readonly string[];\n  /** When not to — and what to use instead (`use`), when another component is the answer. */\n  readonly whenNotToUse: readonly { readonly when: string; readonly use?: ComponentName }[];\n  /** How to use it well: wording, placement, composition. */\n  readonly bestPractices: readonly string[];\n  readonly accessibility: {\n    /** The keyboard, when it does more than Tab and Enter. */\n    readonly keyboard: readonly KeyboardInteraction[];\n    /** Roles, names and announcements: what the component does, what the app must provide. */\n    readonly notes: readonly string[];\n  };\n  /** The components a reader of this page should know about. */\n  readonly related: readonly ComponentName[];\n  readonly web?: PlatformDocs;\n  readonly native?: NativeDocs;\n}\n"
+      "content": "// The documentation of a component, carried by its code: each primitive has a `meta.ts` beside its source\n// (`src/<name>/meta.ts`; a component that exists only in React Native: `src/native/meta/<name>.ts`). Never built into\n// the package: `scripts/build-registry.mjs` reads them into `registry/<name>.json`, which krizaka.com renders as\n// /docs/ui/<name>, and `scripts/registry.test.mjs` fails when one is missing or incomplete.\n//\n// Why a typed module and not JSDoc tags: the fields are lists and links (`related`, `whenNotToUse[].use`, examples),\n// which a type checks and a comment does not; the file is plain data (erasable TypeScript), so Node reads it without a\n// compiler, and an editor completes it.\n\n/** Every documented component: the web primitives (one entry of the package each) and the native-only ones. */\nexport type ComponentName =\n  | \"alert\"\n  | \"audio-player\"\n  | \"avatar\"\n  | \"badge\"\n  | \"button\"\n  | \"card\"\n  | \"checkbox\"\n  | \"chip\"\n  | \"chip-link\"\n  | \"cn\"\n  | \"combobox\"\n  | \"command\"\n  | \"confirm-button\"\n  | \"countdown\"\n  | \"data-table\"\n  | \"date-picker\"\n  | \"dialog\"\n  | \"dropdown-menu\"\n  | \"empty-state\"\n  | \"field\"\n  | \"file-upload\"\n  | \"filter-bar\"\n  | \"glow-card\"\n  | \"image-cropper\"\n  | \"iso\"\n  | \"kbd\"\n  | \"loader\"\n  | \"marquee\"\n  | \"mascots\"\n  | \"media-capture\"\n  | \"meter\"\n  | \"nav-bar\"\n  | \"number-ticker\"\n  | \"page-header\"\n  | \"pagination\"\n  | \"popover\"\n  | \"progress\"\n  | \"radio-group\"\n  | \"search-field\"\n  | \"section-backdrop\"\n  | \"segmented\"\n  | \"separator\"\n  | \"skeleton\"\n  | \"slider\"\n  | \"slot\"\n  | \"spinner\"\n  | \"stat\"\n  | \"stepper\"\n  | \"switch\"\n  | \"tabs\"\n  | \"tag-input\"\n  | \"theme\"\n  | \"toast\"\n  | \"tooltip\"\n  | \"txt\"\n  | \"video-player\"\n  | \"video-trimmer\";\n\n/** Where a component exists: `@krizaka/ui/<name>` (web), `@krizaka/ui/native` (React Native), or both. */\nexport type Platform = \"web\" | \"native\" | \"both\";\n\n/** `stable`: its API only changes in a major. `beta`: it may still change in a minor. */\nexport type Status = \"stable\" | \"beta\";\n\n/** The group of the catalogue. `media`: video, sound, camera, files, cropping. */\nexport type Category = \"actions\" | \"forms\" | \"navigation\" | \"overlays\" | \"feedback\" | \"data-display\" | \"media\" | \"layout\" | \"foundations\";\n\n/**\n * A named example: the file `registry/examples/<component>/<name>.tsx` (web) or\n * `registry/examples/<component>/native/<name>.tsx` (React Native) — at most 40 lines, imported by the stories and\n * shown (live, with its code) by the documentation.\n */\nexport interface Example {\n  /** The file name, kebab-case (`primary`, `icon-button`). */\n  readonly name: string;\n  /** A short title (`Primary`, `Icon button`). */\n  readonly title: string;\n  /** One or two sentences: when this variant is the right one. */\n  readonly description: string;\n}\n\n/** One platform's side of a component. */\nexport interface PlatformDocs {\n  /** The names to import (`[\"Button\", \"IconButton\"]`): from `@krizaka/ui/<name>` on the web, `@krizaka/ui/native` in React Native. */\n  readonly imports: readonly string[];\n  /** The examples, in reading order; the first one is the component's preview. */\n  readonly examples: readonly Example[];\n}\n\n/** The React Native side: the same concept, and what differs from the web API. */\nexport interface NativeDocs extends PlatformDocs {\n  /**\n   * The entry to import from when it is not `@krizaka/ui/native`: a component that needs an Expo module (an optional\n   * peer) has its own, `@krizaka/ui/native/<name>`, so an app that does not use it never installs the module.\n   */\n  readonly entry?: string;\n  /** What differs from the web API (`label` instead of children…); empty for a native-only component. */\n  readonly differences: readonly string[];\n}\n\nexport interface KeyboardInteraction {\n  /** The keys, as written on a keyboard: `Space`, `Enter`, `Arrow keys`, `Esc`, `Tab`. */\n  readonly keys: string;\n  /** What they do. */\n  readonly action: string;\n}\n\nexport interface ComponentMeta {\n  /** The display name: `Button`, `Dropdown menu`. */\n  readonly title: string;\n  /** One sentence: what it is. */\n  readonly summary: string;\n  readonly status: Status;\n  readonly category: Category;\n  /** Must match the sides below: `both` ⇔ `web` and `native`. */\n  readonly platforms: Platform;\n  /** When to reach for it: concrete situations, one per item. */\n  readonly whenToUse: readonly string[];\n  /** When not to — and what to use instead (`use`), when another component is the answer. */\n  readonly whenNotToUse: readonly { readonly when: string; readonly use?: ComponentName }[];\n  /** How to use it well: wording, placement, composition. */\n  readonly bestPractices: readonly string[];\n  readonly accessibility: {\n    /** The keyboard, when it does more than Tab and Enter. */\n    readonly keyboard: readonly KeyboardInteraction[];\n    /** Roles, names and announcements: what the component does, what the app must provide. */\n    readonly notes: readonly string[];\n  };\n  /** The components a reader of this page should know about. */\n  readonly related: readonly ComponentName[];\n  readonly web?: PlatformDocs;\n  readonly native?: NativeDocs;\n}\n"
     }
   ],
   "dependencies": [