{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "combobox",
  "title": "Combobox",
  "description": "A text input that filters a list of items as people type, on the Field contract: pass `label`, `items`, and `error` from your server action or client check.",
  "dependencies": [
    "@base-ui/react@^1.8.0"
  ],
  "registryDependencies": [
    "@ouro/button",
    "@ouro/field",
    "@ouro/lib-control-ref",
    "@ouro/lib-env",
    "@ouro/lib-page-direction",
    "@ouro/lib-page-scroll-hold",
    "@ouro/lib-portal-container",
    "@ouro/lib-refs",
    "@ouro/lib-touch-target",
    "@ouro/lib-use-dev-messages",
    "@ouro/lib-use-field",
    "@ouro/lib-use-sheet-presentation",
    "@ouro/sheet",
    "@ouro/text-field"
  ],
  "files": [
    {
      "path": "registry/ouro/components/ouro/combobox/combobox-styles.ts",
      "content": "export {\n  chipClass,\n  chipRemoveClass,\n  chipsGroupClass,\n  chipsInputClass,\n  emptyClass,\n  itemClass,\n  listClass,\n  popupClass,\n  sheetClearClass,\n  sheetFieldClass,\n  sheetInputClass,\n  sheetListClass,\n  statusClass,\n  triggerClass,\n};\n\n// Class strings for Combobox, apart from the component so its file exports only components\n// (React Fast Refresh). Class strings are literal so the app's Tailwind finds them when it\n// compiles. The one-line box reuses TextField's classes; these are what Combobox adds.\n\n/**\n * The box with chips (`multiple`): Field's control look, but at least one control tall and\n * growing a row at a time as the chips wrap.\n *\n * @internal\n */\nconst chipsGroupClass =\n  \"relative m-0 box-border flex w-full min-w-0 flex-wrap items-center gap-1.5 py-1.5 ps-1.5 pe-3 cursor-text \" +\n  \"min-h-(--ouro-control-h) [--ouro-control-h:calc(var(--spacing)*11)] sm:pointer-fine:[--ouro-control-h:calc(var(--spacing)*9)] \" +\n  \"rounded-ouro-md border border-solid border-input bg-transparent text-base text-foreground sm:pointer-fine:text-sm \" +\n  \"outline-ring outline-offset-2 has-[input:focus-visible]:outline-2 has-[input:focus-visible]:outline-solid \" +\n  \"transition-[border-color] duration-(--ouro-duration-fast) ease-[ease] \" +\n  \"has-[input[aria-invalid=true]]:border-destructive has-[input:disabled]:cursor-not-allowed has-[input:disabled]:opacity-50 \" +\n  \"dark:bg-input/30\";\n\n/**\n * The input after the chips: it takes the rest of the row, and wraps to its own row when\n * the chips leave it too little room.\n *\n * @internal\n */\nconst chipsInputClass =\n  \"m-0 box-border h-8 min-w-16 flex-1 border-0 bg-transparent ps-1.5 py-0 sm:pointer-fine:h-6 \" +\n  \"text-[length:inherit] text-inherit font-[inherit] outline-none placeholder:text-muted-foreground disabled:cursor-not-allowed\";\n\n/**\n * A chip: the picked item's label and its remove button, on the secondary surface. It\n * shows the focus outline while the keyboard is on it (Left Arrow from the input's start).\n *\n * @internal\n */\nconst chipClass =\n  \"inline-flex h-8 max-w-full min-w-0 items-center gap-0.5 rounded-ouro-sm bg-secondary ps-2 text-sm text-secondary-foreground \" +\n  \"sm:pointer-fine:h-6 outline-ring outline-offset-1 data-highlighted:outline-2 data-highlighted:outline-solid \" +\n  \"[&>span]:truncate\";\n\n/**\n * A chip's remove button: a square as tall as the chip, with a 44px hit area on a coarse\n * pointer (its `TouchTarget`).\n *\n * @internal\n * @claim \"A chip's remove button: a square\" registry/ouro/components/ouro/combobox/combobox.touch.test.tsx verify:testExists(registry/ouro/components/ouro/combobox/combobox.touch.test.tsx::Combobox on a phone > gives chip remove buttons a 44px hit area)\n */\nconst chipRemoveClass =\n  \"press relative m-0 box-border inline-flex aspect-square h-full shrink-0 items-center justify-center rounded-ouro-sm border-0 p-0 \" +\n  \"bg-transparent text-inherit cursor-pointer [-webkit-tap-highlight-color:transparent] pointer-fine:hover:bg-accent active:bg-accent motion-safe:active:scale-(--ouro-press-scale) \" +\n  \"focus-visible:outline-2 focus-visible:outline-ring focus-visible:outline-solid [&_svg]:size-3.5\";\n\n/**\n * The popup: the input's width, on the popover surface. It opens at once and closes with a\n * 150ms fade and scale toward the input; with reduced motion it only fades. Its height\n * fits the screen above or below the input.\n *\n * @internal\n * @claim \"It opens at once and closes\" registry/ouro/components/ouro/combobox/combobox.test.tsx verify:testExists(registry/ouro/components/ouro/combobox/combobox.test.tsx::Combobox looks > closes with only a fade when reduced motion is on)\n * @claim \"It opens at once and closes\" registry/ouro/components/ouro/combobox/combobox.test.tsx verify:testExists(registry/ouro/components/ouro/combobox/combobox.test.tsx::Combobox motion > scales about the point Base UI computes next to its input, and leaves on the ease-out token)\n */\nconst popupClass =\n  \"box-border flex w-(--anchor-width) max-w-(--available-width) max-h-[min(var(--available-height),22rem)] flex-col \" +\n  \"origin-(--transform-origin) overflow-hidden rounded-ouro-md border border-solid border-border bg-popover text-popover-foreground \" +\n  \"shadow-(--shadow-lg) outline-none \" +\n  \"[transition:opacity_var(--ouro-duration-fast)_var(--ouro-ease-out),scale_var(--ouro-duration-fast)_var(--ouro-ease-out)] \" +\n  \"data-starting-style:transition-none data-ending-style:opacity-0 data-ending-style:scale-95 \" +\n  \"motion-reduce:[transition:opacity_var(--ouro-duration-fast)_var(--ouro-ease-out)] motion-reduce:data-ending-style:scale-100\";\n\n/**\n * The list of items: it scrolls inside the popup.\n *\n * @internal\n */\nconst listClass = \"box-border min-h-0 flex-1 overflow-y-auto overscroll-contain p-1 scroll-py-1 outline-none data-empty:p-0\";\n\n/**\n * An item: 44px tall on phones and 32px with a fine pointer from `sm`, with a check before\n * the picked ones. The keyboard's or pointer's highlight uses the accent surface.\n *\n * @internal\n * @claim \"An item: 44px tall on phones\" registry/ouro/components/ouro/combobox/combobox.test.tsx verify:testExists(registry/ouro/components/ouro/combobox/combobox.test.tsx::Combobox looks > uses a 16px font and a 44px box on phones, stepping down with a mouse on wider screens)\n * @claim \"An item: 44px tall on phones\" registry/ouro/components/ouro/combobox/combobox.tsx verify:fileLine(registry/ouro/components/ouro/combobox/combobox.tsx, /<BaseCombobox.ItemIndicator\\sclassName=\"col-start-1\\sflex\\s\\[&_svg\\]:size-4\">/)\n */\nconst itemClass =\n  \"relative box-border grid min-h-11 cursor-default grid-cols-[1rem_1fr] items-center gap-2 rounded-ouro-sm px-2 py-1.5 \" +\n  \"text-base leading-5 outline-none select-none sm:pointer-fine:min-h-8 sm:pointer-fine:text-sm \" +\n  \"data-highlighted:bg-accent data-highlighted:text-accent-foreground not-data-disabled:active:bg-accent not-data-disabled:active:text-accent-foreground \" +\n  // Forced colours drop the fill, so the highlight takes the system's pair.\n  \"forced-colors:data-highlighted:bg-[Highlight] forced-colors:data-highlighted:text-[HighlightText] \" +\n  \"data-disabled:cursor-not-allowed data-disabled:opacity-50\";\n\n/**\n * The line that says nothing matched.\n *\n * @internal\n */\nconst emptyClass = \"box-border px-3 py-2 text-sm leading-5 text-muted-foreground empty:hidden\";\n\n/**\n * The loading line: a spinner and the loading label.\n *\n * @internal\n */\nconst statusClass = \"box-border flex items-center gap-2 px-3 py-2 text-sm leading-5 text-muted-foreground empty:hidden\";\n\n/**\n * The control on a phone: a button that looks like the input box and opens the sheet. It\n * shows the picked label, or the placeholder in the muted color.\n *\n * @internal\n */\nconst triggerClass =\n  \"relative m-0 box-border flex w-full min-w-0 items-center justify-between gap-2 h-(--ouro-control-h) px-3 py-0 \" +\n  \"[--ouro-control-h:calc(var(--spacing)*11)] rounded-ouro-md border border-solid border-input bg-transparent \" +\n  \"text-start text-base text-foreground font-[inherit] cursor-pointer [-webkit-tap-highlight-color:transparent] \" +\n  \"outline-ring outline-offset-2 focus-visible:outline-2 focus-visible:outline-solid \" +\n  \"not-disabled:active:bg-accent/60 aria-invalid:border-destructive disabled:cursor-not-allowed disabled:opacity-50 dark:bg-input/30 \" +\n  \"data-placeholder:text-muted-foreground [&>span]:truncate [&_svg]:size-4 [&_svg]:shrink-0 [&_svg]:text-muted-foreground \" +\n  \"group-has-[[data-ouro-combobox-clear]]/combobox-field:[&>span]:me-10\";\n\n/**\n * The field on a phone: the button, with the clear button over its end, before the chevron.\n *\n * @internal\n */\nconst sheetFieldClass = \"group/combobox-field relative min-w-0\";\n\n/**\n * The clear button on a phone, over the end of the field's button, left of the chevron. It\n * keeps a 44px hit area (its `TouchTarget`).\n *\n * @internal\n * @claim \"It keeps a 44px hit area\" registry/ouro/components/ouro/combobox/combobox.touch.test.tsx verify:testExists(registry/ouro/components/ouro/combobox/combobox.touch.test.tsx::Combobox on a phone > gives chip remove buttons a 44px hit area)\n */\nconst sheetClearClass = \"absolute inset-y-0 end-9 my-auto\";\n\n/**\n * The search input pinned at the top of the sheet.\n *\n * @internal\n */\nconst sheetInputClass =\n  \"sticky top-0 z-1 -mx-5 -mt-2 mb-2 box-border flex bg-popover px-5 pt-2 pb-2\";\n\n/**\n * The sheet's list: items fill the width and scroll with the sheet's body.\n *\n * @internal\n */\nconst sheetListClass = \"box-border -mx-2 outline-none\";\n",
      "type": "registry:ui",
      "target": "@components/ouro/combobox/combobox-styles.ts"
    },
    {
      "path": "registry/ouro/components/ouro/combobox/combobox.tsx",
      "content": "\"use client\";\n\nimport { Autocomplete as BaseAutocomplete } from \"@base-ui/react/autocomplete\";\nimport { Combobox as BaseCombobox } from \"@base-ui/react/combobox\";\nimport { mergeProps } from \"@base-ui/react/merge-props\";\nimport { useEffect, useLayoutEffect, useMemo, useRef, useState, type JSX, type KeyboardEvent, type ReactNode, type Ref, type RefCallback, type RefObject } from \"react\";\nimport { Button } from \"@/registry/ouro/components/ouro/button/button\";\nimport { Field } from \"@/registry/ouro/components/ouro/field/field\";\nimport { contractWarnings } from \"@/registry/ouro/components/ouro/field/field-styles\";\nimport { SheetFrame } from \"@/registry/ouro/components/ouro/sheet/sheet\";\nimport { endSlotClass, groupClass, inputClass } from \"@/registry/ouro/components/ouro/text-field/text-field-styles\";\nimport { TouchTarget } from \"@/registry/ouro/lib/ouro/touch-target\";\nimport { FieldOwnerContext, useField, useFormErrors, type ReadonlyErrorMessages } from \"@/registry/ouro/lib/ouro/use-field\";\nimport { useDevWarnings } from \"@/registry/ouro/lib/ouro/use-dev-messages\";\nimport { usePickerSheet } from \"@/registry/ouro/lib/ouro/use-sheet-presentation\";\nimport { controlRef } from \"@/registry/ouro/lib/ouro/control-ref\";\nimport { PageDirection } from \"@/registry/ouro/lib/ouro/page-direction\";\nimport { useMergedRef } from \"@/registry/ouro/lib/ouro/refs\";\nimport { holdPageAtPress } from \"@/registry/ouro/lib/ouro/page-scroll-hold\";\nimport { PortalScope, usePortalContainer } from \"@/registry/ouro/lib/ouro/portal-container\";\nimport {\n  chipClass,\n  chipRemoveClass,\n  chipsGroupClass,\n  chipsInputClass,\n  emptyClass,\n  itemClass,\n  listClass,\n  popupClass,\n  sheetClearClass,\n  sheetFieldClass,\n  sheetInputClass,\n  sheetListClass,\n  statusClass,\n  triggerClass,\n} from \"@/registry/ouro/components/ouro/combobox/combobox-styles\";\n\n/**\n * An item to pick: a string, which is both what shows and what submits, or an object with\n * the `value` that submits and the `label` that shows. `disabled` items show but can't be picked.\n * An object can also show a picture, a second line and a mark, as a people picker does: `media`\n * (an `Avatar`), `description` and `meta` (a `Badge`).\n */\nexport type ComboboxItem = string | ComboboxItemObject;\n\n/** An item as an object: what it submits, what it shows, and what shows around it. */\nexport interface ComboboxItemObject {\n  /** What the item submits, and what `value` and `onValueChange` hold. */\n  value: string;\n  /** What the item shows, on its row and on its chip with `multiple`; screen readers hear it first. */\n  label: string;\n  /** The item shows but can't be picked. */\n  disabled?: boolean | undefined;\n  /**\n   * A second, muted line under the label, such as a person's job title or email. It stays on\n   * one line, cut with an ellipsis, and shows whole on hover (its `title`).\n   * @claim \"It stays on one line, cut\" registry/ouro/components/ouro/combobox/combobox.test.tsx verify:testExists(registry/ouro/components/ouro/combobox/combobox.test.tsx::Combobox rich items > shows media, a description and a mark on a row, and media on its chip)\n   */\n  description?: string | undefined;\n  /**\n   * A picture before the label, on the row and, with `multiple`, on the chip: an `Avatar` with\n   * `alt=\"\"` (the label already names it) and `size=\"xs\"`, which fits a chip.\n   */\n  media?: ReactNode;\n  /** A small mark at the row's end, such as a `<Badge>` that says \"1:1\". */\n  meta?: ReactNode;\n}\n\n/**\n * Props every Combobox takes, whatever it picks.\n *\n * @claim \"Props every Combobox takes, whatever it\" registry/ouro/components/ouro/combobox/combobox.test-d.ts verify:fileLine(registry/ouro/components/ouro/combobox/combobox.test-d.ts, /expectTypeOf<\\{\\slabel:\\s\"Herb\";\\sitems:\\s\\[\"Basil\",\\s\"Dill\"\\]\\s\\}>\\(\\)\\.toExtend<ComboboxProps>/)\n */\nexport interface ComboboxBaseProps {\n  /**\n   * What the field is for, shown above it and read as its name. Required: every control\n   * needs a name. To hide it visually, keep it and add `hideLabel`. A placeholder is not a label.\n   * @claim \"Required: every control needs a name\" registry/ouro/components/ouro/combobox/combobox.test-d.ts verify:fileLine(registry/ouro/components/ouro/combobox/combobox.test-d.ts, /expectTypeOf<\\{\\sitems:\\sstring\\[\\]\\s\\}>\\(\\)\\.not\\.toExtend<ComboboxProps>/)\n   */\n  label: string;\n  /** Hides the label visually; screen readers still read it as the field's name. */\n  hideLabel?: boolean | undefined;\n  /** Supporting text under the label, read after the label through `aria-describedby`. */\n  description?: ReactNode | undefined;\n  /**\n   * What is wrong, from your server action or client check. The message (or several, as a\n   * list) shows under the field, which gets `aria-invalid`. A message is text or a React node (one with a link); an empty string or array means valid.\n   */\n  error?: ReadonlyErrorMessages | undefined;\n  /** Something must be picked: the input gets `aria-required`, and the label a marker. */\n  required?: boolean | undefined;\n  /** Disables the field and its buttons, and fades it. */\n  disabled?: boolean | undefined;\n  /** The form field name the picked value submits under; `multiple` submits one entry per pick. */\n  name?: string | undefined;\n  /**\n   * What people pick from: strings, or `{ value, label }` objects. Combobox filters them as\n   * people type, unless you pass `onInputChange`, which makes them your search results.\n   */\n  items: readonly ComboboxItem[];\n  /** An example shown while the input is empty: `\"Search herbs\"`. It is not a label; pass `label`. */\n  placeholder?: string | undefined;\n  /**\n   * Called with the text as people type. Pass it to search on your server: Combobox then\n   * shows `items` as you give them, without filtering, and you set `loading` while a search\n   * runs. Keep the picked items in `items`, so their labels stay known.\n   */\n  onInputChange?: ((text: string) => void) | undefined;\n  /** A search is running: the list shows a spinner and `loadingLabel`, and is `aria-busy`. */\n  loading?: boolean | undefined;\n  /**\n   * The first item that matches is highlighted as people type, so Enter picks it.\n   * @claim \"The first item that matches is\" registry/ouro/components/ouro/combobox/combobox.test.tsx verify:testExists(registry/ouro/components/ouro/combobox/combobox.test.tsx::Combobox keys > picks the first match on Enter with autoHighlight, and nothing without it)\n   */\n  autoHighlight?: boolean | undefined;\n  /**\n   * Called on each key pressed in the input, before Combobox acts on it. Call\n   * `event.preventDefault()` to stop Combobox's own handling of that key (Enter picking, Tab,\n   * the arrows), such as to move on from an empty input on Enter.\n   * @claim \"Called on each key pressed in\" registry/ouro/components/ouro/combobox/combobox.test.tsx verify:testExists(registry/ouro/components/ouro/combobox/combobox.test.tsx::Combobox keys > hands the app each key first, and leaves a key the app prevents alone)\n   */\n  onInputKeyDown?: ((event: KeyboardEvent<HTMLInputElement>) => void) | undefined;\n  /**\n   * People can see the field and what is picked but not change it: the input takes no text,\n   * nothing in the list can be picked, and the clear and remove buttons go. The list still opens,\n   * to browse.\n   * @claim \"People can see the field and\" registry/ouro/components/ouro/combobox/combobox.test.tsx verify:testExists(registry/ouro/components/ouro/combobox/combobox.test.tsx::Combobox keys > keeps a read-only field as it is)\n   */\n  readOnly?: boolean | undefined;\n  /**\n   * The text the list shows while `loading`. Translate it with your app.\n   * @default \"Loading…\"\n   */\n  loadingLabel?: string | undefined;\n  /**\n   * The text the list shows when nothing matches. Translate it with your app.\n   * @default \"No results\"\n   */\n  emptyLabel?: string | undefined;\n  /**\n   * The name of the button that clears the field, as visually hidden text and not an\n   * `aria-label`, so a test's label lookup for the field finds the field alone. It shows while\n   * there is something to clear. Translate it with your app.\n   * @default \"Clear\"\n   */\n  clearLabel?: string | undefined;\n  /**\n   * The label of the button that closes the sheet on a phone (a visible button with\n   * `multiple`). Translate it with your app.\n   * @default \"Done\"\n   */\n  doneLabel?: string | undefined;\n  /**\n   * Layout only: margins, width, grid placement (`mt-4`, `col-span-2`). Appearance classes\n   * warn in development; style fields in your theme.\n   */\n  className?: string | undefined;\n  /** The input element. On a phone, it is the search input in the sheet, while the sheet is open. */\n  ref?: Ref<HTMLInputElement> | undefined;\n\n  /** Not a prop. Ouro UI uses `error`: `<Combobox error=\"Required.\">`. */\n  errorMessage?: { 'Use <Combobox error=\"Required.\">': never };\n  /** Not a prop. Ouro UI uses `description`: `<Combobox description=\"...\">`. */\n  helperText?: { 'Use <Combobox description=\"...\">': never };\n  /** Not a prop. `error` marks the field invalid: `<Combobox error=\"What is wrong\">`. */\n  isInvalid?: { 'Use <Combobox error=\"What is wrong\">': never };\n  /** Not a prop. `error` marks the field invalid: `<Combobox error=\"What is wrong\">`. */\n  invalid?: { 'Use <Combobox error=\"What is wrong\">': never };\n  /** Not a prop. Ouro UI uses `required`: `<Combobox required>`. */\n  isRequired?: { 'Use <Combobox required>': never };\n  /** Not a prop. Ouro UI uses `disabled`: `<Combobox disabled>`. */\n  isDisabled?: { 'Use <Combobox disabled>': never };\n  /** Not a prop. Ouro UI uses `items`: `<Combobox items={[\"Basil\", \"Dill\"]}>`. */\n  options?: { 'Use <Combobox items={[\"Basil\", \"Dill\"]}>': never };\n  /** Not a prop. Ouro UI uses `loading`: `<Combobox loading>`. */\n  isLoading?: { 'Use <Combobox loading>': never };\n  /** Not a prop. Ouro UI uses `multiple`: `<Combobox multiple>`. */\n  isMulti?: { 'Use <Combobox multiple>': never };\n  /** Not a prop. Ouro UI uses `allowCustomValue`: `<Combobox allowCustomValue>`. */\n  freeSolo?: { 'Use <Combobox allowCustomValue>': never };\n  /** Not a prop. Ouro UI uses `allowCustomValue`: `<Combobox allowCustomValue>`. */\n  creatable?: { 'Use <Combobox allowCustomValue>': never };\n  /** Not a prop. Ouro UI uses `onInputChange`: `<Combobox onInputChange={(text) => …}>`. */\n  onSearch?: { 'Use <Combobox onInputChange={(text) => ...}>': never };\n  /** Not a prop. Ouro UI uses `onInputChange`: `<Combobox onInputChange={(text) => …}>`. */\n  onInputValueChange?: { 'Use <Combobox onInputChange={(text) => ...}>': never };\n  /** Not a prop. Combobox reports the pick itself: `<Combobox onValueChange={(value) => …}>`. */\n  onChange?: { 'Use <Combobox onValueChange={(value) => ...}>': never };\n  /** Not a prop. Ouro UI uses `emptyLabel`: `<Combobox emptyLabel=\"No herbs\">`. */\n  noOptionsMessage?: { 'Use <Combobox emptyLabel=\"No herbs\">': never };\n  /** Not a prop. The clear button shows whenever there is something to clear. */\n  isClearable?: { 'The clear button shows whenever there is a value': never };\n}\n\n/** A Combobox that picks one item: its value, or `null` when nothing is picked. */\nexport type ComboboxSingleProps = ComboboxBaseProps & {\n  /** Pick several items, shown as chips. */\n  multiple?: false | undefined;\n  /** Accept any text, not only an item. */\n  allowCustomValue?: false | undefined;\n  /** The picked item's value, when you control it; `null` is nothing picked. */\n  value?: string | null | undefined;\n  /** The item picked at first, when the field keeps its own. */\n  defaultValue?: string | null | undefined;\n  /** Called with the picked item's value, or `null` when cleared. */\n  onValueChange?: ((value: string | null) => void) | undefined;\n  /**\n   * The input's text, when you control it with `onInputChange`. Set it to `\"\"` in\n   * `onValueChange` to clear the input after a pick.\n   */\n  inputValue?: string | undefined;\n  /** Only with `multiple`. */\n  removeLabel?: never;\n  /** Only with `allowCustomValue`. */\n  customValueLabel?: never;\n};\n\n/** A Combobox that picks several items, shown as chips in the input. */\nexport type ComboboxMultipleProps = ComboboxBaseProps & {\n  /** Pick several items, shown as chips; the value is an array. */\n  multiple: true;\n  /** Not with `multiple`: `allowCustomValue` keeps one typed value. */\n  allowCustomValue?: false | undefined;\n  /** The picked items' values, when you control them. */\n  value?: string[] | undefined;\n  /** The items picked at first, when the field keeps its own. */\n  defaultValue?: string[] | undefined;\n  /** Called with the picked items' values. */\n  onValueChange?: ((value: string[]) => void) | undefined;\n  /**\n   * The input's text, when you control it with `onInputChange`. Set it to `\"\"` in\n   * `onValueChange` to clear the input after a pick.\n   * @claim \"in `onValueChange` to clear the input after a pick\" registry/ouro/components/ouro/combobox/combobox.test.tsx verify:testExists(registry/ouro/components/ouro/combobox/combobox.test.tsx::Combobox keys > takes its text from inputValue, and clears it after a pick when the app says so)\n   */\n  inputValue?: string | undefined;\n  /**\n   * The name of a chip's remove button, from the item's label, as visually hidden text and not\n   * an `aria-label`. Translate it with your app.\n   * @default (label) => `Remove ${label}`\n   */\n  removeLabel?: ((label: string) => string) | undefined;\n  /** Only with `allowCustomValue`. */\n  customValueLabel?: never;\n};\n\n/** A Combobox that accepts any text, suggesting matching items as people type. */\nexport type ComboboxCustomProps = ComboboxBaseProps & {\n  /** Accept any text: the value is what is in the input, and items are suggestions. */\n  allowCustomValue: true;\n  /** Not with `allowCustomValue`: it keeps one typed value. */\n  multiple?: false | undefined;\n  /** The text, when you control it. */\n  value?: string | undefined;\n  /** The text at first, when the field keeps its own. */\n  defaultValue?: string | undefined;\n  /**\n   * Called with the text as people type or pick a suggestion. A suggestion puts its `label`\n   * in the input, and the text is the value, so an `{ value, label }` item submits its label.\n   */\n  onValueChange?: ((value: string) => void) | undefined;\n  /** Not with `allowCustomValue`: the text is the value, which `value` controls. */\n  inputValue?: never;\n  /**\n   * The sheet's row (on a phone) that keeps what was typed, from the text. Translate it with\n   * your app.\n   * @default (text) => `Use “${text}”`\n   */\n  customValueLabel?: ((text: string) => string) | undefined;\n  /** Only with `multiple`. */\n  removeLabel?: never;\n};\n\n/**\n * Props for {@link Combobox}: one item (the default), several with `multiple`, or any text\n * with `allowCustomValue`.\n */\nexport type ComboboxProps = ComboboxSingleProps | ComboboxMultipleProps | ComboboxCustomProps;\n\n/** An item as Base UI's list holds it. */\ninterface Option {\n  value: string;\n  label: string;\n  disabled?: boolean | undefined;\n  description?: string | undefined;\n  media?: ReactNode;\n  meta?: ReactNode;\n  /** The sheet's row that keeps the typed text (`allowCustomValue`): it shows `label` but picks `value`. */\n  custom?: boolean | undefined;\n}\n\n/** What the field shows inside it, from the props, for either way of picking. */\ninterface ControlProps {\n  sheet: boolean;\n  onReset: (() => void) | undefined;\n  label: string;\n  items: readonly ComboboxItem[];\n  multiple: boolean;\n  value: unknown;\n  defaultValue: unknown;\n  onValueChange: ((value: never) => void) | undefined;\n  onInputChange: ((text: string) => void) | undefined;\n  placeholder: string | undefined;\n  required: boolean | undefined;\n  loading: boolean | undefined;\n  loadingLabel: string;\n  emptyLabel: string;\n  clearLabel: string;\n  doneLabel: string;\n  removeLabel: (label: string) => string;\n  customValueLabel: (text: string) => string;\n  /** `allowCustomValue` on a phone: one value, which may be typed text. */\n  custom: boolean;\n  inputRef: Ref<HTMLInputElement> | undefined;\n  autoHighlight: boolean | undefined;\n  onInputKeyDown: ((event: KeyboardEvent<HTMLInputElement>) => void) | undefined;\n  readOnly: boolean | undefined;\n  inputValue: string | undefined;\n}\n\n/** Field's messages and root name Combobox. */\nconst owner = { name: \"Combobox\", data: \"combobox\" };\n/** Marks the hidden input Base UI submits a picked value with. */\nconst markInput = controlRef(\"combobox\", \"hidden-input\");\n\n/**\n * A callback ref that marks the visually hidden Dismiss button Base UI adds for screen readers\n * while the list is open, beside the input and beside the popup. Base UI takes neither props\n * nor a ref for it, so the marker goes on whenever one appears under the element.\n */\nfunction dismissMarker(item: string, part: string): RefCallback<HTMLElement> {\n  return (element) => {\n    const mark = () => {\n      for (const dismiss of element!.querySelectorAll('span[role=\"button\"]:not([data-base-ui-focus-guard])')) {\n        dismiss.setAttribute(\"data-ouro-control\", item);\n        dismiss.setAttribute(\"data-ouro-part\", part);\n      }\n    };\n    mark();\n    const observer = new MutationObserver(mark);\n    observer.observe(element!, { childList: true, subtree: true });\n    return () => observer.disconnect();\n  };\n}\nconst markDismiss = dismissMarker(\"combobox\", \"dismiss\");\nconst markPopupDismiss = dismissMarker(\"combobox\", \"popup-dismiss\");\n\nconst toOption = (item: ComboboxItem): Option => (typeof item === \"string\" ? { value: item, label: item } : item);\n\n/**\n * Icons drawn in the text color at 16px, like the other Ouro icons.\n *\n * @claim \"Icons drawn in the text color\" registry/ouro/components/ouro/combobox/combobox.tsx verify:fileLine(registry/ouro/components/ouro/combobox/combobox.tsx, /viewBox=\"0\\s0\\s16\\s16\"/)\n * @claim \"Icons drawn in the text color\" registry/ouro/components/ouro/combobox/combobox.tsx verify:fileLine(registry/ouro/components/ouro/combobox/combobox.tsx, /\\[&_svg\\]:size-4/)\n */\nfunction Icon({ children }: { children: ReactNode }): JSX.Element {\n  return (\n    <svg\n      aria-hidden=\"true\"\n      viewBox=\"0 0 16 16\"\n      fill=\"none\"\n      stroke=\"currentColor\"\n      strokeWidth=\"1.5\"\n      strokeLinecap=\"round\"\n      strokeLinejoin=\"round\"\n      className=\"size-4\"\n    >\n      {children}\n    </svg>\n  );\n}\n\nconst CrossIcon = () => (\n  <Icon>\n    <path d=\"M4.5 4.5l7 7M11.5 4.5l-7 7\" />\n  </Icon>\n);\n\nconst ChevronIcon = () => (\n  <Icon>\n    <path d=\"M4.5 6.5 8 10l3.5-3.5\" />\n  </Icon>\n);\n\n/**\n * A text input that filters a list of items as people type, on the Field contract: pass\n * `label`, `items`, and `error` from your server action or client check. It picks one item,\n * several as chips with `multiple`, or accepts any text with `allowCustomValue`. Pass\n * `onInputChange` and `loading` to search on your server. A clear button shows while there\n * is a value. On a phone (below 640px with touch) the field is a button that opens a\n * full-height bottom sheet with the search input pinned at the top, and a clear button sits\n * beside it. With `allowCustomValue` the sheet's first row keeps what was typed\n * (`customValueLabel`). The sheet opens with focus on itself, not the search input, so the\n * keyboard does not cover the list until people tap the search (as Base UI does for touch).\n * In a right-to-left page (`dir=\"rtl\"` on `<html>`) the arrow keys move between chips from the right: ArrowRight goes from the input to the last chip.\n * There, End also scrolls long typed text to its end, on the left.\n *\n * Use `Select` instead for a short list people don't need to search, and `TextField` for\n * free text with no suggestions.\n *\n * @group Forms\n * @see https://ui.ouroboros.bot/docs/combobox\n *\n * @example\n * <Combobox label=\"Herb\" name=\"herb\" items={[\"Basil\", \"Dill\", \"Thyme\"]} />\n * <Combobox label=\"Tags\" name=\"tags\" multiple items={tags} defaultValue={[\"Quick\"]} />\n * <Combobox label=\"Recipe\" items={results} loading={searching} onInputChange={search} />\n * <Combobox label=\"Cuisine\" name=\"cuisine\" allowCustomValue items={[\"Italian\", \"Thai\"]} />\n * @claim \"On a phone (below 640px with\" registry/ouro/components/ouro/combobox/combobox.touch.test.tsx verify:testExists(registry/ouro/components/ouro/combobox/combobox.touch.test.tsx::Combobox on a phone > is a button in the field that opens a sheet titled with the label)\n * @claim \"In a right-to-left page\" registry/ouro/components/ouro/combobox/combobox.test.tsx verify:testExists(registry/ouro/components/ouro/combobox/combobox.test.tsx::Combobox multiple > moves between its chips with the arrow keys of a right-to-left page, where the last chip sits right of the input)\n * @claim \"There, End also scrolls long\" registry/ouro/components/ouro/combobox/combobox.test.tsx verify:testExists(registry/ouro/components/ouro/combobox/combobox.test.tsx::Combobox allowCustomValue > shows the end of long text on End in a right-to-left page, where the end is on the left)\n * @claim \"On a phone (below 640px with\" registry/ouro/components/ouro/combobox/combobox.touch.test.tsx verify:testExists(registry/ouro/components/ouro/combobox/combobox.touch.test.tsx::Combobox on a phone > clears a single pick with a clear button beside the field, by tap or from the keyboard)\n */\nexport function Combobox(props: ComboboxProps): JSX.Element {\n  const {\n    label,\n    hideLabel,\n    description,\n    error,\n    required,\n    disabled,\n    name,\n    items,\n    placeholder,\n    onInputChange,\n    loading,\n    autoHighlight,\n    onInputKeyDown,\n    readOnly,\n    loadingLabel = \"Loading…\",\n    emptyLabel = \"No results\",\n    clearLabel = \"Clear\",\n    doneLabel = \"Done\",\n    className,\n    ref,\n    multiple = false,\n    allowCustomValue = false,\n    value,\n    defaultValue,\n    onValueChange,\n    removeLabel = (item: string) => `Remove ${item}`,\n    customValueLabel = (text: string) => `Use “${text}”`,\n    inputValue,\n    // Guard props (hint types), dropped here so they never reach the DOM.\n    errorMessage,\n    helperText,\n    isInvalid,\n    invalid,\n    isRequired,\n    isDisabled,\n    options,\n    isLoading,\n    isMulti,\n    freeSolo,\n    creatable,\n    onSearch,\n    onInputValueChange,\n    onChange,\n    noOptionsMessage,\n    isClearable,\n  } = props as ComboboxBaseProps & {\n    multiple?: boolean;\n    allowCustomValue?: boolean;\n    value?: unknown;\n    defaultValue?: unknown;\n    onValueChange?: (value: never) => void;\n    removeLabel?: (label: string) => string;\n    customValueLabel?: (text: string) => string;\n    inputValue?: string;\n  };\n  const form = useFormErrors();\n  const [ownCustomValue, setOwnCustomValue] = useState(defaultValue ?? \"\");\n  // A change drops a Form error for this name, as typing does in a text field.\n  const handleValueChange = (next: never) => {\n    if (allowCustomValue && !multiple && value === undefined) setOwnCustomValue(next);\n    if (name !== undefined) form?.clear(name);\n    onValueChange?.(next);\n  };\n  const sheet = usePickerSheet();\n  const custom = allowCustomValue && !multiple;\n  const customProps = props.allowCustomValue && !props.multiple ? props : undefined;\n  const resetCustom = customProps && customProps.value === undefined ? () => {\n    const next = customProps.defaultValue ?? \"\";\n    if (next !== ownCustomValue) {\n      setOwnCustomValue(next);\n      if (name !== undefined) form?.clear(name);\n      customProps.onValueChange?.(next);\n    }\n  } : undefined;\n\n  useDevWarnings(\n    \"Combobox\",\n    process.env.NODE_ENV !== \"production\"\n      ? () => [\n          ...contractWarnings(\"Combobox\", { errorMessage, helperText, isInvalid, invalid, isRequired, isDisabled }),\n          options !== undefined && [\"options is not a prop\", \"<Combobox items={[…]}>\"],\n          isLoading !== undefined && [\"isLoading is not a prop\", \"<Combobox loading>\"],\n          isMulti !== undefined && [\"isMulti is not a prop\", \"<Combobox multiple>\"],\n          freeSolo !== undefined && [\"freeSolo is not a prop\", \"<Combobox allowCustomValue>\"],\n          creatable !== undefined && [\"creatable is not a prop\", \"<Combobox allowCustomValue>\"],\n          onSearch !== undefined && [\"onSearch is not a prop\", \"<Combobox onInputChange={(text) => …}>\"],\n          onInputValueChange !== undefined && [\"onInputValueChange is not a prop\", \"<Combobox onInputChange={(text) => …}>\"],\n          onChange !== undefined && [\"onChange is not a prop\", \"<Combobox onValueChange={(value) => …}>\"],\n          noOptionsMessage !== undefined && [\"noOptionsMessage is not a prop\", `<Combobox emptyLabel=\"${String(noOptionsMessage)}\">`],\n          isClearable !== undefined && [\"isClearable is not a prop; the clear button shows whenever there is a value\", \"<Combobox>\"],\n          inputValue !== undefined &&\n            !onInputChange && [\"inputValue needs onInputChange, or the text can never change\", \"<Combobox inputValue={text} onInputChange={setText}>\"],\n          multiple &&\n            allowCustomValue && [\n              \"multiple and allowCustomValue do not combine; allowCustomValue keeps one typed value\",\n              \"<Combobox multiple items={tags}>\",\n            ],\n        ]\n      : /* istanbul ignore next @preserve -- production only */ undefined,\n  );\n\n  const control: ControlProps = {\n    sheet,\n    onReset: resetCustom,\n    label,\n    items,\n    multiple,\n    value: custom && value === undefined ? ownCustomValue : value,\n    defaultValue,\n    onValueChange: handleValueChange,\n    onInputChange,\n    placeholder,\n    required,\n    loading,\n    loadingLabel,\n    emptyLabel,\n    clearLabel,\n    doneLabel,\n    removeLabel,\n    customValueLabel,\n    custom,\n    inputRef: ref,\n    autoHighlight,\n    onInputKeyDown,\n    readOnly,\n    inputValue,\n  };\n\n  return (\n    <FieldOwnerContext.Provider value={owner}>\n      <Field\n        label={label}\n        hideLabel={hideLabel}\n        description={description}\n        error={error}\n        required={required}\n        disabled={disabled}\n        name={name}\n        className={className}\n      >\n        {/* On a phone, allowCustomValue uses the sheet too, with a row that keeps the typed text. */}\n        {custom && !sheet ? <AutocompleteControl {...control} /> : <ComboboxControl {...control} />}\n      </Field>\n    </FieldOwnerContext.Provider>\n  );\n}\n\n/**\n * The input's press and key handlers: the page hold's, with the app's `onInputKeyDown` ahead of\n * it. Base UI merges handlers so the last runs first; a key the app prevents skips the rest, the\n * page hold's and Base UI's own.\n */\nfunction inputHandlers(onInputKeyDown: ((event: KeyboardEvent<HTMLInputElement>) => void) | undefined) {\n  return mergeProps<\"input\">(holdPageAtPress.listInput, {\n    onKeyDown: (event) => {\n      onInputKeyDown?.(event);\n      if (event.defaultPrevented) event.preventBaseUIHandler();\n    },\n  });\n}\n\n/** An item's row: its label alone, or with its picture, second line and mark. */\nfunction ItemContent({ option }: { option: Option }): JSX.Element {\n  if (option.media == null && !option.description && option.meta == null) return <span className=\"col-start-2\">{option.label}</span>;\n  return (\n    <span className=\"col-start-2 flex min-w-0 items-center gap-2\">\n      {option.media != null && (\n        <span data-ouro-combobox-media=\"\" className=\"flex shrink-0\">\n          {option.media}\n        </span>\n      )}\n      <span className=\"flex min-w-0 flex-1 flex-col\">\n        <span className=\"truncate\">{option.label}</span>\n        {option.description && (\n          // Muted, nudged toward the text color (as ConversationList's quiet lines), so it keeps 4.5:1 on a highlighted row too.\n          <span\n            data-ouro-combobox-description=\"\"\n            title={option.description}\n            className=\"truncate text-xs text-[color-mix(in_oklab,var(--muted-foreground)_80%,var(--foreground))]\"\n          >\n            {option.description}\n          </span>\n        )}\n      </span>\n      {option.meta != null && (\n        <span data-ouro-combobox-meta=\"\" className=\"flex shrink-0\">\n          {option.meta}\n        </span>\n      )}\n    </span>\n  );\n}\n\n/** The list's status, empty message and items, in the popup or the sheet. */\nfunction ListBody({\n  loading,\n  loadingLabel,\n  emptyLabel,\n  showEmpty,\n  className,\n  renderItem,\n}: {\n  loading: boolean | undefined;\n  /** Whether \"nothing matched\" applies: not before a server search has been typed. */\n  showEmpty: boolean;\n  loadingLabel: string;\n  emptyLabel: string;\n  className: string;\n  renderItem: (option: Option) => JSX.Element;\n}): JSX.Element {\n  return (\n    <>\n      <BaseCombobox.Status className={statusClass}>\n        {loading && (\n          <>\n            <svg\n              aria-hidden=\"true\"\n              data-ouro-spinner=\"\"\n              viewBox=\"0 0 24 24\"\n              fill=\"none\"\n              className=\"size-4 animate-[ouro-spin_0.8s_linear_infinite] motion-reduce:animate-[ouro-pulse_1.6s_ease-in-out_infinite]\"\n            >\n              <circle cx=\"12\" cy=\"12\" r=\"9\" stroke=\"currentColor\" strokeWidth=\"2.5\" opacity=\"0.25\" />\n              <path d=\"M21 12a9 9 0 0 0-9-9\" stroke=\"currentColor\" strokeWidth=\"2.5\" strokeLinecap=\"round\" />\n            </svg>\n            {loadingLabel}\n          </>\n        )}\n      </BaseCombobox.Status>\n      <BaseCombobox.Empty className={emptyClass}>{!loading && showEmpty && emptyLabel}</BaseCombobox.Empty>\n      <BaseCombobox.List className={className}>{renderItem}</BaseCombobox.List>\n    </>\n  );\n}\n\n/**\n * Keeps the page exposed to assistive technology while the list is open. Base UI hides the\n * page around the input and the list with aria-hidden on the children of their ancestors,\n * which leaves the page's links and fields focusable yet hidden and takes its heading away. A\n * combobox list leaves the page as it is, so such a child that gains aria-hidden while the list\n * is open loses it at once, unless the same change hid what holds the input or the list, as a\n * dialog opened over the list hides the page around itself. What the app hid before, and what\n * it hides deeper in the page, stays hidden. It reads only the input and the list, never the\n * whole page, so opening the list costs no search of the page. It renders in the portal, which\n * holds the list only while it is open.\n *\n * @claim \"It reads only the input and the list, never the whole page, so opening the list costs no search of the page.\" registry/ouro/components/ouro/combobox/combobox.test.tsx verify:testExists(registry/ouro/components/ouro/combobox/combobox.test.tsx::Combobox > opens its list without searching the whole page, while it keeps the page exposed)\n */\nfunction KeepPageExposed({ input, list }: { input: RefObject<HTMLElement | null>; list: RefObject<HTMLElement | null> }): null {\n  useLayoutEffect(\n    () => {\n      const observer = new MutationObserver((records) => {\n        const kept = [input.current, list.current];\n        const targets = records.map(({ target }) => target as Element);\n        if (targets.some((target) => kept.some((element) => target.contains(element)))) return;\n        for (const target of targets) if (kept.some((element) => target.parentNode!.contains(element))) target.removeAttribute(\"aria-hidden\");\n      });\n      observer.observe(document.body, { attributes: true, attributeFilter: [\"aria-hidden\"], subtree: true });\n      // Stryker disable next-line ArrowFunction: once the list closes nothing is around it to unhide, so an observer left connected changes nothing.\n      return () => observer.disconnect();\n    },\n    // Stryker disable next-line ArrayDeclaration: the refs are the same objects for the popup's life, so the effect runs once whatever its dependencies.\n    [input, list],\n  );\n  return null;\n}\n\n/** The popup under (or over) the input, on wider screens and with a mouse. */\nfunction Popup({ input, loading, children }: { input: RefObject<HTMLElement | null>; loading: boolean | undefined; children: ReactNode }): JSX.Element {\n  const portal = usePortalContainer(\"Combobox\", true);\n  const list = useRef<HTMLDivElement>(null);\n  const positionerRef = useMergedRef(markPopupDismiss, list);\n  // Inside a Dialog its own layers sit at z-1000; 1000 above --ouro-layer clears them there and\n  // on the page, as Select's list does.\n  return (\n    <BaseCombobox.Portal {...portal} data-ouro=\"combobox-portal\" className=\"relative isolate z-[calc(var(--ouro-layer)+1000)]\">\n      <PortalScope>\n        <KeepPageExposed input={input} list={list} />\n        <BaseCombobox.Positioner ref={positionerRef} sideOffset={4} className=\"outline-none\">\n          <BaseCombobox.Popup data-ouro=\"combobox-popup\" aria-busy={loading || undefined} className={popupClass}>\n            {children}\n          </BaseCombobox.Popup>\n        </BaseCombobox.Positioner>\n      </PortalScope>\n    </BaseCombobox.Portal>\n  );\n}\n\n/**\n * The end of the box: the clear button, while there is something to clear, and a chevron.\n * The chevron is drawn, not a button: pressing anywhere in the box opens the list, and the\n * arrow keys open it from the keyboard. (Base UI gives a trigger button the input's id on the\n * server, so a server-rendered page would hold that id twice.)\n */\nfunction EndButtons({ clearLabel, readOnly }: { clearLabel: string; readOnly: boolean | undefined }): JSX.Element {\n  return (\n    <span className={endSlotClass}>\n      {!readOnly && (\n      <BaseCombobox.Clear\n        render={\n          <Button variant=\"plain\" tone=\"secondary\" size=\"sm\" data-ouro-combobox-clear=\"\" data-ouro-control=\"combobox\" data-ouro-part=\"clear\" className=\"aspect-square px-0\">\n            <CrossIcon />\n            <span className=\"sr-only\">{clearLabel}</span>\n          </Button>\n        }\n      />\n      )}\n      <BaseCombobox.Icon data-ouro-combobox-icon=\"\" className=\"flex size-8 items-center justify-center text-muted-foreground sm:pointer-fine:size-6 [&_svg]:size-4\">\n        <ChevronIcon />\n      </BaseCombobox.Icon>\n    </span>\n  );\n}\n\n/** Restores a custom value only after an uncancelled reset, unless a later edit or unmount won. */\nfunction useCustomReset(ref: RefObject<HTMLInputElement | HTMLButtonElement | null>, value: unknown, onReset: (() => void) | undefined) {\n  const latest = useRef({ value, onReset });\n  useLayoutEffect(() => { latest.current = { value, onReset }; });\n  useEffect(() => {\n    const element = ref.current;\n    const form = element?.form;\n    if (!form || !onReset) return;\n    const reset = (event: Event) => {\n      const before = latest.current.value;\n      queueMicrotask(() => {\n        if (!event.defaultPrevented && event.target === form && ref.current === element && latest.current.value === before) latest.current.onReset?.();\n      });\n    };\n    form.addEventListener(\"reset\", reset);\n    return () => form.removeEventListener(\"reset\", reset);\n  }, [ref, onReset]);\n}\n\n/** A Combobox that picks one item or several, on Base UI Combobox. */\nfunction ComboboxControl(props: ControlProps): JSX.Element {\n  const { label, items, multiple, value, defaultValue, onValueChange, onInputChange, placeholder, required, loading } = props;\n  const { loadingLabel, emptyLabel, clearLabel, doneLabel, removeLabel, customValueLabel, custom, inputRef, sheet } = props;\n  const { autoHighlight, onInputKeyDown, readOnly, inputValue } = props;\n  const field = useField()!;\n  // Ouro's own invalid state (the error prop or the Form's error for this name), not Base UI's,\n  // which would count it as a failed check and block the next submit.\n  const invalid = field.invalid;\n  // The input's text: for the \"nothing matched\" line and the row that keeps typed text.\n  const [text, setText] = useState(\"\");\n  // With allowCustomValue the text is the value, so an item's label is what it submits, as in\n  // the popup (Autocomplete), whatever its `value`.\n  const options = useMemo(\n    () => items.map((item) => {\n      const option = toOption(item);\n      return custom ? { ...option, value: option.label } : option;\n    }),\n    [items, custom],\n  );\n  // Every item seen so far, so a picked value keeps its label when search results change.\n  // A map kept for the component's life (state that is never set), added to as items arrive.\n  const [known] = useState(() => new Map<string, Option>());\n  for (const option of options) known.set(option.value, option);\n  const toSelected = (picked: string): Option => known.get(picked) ?? { value: picked, label: picked };\n  const toBase = (picked: unknown) =>\n    multiple\n      ? ((picked as string[] | undefined) ?? []).map(toSelected)\n      : picked == null || (custom && picked === \"\")\n        ? null\n        : toSelected(picked as string);\n  // With allowCustomValue, typed text that is not an item gets a row of its own, first.\n  const typed = text.trim();\n  const listed =\n    custom && typed !== \"\" && !options.some((option) => option.label === typed)\n      ? [{ value: typed, label: customValueLabel(typed), custom: true }, ...options]\n      : options;\n  const shown = (option: Option) => (option.custom ? option.value : option.label);\n\n  const [open, setOpen] = useState(false);\n  const triggerRef = useRef<HTMLButtonElement>(null);\n  const resetInputRef = useRef<HTMLInputElement>(null);\n  const setInputRef = useMergedRef(inputRef, resetInputRef);\n  useCustomReset(sheet ? triggerRef : resetInputRef, value, props.onReset);\n  const report = onValueChange as ((value: string | string[] | null) => void) | undefined;\n  // The sheet's clear button, beside the field for a single pick that can change.\n  // Stryker disable next-line ConditionalExpression,LogicalOperator,BooleanLiteral: the sheet shows only on a coarse-pointer phone, which the Chromium project mutation runs in cannot be; combobox.touch.test.tsx holds a read-only field's missing clear button there.\n  const sheetClear = !multiple && !readOnly;\n  const showEmpty = !onInputChange || (inputValue ?? text) !== \"\";\n\n  const renderItem = (option: Option) => (\n    <BaseCombobox.Item key={option.value} value={option} disabled={option.disabled} data-ouro-control=\"combobox\" data-ouro-part=\"option\" className={itemClass}>\n      <BaseCombobox.ItemIndicator className=\"col-start-1 flex [&_svg]:size-4\">\n        <Icon>\n          <path d=\"M3.5 8.5 6.5 11.5 12.5 4.5\" />\n        </Icon>\n      </BaseCombobox.ItemIndicator>\n      <ItemContent option={option} />\n    </BaseCombobox.Item>\n  );\n  const body = (className: string) => (\n    <ListBody\n      loading={loading}\n      loadingLabel={loadingLabel}\n      emptyLabel={emptyLabel}\n      showEmpty={showEmpty}\n      className={className}\n      renderItem={renderItem}\n    />\n  );\n\n  const input = (className: string, extra: { \"aria-label\"?: string } = {}) => (\n    <BaseCombobox.Input\n      {...extra}\n      {...inputHandlers(onInputKeyDown)}\n      readOnly={readOnly}\n      ref={setInputRef}\n      data-ouro-control=\"combobox\"\n      data-ouro-part=\"input\"\n      placeholder={placeholder}\n      aria-describedby={sheet ? undefined : field.describedBy}\n      {...(invalid && !sheet ? { \"aria-invalid\": true } : {})}\n      className={className}\n    />\n  );\n\n  const directed = (\n    <BaseCombobox.Root\n      items={listed}\n      multiple={multiple}\n      isItemEqualToValue={(item: Option, picked: Option) => item.value === picked.value}\n      itemToStringLabel={shown}\n      filter={onInputChange ? null : undefined}\n      onInputValueChange={(next, details) => {\n        setText(next);\n        if (details.reason !== \"item-press\") onInputChange?.(next);\n      }}\n      inputValue={inputValue}\n      autoHighlight={autoHighlight}\n      readOnly={readOnly}\n      required={required}\n      inputRef={markInput}\n      openOnInputClick\n      open={open}\n      onOpenChange={(next: boolean, details: { reason: string }) => {\n        // An inline trigger closes Base UI's always-open list; its own click opens our sheet.\n        if (!sheet || details.reason !== \"trigger-press\") setOpen(next);\n      }}\n      {...(value !== undefined ? { value: toBase(value) } : { defaultValue: toBase(defaultValue) })}\n      onValueChange={(next: Option | Option[] | null) =>\n        report?.(Array.isArray(next) ? next.map((option) => option.value) : (next?.value ?? (custom ? \"\" : null)))\n      }\n      {...(sheet\n        ? {\n            inline: true,\n          }\n        : {})}\n    >\n      {sheet ? (\n        <div data-ouro-combobox-field=\"\" className={sheetFieldClass}>\n          <BaseCombobox.Trigger\n            ref={triggerRef}\n            aria-describedby={field.describedBy}\n            {...(invalid ? { \"aria-invalid\": true } : {})}\n            data-ouro-combobox-trigger=\"\"\n            data-ouro-control=\"combobox\"\n            data-ouro-part=\"trigger\"\n            className={triggerClass}\n            // With an inline list there is no Base UI popup for the trigger to open: it opens the sheet.\n            onClick={() => setOpen(true)}\n          >\n            <BaseCombobox.Value placeholder={placeholder}>\n              {(picked: Option | Option[] | null) => {\n                const labels = (Array.isArray(picked) ? picked : picked ? [picked] : []).map(shown);\n                return <span>{labels.length > 0 ? labels.join(\", \") : placeholder}</span>;\n              }}\n            </BaseCombobox.Value>\n            <ChevronIcon />\n          </BaseCombobox.Trigger>\n          {sheetClear && (\n            // Beside the button, not in it: a button can't hold another. It is in the Tab order\n            // here, since the button, not an input, has focus; clearing puts focus back on the button.\n            <BaseCombobox.Clear\n              tabIndex={0}\n              data-ouro-combobox-clear=\"\"\n              className={sheetClearClass}\n              onClick={() => triggerRef.current?.focus()}\n              render={\n                <Button variant=\"plain\" tone=\"secondary\" size=\"sm\" data-ouro-control=\"combobox\" data-ouro-part=\"clear\" className=\"aspect-square px-0\">\n                  <CrossIcon />\n                  <span className=\"sr-only\">{clearLabel}</span>\n                </Button>\n              }\n            />\n          )}\n          <SheetFrame\n            title={label}\n            closeLabel={doneLabel}\n            side=\"bottom\"\n            // One tall snap point: the sheet keeps its height as results filter and load, so the\n            // search input stays where the thumb left it.\n            snapPoints={[1]}\n            open={open}\n            onOpenChange={setOpen}\n            finalFocus={triggerRef}\n            footer={\n              multiple ? (\n                <Button fullWidth data-ouro-control=\"combobox\" data-ouro-part=\"done\" onClick={() => setOpen(false)}>\n                  {doneLabel}\n                </Button>\n              ) : undefined\n            }\n          >\n            <div data-ouro-combobox-search=\"\" className={sheetInputClass}>\n              <div ref={markDismiss} data-ouro-input-group=\"\" className={groupClass}>\n                {input(inputClass, { \"aria-label\": label })}\n              </div>\n            </div>\n            {body(sheetListClass)}\n          </SheetFrame>\n        </div>\n      ) : (\n        <>\n          <BaseCombobox.InputGroup ref={markDismiss} data-ouro-input-group=\"\" className={multiple ? chipsGroupClass : groupClass}>\n            {multiple ? (\n              <BaseCombobox.Chips className=\"contents\">\n                <BaseCombobox.Value>\n                  {(picked: Option[]) => (\n                    <>\n                      {picked.map((option) => (\n                        // Base UI marks a read-only field's chips aria-readonly, which a chip (no role) may\n                        // not carry; the input's readonly already says it.\n                        <BaseCombobox.Chip key={option.value} data-ouro-combobox-chip=\"\" className={chipClass} render={(chip) => <div {...chip} aria-readonly={undefined} />}>\n                          {option.media != null && (\n                            <div data-ouro-combobox-chip-media=\"\" className=\"-ms-1 flex shrink-0\">\n                              {option.media}\n                            </div>\n                          )}\n                          <span>{option.label}</span>\n                          {!readOnly && (\n                            <BaseCombobox.ChipRemove data-ouro-combobox-chip-remove=\"\" data-ouro-control=\"combobox\" data-ouro-part=\"chip-remove\" className={chipRemoveClass}>\n                              <TouchTarget />\n                              <CrossIcon />\n                              <span className=\"sr-only\">{removeLabel(option.label)}</span>\n                            </BaseCombobox.ChipRemove>\n                          )}\n                        </BaseCombobox.Chip>\n                      ))}\n                      {input(chipsInputClass)}\n                    </>\n                  )}\n                </BaseCombobox.Value>\n              </BaseCombobox.Chips>\n            ) : (\n              input(inputClass)\n            )}\n            <EndButtons clearLabel={clearLabel} readOnly={readOnly} />\n          </BaseCombobox.InputGroup>\n          <Popup input={resetInputRef} loading={loading}>{body(listClass)}</Popup>\n        </>\n      )}\n    </BaseCombobox.Root>\n  );\n  // The input decides the direction: a right-to-left page's arrow keys move between its chips from the right.\n  return <PageDirection of={resetInputRef}>{directed}</PageDirection>;\n}\n\n/** A Combobox that accepts any text, on Base UI Autocomplete. */\nfunction AutocompleteControl(props: ControlProps): JSX.Element {\n  const { items, value, onValueChange, onInputChange, placeholder, required, loading } = props;\n  const { loadingLabel, emptyLabel, clearLabel, inputRef, autoHighlight, onInputKeyDown, readOnly } = props;\n  const field = useField()!;\n  // Ouro's own invalid state (the error prop or the Form's error for this name), not Base UI's,\n  // which would count it as a failed check and block the next submit.\n  const invalid = field.invalid;\n  const suggestions = useMemo(() => items.map((item) => toOption(item)), [items]);\n  const report = onValueChange as ((value: string) => void) | undefined;\n  const resetInputRef = useRef<HTMLInputElement>(null);\n  const setInputRef = useMergedRef(inputRef, resetInputRef);\n  useCustomReset(resetInputRef, value, props.onReset);\n  const directed = (\n    <BaseAutocomplete.Root\n      items={suggestions}\n      inputRef={markInput}\n      itemToStringValue={(option: Option) => option.label}\n      filter={onInputChange ? null : undefined}\n      autoHighlight={autoHighlight}\n      readOnly={readOnly}\n      required={required}\n      openOnInputClick\n      value={value as string}\n      onValueChange={(next, details) => {\n        report?.(next);\n        // A picked suggestion is not a new search.\n        if (details.reason !== \"item-press\") onInputChange?.(next);\n      }}\n    >\n      <BaseAutocomplete.InputGroup ref={markDismiss} data-ouro-input-group=\"\" className={groupClass}>\n        <BaseAutocomplete.Input\n          {...inputHandlers(onInputKeyDown)}\n          readOnly={readOnly}\n          ref={setInputRef}\n          data-ouro-control=\"combobox\"\n          data-ouro-part=\"input\"\n          placeholder={placeholder}\n          aria-describedby={field.describedBy}\n          {...(invalid ? { \"aria-invalid\": true } : {})}\n          className={inputClass}\n        />\n        <EndButtons clearLabel={clearLabel} readOnly={readOnly} />\n      </BaseAutocomplete.InputGroup>\n      <Popup input={resetInputRef} loading={loading}>\n        <ListBody\n          loading={loading}\n          loadingLabel={loadingLabel}\n          emptyLabel={emptyLabel}\n          showEmpty={!onInputChange || value !== \"\"}\n          className={listClass}\n          renderItem={(option) => (\n            <BaseAutocomplete.Item key={option.value} value={option} disabled={option.disabled} data-ouro-control=\"combobox\" data-ouro-part=\"option\" className={itemClass}>\n              <ItemContent option={option} />\n            </BaseAutocomplete.Item>\n          )}\n        />\n      </Popup>\n    </BaseAutocomplete.Root>\n  );\n  // End scrolls the input to its end, which in a right-to-left input is a negative scrollLeft.\n  return <PageDirection of={resetInputRef}>{directed}</PageDirection>;\n}\n",
      "type": "registry:ui",
      "target": "@components/ouro/combobox/combobox.tsx"
    }
  ],
  "docs": "A text input that filters a list of items as people type, on the Field contract: pass `label`, `items`, and `error` from your server action or client check. Import: import { Combobox } from \"@/components/ouro/combobox/combobox\", with @/components replaced by your components alias (aliases.components in components.json, such as ~/components). Also installed: button, field, sheet, text-field, the helpers they import in lib/ouro. Needs ouro-base in your stylesheet: add that item once per app, from the same place as this one, if you have not. Docs: https://ui.ouroboros.bot/docs/combobox.md Ouro UI v1.3.257.",
  "type": "registry:ui"
}