@openreachtech/furo-vue 1.5.0 → 1.7.0

package/docs/furo-select.md

@@ -0,0 +1,443 @@
+# `<FuroSelect>` Interface Specification
+
+## Overview
+
+`<FuroSelect>` is a select molecule built on a headless select primitive. It follows the same contract style as the field atoms:
+
+- behavior via `parcel` (and a few top-level attribute props)
+- fallthrough attributes merged onto the root where applicable
+- Furo emits (`change-value`, `commit-value`, `update:value`)
+- `v-model:value` support (synced through fallthrough `value` / `@update:value`)
+
+For a select, the selection gesture is the commit point, so `change-value` and `commit-value` fire together with the same payload (honoring the Furo form-control event contract).
+
+Read [`FuroTextField`](./furo-text-field.md) first for the shared `parcel` vs fallthrough mental model and event handler style.
+
+**Source files:**
+
+- `lib/components/molecules/FuroSelect/FuroSelect.vue`
+- `lib/components/molecules/FuroSelect/FuroSelectContext.js`
+- `lib/components/molecules/FuroSelect/SelectEmitPayload.js`
+
+---
+
+## Props
+
+### Rule: `parcel` vs fallthrough vs top-level attributes
+
+| Mechanism | When to use | Bound to |
+| --- | --- | --- |
+| `:parcel` | Furo behavior (`value`, `options`, `invalid`, `loading`, `placeholder`, root props such as `multiple`, `defaultValue`, `disabled`) | The root (via `extractRootAttributes()`) |
+| `triggerParcel` / `portalParcel` / `contentParcel` | Extra attributes for the trigger, portal, or content parts | Matching part |
+| Fallthrough attributes | HTML-like and root attrs (`name`, `required`, `id`, `aria-*`, …) | Merged into the root together with `parcel` |
+
+```html
+<FuroSelect
+  v-model:value="context.territoryRef.value"
+  :parcel="{
+    placeholder: 'Select a territory',
+    options: context.territoryOptions,
+    invalid: context.statusReactive.isInvalidTerritory,
+  }"
+  name="territory"
+  :required="true"
+/>
+```
+
+### Top-level component props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `parcel` | root behavior object or `null` | `null` | Root behavior and Furo fields |
+| `triggerParcel` | trigger attribute object or `null` | `null` | Extra trigger attributes |
+| `portalParcel` | portal attribute object or `null` | `null` | Attributes of the portal the option list renders in, such as `to` or `disabled`. The list renders at `body` by default, so a transformed or clipping ancestor such as `FuroDialog` leaves it in place |
+| `contentParcel` | content attribute object or `null` | `null` | Extra content attributes (`side-offset` defaults to `4` on the component) |
+
+### `parcel` shape (Furo fields)
+
+These keys live on `parcel` (not on a nested `triggerParcel` inside `parcel`):
+
+| Key | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `value` | `string \| number \| object \| null` (an acceptable value) or array when `multiple` | No | `null` | Controlled value; objects are supported — see [Object values](#object-values) |
+| `defaultValue` | same as `value` | No | — | Uncontrolled initial value (root `defaultValue`) |
+| `options` | `Array<FuroSelectOption>` | No | `[]` | Unified list; see [Unified options](#unified-options) |
+| `optionLabel` | `string \| ((option) => string)` | No | uses `option.label` | Key name or function that selects each option's display label; see [Custom option shape](#custom-option-shape) |
+| `optionValue` | `string \| ((option) => value)` | No | uses `option.value` | Key name or function that selects each option's model value — what `update:value` emits and what the bound value matches against; see [Custom option shape](#custom-option-shape) |
+| `invalid` | `boolean` | No | `false` | Invalid visual state + `aria-invalid` on trigger |
+| `loading` | `boolean` | No | `false` | Loading state on trigger (spinner icon); suppresses empty row |
+| `placeholder` | `string` | No | `''` | Passed to the value display |
+| `textDirection` | `toRight` or `toLeft` | No | `toRight` | Maps to the root `dir` (`ltr` / `rtl`) |
+| `multiple` | `boolean` | No | `false` | Multi-select (root); see [Multiple selection](#multiple-selection) |
+| `disabled` | `boolean` | No | `false` | May be set on `parcel` or as fallthrough; forwarded to the root |
+
+Remaining `parcel` keys are forwarded to the root (for example `name`, `required`, `defaultValue`, `multiple`). Furo-specific keys above are consumed by the context/template.
+
+`parcel` values should be JSON-serializable.
+
+#### Object values
+
+An option `value` may be an object, not just a `string` / `number`. The value
+flows through the root unchanged, and the context resolves the matching
+`selectedOption` with deep (`JSON.stringify`) equality in `onChangeValue()`, so
+an object `value` correctly resolves its option, index, and payload.
+
+Caveat: `SelectEmitPayload.matchesOption({ value })` uses strict `===`, so it
+matches object values **by reference only**. When binding objects, compare by a
+stable id/key rather than relying on `matchesOption()` with an object literal.
+
+#### Custom option shape
+
+By default an option renders `option.label` and carries `option.value` as its
+model value. When options do not follow that shape (for example `{ id, name }`),
+map them with `optionLabel` / `optionValue`:
+
+- `optionLabel` — a key name (`'name'`) or a function (`option => option.name`)
+  that selects the **display label** for each option. When unset, `option.label`
+  is used.
+- `optionValue` — a key name (`'id'`) or a function that selects the **model
+  value** — what `update:value` emits and what the bound `value` matches against.
+  When unset, `option.value` (a primitive) is used.
+
+Both keys are backward-compatible: with neither set, behavior is exactly as
+before (`label` = `option.label`, `value` = `option.value`).
+
+```html
+<FuroSelect
+  :parcel="{
+    placeholder: 'Select a member',
+    optionLabel: 'name',
+    optionValue: 'id',
+    options: [
+      { id: 50001, name: 'Ada Lovelace' },
+      { id: 50002, name: 'Alan Turing' },
+    ],
+  }"
+  @change-value="context.onChangeMember({ payload: $event })"
+/>
+```
+
+`textDirection` maps to the root `dir`:
+
+- `toRight` → `ltr`
+- `toLeft` → `rtl`
+
+#### Unified `options`
+
+Applications pass a **single** `parcel.options` array. The component renders either a **group** (group label + child rows) or a **leaf** (option row) per top-level entry.
+
+**Classification (as implemented):** An entry is rendered as a **group** when it has a non-empty `options` array (`shouldShowGroupOption()`). Otherwise it is rendered as a **leaf** row. A group entry **may** include a `value` field (used only for flattening / payload matching, not as a selectable row in the template).
+
+Nested `options` inside a group contain leaf rows only (no nested groups in v1).
+
+**`selectedIndex` / payload matching:** `FuroSelectContext.generateFlattenedOptions()` builds the list used to resolve `selectedOption` and indices. For grouped data it includes the **group header object** as the first entry in each group block, then each child leaf. Flat top-level leaves use `groupIndex: null` and `optionIndex` equal to their index in `parcel.options`.
+
+#### `FuroSelectOption`
+
+| Key | Type | Required | Default |
+| --- | --- | --- | --- |
+| `value` | `string \| number \| object` (an acceptable value) | Yes (leaf) | — |
+| `label` | `string` | Yes | — |
+| `disabled` | `boolean` | No | `false` |
+| `separator` | `boolean` | No | `false` | Renders a separator after the row when `true` |
+| `options` | `Array<FuroSelectOption>` | No | — | When non-empty, entry is treated as a group |
+
+Additional properties are allowed (icons, captions, foreign keys) as long as the whole `parcel` stays JSON-serializable. Preserve full option objects for slots and `SelectEmitPayload.selectedOption`.
+
+#### Group entries
+
+Group rows are elements of `parcel.options` with `label` and non-empty `options`:
+
+| Key | Type | Required |
+| --- | --- | --- |
+| `label` | `string` | Yes |
+| `options` | `Array<FuroSelectOption>` | Yes (non-empty for group UI) |
+| `disabled` | `boolean` | No |
+| `value` | `string \| number` | No | Optional; included in flatten list |
+
+#### Disabled precedence
+
+Per-option **effective** disabled on each option row:
+
+- **Leaf row:** `option.disabled` (root `disabled` is on the root)
+- **Grouped child:** `groupChildOption.disabled || group.disabled`
+
+Root / parcel `disabled` disables the whole control via the root.
+
+### Fallthrough attributes
+
+Consumed via `inheritAttrs: false` and merged in `extractRootAttributes()` (`...attrs`, `...parcel`, `dir`, `modelValue`).
+
+Common attributes:
+
+| Attribute | Behavior |
+| --- | --- |
+| `name` | Forwarded to the root |
+| `disabled` | Forwarded to the root |
+| `required` | Forwarded to the root |
+| `id` | Forwarded to the root (not trigger-only) |
+| `aria-label` / `aria-labelledby` / `aria-describedby` | Forwarded to the root |
+| `value` | Watched with `parcel.value` for controlled sync (`v-model:value`) |
+
+Prefer `parcel.placeholder` over a fallthrough `placeholder` (placeholder is read from `parcel` in `extractPlaceholder()`).
+
+---
+
+## Slots
+
+| Slot | Scoped props | Default content |
+| --- | --- | --- |
+| `trigger-content` | — | Value display + trigger icon area |
+| `trigger-text` | — | Inside the value display (optional extra trigger label) |
+| `trigger-icon` | — | Caret icon when not loading |
+| `trigger-loading-icon` | — | Spinner when `parcel.loading` |
+| `content-before` | — | Before scroll up button |
+| `content-after` | — | After scroll down button |
+| `scroll-up-button` | — | Caret up icon |
+| `scroll-down-button` | — | Caret down icon |
+| `group` | `{ group, groupIndex }` | Group label + child options |
+| `group-label` | `{ group, groupIndex }` | Group `label` text |
+| `option` | `{ option, optionIndex, group?, groupIndex? }` | Option text + indicator |
+| `option-text` | `{ option, optionIndex }` | Option `label` |
+| `option-indicator` | `{ option, optionIndex }` | Check icon |
+| `separator` | `{ option, optionIndex }` | Separator when `option.separator` |
+| `empty` | — (no scoped props passed today) | Shown when `hasEmptyOptions()`; default text `No options` |
+
+**Empty / loading:** `hasEmptyOptions()` is true when `options` is empty **and** `loading` is false. While `loading` is true, the trigger shows the loading icon and the empty row is not shown.
+
+---
+
+## Emits
+
+| Event | Payload | When |
+| --- | --- | --- |
+| `change-value` | `SelectEmitPayload` | On selection (root `@update:model-value`) |
+| `commit-value` | `SelectEmitPayload` | Same gesture; selection is the commit point |
+| `update:value` | `value \| Array<value> \| null` | Same gesture; a single value in single mode, the full array of selected values in multiple mode (values reflect `optionValue` when set) |
+
+`@update:open` is not exposed.
+
+### Parent handler style
+
+```js
+onChangeValue ({
+  payload,
+}) {
+  this.statusReactive.isInvalidTerritory = payload.hasEmptyValue()
+}
+```
+
+---
+
+## `SelectEmitPayload` API
+
+`SelectEmitPayload` extends [`BaseEmitPayload`](../lib/emit-payload/BaseEmitPayload.js).
+
+| Member | Type | Description |
+| --- | --- | --- |
+| `value` | `string \| number \| object \| null` | Primary selected value (`selectedOption.value`) |
+| `values` | `Array<string \| number \| object> \| null` | All selected values in multi-select |
+| `controlElement` | `HTMLElement \| null` | Trigger element from custom event `detail.target` |
+| `selectedOption` | `FuroSelectOption \| null` | Matched row from flatten list |
+| `selectedIndex` | `number \| null` | `optionIndex` on matched row |
+| `selectedOptions` | `Array<FuroSelectOption> \| null` | Multi-select matches |
+| `selectedIndices` | `Array<number> \| null` | Multi-select indices |
+| `hasEmptyValue()` | `boolean` | `value === null` |
+| `hasSelectedValue()` | `boolean` | `value !== null` |
+| `matchesOption({ value })` | `boolean` | Strict (`===`) equality with `value`. Matches object values by **reference only** — for object values compare by id/key instead |
+
+Custom event `detail` also includes `selectedGroupIndex` / `selectedGroupIndices` (used internally; not exposed as payload getters today).
+
+---
+
+## `v-model:value` and state handling
+
+```html
+<FuroSelect
+  v-model:value="context.territoryRef.value"
+  :parcel="{ options: context.territoryOptions, placeholder: 'Select a territory' }"
+/>
+```
+
+Equivalent to fallthrough `value` + `@update:value` with internal sync in `setupComponent()`.
+
+### Controlled vs uncontrolled
+
+| Mode | How |
+| --- | --- |
+| Controlled | `parcel.value` and/or `v-model:value` / fallthrough `value` |
+| Uncontrolled | `parcel.defaultValue` (omit `value`) |
+
+### State matrix
+
+| State | Source |
+| --- | --- |
+| Selected value | `parcel.value` / `v-model:value` / `defaultValue` |
+| Whole control `disabled` | `parcel.disabled` or fallthrough `disabled` on root |
+| Row `disabled` | `option.disabled` and/or `group.disabled` |
+| `invalid` | `parcel.invalid` |
+| `placeholder` | `parcel.placeholder` |
+| `options` | `parcel.options` |
+| `loading` | `parcel.loading` (trigger UI; hides empty state) |
+
+### Multiple selection
+
+Set `parcel.multiple: true`. Use array `defaultValue` / internal value. `change-value` exposes `payload.value` as the **first** selected value; use `payload.values` / `payload.selectedOptions` for the full set. `update:value` now reliably emits the **full array** of selected values, and the selection **persists across re-open** (previously it emitted only a single value). In single mode `update:value` emits a single value.
+
+---
+
+## Internal structure
+
+### Underlying primitive and Furo option naming
+
+The underlying headless select primitive uses item/group terminology. Furo’s public API uses **`option`** (slot and `parcel.options`); the component maps options to the primitive's item rows internally.
+
+### Composition
+
+```text
+div.unit-form-control.select
+  root
+    trigger(.trigger)
+      slot trigger-content → value display + icon
+    portal
+      content(.unit-select-content)
+        slot content-before
+        scroll-up-button
+        viewport(.viewport)
+          group* / option*   # group vs leaf from parcel.options
+          optional empty option
+        scroll-down-button
+        slot content-after
+```
+
+Use `data-*` states in styles: `data-placeholder`, `data-disabled`, `data-highlighted`, etc.
+
+---
+
+## Accessibility requirements
+
+- Trigger remains a semantic `button`.
+- Provide a visible label (`label` + `for` / `id`, or `aria-label` / `aria-labelledby`).
+- `aria-invalid` is set on the trigger from `parcel.invalid`.
+- Keyboard / focus behavior is delegated to the underlying primitive.
+- Forward `name` and `required` on root for form integration.
+
+---
+
+## Styling convention
+
+Inside the SFC, styles use `@layer furo`:
+
+- Root wrapper: `.unit-form-control.select`
+- Trigger: `.trigger` (invalid `.invalid`, loading `.loading`)
+- Dropdown: `.unit-select-content`, `.viewport`, `.group`, `.option`, `.separator`
+- Tokens align with other field atoms (`--color-input`, `--size-input-height`, etc.)
+- Option rows take their minimum height from `--size-option-height`
+
+---
+
+## Examples
+
+### Basic (controlled)
+
+```html
+<FuroSelect
+  :parcel="{
+    value: context.statusReactive.territory,
+    invalid: context.statusReactive.isInvalidTerritory,
+    placeholder: 'Select a territory',
+    options: [
+      { value: 'JP', label: 'Japan' },
+      { value: 'VN', label: 'Vietnam' },
+      { value: 'TW', label: 'Taiwan' },
+      { value: 'US', label: 'United States' },
+    ],
+  }"
+  name="territory"
+  :required="true"
+  @change-value="context.onChangeTerritory({ payload: $event })"
+/>
+```
+
+### Grouped options
+
+```html
+<FuroSelect
+  :parcel="{
+    value: context.statusReactive.fruit,
+    placeholder: 'Pick a fruit',
+    options: [
+      {
+        label: 'Citrus',
+        options: [
+          { value: 'orange', label: 'Orange' },
+          { value: 'lemon', label: 'Lemon' },
+        ],
+      },
+      {
+        label: 'Berries',
+        disabled: true,
+        options: [
+          { value: 'strawberry', label: 'Strawberry' },
+          { value: 'blueberry', label: 'Blueberry', disabled: true },
+        ],
+      },
+    ],
+  }"
+/>
+```
+
+### Uncontrolled default
+
+```html
+<FuroSelect
+  name="territory"
+  :parcel="{
+    defaultValue: 'JP',
+    placeholder: 'Select a territory',
+    options: context.territoryOptions,
+  }"
+/>
+```
+
+### Empty slot
+
+```html
+<FuroSelect
+  :parcel="{
+    placeholder: 'Assignee',
+    options: [],
+  }"
+>
+  <template #empty>
+    <span>No assignees available</span>
+  </template>
+</FuroSelect>
+```
+
+### Custom option row
+
+```html
+<FuroSelect
+  :parcel="{
+    placeholder: 'Choose row',
+    options: context.customRowOptions,
+  }"
+>
+  <template #option-text="{ option }">
+    <strong>{{ option.label }}</strong>
+    <small>{{ option.caption }}</small>
+  </template>
+</FuroSelect>
+```
+
+Live samples: `pages/samples/components/playground/FuroSelectPlayground/index.vue`.
+
+---
+
+## Known gaps and follow-ups
+
+- **Multi-select:** `update:value` now emits the full array of selected values and the selection persists across re-open; `payload.value` still surfaces the primary value (use `payload.values` for the full set).
+- **`empty` slot:** typedef allows `{ loading }` but the template does not pass scoped props yet.
+- **Group classification:** spec previously used “no `value` on group”; implementation uses non-empty `options` only.
+- **Open state:** `@update:open` / `open` on `parcel` not exposed.

package/docs/furo-separator.md

@@ -0,0 +1,87 @@
+# FuroSeparator
+
+Presentational divider drawn between sibling content — toolbar groups, menu sections, and section boundaries. Built on a headless separator primitive that handles the correct `role` / `aria-orientation` semantics. It carries no value and emits nothing.
+
+## Summary
+
+| Field | Value |
+|---|---|
+| **Layer** | Molecule |
+| **Path** | `lib/components/molecules/FuroSeparator/` |
+| **Base primitive** | Headless separator (`role="separator"` with `aria-orientation`, or `role="none"` when decorative) |
+| **Composes** | Nothing — a single styled rule |
+| **Emits** | None |
+| **Orientation** | `horizontal` (default) or `vertical` |
+
+---
+
+## Public API
+
+### Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `parcel` | `SeparatorParcel \| null` | `null` | Reactive data object holding orientation and the decorative flag. |
+
+### Parcel keys
+
+| Key | Type | Default | Description |
+|---|---|---|---|
+| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Direction the divider runs. `horizontal` spans the full inline width; `vertical` stretches to the parent's height. |
+| `decorative` | `boolean` | `false` | When `true`, the divider is purely visual and drops the `separator` role so assistive tech ignores it. Use for dividers that repeat content already conveyed by layout. |
+
+### Emits
+
+None. The separator is presentational.
+
+### Slots
+
+None.
+
+---
+
+## Behavior
+
+| Concern | Behavior |
+|---|---|
+| **Orientation** | `parcel.orientation` maps to the `horizontal` / `vertical` root class and to the primitive's `aria-orientation`; no JS branching. |
+| **Semantics** | Non-decorative separators expose `role="separator"`. Decorative separators expose `role="none"` and no orientation semantics. |
+| **Sizing** | Thickness is `--size-thinnest`. Horizontal fills `width: 100%`; vertical uses `align-self: stretch` so it matches a flex row's height. |
+| **Passthrough** | Extra attributes fall through to the rule element (`inheritAttrs: false` + `v-bind="$attrs"`). |
+
+---
+
+## Usage
+
+```vue
+<!-- Horizontal section divider -->
+<FuroSeparator :parcel="{ orientation: 'horizontal' }" />
+
+<!-- Vertical divider between toolbar groups -->
+<div class="toolbar">
+  <FuroButton :parcel="{ label: 'Bold' }" />
+  <FuroSeparator :parcel="{ orientation: 'vertical' }" />
+  <FuroButton :parcel="{ label: 'Link' }" />
+</div>
+```
+
+---
+
+## Composition notes
+
+- Imports nothing from the app — no GraphQL, PrimeVue, Vue Router, or Nuxt-specific imports.
+- All logic lives in `FuroSeparatorContext` as an extract-only getter (`orientation`) and one boolean method (`isDecorative()`).
+- CSS is wrapped in `@layer furo`; dimensions use `rem` / `--size-thinnest` and the rule color references the semantic `--color-border` token only.
+
+---
+
+## Testing
+
+- Context logic (`orientation` getter, `isDecorative()`) is fully covered by jsdom unit tests, with the boolean method split into truthy / falsy describe blocks.
+- No SFC mount test: behavior is declarative bindings over the tested context plus the headless primitive's own semantics. Rendered output (orientation class, role) is verified by manual QA in the playground.
+
+---
+
+## Playground
+
+`/samples/components/playground` → **Separator** tab. Demonstrates horizontal, vertical (between inline items), and decorative dividers.