@openreachtech/furo-vue 1.6.0 → 1.7.0

package/docs/furo-table.md

@@ -0,0 +1,233 @@
+# FuroTable
+
+Domain-agnostic, presentational data table organism. Renders a native `<table>` from a `columns` + `rows` parcel and exposes per-cell slots, controlled sort, row selection, and loading/empty/error states.
+
+| **Layer** | Organism (`lib/components/organisms/FuroTable/`) |
+| **Base** | Native `<table>` (no headless table primitive) |
+| **Selection control** | `FuroCheckbox` atom |
+| **Sub-context** | `FuroTableRowItemContext` (per-row presentation) |
+
+FuroTable is **controlled**: it emits sort and selection intent and re-reads its parcel. It never sorts, filters, paginates, or fetches data itself. Cell rendering, row actions, and column formatting live in the consumer app via slots — the library ships no renderer or action registry. A trailing per-row actions column (`row-actions` slot) and a footer region (`footer` slot) are opt-in structural slots for the common list-view layout.
+
+## Props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `parcel` | `FuroTableParcel \| null` | Closed-set, JSON-serializable table state (below) |
+
+### `FuroTableParcel`
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `columns` | `Array<FuroTableColumn>` | `[]` | Column configuration |
+| `rows` | `Array<object>` | `[]` | Raw row records (rendered in the order given) |
+| `rowKey` | `string` | `'id'` | Field used as each row's unique key |
+| `selectable` | `boolean` | `false` | Show the selection column + select-all checkbox |
+| `selectedRowKeys` | `Array<string \| number> \| null` | `null` | Controlled selection. `null` = uncontrolled (table holds its own selection) |
+| `sort` | `{ field: string, direction: 'asc' \| 'desc' } \| null` | `null` | Active sort indicator (controlled) |
+| `loading` | `boolean` | `false` | Render the loading state |
+| `errorMessage` | `string \| null` | `null` | When set, render the error state (takes precedence over loading/empty/rows) |
+| `emptyText` | `string` | `'No records'` | Text for the default empty state |
+| `virtual` | `FuroTableVirtual \| null` | `null` | When set, fixed-height virtual scrolling (below) |
+| `totalRecords` | `number \| null` | `null` (falls back to `rows.length`) | Full dataset size — drives total scroll height in virtual mode |
+| `rowOffset` | `number` | `0` | Global index of `rows[0]` — lets `rows` be a sparse window in virtual mode |
+| `resizable` | `boolean` | `false` | Show drag handles on column edges (below) |
+| `compact` | `boolean` | `false` | Compact density — denser rows, tighter padding, smaller text |
+| `gridLines` | `boolean` | `false` | Vertical borders between columns |
+| `rowActionsLabel` | `string` | `''` | Header text for the trailing row-actions column (only rendered when the `row-actions` slot is provided) |
+| `rowActionsWidth` | `string` | `'6rem'` | CSS width of the row-actions column |
+
+### `FuroTableVirtual`
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `itemSize` | `number` | — | Fixed row height in px |
+| `height` | `number` | — | Scroll viewport height in px |
+| `overscan` | `number` | `4` | Extra rows rendered above and below the viewport |
+| `endThreshold` | `number` | `8` | How close (in rows) a downward scroll must get to the loaded window's end before `reach-end` fires |
+
+### `FuroTableColumn`
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `field` | `string` | — | Key into each row record |
+| `label` | `string` | `field` | Header text |
+| `sortable` | `boolean` | `false` | Clicking the header label emits `sort:change` |
+| `align` | `'start' \| 'center' \| 'end'` | `'start'` | Cell text alignment |
+| `width` | `string` | — | Initial CSS width (e.g. `'12rem'`). Otherwise the fixed layout shares width equally |
+
+State precedence: **error → loading → empty → rows**.
+
+## Loading
+
+`parcel.loading` draws one of two presentations, chosen by whether rows already sit on screen:
+
+| Rows | Presentation |
+|------|--------------|
+| none | a centered spinner row inside the body, so a first load never dims an empty table |
+| some | a floating overlay above the whole table, so a refresh keeps its rows and shifts no layout |
+
+Under both, the scroll region carries `inert` and the root carries `aria-busy="true"`. Every control inside therefore stops answering pointer and keyboard alike: the select-all and per-row checkboxes render disabled, a sortable header stops cycling, a resize handle stops dragging, and whatever you passed to `cell` or `row-actions` goes unreachable with them. Note that `inert` also drops the table out of the accessibility tree for as long as it lasts, which is why the root announces itself busy. Clearing `loading` restores everything.
+
+One gap is worth knowing: a menu or popover that portals its content renders outside the scroll region, so a dropdown already open when the load began stays interactive even though its trigger does not. Close it yourself if a refresh must not act on the row underneath.
+
+## Events
+
+| Event | Payload | When |
+|-------|---------|------|
+| `sort:change` | `{ field: string, direction: 'asc' \| 'desc' \| null }` | A sortable header is clicked. Cycles `asc → desc → null` (the third click clears the sort; `direction: null` restores the default order) |
+| `selection:change` | `{ selectedRowKeys: Array<string \| number> }` | A row or the select-all checkbox toggles |
+| `update:selectedRowKeys` | `Array<string \| number>` | `v-model:selectedRowKeys` sync (fires with `selection:change`) |
+| `range:change` | `{ first: number, last: number }` | Virtual mode only — the visible global row window moved. Fires on mount and thereafter only when the window changes. Best for **sparse-window** consumers that fetch exactly the visible window |
+| `reach-end` | `{ first: number, last: number, loadedCount: number, totalRecords: number }` | Virtual mode only — a **downward** scroll came within `endThreshold` rows of the loaded window's end while more records remain. Also fires on mount, and again whenever the loaded window changes size, so a window still holding unloaded rows never waits for a scroll. Best for **infinite-append** consumers: fires once per loaded window, re-arming when it grows and when a refresh shrinks it, never on upward scroll and never before the end |
+| `row:click` | `{ row: object, rowKey: string \| number \| null }` | A data row is clicked. Use it to navigate to a detail view. The built-in selection cell stops propagation; interactive `cell`-slot content (buttons, dropdowns, links) should `@click.stop` to opt out |
+
+## Slots
+
+| Slot | Scope | Fallback |
+|------|-------|----------|
+| `header-cell` | `{ column }` | `column.label` |
+| `cell` | `{ row, column, value }` | the raw cell value |
+| `loading` | — | a spinner icon |
+| `empty` | — | `parcel.emptyText` |
+| `error` | `{ message }` | `parcel.errorMessage` |
+| `placeholder` | `{ index }` | a shimmer skeleton bar (virtual mode, unloaded row) |
+| `row-actions` | `{ row }` | (none) — providing this slot adds a trailing actions column |
+| `pagination` | — | (empty) — host a `FuroPagination` here |
+| `footer` | `{ selection }` | (none) — providing this slot renders a footer region below the table. `selection` is `{ keys, count }` |
+
+The sort trigger is the **header label** only (not the whole header cell), so it does not conflict with the resize handle. It is keyboard-accessible (`role="button"`, `tabindex`, Enter/Space). Clicking cycles through three states — **ascending → descending → unsorted** — so a third click restores the default order. A sortable column always shows a sort icon: a dimmed neutral (bidirectional) icon by default, brightening to a directional up/down icon once it is the active sort.
+
+## Column resizing
+
+Set `parcel.resizable` to show a drag handle on the right edge of each header. Dragging sets an explicit px width for that column. The table uses `table-layout: fixed` with a `<colgroup>`, so:
+
+- Column widths are stable across loading / empty / error / data states — no width jump when content changes.
+- Resized widths and configured `column.width` are applied via the `<colgroup>`; unsized columns share the remaining width equally.
+- Minimum column width is 80px.
+
+Resizing is **fit mode** (like a contained data table): the table's total width stays fixed, and dragging a column trades width with the column to its right (both clamped to the minimum). The table never grows from a resize, so a column can never be pushed off-screen with an unreachable handle. Consequently the **last column has no resize handle** (no neighbour to trade with). On the first resize all column widths are pinned to their current rendered size so the rest stay put.
+
+The scroll container is `overflow: auto`, so horizontal scroll still appears if the *content itself* is too wide (e.g. many columns or explicit `column.width`s exceeding the container) — resizing just never triggers it.
+
+The drag uses pointer capture on the handle, so resizing continues smoothly even when the cursor leaves the handle.
+
+## Density & grid lines
+
+Set `parcel.compact` for a denser layout (shorter rows, tighter padding, smaller text) — useful for data-dense list views. Set `parcel.gridLines` to draw vertical borders between columns.
+
+Cell padding is a token pair, so an app retunes density without targeting furo's class names:
+
+| Token | Default | Controls |
+|-------|---------|----------|
+| `--size-table-cell-inline` | `1rem` | Inline padding of every header, body, placeholder and actions cell |
+| `--size-table-cell-block` | `0` | Block padding of the same cells. Rows keep their own height, so a value only grows a row once content plus padding exceeds it |
+
+Compact density and the selection (checkbox) cell derive from `--size-table-cell-inline`, so one value keeps them in proportion: a compact cell takes half of it, the selection cell takes half of it, and the compact selection cell takes `0.375` times it. At the default `1rem` these come to the `0.5rem`, `0.5rem` and `0.375rem` the table has always drawn.
+
+```css
+:root {
+  --size-table-cell-inline: 0.75rem;
+  --size-table-cell-block: 0.5rem;
+}
+```
+
+## Row interaction
+
+Listen to `row:click` to make rows navigate (the CRM list view links each row to its detail page). The payload carries the full `row` and its `rowKey`, so the consumer owns the navigation. The built-in selection checkbox cell stops click propagation, so toggling selection never fires `row:click`. Any interactive content you put in a `cell` slot (action buttons, dropdown menus, links) should add `@click.stop` so it does not also trigger row navigation.
+
+## Overflow & truncation
+
+Default header and cell text truncate with an ellipsis (the layout is `table-layout: fixed`). Truncation is applied to wrapper spans (`.label-text`, `.cell-text`) — **not** the `<td>` — so interactive slot content (buttons, dropdown triggers, focus rings) is never clipped. Custom `cell` slot content controls its own overflow.
+
+## Row-actions column & footer
+
+Two structural slots cover the standard list-view chrome without leaking domain logic into the library:
+
+- **`row-actions`** — providing this slot adds a dedicated trailing column, so per-row action buttons or an action menu (e.g. `FuroDropdownMenu`) stay aligned in their own column instead of being squeezed into the last `cell`. The slot scope gives you the raw `row` (which carries the row key). The actions `<td>` stops click propagation, so pressing an action never fires `row:click`. The header shows `parcel.rowActionsLabel` (empty by default) and the column width is `parcel.rowActionsWidth` (`6rem` by default). It works in both normal and virtual modes; unloaded virtual rows keep the same cell structure as loaded ones, so the placeholder spans only the data columns and the selection and actions cells render empty beside it. Keeping those cells is what stops the checkbox column from blinking out of the layout while a virtual table scrolls through unloaded rows.
+- **`footer`** — providing this slot renders a footer region below the table (and below `pagination`), suited to a bulk-action bar or a summary row. The slot scope exposes a single `selection` object (`{ keys, count }`), so a bar like "3 selected — Delete" needs no extra wiring.
+
+```vue
+<FuroTable :parcel="{ columns, rows, selectable: true, rowActionsLabel: 'Actions' }">
+  <template #row-actions="{ row }">
+    <FuroButton :parcel="{ variant: 'ghost', size: 'sm' }" @click="onEdit(row)">
+      Edit
+    </FuroButton>
+  </template>
+
+  <template #footer="{ selection }">
+    <span v-if="selection.count > 0">{{ selection.count }} selected</span>
+  </template>
+</FuroTable>
+```
+
+## Column types via the `cell` slot
+
+The table is presentational, so any column type (inline-editable fields, single action buttons, multi-action dropdown menus, badges, links, etc.) is rendered by the consumer through the `cell` slot, keyed on `column.field`. The library ships no editor or action registry. See the playground "Editable + action columns" and "Actions menu (dropdown)" samples.
+
+## Usage
+
+```vue
+<FuroTable
+  :parcel="{
+    columns: [
+      { field: 'name', label: 'Name', sortable: true },
+      { field: 'email', label: 'Email', sortable: true },
+      { field: 'role', label: 'Role', align: 'end' },
+    ],
+    rows: members,
+    selectable: true,
+    selectedRowKeys: selectedKeys,
+    sort: activeSort,
+  }"
+  @sort:change="onSortChange"
+  @selection:change="onSelectionChange"
+>
+  <template #cell="{ column, value }">
+    <RoleBadge v-if="column.field === 'role'" :role="value" />
+    <template v-else>{{ value }}</template>
+  </template>
+
+  <template #pagination>
+    <FuroPagination :parcel="{ limit: 20, totalRecords: total }" />
+  </template>
+</FuroTable>
+```
+
+The consumer owns the data lifecycle: re-sort `rows` and re-pass `parcel.sort` on `sort:change`, and re-pass `selectedRowKeys` on `selection:change` (or omit it for uncontrolled selection).
+
+## Virtual scroll
+
+For large datasets (thousands of rows), set `parcel.virtual` to enable fixed-height windowing. The table renders only the rows in the viewport (plus overscan), padded by leading/trailing spacer rows so scroll geometry stays exact. The header stays sticky.
+
+It is **controlled and sparse-aware**, matching a lazy-fetch model:
+
+- `totalRecords` drives the full scroll height.
+- `rows` may be just the loaded window; `rowOffset` is the global index of `rows[0]`.
+- On scroll, the table emits `range:change { first, last }`. The consumer fetches that window (e.g. via the ListView adapter / GraphQL) and re-passes `rows` + `rowOffset`.
+- Indices in the visible window that are not yet loaded render as placeholder rows (a shimmer skeleton by default, or the `placeholder` slot). This makes **async** lazy-loading seamless: emit a fetch on `range:change`, render skeletons while it resolves, then re-pass `rows`. Use a request token to discard superseded windows.
+
+```vue
+<FuroTable
+  :parcel="{
+    columns,
+    rows: loadedWindow,        // sparse window
+    rowOffset: windowOffset,   // global index of loadedWindow[0]
+    totalRecords: 1000,
+    virtual: { itemSize: 40, height: 400 },
+  }"
+  @range:change="loadWindow"   // fetch rows for { first, last }
+/>
+```
+
+The fixed-height windowing is hand-rolled (no virtualizer dependency). The initial window is the consumer's responsibility (the table emits `range:change` on scroll, not on mount), so load the first window before render.
+
+## Not in MVP
+
+- **Dynamic / measured row height** — virtual scroll is fixed-height (`itemSize`) only.
+- **Inline / bulk edit host** — deferred to P3; build on top via the `cell` slot.
+- **Local sorting / filtering / pagination** — out of scope by design; the table is controlled.
+
+## Playground
+
+`/samples/components/playground` → **Table** tab.

package/docs/furo-tabs.md

@@ -0,0 +1,173 @@
+# FuroTabs
+
+Organism — tabbed layout built on a headless tabs primitive (`Root` + `List` +
+`Trigger` + `Content` + optional `Indicator`). Renders a trigger row from a
+declarative `tabs` list and a panel per tab via named slots, tracking the active
+tab and emitting changes. Supports two visual variants (`line`, `solid`), a
+scrollable trigger row with navigation buttons, and a panel-less menu mode.
+Domain-agnostic: no GraphQL, router, or Nuxt imports — the consumer wires the
+emitted value to its own state.
+
+Location: `lib/components/organisms/FuroTabs/`
+
+## Props
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `parcel` | `FuroTabsParcel \| null` | `null` | Reactive behavior object (below) |
+
+### `parcel`
+
+| Key | Type | Default | Notes |
+|-----|------|---------|-------|
+| `tabs` | `Array<FuroTabsTab>` | `[]` | Tab descriptors that drive the trigger row and panel slots (below). |
+| `value` | `string \| null` | — | Active tab value, where the presence of the key decides ownership. Absent, the component manages its own active tab, defaulting to the first tab. Present with a value, the parent owns the active tab. Present and `null`, the parent owns it and no tab is active. |
+| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Layout direction of the trigger row. |
+| `variant` | `'line' \| 'solid'` | `'line'` | `line` is an underlined trigger row with a sliding indicator; `solid` is a segmented control where the active trigger gets a raised background. |
+| `scrollable` | `boolean` | `false` | When `true`, the trigger row scrolls and previous/next navigation buttons appear once it overflows. |
+| `showPanels` | `boolean` | `true` | When `false`, no panels render — the component is a navigation menu only (the active value drives an external `router-view`). |
+| `showIndicator` | `boolean` | `true` | Renders the animated sliding indicator. Applies to the `line` variant only — the `solid` variant marks the active tab with its background instead. |
+| `disabled` | `boolean` | `false` | Disables the whole tab set. |
+| `scrollPreviousLabel` | `string` | `'Scroll to previous tabs'` | Accessible name of the scroll-toward-start button. Set it to translate the control. |
+| `scrollNextLabel` | `string` | `'Scroll to next tabs'` | Accessible name of the scroll-toward-end button. Set it to translate the control. |
+
+### `FuroTabsTab`
+
+| Key | Type | Default | Notes |
+|-----|------|---------|-------|
+| `value` | `string` | — | Unique tab identifier; also the default panel slot name. It reaches the DOM inside the trigger and panel element ids, so pass a token valid in an id (see the notes below). |
+| `label` | `string` | — | Trigger text (overridable via the `label-<value>` slot). |
+| `slotName` | `string` | `value` | Overrides the panel slot name for this tab. |
+| `disabled` | `boolean` | `false` | Disables this single tab. |
+| `attrs` | `Record<string, string \| number \| boolean>` | — | Attributes set on this tab's trigger element, for a state the component does not own (`aria-current`, your own `data-*`). The component owns the trigger's element shape, its identity and its active state, so the bag drops those keys rather than applying them: `value`, `disabled`, `id`, `role`, `type`, `aria-selected`, `aria-controls`, `data-state`, `data-disabled` and `data-orientation`. |
+| `class` | `string` | — | Class name added to this tab's trigger element, alongside the component's own `tab` class. |
+
+## Events
+
+| Event | Payload | When |
+|-------|---------|------|
+| `update:value` | `string` | Active tab changed — enables `v-model:value`. |
+| `tab:change` | `{ value: string }` | Active tab changed. |
+
+## Slots
+
+| Slot | Purpose |
+|------|---------|
+| `<value>` (or `<slotName>`) | Panel content for the matching tab. One slot per tab, keyed by the tab's `value` (or its `slotName` override). |
+| `label-<value>` | Custom trigger content for the matching tab, receiving `{ value, label }`. When omitted, the trigger shows `label`. |
+
+## Usage
+
+### Uncontrolled
+
+```vue
+<FuroTabs
+  :parcel="{ tabs: [
+    { value: 'profile', label: 'Profile' },
+    { value: 'settings', label: 'Settings' },
+  ]}"
+  @tab:change="onTabChange($event.value)"
+>
+  <template #profile>...profile panel...</template>
+  <template #settings>...settings panel...</template>
+</FuroTabs>
+```
+
+### Controlled (`v-model:value`)
+
+```vue
+<FuroTabs
+  :parcel="{ value: activeTab, tabs }"
+  @tab:change="activeTab = $event.value"
+>
+  <template #profile>...</template>
+  <template #settings>...</template>
+</FuroTabs>
+```
+
+### Vertical orientation
+
+```vue
+<FuroTabs :parcel="{ orientation: 'vertical', tabs }">
+  <template #profile>...</template>
+  <template #settings>...</template>
+</FuroTabs>
+```
+
+### Solid variant
+
+```vue
+<FuroTabs :parcel="{ variant: 'solid', tabs }">
+  <template #profile>...</template>
+  <template #settings>...</template>
+</FuroTabs>
+```
+
+### Scrollable trigger row
+
+```vue
+<FuroTabs :parcel="{ scrollable: true, tabs: manyTabs }">
+  <!-- panel slots per tab -->
+</FuroTabs>
+```
+
+### Tab menu (no panels, router-driven)
+
+```vue
+<FuroTabs
+  :parcel="{ showPanels: false, value: route.name, tabs }"
+  @tab:change="router.push({ name: $event.value })"
+/>
+<router-view />
+```
+
+### Custom trigger content
+
+```vue
+<FuroTabs :parcel="{ tabs }">
+  <template #label-profile>★ Profile</template>
+  <template #profile>...</template>
+</FuroTabs>
+```
+
+### Marking a tab with consumer state
+
+```vue
+<FuroTabs
+  :parcel="{ tabs: [
+    { value: 'stage-2', label: '2. Review', class: 'completed' },
+    { value: 'stage-3', label: '3. Waiting', attrs: { 'aria-current': 'step' } },
+  ]}"
+/>
+```
+
+### Translated scroll buttons
+
+```vue
+<FuroTabs
+  :parcel="{
+    scrollable: true,
+    scrollPreviousLabel: '前のタブへスクロール',
+    scrollNextLabel: '次のタブへスクロール',
+    tabs: manyTabs,
+  }"
+/>
+```
+
+## Notes
+
+- The active trigger is marked with `data-state="active"` for styling; disabled
+  triggers are non-interactive.
+- Root CSS class: `unit-tabs` (inside `@layer furo`). Modifier classes: `line` /
+  `solid` (variant), `vertical` (orientation), `scrollable` (scroll mode), and
+  `disabled` (whole control disabled).
+- When `scrollable` is `true`, navigation buttons are auto-disabled at the
+  start/end of the scroll range and recompute on scroll and whenever the
+  trigger row's viewport is resized, whether or not the window itself changed
+  size. A platform without `ResizeObserver` keeps the scroll-event recompute.
+- A tab's `value` is interpolated into the trigger and panel element ids, and
+  into the `aria-controls` / `aria-labelledby` pair built from them. A value
+  carrying a space or another character invalid in an id breaks that pairing
+  silently, with no console warning. Pass a token the application controls
+  (`stage-3`, `orders`), never a raw server string such as a status name, and
+  map back to the server key yourself.

package/docs/furo-text-field.md

@@ -0,0 +1,249 @@
+# `<FuroTextField>` Interface Specification
+
+## Overview
+
+`<FuroTextField>` is a text input Atom in the Furo-Vue component system. It is an opinionated abstraction over a native `<input type="text">` element — it does not mirror raw HTML but encapsulates structure, accessibility, and controlled/uncontrolled state management internally.
+
+---
+
+## Props
+
+`<FuroTextField>` uses **two distinct mechanisms** for receiving data from the parent, each with a different responsibility.
+
+### Rule: `parcel` vs Fallthrough Attributes
+
+| Mechanism              | When to use                                                         | Rendered as    |
+|------------------------|---------------------------------------------------------------------|----------------|
+| `:parcel`              | Props that **control component behavior** (value, invalid state, …) | Not HTML attrs |
+| Fallthrough attributes | Native **HTML attributes** that belong on the `<input>` element     | Direct HTML    |
+
+The distinction maps cleanly to HTML semantics: if it's part of HTML, it should appear as HTML. If it controls Furo's internal logic, it goes into `parcel`.
+
+```html
+<!-- ✅ Correct -->
+<FuroTextField
+  :parcel="context.usernameParcel"
+  :disabled="context.usernameParcel.disabled"
+/>
+
+<!-- context.usernameParcel = { value: '...', invalid: true, ... } -->
+```
+
+> **Why `parcel` exists:** Components with 10+ individual props make it hard to review the wiring between HTML template and Context members. `parcel` consolidates behavior-controlling props into one reviewable object.
+> **Why fallthrough exists:** HTML attributes are structurally part of HTML — they belong in the template where the HTML structure is visible.
+
+---
+
+### `parcel` shape
+
+Behavior-controlling props passed as a single object.
+
+| Key       | Type                    | Required | Default | Description                                 |
+|-----------|-------------------------|----------|---------|---------------------------------------------|
+| `value`   | `string \| number \| null` | No    | `null`  | Controlled value. Synced to internal `ref`. |
+| `invalid` | `boolean`               | No       | `false` | Applies invalid/error visual state.         |
+
+> All values must be **JSON-serializable** (no functions, no class instances).
+
+---
+
+### Fallthrough Attributes (HTML attributes)
+
+Native HTML attributes passed directly on the component element. Vue automatically forwards them to the underlying `<input>`.
+
+| Attribute      | Type      | Description                                  |
+|----------------|-----------|----------------------------------------------|
+| `disabled`     | `boolean` | Disables user interaction.                   |
+| `required`     | `boolean` | Marks the field as required.                 |
+| `placeholder`  | `string`  | Placeholder text displayed inside the input. |
+| `name`         | `string`  | Form field name.                             |
+| `autocomplete` | `string`  | Browser autocomplete hint.                   |
+
+> The `type` attribute is intentionally excluded from fallthrough — the component always renders `type="text"`.
+
+```html
+<FuroTextField
+  :parcel="context.usernameParcel"
+  :disabled="context.usernameParcel.disabled"
+  placeholder="Enter your username"
+  name="username"
+  autocomplete="username"
+/>
+```
+
+---
+
+## Emits
+
+Each emit passes a **`TextFieldEmitPayload` instance** directly as the event argument. In the template, `$event` is that `TextFieldEmitPayload` instance.
+
+```js
+// Inside <FuroTextField>
+emit('change-value', TextFieldEmitPayload.create({ rawEvent }))
+```
+
+```html
+<!-- ✅ Correct — $event is the TextFieldEmitPayload instance -->
+<FuroTextField
+  :parcel="context.buildTextFieldParcel()"
+  @change-value="context.onChangeValue({ payload: $event })"
+/>
+```
+
+> **Event handler style:** In the parent Context, always use **single object parameter destructuring**. The template wraps `$event` into `{ payload: $event }` when calling Context methods.
+
+---
+
+### `@change-value`
+
+Emitted on every `input` event (i.e., each keystroke).
+
+```html
+<FuroTextField
+  :parcel="context.buildTextFieldParcel()"
+  @change-value="context.onChangeValue({ payload: $event })"
+/>
+```
+
+### `@commit-value`
+
+Emitted on `blur` event or `Enter` key press.
+
+```html
+<FuroTextField
+  :parcel="context.buildTextFieldParcel()"
+  @commit-value="context.onCommitValue({ payload: $event })"
+/>
+```
+
+### `@update:value`
+
+Emitted alongside both `@change-value` and `@commit-value` to support `v-model:value`. The argument is the raw string value (not a payload instance).
+
+> **Naming rationale:**
+> `@change-value` replaces the potentially confusing `@input` native name, making developer intent explicit.
+> `@commit-value` replaces `@change` to avoid collision with native `change` event semantics and is more readable.
+> Furo names are based on what the parent component *wants*, not on internal browser events.
+
+> **Emitter responsibility:** `<FuroTextField>` **always emits** regardless of validity. The parent (Context) decides how to respond. The component never cancels an emit based on value state.
+
+---
+
+## Event Handler Style in Context
+
+All event handlers use **single object parameter destructuring** — no exceptions. This keeps Context code consistent with the rest of the ORT coding style.
+
+```js
+// ✅ Correct
+onChangeValue ({
+  payload
+}) {
+  const isValid = this.validatesEmail({
+    payload
+  })
+
+  this.statusReactive.isEmailInvalid = !isValid
+}
+
+// ❌ Wrong — single positional argument breaks consistency
+onChangeValue (payload) {
+  ...
+}
+```
+
+> **Why not allow `(payload)` as an exception?** Remembering exceptional rules wastes mental resources. `EmitPayload` is designed to be expressive enough that `extra` parameters are never needed. If extra parameters become necessary in the future, it will be addressed as a major version upgrade of furo.
+
+---
+
+## `TextFieldEmitPayload` API
+
+The payload object received in all event handlers exposes the following members:
+
+| Member                  | Type               | Description                                                                |
+|-------------------------|--------------------|----------------------------------------------------------------------------|
+| `.value`                | `string \| null`   | Current raw string value of the input.                                     |
+| `.trimmedValue`         | `string \| null`   | Whitespace-trimmed version of `.value` (getter form).                      |
+| `.extractTrimmedValue()` | `string \| null`   | Whitespace-trimmed version of `.value`.                                     |
+| `.hasEmptyText()`       | `boolean`          | `true` if `.value` is empty or the control is missing.                     |
+| `.hasEmptyTrimmedText()`| `boolean`          | `true` if `.extractTrimmedValue()` is empty or the control is missing.     |
+| `.hasEnteredText()`     | `boolean`          | `true` if `.value` has at least one character (whitespace counts).         |
+| `.hasEnteredTrimmedText()`| `boolean`        | `true` if `.extractTrimmedValue()` has at least one non-whitespace character. |
+
+```js
+onChangeValue ({
+  payload
+}) {
+  if (payload.hasEmptyTrimmedText()) {
+    this.statusReactive.isEmailInvalid = true
+    return
+  }
+
+  this.statusReactive.isEmailInvalid = !this.validatesEmail({ payload })
+}
+```
+
+---
+
+## `v-model` Support
+
+`v-model:value` is supported as syntactic sugar over `:parcel` value binding + `@update:value`.
+
+```html
+<!-- These two are equivalent -->
+<FuroTextField v-model:value="context.someRef.value" />
+
+<FuroTextField
+  :parcel="{
+    value: context.someRef.value
+  }"
+  @update:value="context.someRef.value = $event"
+/>
+```
+
+> A watcher **inside** `<FuroTextField>` synchronizes both `parcel.value` and `attrs.value` with the internal `ref`. No watcher is required in the parent component.
+
+---
+
+## Controlled vs. Uncontrolled State
+
+`<FuroTextField>` supports **both modes**:
+
+| Mode         | How                                                               |
+|--------------|-------------------------------------------------------------------|
+| Controlled   | Pass `:parcel="{ value: ... }"` or `v-model:value`. Internal ref syncs from prop. |
+| Uncontrolled | Omit `value` in parcel. Internal ref manages its own state.      |
+
+> The watcher inside `setupComponent()` reads from `parcel.value` first, then falls back to `attrs.value`. If both are absent, the internal value is `null`.
+
+---
+
+## Example: Validation in Parent Context
+
+When a parent needs to validate on change, use `@change-value` — no watcher needed:
+
+```js
+// In Context class
+onChangeValue ({
+  payload
+}) {
+  const isValid = this.validatesEmail({
+    payload
+  })
+
+  this.statusReactive.isEmailInvalid = !isValid
+}
+```
+
+```html
+<FuroTextField
+  :parcel="{
+    value: context.emailRef.value,
+    invalid: context.statusReactive.isEmailInvalid,
+  }"
+  :required="true"
+  placeholder="Enter your email"
+  @change-value="context.onChangeValue({ payload: $event })"
+/>
+```
+
+---