---

## Select
Discriminated union over `multiple`. Consumers pick a single shape at the
call site and the value type narrows accordingly — `<Select multiple bind:value>`
binds to `T[]`, `<Select bind:value>` binds to `T | null`. See
`SelectSingleProps` / `SelectMultipleProps` for the per-mode details.

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

### Examples
```svelte
<Select
  label="Country"
  options={[
    { label: 'Germany', value: 'de' },
    { label: 'France', value: 'fr' },
    { label: 'Spain', value: 'es' },
  ]}
  bind:value={country}
  placeholder="Choose a country"
/>
```

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

```svelte
<Select
  label="Tags"
  options={tags}
  multiple
  selectionIndicator="checkbox"
  bind:value={selectedTags}
/>
```

```svelte
<Select options={...} multiple bind:value bind:open>
  {#snippet customTrigger(selected, isOpen, clear)}
    <Button variant="ghost" size="sm">
      <FilterIcon />
      {#if selected.length > 0}
        <Badge size="xs">{selected.length}</Badge>
      {/if}
    </Button>
  {/snippet}
</Select>
```

```svelte
<Select
  label="Role"
  groups={[
    { label: 'Engineering', options: [
      { label: 'Frontend', value: 'fe' },
      { label: 'Backend', value: 'be' }
    ]},
    { label: 'Design', options: [
      { label: 'UX', value: 'ux' },
      { label: 'Visual', value: 'vis' }
    ]}
  ]}
  bind:value={role}
  required
  error={roleError}
/>
```

### Variants
- variant: filled, ghost, outlined, underline (default: outlined)
- size: lg, md, sm (default: md)
- disabled: true (default: false)
- error: true (default: false)
- messageType: error, helper (default: helper)
- open: true (default: false)
- required: true (default: false)
- selected: true (default: false)
- tier: commit, modify (default: modify)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| class | `string` | no |  | Extra classes merged onto the root wrapper element. |
| clearable | `boolean` | no | false | Show a clear button when a value is selected. |
| 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). |
| closeOnSelect | `boolean` | no |  | Whether the listbox closes after a selection is made. Defaults to `true` in single-select and `false` in multi-select — the multi-select default lets users tick multiple options without re-opening, matching the established multi-select pattern. |
| customItem | `Snippet<[SelectOption<T>, boolean, () => void]>` | no |  | Replace the default per-option rendering. Receives the option, its selection state, and a `toggle` callback (call to select/deselect). The outer `<div role="option">` container is still owned by Select for ARIA correctness — the snippet renders the option's visible contents.  Positional args: `(option, isSelected, toggle)`. |
| customTrigger | `Snippet<[SelectOption<T>[], boolean, () => void]>` | no |  | Replace the entire trigger button (chevron, label, clear control) with a custom element. Receives the selected options, current open state, and a `clear` callback. Use this for icon-only triggers, badge-counter triggers, or any non-standard chrome — the Select still owns open/close + selection state via the returned callbacks.  Positional args: `(selected, open, clear)`. |
| customTriggerContent | `Snippet<[SelectOption<T>[]]>` | no |  | Replace only the trigger's text/label area (chevron and clear button stay intact). Receives the selected options. Useful for showing icons next to the label, badges with counts, or formatted multi-select summaries while keeping the standard outlined-Select chrome.  Positional args: `(selected)`. |
| disabled | `boolean` | no | false | Whether the Select is disabled and non-interactive |
| error | `string` | no |  | Error message below the select. Overrides `helper` and forces danger styling. |
| groups | `SelectGroup<T>[]` | no |  | Grouped options with section labels. Takes precedence over `options`. |
| helper | `string` | no |  | Helper text below the select. Hidden when `error` is set. |
| id | `string` | no |  | Explicit `id` for the component. Auto-generated if omitted. |
| label | `string` | no |  | Label text displayed above the select, auto-linked via `id`. |
| mint | `MintProp` | no | 'none' | Micro-interaction preset. |
| multiPlaceholder | `string | ((selected: SelectOption<T>[]) => string)` | no |  | Placeholder shown when one or more values are picked. Pass a string for a static label ("3 selected") or a function that receives the currently selected options and returns a custom string. When unset, the trigger lists the selected labels comma-separated. |
| multiple | `'false' | 'true'` | no |  | Single-select mode (the default). Omit or set to `false` explicitly. |
| name | `string` | no |  | Shared `name` for a hidden input for native form submission. |
| nullOption | `string | NullOptionConfig` | no |  | Render an explicit "no value" option as the first row of the listbox. Selecting it sets the bound value to `null`. When `value` is `null`, the trigger displays this label instead of the placeholder.  Pass a string to use it as the label, or a `NullOptionConfig` for more control. Ignored when `groups` is set — group structures own their option list. |
| 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 whether the listbox is open. Supports `bind:open` for parents that need to coordinate open/close (e.g. attaching a custom trigger button outside the Select wrapper). |
| options | `SelectOption<T>[]` | no |  | Flat list of selectable options. |
| placeholder | `string` | no | 'Select...' | Text shown when no value is selected. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ Select: {...} }}>`. 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. |
| required | `boolean` | no | false | Adds a required asterisk to the label. |
| selectionIndicator | `'checkmark' | 'none'` | no |  | Selection indicator rendered next to each option. - `'checkmark'` — trailing check icon (default) - `'none'` — no indicator (typical when using `customItem`) |
| slotClasses | `Partial<Record<SelectSlots, string>>` | no |  | Per-slot class overrides merged with tv() styles. Slots: wrapper (root — what `class` also targets) | base | trigger | triggerText | placeholder | chevron | clear | listbox | option | optionLabel | optionCheck | optionCheckbox | group | groupLabel | label | message. |
| syncWidth | `boolean` | no | true | Whether the listbox matches the trigger's width. Set `false` for icon-only or compact triggers where the listbox should size to its content instead. |
| unstyled | `boolean` | no |  | Remove all default tv() classes. |
| usePortal | `boolean` | no | true | When true, the listbox is rendered into the browser top layer via the native `popover` API, so it cannot be clipped by `overflow: auto` ancestors. When false, the listbox stays in the regular DOM flow — useful inside other popovers/portals to avoid double-portaling. |
| value | `T[]` | no | [] | Currently selected values. Supports `bind:value`. |
| variant | `SelectVariants['variant']` | no | 'outlined' | Visual style. - `outlined` (default) — visible border, surface-base background - `filled` — surface-interactive fill, no border (compact toolbars) - `ghost` — transparent until hover/focus (dense menus, inline editors) - `underline` — bottom-line only, no border-box (editorial knob-strips,   docs playgrounds) |
| size | `'lg' | 'md' | 'sm'` | no | md | Controls the dimensions, padding, and text size of the Select. Affects the component's physical footprint. Available options: lg, md, sm. |
| messageType | `'error' | 'helper'` | no | helper | Controls the messageType behavior and appearance of the Select component. Available options: error, helper. |
| selected | `'true'` | no | false | Controls the selected behavior and appearance of the Select component. Available options: true. |
| tier | `'commit' | 'modify'` | no | modify | Controls the tier behavior and appearance of the Select component. Available options: commit, modify. |