---

## Combobox
Searchable menu (autocomplete) combining a text input with a
filterable option list. Implements the ARIA combobox pattern with
keyboard navigation, custom filtering, and two-way bindable state.

**Import:** `import { Combobox } from '@urbicon-ui/blocks';`

### Examples
```svelte
<Combobox
  options={[
    { label: 'Apple', value: 'apple' },
    { label: 'Banana', value: 'banana' },
    { label: 'Cherry', value: 'cherry' }
  ]}
  bind:value={selected}
  placeholder="Search fruit…"
/>
```

```svelte
<Combobox
options={tenants.map((t) => ({ label: t.name, value: t.id }))}
bind:value={tenantId}
/>
```

```svelte
<Combobox
  options={countries}
  bind:value={country}
  filter={(option, query) => option.label.toLowerCase().startsWith(query.toLowerCase())}
  clearable
  size="lg"
/>
```

### Variants
- size: lg, md, sm (default: md)
- disabled: true (default: false)
- open: true (default: false)
- tier: commit, modify (default: modify)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| options | `ComboboxOption<T>[]` | yes |  | Array of selectable options. Each needs a unique `value`. |
| ...ComboboxVariants | `VariantProps` | no |  | Styling variants from ComboboxVariants |
| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
| class | `string` | no |  | Extra classes merged onto the root wrapper element. |
| clearable | `boolean` | no | false | Show a clear button when a value is selected. Click or press Escape to reset. |
| closeOnClickOutside | `boolean` | no |  | Whether the listbox closes on outside click. Default `true`. Set to `false` to pin the listbox open while the consumer manages dismissal explicitly. |
| closeOnEscape | `boolean` | no |  | Whether the listbox closes on Escape key. Default `true`. Set to `false` for inline contexts where Escape should be intercepted by an outer widget (e.g. a row editor that wants to revert on Escape). |
| customOption | `Snippet<[ComboboxOption<T>, boolean]>` | no |  | Custom option renderer. Receives the option and whether it is selected. |
| disabled | `boolean` | no | false | Disable the entire combobox. |
| error | `string` | no |  | Error message — replaces helper text and flags the field as invalid. |
| filter | `(option: ComboboxOption<T>, query: string) => boolean` | no |  | Custom filter replacing the built-in case-insensitive label match. Return `true` to include an option. |
| helper | `string` | no |  | Helper text shown below the field. Hidden when an error is set. |
| id | `string` | no |  | Deterministic HTML `id` for the component. Auto-generated when omitted. |
| label | `string` | no |  | Field label rendered above the input. |
| mint | `MintProp` | no | 'none' | Micro-interaction preset. Form controls default to 'none' for a clean feel. |
| name | `string` | no |  | Shared `name` for a hidden input for native form submission. |
| noResultsText | `string` | no | 'No results found' | Text displayed when the filter produces no matches. |
| onClickOutside | `() => void` | no |  | Fires after an outside click closes the listbox. Use for analytics or side-effects on dismiss. Does NOT control whether the listbox closes — that is governed by `closeOnClickOutside`. |
| onEscape | `() => void` | no |  | Fires after Escape closes the listbox. Use for analytics or to clear ephemeral state on dismiss. Does NOT control whether the listbox closes — that is governed by `closeOnEscape`. |
| onValueChange | `(value: T | null) => void` | no |  | Fires after the selected value changes. Receives the new value or `null` on clear. |
| open | `boolean` | no | false | Controls the open state of the listbox. Supports `bind:open`. |
| placeholder | `string` | no | 'Search…' | Placeholder shown when the input is empty. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ Combobox: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
| query | `string` | no |  | Current search query text. Supports `bind:query` for external control (e.g. server-side filtering). |
| required | `boolean` | no | false | Marks the field as required. Adds the asterisk on the label. |
| slotClasses | `Partial<Record<ComboboxSlots, string>>` | no |  | Per-slot class overrides merged with tv() styles. Slots: base | label | requiredMark | inputWrapper | input | message | hint | listbox | option | optionActive | optionSelected | noResults | clear | chevron |
| unstyled | `boolean` | no | false | Remove all default tv() classes — only user-provided classes apply. |
| value | `T | null` | no |  | Currently selected value. Supports `bind:value` for two-way binding. |
| size | `'lg' | 'md' | 'sm'` | no | md | Controls the dimensions, padding, and text size of the Combobox. Affects the component's physical footprint. Available options: lg, md, sm. |
| tier | `'commit' | 'modify'` | no | modify | Controls the tier behavior and appearance of the Combobox component. Available options: commit, modify. |

Inherited from:
- ComboboxVariants (external)
- Omit<HTMLAttributes<HTMLDivElement>, 'children'> (omit-pattern)