combobox — the searchable select

The commit paths are the contract: Enter commits the highlighted row (or, with nothing highlighted, resolves the raw text — exact option, else the custom value when allowCustom, else nothing); blur resolves the same way; Escape reverts to the committed display; Tab keeps the typed text through the same resolution. The “Use “xxx”” row appears only when nothing matched — while matches exist they are the answer.

The ARIA contract is the hard one and this family takes the APG shape with zero focus management: role="combobox" sits on the input, aria-expanded mirrors the panel, aria-controls and aria-owns name the top-layer listbox (a DOM sibling promoted by popover="auto"), and the roving highlight rides aria-activedescendant — focus never enters the panel, so there is no focus restitution to get wrong (measured: after ArrowDown and commit, document.activeElement is still the input). In multiple mode the listbox is aria-multiselectable, the trigger wears chips with per-chip “remove X” buttons, and the committed array crosses to FormData as repeated same-name entries through the faceless form-field bridge — the name prop is intercepted off the native input, which never submits its display text.

The paint is the terminal bezel the select family owns, and the theme axis splits it: the typed atoms (shell border and ground, chips, the active/selected row grounds) freeze at the :root pole while the raw machines (well shadow, row hover, panel ink, focus ring) flip under a scoped .dark — one listbox, two time-bases, detailed in the axis table below. Kinship: select is the composite sibling sharing the panel law; tags-input shares the chip law; cascader is the honest-path cousin — the ruled chain-of-<select>s route for dependent choices that need no typing at all.

Focus one: the text selects itself and the panel opens on the full list with the committed row highlighted (the 2px --primary edge); typing filters live and auto-highlights the first match. Try wasi in the first field — no match, so the “Use “wasi”” row appears in primary; press Enter to commit it as a custom value. The strict field (allowCustom={false}) keeps its committed label instead.

<script lang="ts">
  import Combobox from '@ui/combobox.svelte';
  import type { ComboboxOption } from '@ui/combobox.svelte';

  const backendOptions: ComboboxOption[] = [
    { value: 'node-pty', label: 'node-pty', description: 'conpty / forkpty — the battle-tested addon' },
    { value: 'bun-terminal', label: 'Bun.Terminal', description: 'linux/macos since 1.3.13, windows 1.3.14' },
    { value: '@sigma/pty-ffi', label: '@sigma/pty-ffi', description: 'deno FFI over rust portable-pty' },
    { value: 'termless', label: 'termless', description: 'VT emulator — not a pty host', disabled: true },
  ];

  let backendRoute = $state<string | undefined>('node-pty');
  let backendStrict = $state<string | undefined>(undefined);
  let backendCustom = $state<string | undefined>(undefined);
</script>

<Combobox label="backend — type to filter" bind:value={backendRoute} options={backendOptions} />

<!-- strict: allowCustom={false} reverts stray text on blur -->
<Combobox
  label="strict — no custom values"
  allowCustom={false}
  bind:value={backendStrict}
  options={backendOptions.slice(0, 3)}
  placeholder="Search..."
/>

<!-- no match → the “Use “xxx”” row -->
<Combobox
  label="custom — try “wasi”"
  bind:value={backendCustom}
  options={backendOptions.slice(0, 3)}
  placeholder="Search or type..."
/>

<!-- error wiring: aria-invalid + dashed shell -->
<Combobox label="backend" error="backend is required" options={backendOptions} />

The component keeps the popover orchestration law of the family: popover="auto" panels anchored with CSS Anchor Positioning (anchor-size(width), flip fallbacks, viewport-center when the engine lacks it), focus that never enters the panel — the roving highlight rides aria-activedescendant + aria-owns off the input itself — and geometry from logical properties only, so dir="rtl" mirrors the chevron and the selected-row edge with zero branches.

const backends: ComboboxOption[] = [
  { value: 'node-pty', label: 'node-pty', description: 'conpty / forkpty addon' },
  { value: 'bun-terminal', label: 'Bun.Terminal', description: 'linux/macos 1.3.13+, windows 1.3.14' },
  { value: '@sigma/pty-ffi', label: '@sigma/pty-ffi', description: 'deno FFI over rust portable-pty' },
];

<!-- type to filter (label, case-insensitive); ↑/↓ + Enter commits; Escape
     reverts; Tab keeps. No match + allowCustom → the “Use “xxx”” row -->
<Combobox label="backend" bind:value={backend} options={backends} />

<!-- strict: allowCustom={false} reverts stray text on blur -->
<Combobox label="runtime" allowCustom={false} options={backends} />

<script lang="ts">
  import Combobox from '@ui/combobox.svelte';
  import type { ComboboxOption } from '@ui/combobox.svelte';

  const backendOptions: ComboboxOption[] = [
    { value: 'node-pty', label: 'node-pty' },
    { value: 'bun-terminal', label: 'Bun.Terminal' },
    { value: '@sigma/pty-ffi', label: '@sigma/pty-ffi' },
  ];

  let pickedStacks = $state<string[]>(['node-pty']);
  let clearedRoute = $state<string | undefined>('bun-terminal');
</script>

<!-- multiple: bind an ARRAY in selection order; getAll(name) returns
     the picks byte-for-byte in order -->
<Combobox
  label="stacks (multiple)"
  multiple
  name="stacks"
  bind:value={pickedStacks}
  options={backendOptions}
  placeholder="pick several…"
/>

<!-- showClear: × in the trigger lane; clearing submits honestly empty -->
<Combobox
  label="backend (showClear)"
  showClear
  name="backend-clear"
  bind:value={clearedRoute}
  options={backendOptions}
/>

The transport is the DECIDED one (design.md): no hidden inputs, no joined-string channel — newline-bearing, quote-bearing and arbitrary Unicode values survive byte-for-byte because each value is a separate FormData entry. The breaking change is deliberate and documented: in multiple mode bind:value is string[] — there is no compatibility shim. Blur no longer commits raw text in multiple mode; chips join through explicit Enter / row click only.

<!-- multiple: bind an ARRAY in selection order; the committed
     array submits as repeated same-name FormData entries through the
     form-field bridge's MULTIVALUE seam — getAll(name) returns the
     picks byte-for-byte in order (BREAKING: value becomes string[]) -->
<Combobox label="stacks" multiple bind:value={stacks} options={backends} />

<!-- showClear: × in the trigger lane when something is committed;
     clearing submits honestly empty (no entry, never "undefined") -->
<Combobox label="backend" showClear bind:value={backend} options={backends} />

const stacks = $state<string[]>([]);

<script lang="ts">
  import Combobox from '@ui/combobox.svelte';
  import type { ComboboxOption } from '@ui/combobox.svelte';

  const backendOptions: ComboboxOption[] = [
    { value: 'node-pty', label: 'node-pty' },
    { value: 'bun-terminal', label: 'Bun.Terminal' },
  ];

  let backendRtl = $state<string | undefined>('bun-terminal');
</script>

<!-- logical properties only: dir="rtl" mirrors the chevron and the
     selected-row edge with zero branches -->
<div dir="rtl">
  <Combobox label="backend (rtl)" bind:value={backendRtl} options={backendOptions} />
</div>

The chevron sits in the flex flow, the selected-row edge is border-inline-start, and the panel anchors with CSS Anchor Positioning whose offsets are logical too. The writing mode does the rest.