# Combobox

> A field that suggests answers but always keeps what you type. Choices are a help, never a gate.

Source: https://kwark.space/designSystem/components/combobox

## Usage

### What it is
The app’s `Combobox` (`components/ui/Combobox.tsx`) is a text field with suggestions. Its first line of source says the rule: *a choice is a suggestion: typing an answer never requires adding an option first.* Type *Rooftop of the lab* when the list only knows *Edit suite*, and the field keeps it; the list says **Keep your own answer** instead of *No results*.

It has two modes:
- **Editable** (default): type to filter, or open the full list with the chevron. Used for locations, props and any answer the writer may know better than the list.
- **Choose only** (`editable={false}`): the input is read-only and opens the list on click or Space. Used where the value must be one of a few, such as the measurement unit on a character sheet (`CharacterFieldControls.tsx`: *Centimetres*, *Feet and inches*, *As written*).

### When to use
- One answer, with a list of likely ones and the freedom to write another.

### When not to
- The value must be an existing record with an ID (a scene, a crew member): restrict it and say so, or use a [Select](https://kwark.space/designSystem/components/select.md).
- Several answers: [Multiselect](https://kwark.space/designSystem/components/multiselect.md).
- Searching to navigate somewhere: [Search field](https://kwark.space/designSystem/components/search-field.md).

### Behaviour (from the source)
- Typing calls `onChange` on every keystroke and filters by *contains*, ignoring case.
- The list opens below, or above when there is more room above (it measures `options.length × 44 + 8`, up to 256px).
- Down and Up move the active option; Enter takes it; Escape closes without changing; Tab closes.
- The chevron is an [Icon button](https://kwark.space/designSystem/components/icon-button.md) named *Choices for Location*; pressing it opens the full, unfiltered list.
- Closing on blur: the list closes when focus leaves the whole control.

**Do:** *Rooftop of the lab* stays in the field, with *Keep your own answer* under it.

**Don't:** A red *No matching option* that refuses the writer’s own location until someone adds it to a list.

## Style

### Anatomy

1. **Input**: the shared [Text input](https://kwark.space/designSystem/components/text-input.md) box with 44px reserved on the right (`padding-inline-end: var(--k-tap)`). Placeholder *Choose or type*.
2. **Chevron**: a 44px-wide icon button filling the input’s height, 14px glyph in `--k-text-2`; it turns 180° while open.
3. **List**: 4px below the input, as wide as it, at most 256px tall then scrolls. 4px padding, 1px `--k-line`, 6px corners, `--k-surface`. The app draws it with a line and no shadow.
4. **Option**: 44px tall, 8px 12px padding, 6px corners, 14px text that wraps anywhere. Active and current: `--k-raise`.
5. **Keep your own answer**: a presentation row in `--k-text-2` when nothing matches.

The specimen shows the list in the page flow; in the app it is absolutely positioned (`.k-combobox > ul`) and stacks above neighbours with `--ds-z-high`.

### Tokens

| Token | Light | Dark |
|---|---|---|
| `--k-surface` | #ffffff | #1a1a1a |
| `--k-bg` | #f8fafc | #191919 |
| `--k-raise` | #f1f5f9 | #252525 |
| `--k-line` | #e2e8f0 | rgba(255, 255, 255, .1) |
| `--k-text` | #0f172a | #e3e3e3 |
| `--k-text-2` | #5b6779 | #9ca3af |
| `--k-accent-soft` | #e8b58b | #e8b58b |
| `--k-tap` | 44px |  |
| `--k-radius-control` | 6px |  |
| `--k-fs-body` | 14px |  |

## Code

### React

In the Kwark app: `import Combobox from '@/components/ui/Combobox'`.

```tsx
<Combobox id="location" label="Location" value={location}
  onChange={setLocation} options={['Edit suite', 'Edit suite corridor', 'Rooftop']} />

// Choose only (no typing), as the measurement unit on a character sheet:
<Combobox id={`${id}-units`} label="Height unit" editable={false}
  value="Feet and inches" options={['Centimetres', 'Feet and inches', 'As written']} onChange={chooseUnit} />
```

| Prop | Type | Notes |
|---|---|---|
| `id` | `string` | Stable field ID; the list items are named from it. |
| `label` | `string` | Becomes the input’s aria-label and the chevron’s name (*Choices for Location*). |
| `value` | `string` | What the field holds; may be text that is not an option. |
| `options` | `string[]` | Suggestions, filtered by what is typed. |
| `onChange` | `(value: string) => void` | Called on every keystroke and every choice. |
| `editable` | `boolean` | Default true. False makes it choose-only: Space or click opens the list. |
| `readOnly` | `boolean` | Hides the chevron and the list. |

### HTML and CSS

Works anywhere with `kwark.css`.

```html
<div class="kw-specimen-row">
  <label class="kw-field"><span class="kw-label">Location</span><span class="kw-combo"><span class="kw-combo__field"><input class="kw-input" type="text" value="Edit" role="combobox" aria-autocomplete="list" aria-expanded="true" placeholder="Choose or type" autocomplete="off"><button class="kw-ibtn" type="button" aria-label="Choices for Location" aria-haspopup="listbox" aria-expanded="true"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m6 9 6 6 6-6"/></svg></button></span><ul class="kw-combo__list" role="listbox" aria-label="Location choices"><li role="option" aria-selected="true">Edit suite</li><li role="option" aria-selected="false">Edit suite corridor</li></ul></span></label>
  <label class="kw-field"><span class="kw-label">Location</span><span class="kw-combo"><span class="kw-combo__field"><input class="kw-input" type="text" value="Rooftop of the lab" role="combobox" aria-autocomplete="list" aria-expanded="true" placeholder="Choose or type" autocomplete="off"><button class="kw-ibtn" type="button" aria-label="Choices for Location" aria-haspopup="listbox" aria-expanded="true"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m6 9 6 6 6-6"/></svg></button></span><ul class="kw-combo__list" role="listbox" aria-label="Location choices"><li role="presentation">Keep your own answer</li></ul></span></label>
</div>
<div class="kw-specimen-row">
  <label class="kw-field"><span class="kw-label">Height unit</span><span class="kw-combo"><span class="kw-combo__field"><input class="kw-input" type="text" value="Feet and inches" role="combobox" aria-autocomplete="none" aria-expanded="false" readonly autocomplete="off"><button class="kw-ibtn" type="button" aria-label="Choices for Height unit" aria-haspopup="listbox" aria-expanded="false"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m6 9 6 6 6-6"/></svg></button></span></span><span class="kw-hint">Choose only: Space opens the list.</span></label>
  <label class="kw-field"><span class="kw-label">Location</span><span class="kw-combo"><span class="kw-combo__field"><input class="kw-input" type="text" value="Edit suite" aria-readonly="true" readonly></span></span><span class="kw-hint">Read only: no chevron, no list.</span></label>
</div>
```

## Accessibility

### Keyboard
| Key | Editable | Choose only |
|---|---|---|
| Typing | Filters and opens | — |
| Space | Types a space | Opens or closes |
| Down / Up | Opens; moves the active option | Same |
| Home / End | Moves the text caret | First and last option |
| Enter | Takes the active option | Same |
| Escape | Closes without changing | Same |

### Roles and names
- The input is `role="combobox"` with `aria-autocomplete="list"` (or `"none"` when choose-only), `aria-expanded`, `aria-controls` while open, and `aria-activedescendant` for the active option. Focus never leaves the input.
- The list is `role="listbox"` named *Location choices*; options have `aria-selected`.
- The empty row is `role="presentation"`, so it is not offered as a choice.
- The chevron is `aria-haspopup="listbox"` and does not take focus from the input on mouse down.

## For agents

### Rules

- **Must** keep text the person typed when it matches no option; show "Keep your own answer", never an error.
- **Must** use the shared `Combobox` from components/ui; never a native `<datalist>`.
- **Always** name the chevron "Choices for" and the field’s label.
- **Never** move focus into the list; use aria-activedescendant from the input.
- **Always** use choose-only mode (editable={false}) when the value must be one of a fixed few.

### AI readiness test

**Task:** Add a Location field to the scene details panel.

**Give the agent:** Combobox, Text input.

**Constraint:** Locations come from the project, but the writer may name a new one.

**A reliable answer:**
- Uses the shared Combobox
- Placeholder Choose or type
- Typed new location is kept
- Keep your own answer when nothing matches
- Chevron named Choices for Location
