@openreachtech/furo-vue 1.6.0 → 2.0.0

package/docs/furo-dropdown-menu.md

@@ -0,0 +1,298 @@
+# `<FuroDropdownMenu>` Interface Specification
+
+## Overview
+
+`<FuroDropdownMenu>` is an action/navigation menu molecule in the Furo-Vue component system. Its **public contract is Furo-defined**: applications pass `parcel` and `triggerParcel`, listen to Furo emits, and optionally override the trigger slot — without importing any headless menu library.
+
+Implementation uses a headless menu primitive inside `lib/components/molecules/FuroDropdownMenu/*` only. That dependency is **not** part of the application API.
+
+**No `v-model`:** unlike `FuroSelect`, this menu does not represent a form value. It emits selection and checkbox events; parent code owns persistent checked state for checkbox rows.
+
+**Default trigger:** the underlying primitive renders a native `<button>` trigger (no `as-child`). Appearance uses `triggerParcel` tokens (`variant`, `size`) aligned with `FuroButton` — the `FuroButton` SFC is **not** used as trigger because `as-child` composition breaks open behavior.
+
+**Custom trigger slot:** Label content only (text, icons). Do not nest another `<button>`.
+
+**Source files:**
+
+- `lib/components/molecules/FuroDropdownMenu/FuroDropdownMenu.vue`
+- `lib/components/molecules/FuroDropdownMenu/FuroDropdownMenuOptionRows.vue`
+- `lib/components/molecules/FuroDropdownMenu/FuroDropdownMenuContext.js`
+- `lib/components/molecules/FuroDropdownMenu/DropdownMenuOptionSelectEmitPayload.js`
+
+**Live samples:** `pages/samples/components/playground/FuroDropdownMenuPlayground/index.vue`
+
+---
+
+## Public API at a glance
+
+| Area | Status | Notes |
+| ---- | ------ | ----- |
+| **SFC surface** | | |
+| Props `parcel`, `triggerParcel` | **Implemented** | See tables below |
+| **Menu** | | |
+| `parcel.options` declarative rows | **Implemented** | Action, checkbox, submenu, separator |
+| Custom trigger slot | **Implemented** | `#trigger`; label inside native trigger button |
+| `option-label` scoped slot | **Implemented** | Override row label rendering |
+| Default slot | **Implemented** | Extra menu children (advanced) |
+| **Emits** | | |
+| `open:change` | **Implemented** | `{ open: boolean }` |
+| `option:select` | **Implemented** | `DropdownMenuOptionSelectEmitPayload` |
+| `option:checked-change` | **Implemented** | `{ option, checked }` |
+
+---
+
+## Props
+
+### `parcel` — `FuroDropdownMenuParcel`
+
+| Key | Type | Default | Description |
+| --- | ---- | ------- | ----------- |
+| `open` | `boolean` | uncontrolled | Controlled open state; omit for internal state |
+| `disabled` | `boolean` | `false` | Disables trigger and menu |
+| `side` | `'top' \| 'right' \| 'bottom' \| 'left'` | `'bottom'` | Positioning control: which edge of the trigger the menu opens against |
+| `align` | `'start' \| 'center' \| 'end'` | `'start'` | Positioning control: how the menu aligns along that edge |
+| `sideOffset` | `number` | `4` | Positioning control: gap between trigger and menu, in `rem`-equivalent pixels |
+| `options` | `Array<FuroDropdownMenuOption>` | `[]` | Declarative menu rows |
+
+### `FuroDropdownMenuOption`
+
+| Key | Type | Description |
+| --- | ---- | ----------- |
+| `label` | `string` | Visible row label |
+| `value` | `string` | Stable identifier for handlers |
+| `disabled` | `boolean` | Non-interactive row |
+| `separator` | `boolean` | Renders separator instead of a selectable row |
+| `variant` | `'default' \| 'destructive'` | Destructive styling for delete actions |
+| `type` | `'action' \| 'checkbox' \| 'submenu'` | Row kind; omit for action |
+| `checked` | `boolean` | Checkbox row checked state (parent-owned) |
+| `keepOpen` | `boolean` | Action row: keep menu open after select |
+| `options` | `Array<FuroDropdownMenuOption>` | Nested rows for `type: 'submenu'` |
+
+**Row kind resolution (priority):**
+
+1. `separator: true` → separator
+2. `type: 'submenu'` with `options` array → nested submenu
+3. `type: 'checkbox'` → checkbox row (menu stays open on toggle)
+4. default → action row (closes menu unless `keepOpen: true`)
+
+### `triggerParcel` — trigger appearance
+
+| Key | Type | Default | Description |
+| --- | ---- | ------- | ----------- |
+| `variant` | `string` | — | Default trigger appearance token, aligned with `FuroButton` |
+| `size` | `string` | — | Default trigger size token, aligned with `FuroButton` |
+| `asChild` | `boolean` | `false` | When `true`, the `#trigger` slot's own element becomes the trigger — no wrapper `<button>` and no forced `.unit-button` styling — so a consumer can supply their own trigger element without a nested button |
+
+By default (`asChild: false`) the menu renders the styled native button and the
+`#trigger` slot fills its label content. Set `asChild: true` to hand the trigger
+element to the consumer (for example a `<FuroButton>` or an `<a>`), letting the
+slotted element itself become the trigger. See [Consumer-owned trigger](#consumer-owned-trigger-aschild).
+
+---
+
+## Emits
+
+| Event | Payload | When |
+| ----- | ------- | ---- |
+| `open:change` | `{ open: boolean }` | Menu open state changes |
+| `option:select` | `DropdownMenuOptionSelectEmitPayload` | User selects an enabled action row |
+| `option:checked-change` | `{ option: FuroDropdownMenuOption, checked: boolean }` | User toggles a checkbox row |
+
+### Parent handler style (action rows)
+
+```js
+runMenuAction ({
+  payload,
+}) {
+  const value = payload.option.value
+
+  if (!value) {
+    return
+  }
+
+  this.runAction({
+    value,
+  })
+}
+```
+
+### Parent handler style (checkbox rows)
+
+Checkbox rows do **not** close the root menu. Parent code must update `parcel.options` (including nested submenu options) when receiving `option:checked-change`:
+
+```js
+syncCheckboxOption ({
+  payload,
+}) {
+  this.menuOptions = this.applyCheckedChangeToOptions({
+    options: this.menuOptions,
+    targetValue: payload.option.value,
+    checked: payload.checked,
+  })
+}
+```
+
+Use `keepOpen: true` on action rows when the menu should stay open after a one-shot action (for example “Reset filters” inside a submenu).
+
+---
+
+## Slots
+
+| Slot | Scoped props | Default |
+| ---- | ------------ | ------- |
+| `trigger` | — | Native button labeled "Menu" (FuroButton-compatible styling) |
+| `option-label` | `option`, `index` | `option.label` text |
+| `default` | — | Empty — append custom menu content (advanced) |
+
+---
+
+## Accessibility
+
+- Default trigger sets `aria-haspopup="menu"`.
+- The underlying primitive manages `aria-expanded` on the trigger.
+- Keyboard: Arrow keys navigate, Enter selects, Escape closes (primitive baseline).
+- Checkbox rows expose checked state through the underlying primitive's checkbox row.
+- Disabled options are skipped via the underlying primitive plus a Furo guard on emits.
+- Menu rows take their minimum height from `--size-option-height`, so an app raises them to a larger touch target without overriding menu CSS.
+
+---
+
+## Examples
+
+### Declarative action options
+
+```html
+<FuroDropdownMenu
+  :parcel="{
+    options: [
+      { label: 'Edit', value: 'edit' },
+      { separator: true },
+      { label: 'Delete', value: 'delete', variant: 'destructive' },
+    ],
+  }"
+  @option:select="context.runRowAction({ payload: $event })"
+/>
+```
+
+### Checkbox filters (multi-toggle, menu stays open)
+
+```html
+<FuroDropdownMenu
+  :parcel="{
+    options: context.extractCheckboxFilterMenuOptions(),
+  }"
+  @option:checked-change="context.recordOptionCheckedChange({ payload: $event })"
+/>
+```
+
+```js
+extractCheckboxFilterMenuOptions () {
+  return [
+    {
+      type: 'checkbox',
+      label: 'Show archived',
+      value: 'archived',
+      checked: this.showArchived,
+    },
+    {
+      type: 'checkbox',
+      label: 'Show drafts',
+      value: 'drafts',
+      checked: this.showDrafts,
+    },
+  ]
+}
+```
+
+### Submenu with nested checkboxes
+
+```html
+<FuroDropdownMenu
+  :parcel="{
+    options: [
+      { label: 'Export CSV', value: 'export-csv' },
+      {
+        type: 'submenu',
+        label: 'Column filters',
+        value: 'column-filters',
+        options: context.extractCheckboxFilterMenuOptions(),
+      },
+      { separator: true },
+      {
+        label: 'Reset filters',
+        value: 'reset-filters',
+        keepOpen: true,
+      },
+    ],
+  }"
+  @option:select="context.recordOptionSelect({ payload: $event })"
+  @option:checked-change="context.recordOptionCheckedChange({ payload: $event })"
+/>
+```
+
+### Custom trigger
+
+Set `triggerParcel` for variant/size, then override `#trigger` slot content:
+
+```html
+<FuroDropdownMenu
+  :parcel="{ options: context.extractActionMenuOptions() }"
+  :trigger-parcel="{
+    variant: 'secondary',
+    size: 'sm',
+  }"
+  @option:select="context.runRowAction({ payload: $event })"
+>
+  <template #trigger>
+    <Icon name="ph:dots-three-outline" />
+    Actions
+  </template>
+</FuroDropdownMenu>
+```
+
+### Consumer-owned trigger (`asChild`)
+
+Set `triggerParcel.asChild: true` so the slotted element itself becomes the
+trigger — no wrapper `<button>`, no forced `.unit-button` styling:
+
+```html
+<FuroDropdownMenu
+  :parcel="{ options: context.extractActionMenuOptions() }"
+  :trigger-parcel="{ asChild: true }"
+  @option:select="context.runRowAction({ payload: $event })"
+>
+  <template #trigger>
+    <FuroButton :parcel="{ variant: 'secondary' }">
+      Actions
+    </FuroButton>
+  </template>
+</FuroDropdownMenu>
+```
+
+The default (`asChild: false`) still renders the styled native button.
+
+---
+
+## Implementation status
+
+| Deliverable | Status |
+| ----------- | ------ |
+| `FuroDropdownMenu.vue` + context + payloads | Shipped |
+| `FuroDropdownMenuOptionRows.vue` (recursive rows) | Shipped |
+| Submenus (`type: 'submenu'`) | Shipped |
+| Checkbox options (`type: 'checkbox'`) | Shipped |
+| `keepOpen` action rows | Shipped |
+| Playground `FuroDropdownMenuPlayground` | Shipped |
+| Unit tests (context + payloads) | Shipped |
+| Default trigger via `<FuroButton>` SFC | **Deferred** | Blocked by atom polymorphic root — see below |
+| Radio menu options | Out of scope |
+
+---
+
+## Deferred work: default trigger as `<FuroButton>`
+
+**Status:** Intentionally not shipped. Default trigger is the primitive's native trigger button with `FuroButton`-compatible styling via `triggerParcel`.
+
+**Why:** the primitive's `as-child` trigger + `<FuroButton>` does not open the menu — Vue component boundary and missing `ref` forward on `FuroButton`. Full analysis: `docs/furo-vue/performance-and-pitfalls.md` §11.
+
+**When fixed on `FuroButton`:** Re-evaluate replacing duplicated `.unit-button` CSS in `FuroDropdownMenu.vue` with `<FuroButton>` as the default trigger. Until then, do not nest `<FuroButton>` under the primitive's `as-child` trigger in application code.

package/docs/furo-editable-field.md

@@ -0,0 +1,391 @@
+# `<FuroEditableField>` Interface Specification
+
+## Overview
+
+`<FuroEditableField>` is a **shipped** editable molecule in the Furo-Vue component system. Applications use `parcel`, Furo emits, documented slots, and attribute fallthrough only — no internal implementation imports.
+
+Implementation wraps a headless inline-edit primitive (`Root`, `Area`, `Preview`, `Input`, …) inside `lib/components/molecules/FuroEditableField/*`. The underlying primitive is **not** part of the application API.
+
+Contract style aligns with [`FuroTextField`](./furo-text-field.md) and [`FuroCheckbox`](./furo-checkbox.md):
+
+- Furo-owned behavior via `:parcel` (`FuroEditableFieldParcel`)
+- primitive-owned edit lifecycle keys also live on `parcel` but are **forwarded** to the root (not interpreted by Furo)
+- HTML / form attributes via fallthrough (`name`, `required`, `id`, `aria-*`, …)
+- Furo emit: `commit-value` with `EditableEmitPayload`
+- default **text** editor (`FuroTextField`) when `#editor` is omitted
+- `#editor` slot for number, boolean, select, file, and other custom controls
+
+**Public SFC prop:** `parcel` only (+ attribute fallthrough).
+
+**Live samples:** `pages/samples/components/playground/FuroEditableFieldPlayground/index.vue`
+
+### Abstraction boundary
+
+| Layer | Responsibility |
+| ----- | -------------- |
+| Application | `parcel`, slots, `@commit-value` listener; updates `parcel.value` after commit |
+| Molecule (`FuroEditableField`) | Draft/commit sync, preview text, floating editor position, undo, `EditableEmitPayload` |
+| Underlying primitive (maintainers) | Edit mode open/close, activation/submit gestures on default surface; internal only |
+
+**Rules:**
+
+1. Documented **Furo-owned** `parcel` keys are stripped in `extractRootAttributes()` before optional passthrough to the underlying primitive.
+2. Do **not** import the underlying editable primitive in application code.
+3. Sync committed value in the parent on `@commit-value` — Furo does **not** emit `update:value`.
+
+**Source files:**
+
+- `lib/components/molecules/FuroEditableField/FuroEditableField.vue`
+- `lib/components/molecules/FuroEditableField/FuroEditableFieldContext.js`
+- `lib/components/molecules/FuroEditableField/EditableEmitPayload.js`
+- `lib/components/molecules/FuroEditableField/processors/EditorCollisionProcessor.js`
+- `lib/components/molecules/FuroEditableField/processors/ObjectProcessor.js`
+
+---
+
+## Public API at a glance
+
+| Area | Status | Notes |
+| ---- | ------ | ----- |
+| **SFC surface** | | |
+| Public prop `parcel` only (+ attribute fallthrough) | **Implemented** | See [`FuroEditableFieldParcel`](#furoeditablefieldparcel) |
+| **Value** | | |
+| `parcel.value` (controlled sync) | **Implemented** | Watched; updates `committedValueRef` and `draftValueRef` |
+| `v-model:value` | **Not implemented** | Listen to `@commit-value` and assign `parcel.value` in the parent |
+| **Furo-owned parcel** | | |
+| `invalid`, `disabled`, `required`, `readonly` | **Implemented** | `disabled` / `required` / `readonly` also from fallthrough attrs |
+| `placeholder` | **Implemented** | Default text editor + forwarded placeholder on the root |
+| `emptyPreviewText` | **Implemented** | Default `'---'` when value is empty |
+| `showActions` | **Implemented** | Default `false`; shows Edit trigger and enables action-button row |
+| `showEditing` | **Implemented** | Default `false`; sets internal editing flag on mount |
+| `showUndoChange` | **Implemented** | Default `false`; shows undo control when committed value diverges from mount snapshot |
+| `collisionBoundary` | **Implemented** | `HTMLElement`, `Ref<HTMLElement>`, or `null`; clamps floating editor position |
+| **Primitive-forwarded parcel** | | |
+| `activationMode`, `submitMode`, `selectOnFocus`, `startWithEditMode`, `maxLength`, `autoResize` | **Implemented** | Passed through `extractRootAttributes()` to the root; the primitive's defaults apply when omitted |
+| `variant`, `preserveLayout`, `editOverlay` | **Not implemented** | Editor uses `position: fixed` collision positioning when editing |
+| `previewText`, `multiline`, `editing` / `v-model:editing` | **Not implemented** | Use `#preview` slot; `#editor` + `FuroTextarea`; the primitive's state is internal |
+| **Emits** | | |
+| `commit-value` | **Implemented** | On successful submit and on undo |
+| `update-editing-state` | **Implemented** | the primitive's `@update:state` → `onUpdateEditingState()`; payload is `EdittingState` |
+| `change-value`, `cancel-edit`, `update:value` | **Not implemented** | Draft changes are local until commit |
+| **Slots** | | |
+| `preview`, `editor` | **Implemented** | `editor` replaces default `FuroTextField` |
+| `edit-trigger`, `submit-trigger`, `cancel-trigger`, `undo-trigger` | **Implemented** | Optional custom triggers |
+| `#edit` (legacy name) | **Not implemented** | Use `#editor` |
+| **Editor overlay** | | |
+| Fixed collision-aware editor panel | **Implemented** | `EditorCollisionProcessor`; scroll/resize listeners while editing |
+| Teleport to `document.body`, `editOverlay: 'inset'` | **Not implemented** | |
+| Closed `parcel` (reject unknown keys) | **Not implemented** | Unknown keys may pass through to the underlying primitive |
+
+---
+
+## `FuroEditableFieldParcel`
+
+Behavior-controlling props passed as `:parcel`. Furo-owned values must be **JSON-serializable** (no functions, no class instances). `collisionBoundary` may be a Vue `Ref`.
+
+### `parcel` vs fallthrough
+
+| Mechanism | Use for |
+| --------- | ------- |
+| `:parcel` | Furo behavior and the root's options |
+| Fallthrough attributes | Native HTML on the root (`name`, `required`, `id`, `aria-*`, `placeholder`, …) |
+
+Merged defaults (Furo-owned keys only):
+
+| Key | Default |
+| --- | ------- |
+| `emptyPreviewText` | `'---'` |
+| `showActions` | `false` |
+| `showEditing` | `false` |
+| `showUndoChange` | `false` |
+
+### Furo-owned keys
+
+Stripped before forwarding to the underlying primitive. Interpreted by `FuroEditableFieldContext`.
+
+| Key | Type | Default | Description |
+| --- | ---- | ------- | ----------- |
+| `value` | `FuroEditableValue` | — | Committed value. Parent should update this after `@commit-value` |
+| `invalid` | `boolean` | `false` | Passed to default `FuroTextField`; use `#editor` for custom invalid UI |
+| `disabled` | `boolean` | `false` | Also respected from fallthrough `disabled`, including the bare `<FuroEditableField disabled>` spelling |
+| `required` | `boolean` | `false` | Also respected from fallthrough `required`, including the bare `<FuroEditableField required>` spelling |
+| `readonly` | `boolean` | `false` | Also respected from fallthrough `readonly`, including the bare `<FuroEditableField readonly>` spelling |
+| `editLabel` | `string` | `'Edit'` | Accessible name of the edit trigger |
+| `undoLabel` | `string` | `'Undo'` | Accessible name of the undo control |
+| `submitLabel` | `string` | `'Submit'` | Accessible name of the submit control |
+| `cancelLabel` | `string` | `'Cancel'` | Accessible name of the cancel control |
+| `placeholder` | `string` \| `{ edit: string, preview: string }` | fallthrough `placeholder` or `''` | Default text editor placeholder |
+| `emptyPreviewText` | `string` | `'---'` | Shown when `hasEmptyValue()` is true (no `#preview` slot) |
+| `showActions` | `boolean` | `false` | Show Edit icon trigger (`v-show` on the edit-trigger part) |
+| `showEditing` | `boolean` | `false` | On mount, sets internal `isShowEditing` used for editor positioning |
+| `showUndoChange` | `boolean` | `false` | Show undo button when committed value changed since mount |
+| `collisionBoundary` | `HTMLElement` \| `Ref<HTMLElement \| null>` \| `null` | — | Bounding rect for editor collision; viewport when omitted |
+
+A fallthrough `disabled` or `required` is read by presence, the way HTML reads a valueless flag: every value turns it on except `false` and an absent attribute, so `:disabled="0"` disables. Bind a comparison, as in `:disabled="selectedCount === 0"`, when a number drives the flag. See [ADR 0036](adr/0036-boolean-attribute-presence-decides.md).
+
+### Primitive-forwarded keys
+
+Not in `FURO_EDITABLE_PARCEL_KEYS`. Merged into `extractRootAttributes()` and passed to the root. Furo does not validate or default these — the underlying primitive's semantics apply.
+
+| Key | Type (JSDoc) | Description |
+| --- | ------------ | ----------- |
+| `activationMode` | `'dblclick' \| 'focus' \| 'none'` | How preview enters edit mode |
+| `submitMode` | `'blur' \| 'enter' \| 'both' \| 'none'` | When the primitive auto-submits the draft |
+| `selectOnFocus` | `boolean` | Select all on focus in the primitive's default input path |
+| `startWithEditMode` | `boolean` | Mount in edit mode (primitive) |
+| `maxLength` | `number` | Max length (primitive default input path) |
+| `autoResize` | `boolean` | Auto-resize (primitive default input path) |
+
+Other unknown `parcel` keys are also forwarded to the underlying primitive unless added to `FURO_EDITABLE_PARCEL_KEYS` in a future release.
+
+---
+
+## Emits
+
+Each `@commit-value` argument is an **`EditableEmitPayload` instance**. `$event.value` is the committed value.
+
+```html
+<FuroEditableField
+  :parcel="{ value: context.titleRef.value, showActions: true }"
+  @commit-value="context.titleRef.value = $event.value"
+  @update-editing-state="context.onUpdateEditingState({ editingState: $event })"
+/>
+```
+
+`$event` is an `EdittingState`: `'edit'` when the editor opens, `'submit'` or `'cancel'` when it closes.
+
+| Event | Payload | When |
+| ----- | ------- | ---- |
+| `commit-value` | `EditableEmitPayload` | the primitive's `@submit` → `onSubmitCommittedValue()`; undo button → `onUndoChange()` |
+| `update-editing-state` | `EdittingState` | the primitive's `@update:state` → `onUpdateEditingState()`; values: `'edit'`, `'cancel'`, `'submit'` |
+
+Furo does **not** emit `change-value`, `cancel-edit`, or `update:value`. Draft updates via `updateDraftValue` in the `#editor` slot are internal until the primitive submits or the parent calls scoped `submit()` from the root's slot props.
+
+### `EditableEmitPayload`
+
+| Member | Description |
+| ------ | ----------- |
+| `.value` | Committed value from event `detail.value` |
+| `.controlElement` | `detail.target` from the raw `CustomEvent`, or `null` |
+| `.hasEmptyValue()` | `true` for `null`, `''`, `{}`, `[]` |
+
+Not on payload (removed from earlier spec drafts): `.draftValue`, `.committedValue`, `.reason`, `.isEditing()`, `.extractTrimmedText()`.
+
+---
+
+## Slots
+
+| Slot | Scoped props | Notes |
+| ---- | ------------- | ----- |
+| `preview` | root props + `committedValue`, `draftValue`, `updateDraftValue`, `undoChange` | Used when `hasEmptyValue()` is false; overrides `resolvePreviewText()` |
+| `editor` | Same as `preview` | Replaces default `FuroTextField`; hosts custom atoms |
+| `edit-trigger` | Same | `as-child` when slot provided |
+| `submit-trigger` | Same | Inside editor `.actions`; visible when `isEditing` |
+| `cancel-trigger` | Same | Inside editor `.actions`; visible when `isEditing` |
+| `undo-trigger` | Same | Shown when `showUndoChange` and value changed since mount |
+
+The root's scoped props (`isEditing`, `submit`, `cancel`, `edit`, `modelValue`, `isEmpty`, …) are spread into every slot via `buildSlotProps()`.
+
+### `#editor` integration contract
+
+1. Read `draftValue` — synced from `parcel.value` when edit opens and on each `updateDraftValue`.
+2. On each change → `updateDraftValue({ value })` — updates draft only (no Furo emit).
+3. On save → call scoped `submit()` from the root's props, or rely on the primitive's `submitMode` (`'blur'`, `'enter'`, `'both'`) on the root.
+4. On discard → call scoped `cancel()` from the root's props.
+
+For commit-on-pick controls (select, checkbox, file), set `submitMode: 'none'` on `parcel` and call `submit()` from the child handler, or sync draft and let blur submit if appropriate.
+
+---
+
+## Layout & action UI
+
+| Concern | Behavior |
+| ------- | -------- |
+| Root layout | `.unit-form-control.editable` — flex row; preview ellipsis |
+| Edit trigger | Shown when `parcel.showActions` |
+| Submit / Cancel row | Shown when `showActions` **or** any of `edit-trigger` / `submit-trigger` / `cancel-trigger` slots exist; submit/cancel icons only while `isEditing` |
+| Undo | Shown when `showUndoChange` and `hasOriginalValueChanged()` |
+| Editor panel | `position: fixed` while editing; width matches anchor cell; `z-index: calc(var(--value-z-index-layer-overlay) + 0)` |
+
+There is no `variant: 'inline' \| 'form'` flag. Use `showActions` and table-friendly `collisionBoundary` for inline grids.
+
+---
+
+## Edit lifecycle
+
+```mermaid
+stateDiagram-v2
+  [*] --> Preview: mount
+  Preview --> Editing: primitive activation (click/focus/dblclick/trigger)
+  Editing --> Preview: submit() / blur+submitMode / cancel()
+  Editing --> Preview: scroll outside editor (primitive cancel)
+  Preview --> Preview: commit-value emit (parent updates parcel.value)
+```
+
+| Stage | What happens |
+| ----- | ------------ |
+| Mount | `originalValueRef` ← `parcel.value`; `committedValueRef` / `draftValueRef` synced from `parcel.value` watch |
+| Enter edit | the root opens; `@update:state` → `onUpdateEditingState` → `update-editing-state` emit; focus first `input` / `textarea` in editor |
+| Draft | Default editor: `@change-value` on `FuroTextField` → `updateDraftValue`. Custom `#editor`: parent calls `updateDraftValue` |
+| Commit | the primitive's `@submit` → `onSubmitCommittedValue` → `commit-value` with current draft |
+| Cancel | the primitive's `cancel()` — no Furo emit |
+| Scroll | Window scroll (capture) outside floating editor → `editableRootInstanceRef.cancel()` |
+| Resize | Window `resize` while editing → recalculate editor position |
+| Undo | `onUndoChange()` restores `originalValueRef` to committed + draft → `commit-value` |
+
+`parcel.showEditing` only sets internal `isShowEditing` on mount for positioning; prefer the primitive's `startWithEditMode` to open edit on mount.
+
+---
+
+## Editor collision / overlay
+
+While `isShowEditing` is true, `generateEditorPositionStyle()` runs `EditorCollisionProcessor`:
+
+| Input | Role |
+| ----- | ---- |
+| Anchor rect | `.unit-form-control.editable` root `getBoundingClientRect()` |
+| Editor size | Floating `.editor` `offsetWidth` / `offsetHeight` |
+| Boundary | `parcel.collisionBoundary` rect, or viewport (`document.documentElement.clientWidth` / `clientHeight`) |
+
+| Rule | Behavior |
+| ---- | -------- |
+| Horizontal overflow | Prefer anchor `left`; flip to `anchor.right - editorWidth` if needed; clamp inside boundary |
+| Vertical overflow | Prefer anchor `top`; flip to `anchor.bottom - editorHeight` if needed; clamp inside boundary |
+| Width | Editor panel width = anchor width |
+
+**Table usage:** pass the table element as `collisionBoundary` so dropdowns stay inside the table box (see playground).
+
+```html
+:parcel="{
+  value: row.title,
+  showActions: true,
+  collisionBoundary: context.tableElementRef.value,
+}"
+```
+
+Editor is **not** teleported to `document.body`; it is `position: fixed` relative to the viewport with coordinates derived from the anchor.
+
+---
+
+## Value types
+
+`FuroEditableValue` — any value except `undefined`.
+
+| Kind | Examples | Default preview (`resolvePreviewText`) | Empty (`hasEmptyValue`) |
+| ---- | -------- | -------------------------------------- | ------------------------ |
+| `null` | `null` | `''` (shows `emptyPreviewText`) | yes |
+| `string` | `'Acme'`, `''` | `String(value)`; `''` is **not** empty | only `null` for primitives |
+| `number` | `42`, `0` | `String(value)` | no |
+| `boolean` | `true`, `false` | `String(value)` | no |
+| Plain object | `{ label: 'US', value: 'us' }` | `JSON.stringify(value)` | yes when `{}` |
+| Array | `['a', 'b']` | `String(value)` (comma-separated) | yes when `[]` |
+
+For human-readable preview (options, booleans, masked passwords), use `#preview` — there is no `previewText` parcel key.
+
+`updateDraftValue({ value })` assigns `value ?? null` — passing `undefined` coerces to `null`.
+
+`ObjectProcessor` provides deep equality for undo comparison on objects and arrays.
+
+---
+
+## Usage examples
+
+### Default text editor
+
+From playground — `showActions`, `showUndoChange`, commit via payload:
+
+```html
+<FuroEditableField
+  :parcel="{
+    value: context.textValueRef.value,
+    showActions: true,
+    showUndoChange: true,
+  }"
+  name="playground-editable-default"
+  @commit-value="context.textValueRef.value = $event.value"
+/>
+```
+
+### Table row with `#editor` (textarea)
+
+```html
+<FuroEditableField
+  :parcel="{
+    value: row.notes,
+    showActions: true,
+    showUndoChange: true,
+    collisionBoundary: context.tableElementRef.value,
+  }"
+  @commit-value="row.notes = $event.value"
+>
+  <template #editor="{ draftValue, updateDraftValue }">
+    <FuroTextarea
+      :parcel="{ value: draftValue }"
+      @change-value="updateDraftValue({ value: $event.value })"
+    />
+  </template>
+</FuroEditableField>
+```
+
+### Select with custom preview
+
+```html
+<FuroEditableField
+  :parcel="{
+    value: row.territoryCode,
+    showActions: true,
+    collisionBoundary: context.tableElementRef.value,
+    submitMode: 'none',
+  }"
+  @commit-value="row.territoryCode = $event.value"
+>
+  <template #preview>
+    {{ row.formatTerritoryPreview() }}
+  </template>
+
+  <template #editor="{ draftValue, updateDraftValue, submit }">
+    <FuroSelect
+      :parcel="{ value: draftValue, options: context.territoryOptions }"
+      @update:value="updateDraftValue({ value: $event })"
+    />
+  </template>
+</FuroEditableField>
+```
+
+### Checkbox — draft sync only; commit on the primitive's submit or explicit `submit()`
+
+```html
+<template #editor="{ draftValue, updateDraftValue }">
+  <FuroCheckbox
+    :parcel="{ value: draftValue }"
+    @update:value="updateDraftValue({ value: $event })"
+  />
+</template>
+```
+
+---
+
+## Non-goals / limitations
+
+- **No `v-model:value`** — parent owns `parcel.value`; listen to `@commit-value`.
+- **No `v-model:editing`** — listen to `@update-editing-state` (`'edit' \| 'cancel' \| 'submit'`) if the parent needs edit-mode telemetry.
+- **No per-keystroke Furo emit** — use child field `@change-value` inside `#editor` if the parent needs live draft telemetry.
+- **No `cancel-edit` emit** — listen to the primitive's cancel only via future API; today cancel is silent at the Furo layer.
+- **No built-in `variant` / `editOverlay` modes** — one floating editor positioning strategy.
+- **Default preview is not option-aware** — objects render as JSON; use `#preview`.
+- **Empty string is not “empty”** for preview placeholder — only `null`, `{}`, and `[]` show `emptyPreviewText`.
+- **Do not import** `EditorCollisionProcessor`, `ObjectProcessor`, or the underlying editable primitive in application code.
+
+---
+
+## Tests
+
+- `tests/__tests__/jsdom/lib/components/molecules/FuroEditableField/EditableEmitPayload.js`
+- `tests/__tests__/jsdom/lib/components/molecules/FuroEditableField/FuroEditableFieldContext.js`
+- `tests/__tests__/jsdom/lib/components/molecules/FuroEditableField/processors/EditorCollisionProcessor.js`
+
+Run:
+
+```bash
+npm test -- tests/__tests__/jsdom/lib/components/molecules/FuroEditableField/
+```