Combobox

1'use client';
2 
3import * as React from 'react';
4 
5// @interlace/combobox v1.0.0 — Interlace design system.
6// Docs, props and live preview: https://ds.interlace.tools/c/combobox
7// What changed since: https://ds.interlace.tools/c/combobox#history
8// Generated banner — keep it, the upgrade diff reads this version.
9 
10/**
11 * @interlace/ui — Combobox
12 *
13 * A text input that filters a list. Built on `@base-ui/react/combobox`: Base UI
14 * owns the filtering (`Intl.Collator`-backed `useFilter`), the
15 * combobox/listbox ARIA pairing, VIRTUAL focus (the input keeps DOM focus and
16 * `aria-activedescendant` moves), single + multiple selection, chips, and the
17 * whole keyboard model. We own the surface — size, tokens, focus ring, target
18 * sizes.
19 * Mirrors: https://ui.shadcn.com/docs/components/combobox
20 *
21 * ## Combobox vs Select vs DropdownMenu
22 *
23 * `Select` is the right primitive when the user picks from a list they can
24 * read at a glance and can NOT type into. `Combobox` is for the list that is
25 * too long to scan — the user types to narrow it. `DropdownMenu` is for
26 * ACTIONS, not values. Reaching for a Combobox under ~7 options is a
27 * downgrade: it trades a one-keystroke listbox for a text field.
28 *
29 * ## Anatomy
30 *
31 *   Combobox (Root)                          (no DOM — state + filtering)
32 *     ├─ ComboboxChips                       (multiple only)
33 *     │   └─ ComboboxChip → ComboboxChipRemove
34 *     ├─ ComboboxControl                     (ours — relative row, no Base UI part)
35 *     │   ├─ ComboboxInput                   (input — data-min-viewport=320)
36 *     │   ├─ ComboboxClear                   (button, keepMounted=false)
37 *     │   └─ ComboboxTrigger → ComboboxIcon  (optional open button)
38 *     └─ ComboboxContent                     (portal → positioner → popup)
39 *         ├─ ComboboxEmpty                   (renders only when 0 results)
40 *         ├─ ComboboxStatus                  (polite live region — async lists)
41 *         └─ ComboboxList
42 *             ├─ ComboboxGroup → ComboboxGroupLabel
43 *             ├─ ComboboxItem                (repeats)
44 *             └─ ComboboxSeparator
45 *
46 * ## Filtering — the one trap in this API
47 *
48 * Base UI filters through `ComboboxCollection`, which `ComboboxList` wraps
49 * implicitly when its child is a FUNCTION. Both of these render; only the
50 * first one filters:
51 *
52// … truncated