@openreachtech/furo-vue 1.5.0 → 1.7.0

package/docs/furo-date-picker.md

@@ -0,0 +1,270 @@
+# FuroDatePicker
+
+Single-date molecule built on a headless date-picker primitive. Features an inline date field (segments for month/day/year) plus a calendar popover with dropdown selects for month and year navigation, the usual date-of-birth picker pattern.
+
+## Summary
+
+| Field | Value |
+|---|---|
+| **Layer** | Molecule |
+| **Path** | `lib/components/molecules/FuroDatePicker/` |
+| **Base primitive** | Headless date-picker (`Root` + calendar popover) |
+| **Value type** | `YYYY-MM-DD` ISO string or `null` |
+| **Granularity** | `day` (date-only; no time) |
+| **Timezone** | Configurable via `timezone` parcel key (default: timezone-naive) |
+| **Calendar nav** | Dropdown selects for month and year (+ Prev/Next buttons) |
+
+---
+
+## Public API
+
+### Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `parcel` | `DatePickerParcel \| null` | `null` | Reactive data object. Furo-only keys are stripped before passthrough to the underlying primitive. |
+| `triggerParcel` | `Record<string, unknown> \| null` | `null` | Passed to the date field / trigger via v-bind. |
+| `contentParcel` | `Record<string, unknown> \| null` | `null` | Passed to the popover content via v-bind. |
+
+### Parcel keys
+
+| Key | Type | Description |
+|---|---|---|
+| `value` | `string \| null` | Currently selected date as `YYYY-MM-DD` or `null`. |
+| `invalid` | `boolean` | Shows error chrome and sets `aria-invalid`. |
+| `placeholder` | `string \| null` | Placeholder text for the date field. |
+| `disabled` | `boolean` | Disables all interaction. |
+| `minValue` | `string \| null` | Minimum selectable date (`YYYY-MM-DD`). Earlier dates are non-interactive. |
+| `maxValue` | `string \| null` | Maximum selectable date (`YYYY-MM-DD`). Later dates are non-interactive. |
+| `displayFormat` | `string \| null` | Reserved for v1.1 localized display format (not yet applied). |
+| `timezone` | `string \| null` | IANA timezone identifier (e.g. `'Asia/Tokyo'`, `'UTC'`). When set, `Date` object inputs are interpreted in this timezone before normalization. Has no effect when `value` is a `YYYY-MM-DD` string (already date-only). Defaults to `null` (timezone-naive: uses local date parts). |
+| `closeOnSelect` | `boolean \| null` | Whether the popover closes when a date is selected. Defaults to `true`. `FuroDateTimePicker` passes `false` to keep the popover open for time selection. |
+| `locale` | `string \| null` | Locale that drives the date field's segment **order** (e.g. `dd/mm/yyyy` vs `mm/dd/yyyy`). Defaults to the browser locale (`navigator.language`), falling back to `'en'` outside the browser. Filled day/month segments are always shown 2-digit regardless of locale (see `formatSegmentValue`). |
+| `preventDeselect` | `boolean \| null` | When `true` (default), re-selecting the already-selected date **keeps** it instead of clearing it. Pass `false` to restore the toggle-off behavior. |
+| `todayButtonText` | `string \| null` | Label for the footer **Today** button. Defaults to `'Today'`; pass `null` to hide the button. |
+| `clearButtonText` | `string \| null` | Label for the footer **Clear** button. Defaults to `'Clear'`; pass `null` to hide the button. |
+
+All parcel keys above are **Furo-only** — they are stripped before the v-bind spread onto the root. Pass additional primitive props via `parcel` to forward them.
+
+### Emits
+
+| Event | Payload | Description |
+|---|---|---|
+| `change-value` | `DatePickerEmitPayload` | Fired when the user selects a date. |
+| `commit-value` | `DatePickerEmitPayload` | Fired on the same selection event (single-date close-on-select UX). |
+| `update:value` | `string \| null` | ISO `YYYY-MM-DD` string or `null`. Suitable for `v-model:value`. |
+
+### Slots
+
+| Slot | Description |
+|---|---|
+| `trigger-icon` | Replaces the default calendar icon inside the trigger. |
+| `prev-icon` | Replaces the left-arrow icon in the calendar header. |
+| `next-icon` | Replaces the right-arrow icon in the calendar header. |
+| `field-suffix` | Renders custom content inside the trigger field, after the date segments and before the trigger icon. A no-op when empty. Used by `FuroDateTimePicker` to host an inline, directly-editable time field in the closed field. |
+| `content-footer` | Renders custom content inside the popover, below the calendar. A no-op when empty. Used by `FuroDateTimePicker` to inject a time field into the same popover. |
+
+---
+
+## Usage
+
+### Basic
+
+```vue
+<FuroDatePicker
+  :parcel="{ placeholder: 'Pick a date' }"
+  @update:value="onValueChange"
+/>
+```
+
+### v-model binding
+
+```vue
+<FuroDatePicker
+  v-model:value="selectedDate"
+  :parcel="{ placeholder: 'Pick a date' }"
+/>
+```
+
+### Min / Max constraints
+
+```vue
+<FuroDatePicker
+  :parcel="{
+    placeholder: 'Booking date',
+    minValue: '2024-06-01',
+    maxValue: '2024-12-31',
+  }"
+  @update:value="onValueChange"
+/>
+```
+
+When no value is set, the calendar view and the date segment placeholders default to **today clamped into `[minValue, maxValue]`** (`resolveCalendarPlaceholder()`). This keeps the year segment within the allowed range when bounds are set but today falls outside them — otherwise the year segment would render blank.
+
+### Invalid state
+
+```vue
+<FuroDatePicker
+  :parcel="{
+    placeholder: 'Required field',
+    invalid: isFieldInvalid,
+  }"
+/>
+```
+
+### Disabled state
+
+```vue
+<FuroDatePicker
+  :parcel="{
+    placeholder: 'Not editable',
+    disabled: true,
+  }"
+/>
+```
+
+### Japan Standard Time (CloudLink spec)
+
+When the consumer always operates in JST (UTC+9) — e.g. CloudLink CRM — pass `timezone: 'Asia/Tokyo'`
+so that `Date` object inputs (which are UTC-based internally) are interpreted on the correct calendar day.
+
+```vue
+<!-- String value: already date-only, timezone has no effect -->
+<FuroDatePicker
+  :parcel="{
+    value: '2024-01-15',
+    timezone: 'Asia/Tokyo',
+    placeholder: 'Select date',
+  }"
+  @update:value="onValueChange"
+/>
+
+<!-- Date object: extracted in JST before normalization -->
+<!-- new Date('2024-01-14T15:30:00Z') → JST 2024-01-15 00:30 → shown as 2024-01-15 -->
+<FuroDatePicker
+  :parcel="{
+    value: utcDateObject,
+    timezone: 'Asia/Tokyo',
+    placeholder: 'Select date',
+  }"
+  @update:value="onValueChange"
+/>
+```
+
+The emitted `update:value` is always a `YYYY-MM-DD` string (date-only). The timezone only affects how incoming `Date` objects are mapped to a calendar day.
+
+---
+
+## Value contract
+
+| Concern | Decision |
+|---|---|
+| Wire format | `YYYY-MM-DD` string — context accepts `Date` objects and `CalendarDate` at boundary and normalizes |
+| Timezone | Configurable via `parcel.timezone` (IANA string). When `null` (default), `Date` objects use local date parts. When set, date parts are extracted via `Intl.DateTimeFormat` in that timezone. YYYY-MM-DD string inputs are always timezone-neutral. |
+| Range | Single-date only; range support deferred to v2 |
+| Clear | Pass `null` to `parcel.value` to clear the field programmatically |
+
+---
+
+## CSS classes
+
+```text
+Field (inline date input)
+  .unit-form-control.date-picker                  ← host div
+  .unit-form-control.date-picker > .field         ← date field
+  .unit-form-control.date-picker > .field.invalid ← invalid state
+  .unit-form-control.date-picker > .field.disabled ← disabled state
+  .unit-form-control.date-picker > .field > .field-input          ← segment (mm/dd/yyyy)
+  .unit-form-control.date-picker > .field > .field-input[data-placeholder] ← placeholder segment
+  .unit-form-control.date-picker > .field > .field-input[data-focused]     ← keyboard-active segment
+  .unit-form-control.date-picker > .field > .trigger              ← calendar icon button
+
+Popover (portaled)
+  .unit-date-picker-content                       ← popover content
+  .unit-date-picker-content > .calendar           ← calendar
+  .unit-date-picker-content > .calendar-actions          ← Today/Clear footer bar
+  .unit-date-picker-content > .calendar-actions > .calendar-action.today  ← Today button
+  .unit-date-picker-content > .calendar-actions > .calendar-action.clear  ← Clear button
+
+Calendar header
+  .unit-date-picker-content > .calendar > .calendar-header        ← header row
+  .unit-date-picker-content > .calendar > .calendar-header > .calendar-nav-button  ← Prev / Next
+  .unit-date-picker-content > .calendar > .calendar-header > .calendar-caption     ← dropdown wrapper
+  .unit-date-picker-content > .calendar > .calendar-header > .calendar-caption > .caption-select ← month/year <select>
+
+Calendar grid
+  .unit-date-picker-content > .calendar > .calendar-grids         ← grid container
+  .unit-date-picker-content > .calendar > .calendar-grids > .calendar-grid          ← <table>
+  … > .calendar-head-row > .calendar-head-cell                    ← weekday labels
+  … > .calendar-row > .calendar-cell                              ← date cell
+  … > .calendar-row > .calendar-cell > .calendar-cell-trigger     ← date button
+  … > .calendar-cell-trigger[data-selected]                       ← selected date
+  … > .calendar-cell-trigger[data-today]                          ← today (dot indicator)
+  … > .calendar-cell-trigger[data-focused]                        ← keyboard-focused date
+  … > .calendar-cell-trigger[data-disabled]                       ← out-of-range date
+  … > .calendar-cell-trigger[data-outside-view]                   ← adjacent month dates
+```
+
+All CSS is scoped under `@layer furo` and uses semantic tokens only (`--color-*`, `--size-*`, `--font-size-*`).
+
+---
+
+## Context: `FuroDatePickerContext`
+
+`FuroDatePickerContext` (extends `BaseFuroContext`) holds all reactive state and computed logic. The Vue component is a thin template wrapper.
+
+Key methods:
+
+| Method | Description |
+|---|---|
+| `normalizeToCalendarDate({ raw })` | Converts `YYYY-MM-DD` / `Date` / `CalendarDate` / `null` → `CalendarDate \| null`. When `parcel.timezone` is set, delegates `Date` objects to `normalizeDateToCalendarDateInTimezone`. |
+| `normalizeDateToCalendarDate({ raw })` | Converts `Date` → `CalendarDate`. Uses `parcel.timezone` when set; otherwise uses local date parts. |
+| `normalizeDateToCalendarDateInTimezone({ raw, timezone })` | Converts `Date` → `CalendarDate` in a specific IANA timezone via `Intl.DateTimeFormat`. Returns `null` for invalid timezone strings. |
+| `extractDatePartsInTimezone({ raw, timezone })` | Returns `{ year, month, day }` string parts extracted by `Intl.DateTimeFormat` for a given timezone. |
+| `normalizeToIsoString({ calendarDate })` | Converts `CalendarDate \| null` → `YYYY-MM-DD` string or `null` |
+| `normalizeMinValue()` | Returns `CalendarDate` from `parcel.minValue` or `undefined` |
+| `normalizeMaxValue()` | Returns `CalendarDate` from `parcel.maxValue` or `undefined` |
+| `extractRootAttributes()` | Builds the root attribute object (strips Furo-only keys, sets `granularity: 'day'`, `closeOnSelect: true`, injects `placeholder` for calendar nav) |
+| `extractCalendarMonths()` | Returns the 12-month array (`{ value, label }[]`) for the month dropdown |
+| `extractCalendarYears()` | Returns year options (`{ value }[]`) bounded by `minValue`/`maxValue` (defaults: −100 / +50 from today) |
+| `stripFuroParcelKeys()` | Removes `FURO_DATE_PICKER_PARCEL_KEYS` from parcel before spreading to the underlying primitive (includes `timezone`) |
+| `onChangeValue({ calendarDate })` | Handles the primitive's `update:modelValue`; emits all three events |
+| `onPlaceholderChange({ calendarDate })` | Syncs `placeholderRef` when Prev/Next navigation fires `update:placeholder` |
+| `onMonthChange({ changeEvent, currentYear })` | Navigates calendar to selected month; reads value from `HTMLSelectElement` |
+| `onYearChange({ changeEvent, currentMonth })` | Navigates calendar to selected year; reads value from `HTMLSelectElement` |
+| `formatSegmentValue({ part, value })` | Zero-pads filled day/month segments to two digits (`3` → `03`, `5` → `05`); year, placeholders, and literals pass through. The underlying primitive renders filled day/month as single digits, so this restores the 2-digit display. |
+| `resolveCloseOnSelect()` | Resolves `parcel.closeOnSelect` (default `true`) — the popover's close-on-select behavior. |
+| `resolveLocale()` | Resolves `parcel.locale`, defaulting to the browser locale, then `'en'` — drives segment order. |
+| `resolvePreventDeselect()` | Resolves `parcel.preventDeselect` (default `true`) — keeps the date when its cell is re-clicked. |
+| `onSelectToday()` | Footer **Today** button handler — selects today clamped into `[minValue, maxValue]` and emits the change trio. |
+| `onClearValue()` | Footer **Clear** button handler — clears the value and emits the change trio with `null`. |
+
+---
+
+## Files
+
+```text
+lib/components/molecules/FuroDatePicker/
+├── FuroDatePicker.vue               ← component
+├── FuroDatePickerContext.js         ← context
+└── DatePickerEmitPayload.js         ← typed emit payload
+
+pages/samples/components/playground/FuroDatePickerPlayground/
+├── index.vue                        ← playground page
+└── FuroDatePickerPlaygroundContext.js
+
+tests/__tests__/jsdom/lib/components/molecules/FuroDatePicker/
+├── FuroDatePickerContext.js         ← context tests
+└── DatePickerEmitPayload.js         ← payload tests
+```
+
+---
+
+## Out of scope (v1)
+
+- Time segments (`FuroTimeField` — Story 1.4)
+- Combined datetime molecule (`FuroDateTimePicker` — Story 1.5)
+- Date range / dual-calendar picker
+- CRM adapter wiring
+- Today/Clear localized button bar
+- i18n locale packs (format string is prop-only v1)

package/docs/furo-date-time-picker.md

@@ -0,0 +1,110 @@
+# FuroDateTimePicker
+
+Combined date + time form control. Composes `FuroDatePicker` (calendar) and `FuroTimeField` (segmented time) into a **single popover** and exposes one combined `v-model:value` as a canonical `YYYY-MM-DDTHH:MM:SS` string. Intended as the `datetime` field editor for the consumer-built ListView / DetailView / FormSequence templates (in `crm-kit-frontend`).
+
+The molecule renders `FuroDatePicker` and injects `FuroTimeField` into the date picker's `content-footer` slot, so the calendar stays single-sourced — there is no duplicated calendar logic.
+
+## Summary
+
+| Field | Value |
+|---|---|
+| **Layer** | Molecule |
+| **Path** | `lib/components/molecules/FuroDateTimePicker/` |
+| **Composes** | `FuroDatePicker` + `FuroTimeField` (the time field is injected into the calendar popover) |
+| **Value type** | `YYYY-MM-DDTHH:MM:SS` ISO string or `null` |
+| **Wire format** | Always second-precision; seconds default to `00`. `granularity` controls only the visible time segments. |
+| **Timezone** | Naive v1; `timezone` parcel key is forwarded to both atoms (the atoms own `Date` normalization). |
+
+---
+
+## Public API
+
+### Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `parcel` | `DateTimePickerParcel \| null` | `null` | Reactive data object. Molecule-only keys are consumed here and used to derive the child parcels. |
+
+### Parcel keys
+
+| Key | Type | Description |
+|---|---|---|
+| `value` | `string \| null` | Combined value as `YYYY-MM-DDTHH:MM:SS` or `null`. The context splits it into date/time parts and recombines on change. |
+| `invalid` | `boolean` | Shows error chrome and sets `aria-invalid` on the unit shell; also forwarded to both atoms. |
+| `placeholder` | `string \| null` | Placeholder text for the date field. |
+| `disabled` | `boolean` | Disables all interaction. |
+| `minValue` | `string \| null` | Minimum selectable datetime (`YYYY-MM-DDTHH:MM:SS`). See cross-field rule below. |
+| `maxValue` | `string \| null` | Maximum selectable datetime (`YYYY-MM-DDTHH:MM:SS`). See cross-field rule below. |
+| `timezone` | `string \| null` | IANA timezone identifier forwarded to both atoms. Default `null` (timezone-naive). |
+| `granularity` | `'hour' \| 'minute' \| 'second' \| null` | Visible time segments. Does not change the wire format (always second precision). |
+| `step` | `number \| null` | Step amount for the time field's increment/decrement buttons. |
+| `timeFormat` | `number \| null` | `12` or `24`. When unset, the locale default applies. |
+
+Consumer passthrough keys (e.g. `name`) that are not in the list above are forwarded to **both** child atoms unchanged.
+
+### Emits
+
+| Event | Payload | Description |
+|---|---|---|
+| `change-value` | `DateTimePickerEmitPayload` | Fired when either the date or time part changes. |
+| `commit-value` | `DateTimePickerEmitPayload` | Fired on the same change event. |
+| `update:value` | `string \| null` | Combined `YYYY-MM-DDTHH:MM:SS` string. Selecting a date fabricates a default time (`12:00:00`) so a complete value is produced; `null` only while no date is set. Suitable for `v-model:value`. |
+
+`DateTimePickerEmitPayload` exposes `value`, `datePart`, `timePart`, `hasValue()`, and `hasEmptyValue()`.
+
+---
+
+## Value contract
+
+| Concern | Behavior |
+|---|---|
+| **Partial emit** | Selecting a date fabricates a default time of `12:00:00` (UAT decision), so the combined value is complete as soon as a date exists and the popover stays open for the user to refine the time. `null` is emitted only while no date is set. |
+| **Popover stays open on date select** | The molecule sets `closeOnSelect: false` on the date atom, so picking a date keeps the popover open for time selection. (Standalone `FuroDatePicker` still closes on select.) |
+| **Cross-field min/max** | The date range is always enforced. The **minimum time** applies only when the selected date equals the minimum date; the **maximum time** applies only when it equals the maximum date. On any other date the full day is allowed. |
+| **Seconds** | The wire value is always `YYYY-MM-DDTHH:MM:SS` (seconds default `00`). |
+| **Preserve-on-change** | Changing the date keeps the current time part; changing the time keeps the current date part. |
+| **Timezone** | Naive v1: `parcel.timezone` is forwarded to both atoms, which own normalization. |
+
+---
+
+## Usage
+
+```vue
+<FuroDateTimePicker
+  :parcel="{
+    placeholder: 'Pick a date & time',
+    value: scheduledAt,
+    minValue: '2024-06-01T08:00:00',
+    maxValue: '2024-12-31T18:00:00',
+    granularity: 'second',
+  }"
+  @update:value="onScheduledAtChange({ value: $event })"
+/>
+```
+
+---
+
+## Composition notes
+
+- The time field is rendered inside the date picker popover via the additive `content-footer` slot on `FuroDatePicker`. Because the time field lives **inside** the popover content (not outside it), editing the time does not trigger an outside-focus/pointer event and the popover stays open.
+- Picking a date does **not** close the popover (`extractDateParcel()` sets `closeOnSelect: false`), and the molecule fabricates a default time of `12:00:00` on first date selection (`applyDefaultTimeOnDateSelection()`). The user can then refine the time without reopening the popover.
+- Re-selecting the already-selected date keeps it (the date atom defaults to `preventDeselect: true`). The atom's footer **Today** / **Clear** buttons and their `todayButtonText` / `clearButtonText` labels pass through the molecule unchanged — **Today** sets the date (and fabricates the noon default), **Clear** resets **both** the date and time parts to `null` (clearing the date with `preventDeselect` on clears the time too — `syncTimeWithDateSelection()`).
+- On open, the calendar is auto-focused by the underlying popover primitive. The molecule forces the date picker into **modal** mode (`extractDateParcel()` sets `modal: true`), so the popover traps focus (the underlying popover primitive's focus scope). Tab then cycles within the popover — calendar → footer time field — instead of escaping to the inline time field in the trigger (the teleported popover sits late in the DOM, so without trapping the focus order is wrong).
+- The trigger field carries a **directly editable** time field: the molecule injects a `FuroTimeField` into `FuroDatePicker`'s `field-suffix` slot, beside the date segments. Users can type the time inline without opening the popover, and the calendar icon still opens the picker for date selection. The inline copy is styled borderless with its steppers hidden so it blends into the single trigger field; the full stepper version lives in the popover footer.
+- The inline field (trigger) and the footer field (popover) are **two views of the same time part**: both bind `value` to `timePart` via `extractTimeParcel()` and route edits through `onTimeChange()`, so editing either keeps both — and the combined `v-model:value` — in sync.
+- Stepping the time before a date is chosen no longer resets itself. Because the combined value emits `null` until both parts are set (Q2), the parent's `v-model` echoes `null` back; `syncFromExternalValue()` skips re-splitting when the external value already equals the current parts' combination, preserving the in-progress part.
+- The popover does not shift when the time changes. The date/time fields use `font-variant-numeric: tabular-nums` (equal-width digits), and the popover is **start-aligned** (`align="start"` on the date content) so a width change in the trigger's inline time field never re-centers/moves the popover.
+- The molecule imports the two atoms only — no GraphQL, PrimeVue, Vue Router, or Nuxt-specific imports.
+
+---
+
+## Testing
+
+- Context and payload logic are covered by jsdom unit tests (`splitValue` / `combineValue`, cross-field bounds, preserve-on-change, partial/null emit, parcel derivation).
+- The full popover open-cycle ("open → pick date → edit time inside → combined value updates, popover stays open") is verified by **manual real-browser UAT** in the playground. A full SFC mount is infeasible in jsdom because the composed atoms import the headless primitive's namespaced entry + Nuxt `#components`, which do not resolve under the jest module map; the integration test is therefore a documented partial driving the context through the same handlers the SFC binds.
+
+---
+
+## Playground
+
+`/samples/components/playground` → **Date Time** tab. Demonstrates basic, pre-filled, bounded window (cross-field time), programmatic set/clear, timezone passthrough, disabled, invalid, and the emit trio event log.

package/docs/furo-dialog.md

@@ -0,0 +1,88 @@
+# FuroDialog
+
+Organism — a modal (or non-modal) dialog built on a headless dialog primitive
+(`Root` + `Portal` + `Overlay` + `Content` + `Title` + `Description` + `Close`).
+Composes overlay, focus trap, Esc/overlay-click dismissal, and an accessible
+heading. Domain-agnostic: no GraphQL, router, or Nuxt imports.
+
+Location: `lib/components/organisms/FuroDialog/`
+
+## Props
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `parcel` | `FuroDialogParcel \| null` | `null` | Reactive behavior object (below) |
+
+### `parcel`
+
+| Key | Type | Default | Notes |
+|-----|------|---------|-------|
+| `open` | `boolean` | — | Controlled open state. When set, the parent owns open/close. When omitted, the dialog manages its own state. |
+| `disabled` | `boolean` | `false` | Disables the trigger. |
+| `modal` | `boolean` | `true` | `false` renders without the overlay scrim and keeps the page interactive. |
+| `title` | `string \| null` | `null` | Heading text. Provide a title (or the `title` slot) for accessibility. |
+| `description` | `string \| null` | `null` | Sub-heading text below the title. |
+| `closeText` | `string` | `'Close'` | Accessible label for the built-in close button. |
+| `closeOnOutsideClick` | `boolean` | `true` | `false` ignores overlay / outside-click dismissal — only the close button or an explicit action closes it. |
+| `closeOnEscape` | `boolean` | `true` | `false` ignores the Escape key. |
+| `size` | `'sm' \| 'default' \| 'lg' \| 'fullscreen'` | `'default'` | Content width variant. `fullscreen` fills the viewport. |
+| `busy` | `boolean` | `false` | While `true`, all dismissal (outside / Esc / close button / `close()`) is blocked — use during async work. |
+| `initialFocus` | `string \| null` | `null` | CSS selector (scoped to the dialog content) of the element to focus on open. When unset, the first focusable element is focused. |
+
+## Events
+
+| Event | Payload | When |
+|-------|---------|------|
+| `update:open` | `boolean` | Open state changed — enables `v-model:open`. |
+| `open:change` | `{ open: boolean }` | Open state changed (semantic form). |
+
+## Slots
+
+| Slot | Purpose |
+|------|---------|
+| `trigger` | Optional element that opens the dialog. Rendered as the trigger via `as-child` — supply your own button/element. Omit when the dialog is opened via controlled `open`. |
+| `title` | Overrides the heading (falls back to `parcel.title`). |
+| `description` | Overrides the description (falls back to `parcel.description`). |
+| default | Dialog body content. Receives a `close()` slot prop to dismiss from inside. |
+| `footer` | Footer region (e.g. action buttons). Receives a `close()` slot prop so action buttons can dismiss the dialog (after running their own logic). |
+| `close` | Content of the built-in close button (defaults to `✕`). |
+
+## Usage
+
+### Uncontrolled (own trigger)
+
+```vue
+<FuroDialog :parcel="{ title: 'Delete record', description: 'This cannot be undone.' }">
+  <template #trigger>
+    <button type="button">Delete…</button>
+  </template>
+  <p>The record will be permanently removed.</p>
+  <template #footer>
+    <button type="button">Cancel</button>
+    <button type="button">Delete</button>
+  </template>
+</FuroDialog>
+```
+
+### Controlled (`v-model:open`)
+
+```vue
+<FuroDialog
+  :parcel="{ open: isDialogOpen, title: 'Settings' }"
+  @open:change="isDialogOpen = $event.open"
+>
+  <p>Open state is owned by the parent.</p>
+</FuroDialog>
+```
+
+## Notes
+
+- The dialog content is portaled to the document body; overlay and content carry
+  `unit-dialog-overlay` / `unit-dialog-content` classes inside `@layer furo`.
+- Always provide a title (text or slot) — it is the dialog's accessible name.
+- A description is optional. Without `parcel.description` or a `description` slot the content declares no described-by target, so the headless primitive logs no accessibility warning.
+- By default the built-in close button, Esc key, and overlay click all dismiss the dialog.
+  Set `closeOnOutsideClick` / `closeOnEscape` to `false` to require an explicit close
+  (e.g. a footer action calling the `close()` slot prop).
+- Overlay scrim color is the `--furo-dialog-overlay-background` component token.
+- The built-in close button takes its size from `--size-close-button-medium`.

package/docs/furo-drawer.md

@@ -0,0 +1,122 @@
+# FuroDrawer
+
+Organism — a slide-in panel docked to a viewport edge, built on a headless
+drawer primitive (`Root` + `Portal` + `Overlay` + `Content` + `Handle` +
+`Title` + `Description` + `Close` + `SwipeArea`). Supports swipe-to-dismiss with
+momentum, optional swipe-to-open, snap points for partially-open resting
+positions, modal / focus-trapped non-modal / fully non-modal modes, controlled
+or uncontrolled open state, and built-in Title/Description + Esc handling.
+Domain-agnostic: no GraphQL, router, or Nuxt imports.
+
+Location: `lib/components/organisms/FuroDrawer/`
+
+## Props
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `parcel` | `FuroDrawerParcel \| null` | `null` | Reactive behavior object (below) |
+
+### `parcel`
+
+| Key | Type | Default | Notes |
+|-----|------|---------|-------|
+| `open` | `boolean` | — | Controlled open state. When set, the parent owns open/close. When omitted, the drawer manages its own state. |
+| `disabled` | `boolean` | `false` | Disables the trigger. |
+| `modal` | `boolean \| 'trap-focus'` | `true` | `true`: overlay scrim + focus trap + scroll lock. `'trap-focus'`: focus trapped but the page stays interactive (side-panel mode). `false`: fully non-modal. |
+| `title` | `string \| null` | `null` | Heading text. Provide a title (or the `title` slot) for accessibility. |
+| `description` | `string \| null` | `null` | Sub-heading text below the title. |
+| `closeText` | `string` | `'Close'` | Accessible label for the built-in close button. |
+| `closeOnOutsideClick` | `boolean` | `true` | `false` ignores overlay / outside-click dismissal. |
+| `closeOnEscape` | `boolean` | `true` | `false` ignores the Escape key. |
+| `side` | `'left' \| 'right' \| 'top' \| 'bottom'` | `'right'` | Edge the panel docks to, slides in from, and is swiped toward to dismiss. |
+| `size` | `'sm' \| 'default' \| 'lg' \| 'fullscreen'` | `'default'` | Cross-axis extent: width for `left`/`right`, height for `top`/`bottom`. `fullscreen` fills the docking axis. |
+| `snapPoints` | `Array<number \| string> \| null` | `null` | Preset resting positions: fractions `0–1`, pixels `> 1`, or `'148px'`/`'30rem'` strings. |
+| `activeSnapPoint` | `number \| string \| null` | `null` | Controlled active snap point. When set, the parent owns it (`update:activeSnapPoint`). |
+| `sequentialSnap` | `boolean` | `false` | `true` snaps one point at a time; `false` snaps to the nearest by distance. |
+| `swipeToOpen` | `boolean` | `false` | Renders an edge grab strip so the panel can be swiped open from closed. |
+| `dragHandle` | `boolean` | `false` | Renders a drag handle (grab indicator) on the docked edge. |
+| `busy` | `boolean` | `false` | While `true`, all dismissal (outside / Esc / close button / `close()`) is blocked — use during async work. |
+| `initialFocus` | `string \| null` | `null` | CSS selector (scoped to the drawer content) of the element to focus on open. |
+
+## Events
+
+| Event | Payload | When |
+|-------|---------|------|
+| `update:open` | `boolean` | Open state changed — enables `v-model:open`. |
+| `open:change` | `{ open: boolean }` | Open state changed (semantic form). |
+| `update:activeSnapPoint` | `number \| string \| null` | Active snap point changed — enables `v-model:activeSnapPoint`. |
+| `snap:change` | `{ snapPoint: number \| string \| null }` | Active snap point changed (semantic form). |
+
+## Slots
+
+| Slot | Purpose |
+|------|---------|
+| `trigger` | Optional element that opens the drawer (rendered via `as-child`). Omit when opened via controlled `open` or swipe-to-open. |
+| `title` | Overrides the heading (falls back to `parcel.title`). |
+| `description` | Overrides the description (falls back to `parcel.description`). |
+| default | Drawer body content. Receives a `close()` slot prop to dismiss from inside. |
+| `footer` | Footer region (e.g. action buttons). Receives a `close()` slot prop. |
+| `close` | Content of the built-in close button (defaults to `✕`). |
+
+## Usage
+
+### Uncontrolled (own trigger)
+
+```vue
+<FuroDrawer :parcel="{ side: 'right', title: 'Filters', dragHandle: true }">
+  <template #trigger>
+    <button type="button">Filters…</button>
+  </template>
+  <p>Filter controls go here. Swipe right or press Esc to close.</p>
+  <template #footer="{ close }">
+    <button type="button" @click="close()">Apply</button>
+  </template>
+</FuroDrawer>
+```
+
+### Snap points (bottom sheet)
+
+```vue
+<FuroDrawer
+  :parcel="{
+    side: 'bottom',
+    size: 'fullscreen',
+    dragHandle: true,
+    snapPoints: [0.4, 0.75, 1],
+  }"
+  @snap:change="onSnap($event.snapPoint)"
+>
+  <template #trigger>
+    <button type="button">Open sheet</button>
+  </template>
+  <p>Drag the handle to rest at 40%, 75%, or 100%.</p>
+</FuroDrawer>
+```
+
+### Controlled (`v-model:open`)
+
+```vue
+<FuroDrawer
+  :parcel="{ open: isOpen, side: 'left', title: 'Navigation' }"
+  @open:change="isOpen = $event.open"
+>
+  <p>Open state is owned by the parent.</p>
+</FuroDrawer>
+```
+
+## Notes
+
+- The drawer content is portaled to the document body; overlay and content carry
+  `unit-drawer-overlay` / `unit-drawer-content` classes inside `@layer furo`.
+- Position composes the active snap-point offset (on the docking axis) with the
+  live swipe-drag offset the primitive exposes via CSS variables; enter/exit use
+  the independent `translate` property so they compose with the drag transform.
+  Both are suppressed under `prefers-reduced-motion: reduce`.
+- `size` controls the cross-axis extent only. `fullscreen` fills the docking axis.
+- `'trap-focus'` mode still renders the overlay element but keeps the page
+  interactive; `false` renders no overlay at all.
+- Always provide a title (text or slot) — it is the drawer's accessible name.
+- Overlay scrim reuses the `--furo-dialog-overlay-background` component token.
+- The built-in close button takes its size from `--size-close-button-medium`.
+- Swipe, momentum, and snap behaviors are pointer-driven and require manual
+  browser QA (the playground "Drawer" tab exercises every mode).