@openreachtech/furo-vue 1.6.0 → 1.7.0

package/docs/furo-autocomplete-field.md

@@ -0,0 +1,719 @@
+# `<FuroAutocompleteField>` Interface Specification
+
+## Overview
+
+`<FuroAutocompleteField>` is a **shipped** autocomplete molecule in the Furo-Vue component system. Its **public contract is Furo-defined**: application developers pass `parcel`, listen to Furo emits, and use documented slots — without importing the underlying primitive library.
+
+Implementation uses a headless combobox primitive inside `lib/components/molecules/FuroAutocompleteField/`* only. That dependency is **not** part of the application API.
+
+Contract style aligns with `[FuroTextField](./furo-text-field.md)` (Furo-first `parcel` + fallthrough where applicable):
+
+- behavior via `:parcel` (`FuroAutocompleteFieldParcel`)
+- HTML / form attributes via fallthrough (`name`, `required`, `id`, `aria-`*, `disabled`, …)
+- Furo emits (`change-value`, `update:value`, `search-keyword`, …)
+- `v-model:value` syncs when the parent controls `parcel.value`
+
+**Public SFC props:** `parcel` (behavior) and `inputParcel` (attributes of the inner `<input role="combobox">`).
+
+**Model shape:** the combobox stores **full option objects** (leaf rows from `parcel.options`), not only `option.value`. `@update:value` and `parcel.value` use that same shape (`FuroAutocompleteOption`, primitive leaf, or arrays thereof in multi mode).
+
+**Input display text:** the input part uses `extractDisplayValue()` → `option.label` (or `String(option)` for primitive leaves). There is no public display callback prop.
+
+`@change-value` fires on **committed gestures** (list selection, select-all toggle, clear) — not on every keystroke. Use `@search-keyword` for debounced parent-driven search.
+
+Read `[FuroTextField](./furo-text-field.md)` for the shared `parcel` mental model.
+
+### Abstraction boundary
+
+
+| Layer                          | Responsibility                                                             |
+| ------------------------------ | -------------------------------------------------------------------------- |
+| Application                    | `parcel`, listeners, slots; replaces `parcel.options` for API-driven lists |
+| Molecule (`FuroAutocompleteField`) | Maps parcel → the underlying combobox primitive; DOM, debounce, client filter, emits |
+| Underlying primitive (maintainers) | Internal only; not part of the application API                             |
+
+
+**Rules:**
+
+1. Documented `parcel` keys are the **Furo contract**. The getter merges defaults, then `...props.parcel`, then the template spreads `v-bind="context.parcel"` onto the root (additional keys may reach the underlying primitive but are **not** supported for apps).
+2. Do **not** use the legacy `triggerParcel` / `portalParcel` / `contentParcel` props — they are **not** on the SFC. The one part-level prop is `inputParcel`, which carries plain input attributes only (see [Accessible name and form wiring](#accessible-name-and-form-wiring)).
+3. `FuroSelect` still uses the older primitive passthrough pattern; autocomplete is Furo-first.
+
+**Source files:**
+
+- `lib/components/molecules/FuroAutocompleteField/FuroAutocompleteField.vue`
+- `lib/components/molecules/FuroAutocompleteField/FuroAutocompleteFieldContext.js`
+- `lib/components/molecules/FuroAutocompleteField/AutocompleteEmitPayload.js`
+- `app/shares/TimerClerk.js`
+
+**Live samples:** `pages/samples/components/playground/FuroAutocompleteFieldPlayground/index.vue`
+
+---
+
+## Public API at a glance
+
+
+| Area                                                        | Status              | Notes                                                                     |
+| ----------------------------------------------------------- | ------------------- | ------------------------------------------------------------------------- |
+| **SFC surface**                                             |                     |                                                                           |
+| Public props `parcel` and `inputParcel` (+ attribute fallthrough) | **Implemented** | See `[FuroAutocompleteFieldParcel](#furoautocompletefieldparcel)`   |
+| `inputParcel` → inner `<input role="combobox">` (`id`, `name`, `aria-*`, `required`, …) | **Implemented** | Gives the combobox an accessible name; see [Accessible name and form wiring](#accessible-name-and-form-wiring) |
+| **Selection & options**                                     |                     |                                                                           |
+| Single + multi; groups, separators, option `icon`           | **Implemented**     | Model = full leaf option object(s), not bare `value`                      |
+| `parcel.value` + `v-model:value`                            | **Implemented**     | Watches `parcel.value` and fallthrough `value`                            |
+| Client filter (`localCompare: true`)                        | **Implemented**     | `filteredOptions()` + the primitive's `useFilter` collator                |
+| Parent-owned list (`localCompare: false`)                   | **Implemented**     | Full `parcel.options`; parent filters (e.g. API)                          |
+| `loading`, `invalid`, `disabled`, `multiple`                | **Implemented**     |                                                                           |
+| `showClear`, `showSelectAll`, `selectAllText`, `emptyText`  | **Implemented**     | Defaults merged in context `parcel` getter                                |
+| **Search & popover**                                        |                     |                                                                           |
+| Debounced `search-keyword` (`string`)                       | **Implemented**     | `TimerClerk`; only while popover open; also `''` on clear                 |
+| `parcel.searchKeyword` → input                              | **Partial**         | One-way watch into `internalSearchKeywordRef`; no `update:search-keyword` |
+| `v-model:search-keyword`                                    | **Not implemented** |                                                                           |
+| Popover open/close                                          | **Internal only**   | `internalOpenPopoverRef`; keyword cleared when popover opens              |
+| `parcel.open` / `v-model:open`                              | **Not implemented** | Template `:open` overrides `parcel.open` from `v-bind`                    |
+| **Emits**                                                   |                     |                                                                           |
+| `update:value`, `change-value`                              | **Implemented**     | Select row, select-all, clear, **chip remove**                            |
+| `search-keyword`                                            | **Implemented**     | Payload is a **string** (not `{ searchKeyword }`)                         |
+| `update:search-keyword`, `update:open`, `commit-value`      | **Not implemented** | Listed on SFC `emits` only; never fired from context                      |
+| **Slots**                                                   |                     |                                                                           |
+| Documented slots (`option-text`, `group-label`, `empty`, …) | **Implemented**     | No `input` / root `trigger` slots                                         |
+| `select-all` scoped `{ checked, indeterminate, disabled }`  | **Not implemented** | Typedef only; slot has no scoped props wired                              |
+| **Spec debt (not in runtime)**                              |                     |                                                                           |
+| Free-form (`allowFreeForm`, `commit-value` on Enter/blur)   | **Not implemented** |                                                                           |
+| Closed `parcel` (reject unknown keys before the primitive) | **Not implemented** | Extra keys still spread to the root                                       |
+
+
+---
+
+## Props
+
+### Rule: `parcel` vs attributes
+
+
+| Mechanism                               | When to use                | Application sees                                                |
+| --------------------------------------- | -------------------------- | --------------------------------------------------------------- |
+| `:parcel`                               | Furo autocomplete behavior | `FuroAutocompleteFieldParcel` (+ merged defaults)               |
+| `:input-parcel`                         | `id`, `name`, `aria-label`, `aria-labelledby`, `aria-describedby`, `required`, … | Bound onto the inner `<input role="combobox">`      |
+| Attributes on `<FuroAutocompleteField>` | e.g. `class`, `style`      | Vue fallthrough to the root wrapper (default `inheritAttrs`); **not** the input |
+
+
+> `**parcel` must be JSON-serializable** — no functions inside `parcel`.
+
+```html
+<FuroAutocompleteField
+  v-model:value="context.assigneeRef.value"
+  :parcel="{
+    placeholder: 'Search assignee',
+    options: context.assigneeOptions,
+    localCompare: false,
+    debounceMilliseconds: 300,
+    loading: context.statusReactive.isLoadingAssignees,
+    invalid: context.statusReactive.isInvalidAssignee,
+  }"
+  name="assignee"
+  @search-keyword="context.onSearchAssignees({ searchKeyword: $event })"
+/>
+```
+
+> `**@search-keyword` payload is a `string**`, not `{ searchKeyword }`. Handlers may accept either for forward compatibility (see playground).
+
+### Component props (public)
+
+
+| Prop     | Type                                    | Default | Description                     |
+| -------- | --------------------------------------- | ------- | ------------------------------- |
+| `parcel` | `FuroAutocompleteFieldParcel` or `null` | `null`  | Furo behavior (see table below) |
+| `inputParcel` | `FuroAutocompleteFieldInputParcel` or `null` | `null` | Attributes bound onto the inner `<input role="combobox">`. Mirrors `FuroSelect`'s `triggerParcel` |
+
+### Accessible name and form wiring
+
+The real control is the inner `<input role="combobox">`, not the root wrapper (a `div`). A `label[for]`, `aria-label`, `aria-labelledby` or `aria-describedby` on the wrapper never reaches it, so route them through `inputParcel`:
+
+```html
+<label id="assignee-label" for="assignee-input">Assignee</label>
+<FuroAutocompleteField
+  v-model:value="context.assigneeRef.value"
+  :parcel="{ options: context.assigneeOptions }"
+  :input-parcel="{
+    id: 'assignee-input',
+    name: 'assignee',
+    'aria-describedby': 'assignee-hint',
+    required: true,
+  }"
+/>
+```
+
+`FuroControlBlock` emits `<label :for="controlId">`; pass the same id as `inputParcel.id`.
+
+`inputParcel` is `InputHTMLAttributes` without `placeholder` and `value`. The component keeps the placeholder (`parcel.placeholder`), the display text and the search keyword for itself, and the primitive keeps `role`, `aria-expanded`, `aria-controls` and `aria-autocomplete`.
+
+
+### `FuroAcceptableValue`
+
+Primitive or object carried in option `value` and payloads:
+
+`string | number | bigint | Record<string, unknown> | null`
+
+The **model** for the field is usually a `**FuroAutocompleteOption` leaf object** (or array of them), not bare `FuroAcceptableValue`, unless options are primitive leaves.
+
+### `FuroAutocompleteFieldParcel`
+
+Keys read in `FuroAutocompleteFieldContext` and/or merged in the `parcel` getter (defaults shown).
+
+
+| Key                    | Type                                                             | Default (getter)     | Description                                                                               |
+| ---------------------- | ---------------------------------------------------------------- | -------------------- | ----------------------------------------------------------------------------------------- |
+| `value`                | `FuroAutocompleteOption | FuroAcceptableValue | Array<…> | null` | —                    | Controlled selection; synced to `internalValueRef` (with fallthrough `value` as fallback) |
+| `options`              | `Array<FuroAutocompleteOption | FuroAcceptableValue>`            | `[]`                 | List rows (groups + leaves)                                                               |
+| `optionLabel`          | `string \| ((option) => string)`                                 | uses `option.label`  | Key name or function that selects each option's display label; also drives local filtering. See [Custom option shape](#custom-option-shape) |
+| `optionValue`          | `string \| ((option) => value)`                                  | whole option object  | Key name or function that selects each option's model value. When unset, `update:value` emits the whole option object (historical default); when set, it emits that key's value or the function's result |
+| `maxVisibleChips`      | `number`                                                         | `null`               | Multi only: render only the first N selected chips, then a `+{count}` overflow indicator. `null` means no cap |
+| `chipOverflow`         | `'wrap' \| 'ellipsis'`                                           | `'wrap'`             | How selected chips behave when they exceed the trigger width: `wrap` flows onto multiple lines; `ellipsis` keeps a single line and truncates |
+| `placeholder`          | `string`                                                         | `'Select an option'` | Input placeholder                                                                         |
+| `loading`              | `boolean`                                                        | `false`              | Input spinner; `filteredOptions()` returns `[]`; suppresses empty state                   |
+| `invalid`              | `boolean`                                                        | `false`              | Root `.invalid` class                                                                     |
+| `disabled`             | `boolean`                                                        | `false`              | Disables combobox                                                                         |
+| `textDirection`        | `'toRight' | 'toLeft'`                                           | `'toRight'`          | Maps to the primitive's `dir` (`ltr` / `rtl`)                                             |
+| `multiple`             | `boolean`                                                        | `false`              | Multi-select; chips in anchor                                                             |
+| `showClear`            | `boolean`                                                        | `true`               | Clear control shown when value selected                                                   |
+| `localCompare`         | `boolean`                                                        | `true`               | `true` → client filter via `useFilter` collator; `false` → parent-owned `options`         |
+| `debounceMilliseconds` | `number`                                                         | `300`                | Debounce for `search-keyword` (`TimerClerk`)                                              |
+| `openOnClick`          | `boolean`                                                        | `true`               | Passed through to the root                                                                |
+| `showSelectAll`        | `boolean`                                                        | `false`              | Multi only; sentinel select-all row                                                       |
+| `selectAllText`        | `string`                                                         | `'Select All'`       | Select-all row label                                                                      |
+| `emptyText`            | `string`                                                         | `'No options.'`      | Default `#empty` copy                                                                     |
+| `creatable`            | `boolean`                                                        | `false`              | Show a "create new" row when the trimmed keyword has no exact label/value match (case-insensitive) |
+| `createOptionText`     | `string`                                                         | `'Create "{keyword}"'` | Create-row text template; `{keyword}` is replaced with the trimmed keyword. Override for i18n / word order |
+| `searchKeyword`        | `string`                                                         | —                    | **Partial** — parent → internal input via watch; no `update:search-keyword`               |
+| `open`                 | `boolean`                                                        | —                    | **Not implemented** — template `:open` uses `internalOpenPopoverRef`                      |
+
+
+Additional keys on `props.parcel` are spread to the root (primitive passthrough). Only the keys above are the **supported Furo contract**.
+
+#### `FuroAutocompleteOption` (leaf / group)
+
+
+| Key         | Type                  | Description                                                         |
+| ----------- | --------------------- | ------------------------------------------------------------------- |
+| `value`     | `FuroAcceptableValue` | Required on leaf rows                                               |
+| `label`     | `string`              | Display, filter text, and input display via `extractDisplayValue()` |
+| `disabled`  | `boolean`             | Row disabled; skipped in select-all when `true`                     |
+| `separator` | `boolean`             | Renders `#separator` after row                                      |
+| `icon`      | `IconProps`           | Optional `#option-icon`                                             |
+| `options`   | `Array<…>`            | Non-empty → **group** (`isGroupOption()`)                           |
+
+
+Extra JSON-serializable keys (e.g. `department`) are allowed for slots and parent logic.
+
+#### Option equality (`compareOption`)
+
+Selection matching uses `compareOption()`:
+
+- Object leaves with `value` key: `JSON.stringify(optionA.value) === JSON.stringify(optionB.value)`
+- Otherwise: strict equality (`===`)
+
+#### Custom option shape
+
+By default the field reads `option.label` for display / filter text and stores
+the **whole option object** as the model value. When options do not follow that
+shape (for example `{ id, name }`), map them with `optionLabel` / `optionValue`:
+
+- `optionLabel` — a key name (`'name'`) or a function (`option => option.name`)
+  that selects the **display / filter label** for each option. When unset,
+  `option.label` is used.
+- `optionValue` — a key name (`'id'`) or a function that selects the **model
+  value**. When unset, `update:value` emits the whole option object (the
+  historical default); when set, it emits that key's value or the function's
+  result.
+
+Both keys are backward-compatible: with neither set, behavior is exactly as
+before (label = `option.label`, value = the whole option object).
+
+```html
+<FuroAutocompleteField
+  v-model:value="context.memberRef.value"
+  :parcel="{
+    placeholder: 'Search member',
+    optionLabel: 'name',
+    optionValue: 'id',
+    options: [
+      { id: 50001, name: 'Ada Lovelace' },
+      { id: 50002, name: 'Alan Turing' },
+    ],
+  }"
+  @change-value="context.onChangeMember({ payload: $event })"
+/>
+```
+
+#### Chip overflow (multiple mode)
+
+In `multiple` mode, `maxVisibleChips` caps how many selected chips render before
+a `+{count}` overflow indicator; `chipOverflow` controls layout when chips
+exceed the trigger width (`wrap` flows onto multiple lines, `ellipsis` keeps a
+single line and truncates). Defaults are backward-compatible: no cap and `wrap`.
+
+```html
+<FuroAutocompleteField
+  v-model:value="context.selectedTagsRef.value"
+  :parcel="{
+    multiple: true,
+    maxVisibleChips: 3,
+    chipOverflow: 'ellipsis',
+    placeholder: 'Search tags',
+    options: context.tagOptions,
+  }"
+  @change-value="context.onChangeTags({ payload: $event })"
+/>
+```
+
+#### Unified options
+
+
+| Shape                        | Rendered as                             |
+| ---------------------------- | --------------------------------------- |
+| `option.options?.length > 0` | Group (group part + `group-label`) |
+| Otherwise                    | Leaf (group part with `as-child`)  |
+
+
+List template iterates `context.filteredOptions()` — top-level entries after client filter (groups stay whole; children filtered inside `filteredOptions()` for object groups).
+
+#### Disabled precedence
+
+- Leaf: `option.disabled`
+- Group child: `shouldDisableOption({ option: childOption })` checks the **child** only
+- Root: `parcel.disabled` on the root
+
+---
+
+## Filtering
+
+List visibility is computed in `filteredOptions()` (context).
+
+
+| `parcel.localCompare` | `parcel.loading` | Visible list                                                                                                                                                |
+| --------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `true` (default)      | `false`          | Subset of `parcel.options` where any group child / leaf matches `internalSearchKeyword` (trimmed) via `useFilter().contains` on `label` and `String(value)` |
+| `true`                | `true`           | `[]` (empty list while loading)                                                                                                                             |
+| `false`               | any              | Full `parcel.options` (parent filters, e.g. API)                                                                                                            |
+
+
+### `hasEmptyOptions()`
+
+```text
+filteredOptions().length === 0 && !loading
+```
+
+While `loading`, `#empty` is hidden (`hasEmptyOptions()` is false) and `#loading` can show inside the viewport.
+
+---
+
+## Search & debounce
+
+Uses `[TimerClerk](../app/shares/TimerClerk.js)` in `setupComponent()` (`debounceMilliseconds` from merged parcel, default **300**).
+
+
+| Step          | Behavior                                                                         |
+| ------------- | -------------------------------------------------------------------------------- |
+| User types    | `onUpdateSearchKeyword` sets `internalSearchKeywordRef`                          |
+| Debounce      | `startTimer({ searchKeyword })` **only if** `internalOpenPopoverRef` is **open** |
+| Tick          | `emit('search-keyword', searchKeyword)` — **string** argument                    |
+| Popover opens | `onUpdateOpenPopover({ isOpen: true })` resets `internalSearchKeyword` to `''`   |
+| Clear button  | Also `emit('search-keyword', '')`                                                |
+
+
+**Not implemented:** `emit('update:search-keyword')`, controlled `parcel.searchKeyword`.
+
+```text
+Input change (popover open)
+  → internalSearchKeywordRef
+  → TimerClerk.startTimer
+  → search-keyword "<string>"
+  → parent updates parcel.options + parcel.loading
+```
+
+---
+
+## Slots
+
+
+| Slot               | Scoped props                                     | Default                                                                                |
+| ------------------ | ------------------------------------------------ | -------------------------------------------------------------------------------------- |
+| `trigger-left`     | —                                                | Optional leading anchor content                                                        |
+| `trigger-right`    | —                                                | Caret icon inside the trigger part                                                     |
+| `cancel`           | —                                                | Clear icon in the clear control                                                        |
+| `content-before`   | —                                                | Before viewport                                                                        |
+| `content-after`    | —                                                | After viewport                                                                         |
+| `select-all`       | —                                                | Select-all label text only (scoped `checked` / `indeterminate` / `disabled` not wired) |
+| `group`            | `group`, `groupIndex`                            | Group + children                                                                       |
+| `group-label`      | `group`, `groupIndex`                            | Group header text                                                                      |
+| `option`           | `option`, `optionIndex`, `group?`, `groupIndex?` | Row + indicator                                                                        |
+| `option-icon`      | `option`, `optionIndex`                          | Icon when `option.icon` set                                                            |
+| `option-text`      | `option`, `optionIndex`                          | Label text                                                                             |
+| `option-indicator` | `option`, `optionIndex`                          | Check icon                                                                             |
+| `separator`        | `option`, `optionIndex`                          | the separator part                                                                     |
+| `empty`            | `searchKeyword`, `loading`                       | `emptyText`                                                                            |
+| `loading`          | `searchKeyword`                                  | Spinner in list                                                                        |
+| `create-option`    | `searchKeyword`                                  | `createOptionText` with `{keyword}` replaced — shown only when `creatable` and no exact match |
+
+
+**Not present:** `input`, `trigger` (use `trigger-left` / `trigger-right`).
+
+The input part is always rendered in the anchor (not slot-replaceable).
+
+---
+
+## Emits
+
+
+| Event                   | Payload                         | When                                                  | Implemented |
+| ----------------------- | ------------------------------- | ----------------------------------------------------- | ----------- |
+| `change-value`          | `AutocompleteEmitPayload`       | Select option, select-all, clear                      | Yes         |
+| `update:value`          | Option object, array, or `null` | Same as above                                         | Yes         |
+| `search-keyword`        | `string`                        | After debounce while popover open; also `''` on clear | Yes         |
+| `update:search-keyword` | `string`                        | —                                                     | **No**      |
+| `update:open`           | `boolean`                       | —                                                     | **No**      |
+| `commit-value`          | `AutocompleteEmitPayload`       | —                                                     | **No**      |
+| `create-option`         | `AutocompleteEmitPayload`       | Select the create row (`creatable`); read the typed value via `payload.extractTrimmedSearchKeyword()` | Yes         |
+
+
+List selection closes the popover and clears `internalSearchKeyword`. Multi toggle on a row updates value without separate commit emit.
+
+### Creatable (parent-owns)
+
+When `parcel.creatable` is `true` and the trimmed keyword has no exact label/value match, a create row appears (text from `createOptionText`, `{keyword}` interpolated; override the string or the `create-option` slot for i18n). Selecting it emits **`create-option`** with an `AutocompleteEmitPayload`, then clears the keyword and closes the popover. The field never mutates its own `options`: the **parent owns** appending the new option to `parcel.options` and to the model.
+
+```js
+onCreateOption ({
+  payload,
+}) {
+  const label = payload.extractTrimmedSearchKeyword()
+
+  if (!label) {
+    return
+  }
+
+  const newOption = {
+    value: label,
+    label,
+  }
+
+  this.tagsReactive.options = [
+    ...this.tagsReactive.options,
+    newOption,
+  ]
+  this.tagsReactive.selectedValue = [
+    ...this.tagsReactive.selectedValue,
+    newOption,
+  ]
+}
+```
+
+```html
+@create-option="context.onCreateOption({ payload: $event })"
+```
+
+### Parent handler style
+
+```js
+onChangeValue ({
+  payload,
+}) {
+  this.statusReactive.isInvalidAssignee = payload.hasEmptyValue()
+}
+
+onSearchAssignees ({
+  searchKeyword,
+}) {
+  this.fetchAssignees({ searchKeyword })
+}
+```
+
+```html
+@search-keyword="context.onSearchAssignees({ searchKeyword: $event })"
+```
+
+---
+
+## `AutocompleteEmitPayload` API
+
+`AutocompleteEmitPayload` extends `[BaseEmitPayload](../lib/emit-payload/BaseEmitPayload.js)`. Built from `CustomEvent` `detail` on selection/clear.
+
+
+| Member                          | Type                                                  | Description                                           |
+| ------------------------------- | ----------------------------------------------------- | ----------------------------------------------------- |
+| `searchKeyword`                 | `string`                                              | From `detail.searchKeyword`                           |
+| `controlElement`                | `HTMLElement | null`                                  | `detail.target`                                       |
+| `selectedOption`                | `FuroAutocompleteOption | FuroAcceptableValue | null` | `detail.selectedOption`                               |
+| `selectedIndex`                 | `number | null`                                       | `detail.selectedIndex`                                |
+| `selectedOptions`               | `Array<…>`                                            | `detail.selectedOptions`                              |
+| `selectedGroupIndex`            | `number | null`                                       | `detail.selectedGroupIndex`                           |
+| `extractValue({ option })`      | `FuroAcceptableValue`                                 | `option.value` if object with `value`, else option    |
+| `extractValues()`               | `Array<FuroAcceptableValue>`                          | Maps `selectedOptions` through `extractValue`         |
+| `hasEmptyValue()`               | `boolean`                                             | `extractValue()` is `null` or `extractValues()` empty |
+| `hasSelectedValue()`            | `boolean`                                             | Negation of `hasEmptyValue()`                         |
+| `extractTrimmedSearchKeyword()` | `string`                                              | Trimmed `searchKeyword`                               |
+| `matchesOption({ value })`      | `boolean`                                             | Strict equality of `extractValue` results             |
+
+
+**Not on class (spec debt):** `value`, `selectedIndices`, `selectedGroupIndices`, `isFreeFormCommit()`.
+
+Use `payload.extractValue()` / `payload.extractValues()` for primitive `value` fields inside options.
+
+---
+
+## `v-model` and state handling
+
+```html
+<FuroAutocompleteField
+  v-model:value="context.assigneeRef.value"
+  :parcel="{
+    value: context.assigneeRef.value,
+    options: context.assigneeOptions,
+    placeholder: 'Search…',
+  }"
+/>
+```
+
+
+| Binding                  | Implemented | Notes                                                                       |
+| ------------------------ | ----------- | --------------------------------------------------------------------------- |
+| `v-model:value`          | **Yes**     | Watches `parcel.value` and fallthrough `value`; emits full option object(s) |
+| `v-model:search-keyword` | **No**      | `parcel.searchKeyword` syncs in only; no `update:search-keyword`            |
+| `v-model:open`           | **No**      | `internalOpenPopoverRef` bound on root; `parcel.open` ignored               |
+
+
+### State matrix
+
+
+| State             | Source                                                                   |
+| ----------------- | ------------------------------------------------------------------------ |
+| Selected value(s) | `parcel.value` / `@update:value`                                         |
+| Filter string     | `internalSearchKeywordRef`; optional one-way from `parcel.searchKeyword` |
+| Popover open      | `internalOpenPopoverRef` only (not `parcel.open`)                        |
+| Disabled          | `parcel.disabled` + fallthrough                                          |
+| Visible options   | `filteredOptions()` from `parcel.options` + `localCompare` + `loading`   |
+| Loading UI        | `parcel.loading`                                                         |
+
+
+---
+
+## Multiple selection + select all
+
+Set `parcel.multiple: true`. Model is an **array of option objects** (can include primitive leaves if options are primitives).
+
+
+| Topic             | Behavior                                                                                                           |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `update:value`    | Full array (or `[]` when cleared / deselect all)                                                                   |
+| `change-value`    | Same gesture; payload lists current selection in `detail`                                                          |
+| Row click         | Toggles membership via `compareOption()`                                                                           |
+| Select all        | `showSelectAll: true`; value `FURO_AUTOCOMPLETE_FIELD_SELECT_ALL_VALUE` (`__furo_autocomplete_field_select_all__`) |
+| Select-all action | Toggles all non-disabled leaves from flattened `options`; closes popover                                           |
+| Chip remove       | `onRemoveOption` emits `update:value` + `change-value` with updated array                                          |
+
+
+---
+
+## Internal implementation (maintainers only)
+
+### Template composition
+
+```text
+Root (v-bind parcel, model-value, :open internal)
+  Anchor.trigger
+    [trigger-left]
+    [multiple chips]
+    Input (display-value → extractDisplayValue / label)
+    Cancel? / loading icon / Trigger [trigger-right]
+  Portal
+    Content
+      [content-before]
+      Viewport
+        select-all option?
+        filteredOptions → groups / leaves / slots
+        Empty?
+        loading div?
+      [content-after]
+```
+
+### Primitive mapping notes
+
+
+| Furo                   | Underlying primitive / behavior            |
+| ---------------------- | ------------------------------------------ |
+| `textDirection`        | `dir` `ltr` / `rtl`                        |
+| `localCompare`         | Furo-side filtering in `filteredOptions()` |
+| `debounceMilliseconds` | `TimerClerk` only (not a primitive prop)   |
+
+
+---
+
+## Accessibility requirements
+
+- Provide a visible label (`<label for>`, `aria-label`, or `aria-labelledby`).
+- Set `textValue` on options when slot content is not plain text (underlying-primitive a11y; **filter still uses `label` / `value` in context**).
+- Combobox roles delegated to the underlying primitive ([combobox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/)).
+- `name` on component for forms; multi-value serialization is application-defined.
+
+---
+
+## Styling convention
+
+Styles in SFC `@layer furo`:
+
+- Root: `.unit-form-control.autocomplete`
+- Anchor: `.trigger`, `.input`, `.multiple`, `.trigger-right`
+- Content: `.unit-autocomplete-content`, `.viewport`, `.group`, `.option`, `.empty`, `.loading`
+- Tokens: field atoms (`--color-input`, `--size-input-height`, …)
+
+Use `data-highlighted`, `data-disabled`, `data-state` from the underlying primitive for state styling.
+
+---
+
+## Examples
+
+### Basic (controlled, client filter)
+
+```html
+<FuroAutocompleteField
+  v-model:value="context.countryRef.value"
+  :parcel="{
+    placeholder: 'Search country',
+    options: [
+      { value: 'JP', label: 'Japan' },
+      { value: 'VN', label: 'Vietnam' },
+      { value: 'US', label: 'United States' },
+    ],
+    invalid: context.statusReactive.isInvalidCountry,
+  }"
+  name="country"
+  @change-value="context.onChangeCountry({ payload: $event })"
+/>
+```
+
+### Grouped options
+
+```html
+<FuroAutocompleteField
+  :parcel="{
+    placeholder: 'Search fruit',
+    options: [
+      {
+        label: 'Citrus',
+        options: [
+          { value: 'orange', label: 'Orange' },
+          { value: 'lemon', label: 'Lemon' },
+        ],
+      },
+    ],
+  }"
+/>
+```
+
+### API-driven options (`localCompare: false`)
+
+```html
+<FuroAutocompleteField
+  v-model:value="context.userRef.value"
+  :parcel="{
+    debounceMilliseconds: 300,
+    loading: context.statusReactive.isSearchingUsers,
+    localCompare: false,
+    options: context.userOptions,
+    placeholder: 'Search users',
+  }"
+  @search-keyword="context.fetchUsers({ searchKeyword: $event })"
+/>
+```
+
+### Object-valued options (model = full option row)
+
+```html
+<FuroAutocompleteField
+  v-model:value="context.personRef.value"
+  :parcel="{
+    options: context.peopleOptions,
+    placeholder: 'Search person',
+  }"
+  @update:value="context.personRef.value = $event"
+/>
+```
+
+```js
+// peopleOptions example: { value: { id: 50001, name: 'Ada' }, label: 'Ada' }
+// personRef holds the selected option object; use option.label for display (built-in)
+```
+
+### Multi-select + select all
+
+```html
+<FuroAutocompleteField
+  v-model:value="context.selectedTagsRef.value"
+  :parcel="{
+    multiple: true,
+    showSelectAll: true,
+    selectAllText: 'Select all tags',
+    placeholder: 'Search tags',
+    options: context.tagOptions,
+  }"
+  @change-value="context.onChangeTags({ payload: $event })"
+/>
+```
+
+### Custom option slot
+
+```html
+<FuroAutocompleteField
+  :parcel="{
+    placeholder: 'Search employee',
+    options: context.employeeOptions,
+  }"
+>
+  <template #option-text="{ option }">
+    <strong>{{ option.label }}</strong>
+    <small>{{ option.department }}</small>
+  </template>
+</FuroAutocompleteField>
+```
+
+---
+
+## Implementation status
+
+
+| Deliverable                                               | Status            |
+| --------------------------------------------------------- | ----------------- |
+| `FuroAutocompleteField.vue` + context + payload           | Shipped           |
+| Public prop: `parcel` only                                | Shipped           |
+| Playground `FuroAutocompleteFieldPlayground`              | Shipped           |
+| Unit tests `FuroAutocompleteFieldContext.js` (jsdom)      | Shipped           |
+| `parcel.searchKeyword` one-way + `v-model:search-keyword` | Partial / pending |
+| `v-model:open` / controlled `parcel.open`                 | Pending           |
+| Free-form + `commit-value`                                | Pending           |
+| Emit on chip remove                                       | Shipped           |
+| Closed `parcel` (strip unknown primitive keys)            | Pending           |
+
+
+---
+
+## Future / spec debt
+
+Planned items **not** in runtime yet:
+
+- `allowFreeForm`, `commit-value`, `generateFreeFormOptionFromKeyword`
+- `resetSearchKeywordOnBlur`, `resetSearchKeywordOnSelect`, `openOnFocus`, `highlightOnHover`, `hideContentWhenEmpty`
+- `update:search-keyword`, `update:open`, controlled `parcel.searchKeyword` / `parcel.open`
+- `select-all` slot scoped `{ checked, indeterminate, disabled }`
+- `AutocompleteEmitPayload.value`, `isFreeFormCommit()`, index arrays
+- Remove pass-through of unknown keys on `v-bind="context.parcel"`
+
+---
+
+## Known gaps and follow-ups
+
+- `**search-keyword` type:** runtime emits `string`; JSDoc on `EMIT_EVENT_HASH` still types `payload: { searchKeyword: string }` — align in code later.
+- `**parcel.searchKeyword`:** inbound sync only; typing in the field does not emit `update:search-keyword` for parents.
+- **Group `disabled`:** not propagated to children in `shouldDisableOption`.
+- **Select-all:** no indeterminate UI state; toggle is all-or-none of enabled leaves.
+- **API race:** parent should cancel in-flight fetches when a new keyword fires.
+- **Form submit with `multiple`:** native `name` may not match array serialization expectations.