@openreachtech/furo-vue 1.6.0 → 1.7.0

package/docs/furo-number-field.md

@@ -0,0 +1,397 @@
+# `<FuroNumberField>` Interface Specification
+
+## Overview
+
+`<FuroNumberField>` is a numeric input Atom in the Furo-Vue component system. It is an opinionated abstraction over a headless number-field primitive — it does not mirror the raw primitive API but encapsulates structure, accessibility, stepper controls, and controlled/uncontrolled state management internally.
+
+Unlike `<FuroTextField>`, which wraps a single `<input>` element, `<FuroNumberField>` renders a composite structure consisting of a decrement button, a formatted input, and an increment button. Keyboard interactions (Arrow Up/Down, Page Up/Page Down) and mouse wheel control are handled by the underlying primitive automatically.
+
+Adheres to the [Spinbutton WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/spinbutton).
+
+---
+
+## Props
+
+`<FuroNumberField>` 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, bounds, formatting, nested primitive parcels, …) | Bound to the root and nested primitive parts |
+| Fallthrough attributes | Non-prop attributes on `<FuroNumberField>` (e.g. `name`, `placeholder`, `disabled`) | Applied per Vue fallthrough rules; see below |
+
+The distinction maps cleanly to responsibilities: numeric behavior and primitive configuration live in `parcel`. Declarative HTML-like hints used with native forms often stay on the component tag for readability.
+
+```html
+<!-- ✅ Correct -->
+<FuroNumberField
+  :parcel="context.quantityParcel"
+  placeholder="Quantity"
+  name="quantity"
+/>
+
+<!-- context.quantityParcel = { value: 1, invalid: false, min: 0, max: 100 } -->
+```
+
+> **Why `parcel` exists:** Components with many 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:** Attributes such as `name`, `placeholder`, or `disabled` stay visible on the component element where the usage is declared.
+
+---
+
+### `parcel` shape
+
+The parcel is **`v-bind` spread onto the root** (via `extractRootAttributes()`), with Furo-specific extensions. It therefore includes every root prop except `modelValue` / `defaultValue` (those are managed internally), plus the fields below.
+
+| Key                 | Type                    | Required | Default     | Description |
+|---------------------|-------------------------|----------|-------------|-------------|
+| `value`             | `number \| null`        | No       | `null`      | Controlled value. Watched and synced into an internal ref. |
+| `invalid`           | `boolean`               | No       | `false`     | Applies invalid/error visual state (`invalid` class and `aria-invalid`). |
+| `min`               | `number`                | No       | —           | Smallest value allowed (the underlying primitive). Also reflected on the inner `<input>` as the `min` attribute. |
+| `max`               | `number`                | No       | —           | Largest value allowed (the underlying primitive). Also reflected on the inner `<input>` as the `max` attribute. |
+| `step`              | `number`                | No       | (primitive default) | Step for increment/decrement. |
+| `stepSnapping`      | `boolean`               | No       | —           | When `false`, avoids snapping to `step` increments (primitive). |
+| `formatOptions`     | `Intl.NumberFormatOptions` | No    | —           | Formatting for the displayed value (currency, percent, decimals, …). |
+| `locale`            | `string`                | No       | —           | BCP 47 locale tag for formatting (e.g. `'en-US'`, `'ja-JP'`). |
+| `inputParcel`       | input part props & input HTML attrs | No | — | Passed to the input part (e.g. `autofocus`, `readonly`, `disabled` when binding at the input layer). |
+| `decrementParcel`   | decrement part props | No | — | Passed to the decrement part. |
+| `incrementParcel`   | increment part props | No | — | Passed to the increment part. |
+
+> All parcel values must be **JSON-serializable** (no functions, no class instances).
+
+#### `parcel.formatOptions` examples
+
+```js
+// Decimal with minimum fraction digits
+formatOptions: {
+  minimumFractionDigits: 2,
+}
+
+// Percentage (often paired with step: 0.01)
+formatOptions: {
+  style: 'percent',
+}
+
+// Currency
+formatOptions: {
+  style: 'currency',
+  currency: 'USD',
+  currencyDisplay: 'symbol',
+}
+```
+
+---
+
+### Fallthrough Attributes (non-prop attributes)
+
+`<FuroNumberField>` only declares the **`parcel`** prop. Any other attributes (`name`, `placeholder`, `disabled`, `class`, `style`, `autofocus`, …) are available on **`componentContext.attrs`**.
+
+Two attributes are **read explicitly** for the inner native `<input>`:
+
+| Attribute     | Behavior |
+|---------------|----------|
+| `name`        | Applied to the inner `<input>` (`extractNameAttribute()`). |
+| `placeholder` | Applied to the inner `<input>` (`extractPlaceholderAttribute()`). |
+
+Remaining fallthrough attributes follow Vue’s default behavior (typically the **single root** is the primitive root). For anything that must attach specifically to the native input or to the input part's props, prefer **`parcel.inputParcel`** (see playground: `inputParcel: { autofocus: true }`).
+
+```html
+<FuroNumberField
+  :parcel="context.quantityParcel"
+  placeholder="0–100"
+  name="quantity"
+  disabled
+/>
+```
+
+> The native `type` attribute is not used as a raw `type="number"` — the underlying primitive implements the spinbutton pattern (`role="spinbutton"`) with locale-aware formatting.
+
+---
+
+## Slots
+
+Optional **`decrement`** and **`increment`** slots replace the default Phosphor minus/plus icons. Both receive a scoped prop:
+
+| Slot        | Scoped props | Default content |
+|-------------|----------------|-----------------|
+| `decrement` | `{ value }` — current numeric model (may be `null`) | `<Icon name="ph:minus" />` |
+| `increment` | `{ value }` — current numeric model (may be `null`) | `<Icon name="ph:plus" />` |
+
+---
+
+## Emits
+
+Each emit passes a **`NumberFieldEmitPayload` instance** directly as the event argument — except **`update:value`**, which emits a bare `number | null`. In the template, `$event` is that payload instance for `change-value` and `commit-value`.
+
+```js
+// Conceptually inside <FuroNumberField> / context
+emit('change-value', payload)
+emit('update:value', payload.value)
+```
+
+```html
+<!-- ✅ Correct — $event is the NumberFieldEmitPayload instance -->
+<FuroNumberField
+  :parcel="context.buildNumberFieldParcel()"
+  @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 when the underlying primitive updates the model — typing, stepping (buttons), arrow keys, or wheel, via `@update:model-value` on the root.
+
+```html
+<FuroNumberField
+  :parcel="context.buildNumberFieldParcel()"
+  @change-value="context.onChangeValue({ payload: $event })"
+/>
+```
+
+### `@commit-value`
+
+Emitted on **`blur`** of the inner `<input>` or **`Enter`** (`@keypress.enter`).
+
+```html
+<FuroNumberField
+  :parcel="context.buildNumberFieldParcel()"
+  @commit-value="context.onCommitValue({ payload: $event })"
+/>
+```
+
+### `@update:value`
+
+Emitted whenever **`change-value`** or **`commit-value`** fires, with the raw **`number | null`** (not a payload instance). Intended for **`v-model:value`**.
+
+> **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:** `<FuroNumberField>` **always emits** regardless of validity or range constraints. 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.validatesQuantityRange({
+    payload
+  })
+
+  this.statusReactive.isQuantityInvalid = !isValid
+}
+
+// ❌ Wrong — single positional argument breaks consistency
+onChangeValue (payload) {
+  ...
+}
+```
+
+---
+
+## `NumberFieldEmitPayload` API
+
+The payload object received in **`change-value`** and **`commit-value`** exposes the following members:
+
+| Member                       | Type             | Description |
+|------------------------------|------------------|-------------|
+| `.value`                     | `number \| null` | Current numeric value. `null` when empty or cleared. |
+| `.controlElement`            | `HTMLElement \| null` | The inner input from the event detail (`detail.target`). |
+| `.hasEmptyValue()`           | `boolean`        | `true` if `.value` is `null`. |
+| `.hasEnteredValue()`         | `boolean`        | `true` if `.value` is a finite number. |
+| `.extractMinValueAttribute()` | `number \| null` | Parses the **`min`** attribute from `.controlElement`. |
+| `.extractMaxValueAttribute()` | `number \| null` | Parses the **`max`** attribute from `.controlElement`. |
+| `.isGreaterThanOrEqualMin()` | `boolean`        | `true` if `.value` >= parsed `min` attribute (both must be valid numbers). |
+| `.isLessThanOrEqualMax()`    | `boolean`        | `true` if `.value` <= parsed `max` attribute (both must be valid numbers). |
+| `.isWithinRange()`           | `boolean`        | `true` if both `min` and `max` attributes exist, parse as numbers, and the value lies between them (inclusive). Otherwise `false`. |
+
+Range helpers use the **DOM `min` / `max` attributes** on the control (mirrored from `parcel.min` / `parcel.max` on the `<input>`), not free parameters.
+
+```js
+onCommitValue ({
+  payload
+}) {
+  if (payload.hasEmptyValue()) {
+    this.statusReactive.isQuantityInvalid = true
+
+    return
+  }
+
+  this.statusReactive.isQuantityInvalid = !payload.isWithinRange()
+}
+```
+
+---
+
+## `v-model` Support
+
+`v-model:value` is supported as syntactic sugar over `:parcel` value binding + `@update:value`.
+
+```html
+<!-- These two are equivalent -->
+<FuroNumberField v-model:value="context.quantityRef.value" />
+
+<FuroNumberField
+  :parcel="{
+    value: context.quantityRef.value
+  }"
+  @update:value="context.quantityRef.value = $event"
+/>
+```
+
+> A watcher **inside** `<FuroNumberField>` synchronizes `parcel.value` with the internal ref when `parcel.value` changes. No watcher is required in the parent component for that sync.
+
+---
+
+## Controlled vs. Uncontrolled State
+
+`<FuroNumberField>` supports **both modes**:
+
+| Mode         | How                                                                 |
+|--------------|---------------------------------------------------------------------|
+| Controlled   | Pass `:parcel="{ value: ... }"` or `v-model:value`. Internal ref tracks updates from the underlying primitive and from `parcel.value`. |
+| Uncontrolled | Omit `value` in `parcel`. Initial behavior follows the underlying primitive's defaults for missing model value. |
+
+---
+
+## Differences from `<FuroTextField>`
+
+### Structure
+
+`<FuroTextField>` renders a single `<input>` element. `<FuroNumberField>` renders a composite structure:
+
+```
+[root]
+  ├── [decrement part]   ← stepper button (–), optional `decrement` slot
+  ├── [input part]       ← formatted input (`as-child` → native `<input>`)
+  └── [increment part]   ← stepper button (+), optional `increment` slot
+```
+
+### `type` attribute
+
+`<FuroTextField>` renders `type="text"`. `<FuroNumberField>` does not rely on `type="number"` — it uses the underlying primitive's spinbutton pattern (`role="spinbutton"`), which is accessible and locale-aware.
+
+### CSS class
+
+`.unit-form-control.number` instead of `.unit-form-control.text`.
+
+### `parcel.value` type
+
+| Component             | `parcel.value` type        |
+|-----------------------|----------------------------|
+| `<FuroTextField>`     | `string \| number \| null` |
+| `<FuroPasswordField>` | `string \| null`           |
+| `<FuroNumberField>`   | `number \| null`           |
+
+Number fields only accept `number | null`. String values are not accepted.
+
+### EmitPayload API
+
+| Component             | EmitPayload class           | Value type       | Key methods (examples) |
+|-----------------------|-----------------------------|------------------|-------------------------|
+| `<FuroTextField>`     | `TextFieldEmitPayload`      | `string \| null` | `.hasEmptyText()`, `.hasEmptyTrimmedText()`, … |
+| `<FuroPasswordField>` | `PasswordFieldEmitPayload`  | `string \| null` | `.hasEmptyText()`, `.hasEmptyTrimmedText()`, … |
+| `<FuroNumberField>`   | `NumberFieldEmitPayload`    | `number \| null` | `.hasEmptyValue()`, `.hasEnteredValue()`, `.isWithinRange()`, … |
+
+### Class naming
+
+All class and type names are prefixed with `Number` instead of `Text`:
+
+| Role            | `FuroTextField`          | `FuroNumberField`            |
+|-----------------|--------------------------|------------------------------|
+| Component       | `FuroTextField`          | `FuroNumberField`            |
+| Context         | `FuroTextFieldContext`   | `FuroNumberFieldContext`     |
+| EmitPayload     | `TextFieldEmitPayload`   | `NumberFieldEmitPayload`     |
+| Parcel typedef  | `FuroTextFieldParcel`    | `FuroNumberFieldParcel`      |
+
+---
+
+## Example
+
+### Basic usage
+
+```html
+<FuroNumberField
+  :parcel="{
+    value: context.statusReactive.quantity,
+    invalid: context.statusReactive.isQuantityInvalid,
+    min: 1,
+    max: 999,
+    step: 1,
+  }"
+  placeholder="1–999"
+  name="quantity"
+  @commit-value="context.onCommitValue({ payload: $event })"
+/>
+```
+
+```js
+onCommitValue ({
+  payload
+}) {
+  if (payload.hasEmptyValue()) {
+    this.statusReactive.isQuantityInvalid = true
+
+    return
+  }
+
+  this.statusReactive.isQuantityInvalid = !payload.isWithinRange()
+}
+```
+
+---
+
+### Currency input
+
+```html
+<FuroNumberField
+  :parcel="{
+    value: context.priceRef.value,
+    invalid: context.statusReactive.isPriceInvalid,
+    min: 0,
+    step: 0.01,
+    locale: 'en-US',
+    formatOptions: {
+      style: 'currency',
+      currency: 'USD',
+    },
+  }"
+  name="price"
+  @change-value="context.onChangeValue({ payload: $event })"
+  @commit-value="context.onCommitValue({ payload: $event })"
+/>
+```
+
+---
+
+### Percentage input
+
+```html
+<FuroNumberField
+  :parcel="{
+    value: context.rateRef.value,
+    invalid: context.statusReactive.isRateInvalid,
+    min: 0,
+    max: 1,
+    step: 0.01,
+    formatOptions: {
+      style: 'percent',
+    },
+  }"
+  name="rate"
+  @commit-value="context.onCommitValue({ payload: $event })"
+/>
+```
+
+---

package/docs/furo-pagination.md

@@ -0,0 +1,101 @@
+# FuroPagination
+
+Molecule — page navigation built on a headless pagination primitive
+(`Root` + `Prev` + `List` + `ListItem` + `Ellipsis` + `Next`). Derives the page
+range, ellipsis gaps, and prev/next disabled bounds from the record count, and
+emits the selected page. Domain-agnostic: no GraphQL, router, or Nuxt imports —
+the consumer wires the emitted page to its own routing or fetching.
+
+Location: `lib/components/molecules/FuroPagination/`
+
+## Props
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `parcel` | `FuroPaginationParcel \| null` | `null` | Reactive behavior object (below) |
+
+### `parcel`
+
+| Key | Type | Default | Notes |
+|-----|------|---------|-------|
+| `page` | `number \| null` | `null` | Controlled current page (1-based). When set, the parent owns the page. When omitted, the component manages its own page. |
+| `offset` | `number \| null` | `null` | Controlled current page expressed as a zero-based record offset (offset/limit-style state, e.g. GraphQL). The page is derived via `floor(offset / limit) + 1`. When both `page` and `offset` are set and they disagree (`offset !== (page - 1) * limit`), development throws and production lets `page` win. Provide only one. |
+| `limit` | `number` | `20` | Records per page. Combined with `totalRecords` to compute the page count. |
+| `totalRecords` | `number` | `0` | Total record count across all pages. |
+| `siblingCount` | `number` | `2` | Pages shown on each side of the current page before collapsing into an ellipsis. |
+| `showEdges` | `boolean` | `true` | When `true`, the first and last pages stay pinned with ellipsis gaps. `false` renders a plain contiguous range. |
+| `disabled` | `boolean` | `false` | Disables the whole control. |
+
+## Events
+
+| Event | Payload | When |
+|-------|---------|------|
+| `update:page` | `number` | Selected page changed — enables `v-model:page`. |
+| `page:change` | `{ page: number, offset: number, limit: number }` | Selected page changed. `offset` (`(page - 1) * limit`) and `limit` are provided so offset/limit data sources (e.g. GraphQL pagination) can use the payload directly. |
+
+## Slots
+
+| Slot | Purpose |
+|------|---------|
+| `previous` | Content of the previous-page button (defaults to a left-caret icon). |
+| `next` | Content of the next-page button (defaults to a right-caret icon). |
+| `ellipsis` | Content of the gap marker (defaults to a three-dots icon). |
+| `page` | Custom content for each page entry, receiving `{ page }`. Rendered via `as-child`, so the slot may supply an anchor (`<a :href>`) for SEO — the click still drives `page:change`. When omitted, each page renders as a plain button labeled with the page number. |
+
+## Usage
+
+### Uncontrolled
+
+```vue
+<FuroPagination
+  :parcel="{ limit: 10, totalRecords: 240 }"
+  @page:change="onPageChange($event.page)"
+/>
+```
+
+### Controlled (`v-model:page`)
+
+```vue
+<FuroPagination
+  :parcel="{ page: currentPage, limit: 10, totalRecords: 240 }"
+  @page:change="currentPage = $event.page"
+/>
+```
+
+### Offset / limit data source (e.g. GraphQL)
+
+```vue
+<FuroPagination
+  :parcel="{ page: currentPage, limit, totalRecords }"
+  @page:change="fetchRecords({ offset: $event.offset, limit: $event.limit })"
+/>
+```
+
+### Controlled by offset (offset-only state)
+
+When the parent holds its pagination state purely as `offset` (no page number),
+feed `offset` in and read it back from the payload:
+
+```vue
+<FuroPagination
+  :parcel="{ offset: pagination.offset, limit: pagination.limit, totalRecords }"
+  @page:change="pagination.offset = $event.offset"
+/>
+```
+
+### Link items (SEO anchors)
+
+```vue
+<FuroPagination :parcel="{ limit: 10, totalRecords: 240 }">
+  <template #page="{ page }">
+    <a :href="`/articles?page=${page}`">{{ page }}</a>
+  </template>
+</FuroPagination>
+```
+
+## Notes
+
+- The current page is marked with `data-selected` for styling; the previous/next
+  buttons are auto-disabled at the first/last page.
+- Root CSS class: `unit-pagination` (inside `@layer furo`). The `disabled`
+  modifier class is applied when the control is disabled.

package/docs/furo-password-field.md

@@ -0,0 +1,75 @@
+# `<FuroPasswordField>` Interface Specification
+
+`<FuroPasswordField>` follows the same architecture as [`<FuroTextField>`](https://chiho-internal.openreach.tech/documents/7762). Read that document first — this page only lists the differences.
+
+---
+
+## Differences from `<FuroTextField>`
+
+### `type` attribute
+
+Always renders `type="password"`. The `type` fallthrough attribute is excluded.
+
+### CSS class
+
+`.unit-form-control.password` instead of `.unit-form-control.text`.
+
+### `parcel.value` type
+
+| Component           | `parcel.value` type       |
+|---------------------|---------------------------|
+| `<FuroTextField>`   | `string \| number \| null` |
+| `<FuroPasswordField>` | `string \| null`         |
+
+Password fields do not accept `number` values.
+
+### Class naming
+
+All class and type names are prefixed with `Password` instead of `Text`:
+
+| Role          | `FuroTextField`          | `FuroPasswordField`            |
+|---------------|--------------------------|--------------------------------|
+| Component     | `FuroTextField`          | `FuroPasswordField`            |
+| Context       | `FuroTextFieldContext`   | `FuroPasswordFieldContext`     |
+| EmitPayload   | `TextFieldEmitPayload`   | `PasswordFieldEmitPayload`     |
+| Parcel typedef | `FuroTextFieldParcel`   | `FuroPasswordFieldParcel`      |
+
+### `PasswordFieldEmitPayload`
+
+`PasswordFieldEmitPayload` extends [`BaseEmitPayload`](../lib/emit-payload/BaseEmitPayload.js) with no additional members beyond the shared text-field helpers. The API (`.value`, `.extractTrimmedValue()`, `.hasEmptyText()`, `.hasEnteredTrimmedText()`, etc.) matches [`TextFieldEmitPayload`](./furo-text-field.md#textfieldemitpayload-api), which also extends `BaseEmitPayload`.
+
+---
+
+## Example
+
+```html
+<FuroPasswordField
+  :parcel="{
+    value: null,
+    invalid: context.statusReactive.isPasswordInvalid,
+  }"
+  :required="true"
+  placeholder="Enter your password"
+  name="password"
+  autocomplete="current-password"
+  @commit-value="context.onCommitValue({
+    payload: $event
+  })"
+/>
+```
+
+```js
+onCommitValue ({
+  payload
+}) {
+  if (payload.hasEmptyTrimmedText()) {
+    this.statusReactive.isPasswordInvalid = true
+
+    return
+  }
+
+  this.statusReactive.isPasswordInvalid = !this.validatesPasswordLength({ payload })
+}
+```
+
+---

package/docs/furo-popover.md

@@ -0,0 +1,114 @@
+# FuroPopover
+
+Click-triggered overlay anchored to a trigger element — inline cell / field edit surfaces, action panels, and detail popouts. Built on a headless popover primitive that handles positioning, focus management, and dismissal (outside click, Escape). Unlike a tooltip it is click-activated and holds arbitrary interactive content, and it reacts only to open-state changes.
+
+## Summary
+
+| Field | Value |
+|---|---|
+| **Layer** | Molecule |
+| **Path** | `lib/components/molecules/FuroPopover/` |
+| **Base primitive** | Headless popover (`Root` + `Trigger` + `Portal` + `Content`) |
+| **Composes** | The trigger slot content plus a portaled content surface |
+| **Emits** | `open:change` |
+| **Controlled** | Optional via `parcel.open` |
+
+---
+
+## Public API
+
+### Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `parcel` | `PopoverParcel \| null` | `null` | Reactive data object holding positioning, disabled, modal, and optional controlled open state. |
+
+### Parcel keys
+
+| Key | Type | Default | Description |
+|---|---|---|---|
+| `side` | `'top' \| 'right' \| 'bottom' \| 'left'` | `'bottom'` | Edge of the trigger the content prefers. |
+| `align` | `'start' \| 'center' \| 'end'` | `'center'` | Alignment along the chosen side. |
+| `sideOffset` | `number` | `4` | Gap in pixels between trigger and content. |
+| `disabled` | `boolean` | `false` | When `true`, the trigger never opens the popover. |
+| `modal` | `boolean` | `false` | When `true`, focus is trapped and interaction outside the content is blocked while open. |
+| `open` | `boolean \| null` | `null` | When set (non-null), open state is controlled by the consumer; otherwise the component manages it internally. |
+
+### Emits
+
+| Event | Payload | Description |
+|---|---|---|
+| `open:change` | `{ open: boolean }` | Fired whenever the open state changes (trigger click, outside click, or Escape). |
+
+### Slots
+
+| Slot | Description |
+|---|---|
+| `trigger` | The element the popover is anchored to. Focusable by default (rendered as a button). |
+| `content` | The popover body. Holds arbitrary interactive content. |
+
+---
+
+## Behavior
+
+| Concern | Behavior |
+|---|---|
+| **Open trigger** | Clicking (or activating via keyboard) the trigger toggles the popover. |
+| **Controlled / uncontrolled** | When `parcel.open` is non-null, the consumer owns the state; otherwise an internal ref tracks it. Either way `open:change` fires. |
+| **Disabled** | `parcel.disabled` forwards to the trigger so it never opens the popover. |
+| **Modal** | `parcel.modal` traps focus inside the content and blocks outside interaction while open. |
+| **Positioning** | `side` / `align` / `sideOffset` bind to the portaled content surface; the primitive flips to stay in view. |
+| **Dismissal** | Outside click and Escape close the popover; focus returns to the trigger. |
+| **Motion** | Content fades + zooms (95% → 100%) on open, anchored to the trigger via the primitive's transform-origin, and fades out on close, then stays hidden (`animation-fill-mode: forwards` ending in `visibility: hidden`) so a closed node that outlives the primitive's unmount is neither drawn nor clickable. Disabled under `prefers-reduced-motion: reduce`. |
+| **Passthrough** | Extra attributes fall through to the trigger (`inheritAttrs: false` + `v-bind="$attrs"`), so consumers can pass `as-child` / `as` to wrap non-button content. |
+
+---
+
+## Usage
+
+```vue
+<!-- Inline field edit -->
+<FuroPopover :parcel="{ side: 'bottom' }">
+  <template #trigger>
+    <FuroButton :parcel="{ label: 'Edit' }" />
+  </template>
+  <template #content>
+    <FuroTextField v-model:value="draft.name" :parcel="draft" />
+  </template>
+</FuroPopover>
+
+<!-- Controlled open state -->
+<FuroPopover
+  :parcel="{ open: context.statusReactive.isEditOpen }"
+  @open:change="context.onOpenChange({ payload: $event })"
+>
+  <template #trigger>
+    <FuroButton :parcel="{ label: 'Open' }" />
+  </template>
+  <template #content>
+    Panel body
+  </template>
+</FuroPopover>
+```
+
+---
+
+## Composition notes
+
+- Imports nothing from the app — no GraphQL, PrimeVue, Vue Router, or Nuxt-specific imports.
+- Public parcel keys are value-oriented; none expose the underlying primitive's API.
+- All logic lives in `FuroPopoverContext`: boolean methods (`isOpenControlled()`, `isDisabled()`, `isModal()`), the positioning extractor (`extractContentAttributes()`), and the open-state resolver/handler (`extractOpenValue()`, `onOpenChange()`).
+- CSS is wrapped in `@layer furo`; dimensions use `rem` and reference only semantic tokens. The surface uses `--color-background` / `--color-border` / `--color-text` so it stays readable against either theme.
+
+---
+
+## Testing
+
+- Context logic is fully covered by jsdom unit tests: boolean methods (`isOpenControlled()`, `isDisabled()`, `isModal()`) split into truthy / falsy describe blocks, `extractContentAttributes()` defaults, `extractOpenValue()` (controlled + uncontrolled), and `onOpenChange()` (emits `open:change`, mutates the ref only when uncontrolled).
+- No SFC mount test: behavior is declarative bindings over the tested context plus the headless primitive's own open/dismiss/focus semantics. Rendered output is verified by manual QA in the playground.
+
+---
+
+## Playground
+
+`/samples/components/playground` → **Popover** tab. Demonstrates default (bottom), right-side start-aligned, modal, and disabled popovers.