@openreachtech/furo-vue 1.5.0 → 1.7.0

package/docs/furo-radio.md

@@ -0,0 +1,125 @@
+# `<FuroRadio>` Interface Specification
+
+## Overview
+
+`<FuroRadio>` is a **shipped** radio atom in the Furo-Vue component system. Its **public contract is Furo-defined**: application developers pass `parcel`, listen to Furo emits, and use documented slots — without importing the underlying primitive library.
+
+Implementation uses a headless radio-group primitive inside `lib/components/atoms/FuroRadio/*` only. That dependency is **not** part of the application API.
+
+Contract style aligns with [`FuroCheckbox`](./furo-checkbox.md) and [`FuroTextField`](./furo-text-field.md):
+
+- behavior via `:parcel` (`FuroRadioParcel`)
+- HTML / form attributes via fallthrough (`name`, `id`, `aria-*`, …)
+- Furo emits (`change-value`, `update:value`)
+- `v-model:value` syncs the chosen option's value
+
+**Public SFC prop:** `parcel` only.
+
+**Model shape:** the **value of the chosen option** (`string | number`), or `null` when nothing is chosen. Unlike `FuroCheckbox`, the model is not a boolean: a radio group answers "which one", not "yes or no".
+
+### One component, not one per button
+
+`FuroRadio` is the whole group, not a single button. A lone radio button is not a usable control — the exclusivity that distinguishes a radio from a checkbox only exists across a set — so the group is the smallest thing worth shipping. Options are declared as data through `parcel.options`, the same way `FuroSelect` declares its choices.
+
+`@change-value` fires on every committed choice.
+
+Read [`FuroTextField`](./furo-text-field.md) for the shared `parcel` mental model.
+
+### Abstraction boundary
+
+| Layer | Responsibility |
+| ----- | -------------- |
+| Application | `parcel`, listeners, slots; controls `parcel.value` |
+| Atom (`FuroRadio`) | Maps parcel → the underlying radio-group primitive; DOM, emits, default indicator |
+| Underlying primitive (maintainers) | Internal only; not part of the application API |
+
+**Rules:**
+
+1. Documented `parcel` keys are the **Furo contract**. Furo-owned keys are stripped in `extractRootAttributes()` before optional passthrough to the underlying primitive.
+2. Do **not** import the underlying radio-group primitive in application code.
+3. An option's own `disabled` is additive to the group's: a group that is disabled disables every option regardless of what each option says.
+
+**Source files:**
+
+- `lib/components/atoms/FuroRadio/FuroRadio.vue`
+- `lib/components/atoms/FuroRadio/FuroRadioContext.js`
+- `lib/components/atoms/FuroRadio/RadioEmitPayload.js`
+
+**Live samples:** `pages/samples/components/playground/FuroRadioPlayground/index.vue`
+
+## Summary
+
+| Field | Value |
+|---|---|
+| **Layer** | Atom |
+| **Path** | `lib/components/atoms/FuroRadio/` |
+| **Base primitive** | Headless radio group (`Root` + option + indicator) |
+| **Value** | `string \| number \| null` via `v-model:value` / `parcel.value` |
+| **Emits** | `change-value`, `update:value` |
+
+## `parcel` keys
+
+| Key | Type | Default | Meaning |
+|---|---|---|---|
+| `value` | `string \| number \| null` | — | The chosen option's value. Supplying this key at all makes the group **controlled**. |
+| `options` | `Array<FuroRadioOption>` | `[]` | The choices to render, in order. |
+| `invalid` | `boolean` | `false` | Renders the error appearance and sets `aria-invalid`. |
+| `disabled` | `boolean` | `false` | Disables every option. |
+| `required` | `boolean` | `false` | Marks the group required. |
+| `size` | `string` | `'1.125rem'` | Diameter of one radio circle. The indicator dot is derived from it. |
+
+### `FuroRadioOption`
+
+| Key | Type | Default | Meaning |
+|---|---|---|---|
+| `label` | `string` | — | Text shown beside the circle. |
+| `value` | `string \| number` | — | The value reported when this option is chosen. |
+| `disabled` | `boolean` | `false` | Withdraws this one option while leaving the rest usable. |
+
+## Controlled and uncontrolled
+
+The group is **controlled** when `parcel` owns a `value` key, even when that key holds `null`. A controlled group never follows its own interaction: it emits, and re-renders only when the parent sends a new `value` back. This is the same rule `FuroCheckbox` follows, so the two controls behave alike when composed in one form.
+
+Omit the key entirely for an **uncontrolled** group, which starts with nothing chosen and then tracks its own state.
+
+## Emits
+
+| Event | Payload | When |
+|---|---|---|
+| `change-value` | `RadioEmitPayload` | The user chooses an option. |
+| `update:value` | `string \| number \| null` | Same moment; this is the `v-model:value` channel. |
+
+### `RadioEmitPayload`
+
+| Member | Returns | Meaning |
+|---|---|---|
+| `value` | `string \| number \| null` | The chosen option's value. |
+| `controlElement` | `HTMLElement \| null` | The group's root element. |
+| `isSelected()` | `boolean` | Whether an option is chosen. A group with nothing chosen reports `false`. |
+
+## Slots
+
+| Slot | Scope | Purpose |
+|---|---|---|
+| `option-label` | `{ option }` | Replaces the default label text for every option, so an application can render a description, a price, or an icon beside the choice. |
+
+## Labels
+
+Each option's circle and text are wrapped in one `<label>`. A `<button>` is a labelable element, so clicking the text activates the option without the component having to mint an `id` per option.
+
+## Styling
+
+| Part | Class | Notes |
+|---|---|---|
+| Group root | `.unit-form-control.radio-group` | Gains `.invalid` and `.disabled`. |
+| One option | `.option` | Gains `.disabled`. |
+| The circle | `.radio` | Carries `data-state="checked"` when chosen. |
+| The dot | `.indicator` | Sized from `--furo-radio-dot-size`. |
+| Label text | `.label` | Only rendered by the default slot content. |
+
+Colour comes from the `--color-selected` family, the role that means "the user chose this". It is deliberately distinct from `--color-primary`, which means "this is the action" and is a dark neutral in the shipped theme. Override `--color-selected` to re-theme every selection control at once.
+
+| Custom property | Default | Meaning |
+|---|---|---|
+| `--furo-radio-size` | `1.125rem` | Diameter of the circle; set from `parcel.size`. |
+| `--furo-radio-dot-size` | `0.5rem` | Diameter of the dot; derived from the circle. |

package/docs/furo-scroll-area.md

@@ -0,0 +1,112 @@
+# FuroScrollArea
+
+Presentational scroll container that wraps overflowing content with a styled, cross-browser scrollbar. Built on a headless scroll-area primitive that hides the native scrollbar and renders a consistent custom one across browsers. It carries no value and emits nothing.
+
+## Summary
+
+| Field | Value |
+|---|---|
+| **Layer** | Molecule |
+| **Path** | `lib/components/molecules/FuroScrollArea/` |
+| **Base primitive** | Headless scroll-area (`Root` + `Viewport` + `Scrollbar` + `Thumb` + `Corner`) |
+| **Composes** | Nothing — a single styled scroll region |
+| **Emits** | None |
+| **Orientation** | `vertical` (default), `horizontal`, or `both` |
+
+---
+
+## Public API
+
+### Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `parcel` | `FuroScrollAreaParcel \| null` | `null` | Reactive data object holding orientation and scrollbar visibility. |
+
+### Parcel keys
+
+| Key | Type | Default | Description |
+|---|---|---|---|
+| `orientation` | `'vertical' \| 'horizontal' \| 'both'` | `'vertical'` | Which scrollbars render, and which axes are scrollable. `both` also renders the corner where they meet. |
+| `scrollbarVisibility` | `'hover' \| 'scroll' \| 'glimpse' \| 'auto' \| 'always'` | unset (`hover`) | **When the scrollbar appears** — it does not affect whether the content scrolls (see Behavior). When unset, the primitive default (`hover`) applies. |
+| `scrollHideDelay` | `number` | unset | Milliseconds before the scrollbar hides after the trigger ends (applies to `hover` / `scroll` / `glimpse`). Forwarded to the primitive. |
+
+#### `scrollbarVisibility` values
+
+| Value | Scrollbar shown |
+|---|---|
+| `hover` (default) | While the pointer is over the scroll area; hides after `scrollHideDelay`. |
+| `scroll` | While scrolling; hides after `scrollHideDelay`. |
+| `glimpse` | Briefly revealed on pointer enter, then hidden. |
+| `auto` | Whenever the axis overflows (native-like overlay), hidden otherwise. |
+| `always` | Always on screen. Best for wide tables / lists where the overflow must be discoverable at a glance. |
+
+### Emits
+
+None. The scroll area is presentational.
+
+### Slots
+
+| Slot | Description |
+|---|---|
+| default | The overflowing content placed inside the scroll viewport. |
+
+---
+
+## Behavior
+
+| Concern | Behavior |
+|---|---|
+| **Orientation** | `parcel.orientation` drives which `Scrollbar` (and `Corner`) renders via `showsVerticalScrollbar()` / `showsHorizontalScrollbar()` / `showsCorner()` — no template branching beyond `v-if`. |
+| **Scrolling vs. visibility** | An axis is scrollable (wheel / touch / keyboard) whenever its scrollbar is rendered — i.e. whenever `orientation` includes that axis. This is **independent of `scrollbarVisibility`**: with the default `hover`, content still scrolls before you hover; only the bar is hidden until you do. An axis not in `orientation` is clipped (`overflow: hidden`) and not scrollable. |
+| **Visibility** | The public `scrollbarVisibility` key maps to the primitive's visibility prop inside `buildOptionalRootAttributes()`; omitted entirely when unset. It changes only *when the bar is shown*, never whether the content scrolls. |
+| **Native scrollbar** | The primitive hides the native scrollbar and renders the styled thumb, so appearance is consistent across browsers. |
+| **Passthrough** | Non-Furo parcel keys (e.g. `scrollHideDelay`, `aria-*`) and extra attributes fall through to the root (`inheritAttrs: false` + `v-bind="$attrs"`). |
+
+---
+
+## Usage
+
+```vue
+<!-- Vertical long list -->
+<FuroScrollArea :parcel="{ orientation: 'vertical' }">
+  <ul>
+    <li v-for="tag in tags" :key="tag">{{ tag }}</li>
+  </ul>
+</FuroScrollArea>
+
+<!-- Wide table row, scrollbar always visible -->
+<FuroScrollArea :parcel="{ orientation: 'horizontal', scrollbarVisibility: 'always' }">
+  <table>...</table>
+</FuroScrollArea>
+
+<!-- Both axes -->
+<FuroScrollArea :parcel="{ orientation: 'both' }">
+  <div class="wide-tall-content">...</div>
+</FuroScrollArea>
+```
+
+The scroll area fills its parent (`width: 100%; height: 100%`). Give the parent a bounded size so content can overflow.
+
+---
+
+## Composition notes
+
+- Imports nothing from the app — no GraphQL, PrimeVue, Vue Router, or Nuxt-specific imports.
+- All logic lives in `FuroScrollAreaContext` as extract-only getters (`orientation`, `scrollbarVisibility`), boolean rendering methods, and the `extractRootClassNames()` / `extractRootAttributes()` mappers.
+- The public `scrollbarVisibility` key is value-oriented; the primitive's own prop name appears only in `buildOptionalRootAttributes()`.
+- CSS is in `@layer furo` and **unscoped**: the underlying viewport is a multi-root (Fragment) component, so a scoped `data-v-*` attribute would not reach its element and the `> .viewport` height rule would not match — collapsing the viewport and breaking scroll. All selectors are namespaced under `.unit-scroll-area`.
+- Dimensions use `rem`; colors reference semantic tokens only (`--color-border` thumb, `--color-ring` on hover). The thumb carries a `::before` that widens its pointer hit-target to ~44px without enlarging the visual bar.
+
+---
+
+## Testing
+
+- Context logic is fully covered by jsdom unit tests: the `orientation` / `scrollbarVisibility` getters, the three boolean rendering methods (split into truthy / falsy describe blocks), `extractRootClassNames()`, and `extractRootAttributes()` (visibility-to-`type` mapping plus passthrough).
+- No SFC mount test: behavior is declarative bindings over the tested context plus the headless primitive's own scroll handling. Rendered scrollbars are verified by manual QA in the playground.
+
+---
+
+## Playground
+
+`/samples/components/playground` → **Scroll Area** tab. Demonstrates a vertical long list, a wide horizontal table row (always-visible scrollbar), and a both-axes grid.

package/docs/furo-search-field.md

@@ -0,0 +1,94 @@
+# `<FuroSearchField>` Interface Specification
+
+## Overview
+
+`<FuroSearchField>` is a **shipped** search field molecule in the Furo-Vue component system. It makes every search entry point in an application look and behave the same: one bordered box holding a leading magnifier and a single-line text control.
+
+It composes the text field atom rather than restyling an input, so the value contract is the one every other field already uses: `parcel` plus `v-model:value`, with `change-value` and `commit-value` carrying the same payload.
+
+**Public SFC prop:** `parcel` only. `class` and `style` land on the wrapper; every other HTML attribute passes through to the inner input.
+
+## Summary
+
+| Field | Value |
+|---|---|
+| **Layer** | Molecule |
+| **Path** | `lib/components/molecules/FuroSearchField/` |
+| **Base primitive** | None; a `div` wrapping the text field atom |
+| **Value** | `string \| number \| null` |
+| **Emits** | `change-value`, `commit-value`, `update:value` |
+| **Composes** | `FuroTextField` for the value, `FuroIcon` for the magnifier |
+
+## Why the attributes split
+
+The wrapper is the box a consumer lays out, so `class` and `style` stay on it: a layout selector such as `.filters .search { flex: 1 }` has to match something with a width. Everything else describes the control, not the box, so `placeholder`, `disabled`, `name`, `aria-label` and the rest reach the inner input untouched. A consumer therefore writes the same attributes they would write on `<FuroTextField>`, and they land where they already expect.
+
+## `parcel` keys
+
+| Key | Type | Default | Meaning |
+|---|---|---|---|
+| `value` | `string \| number \| null` | `null` | The search text. |
+| `invalid` | `boolean` | `false` | Draws the field in its error tone. |
+
+The parcel is deliberately the text field's parcel, minus nothing and plus nothing. A consumer who already knows one field knows this one.
+
+## Events
+
+| Event | Payload | When |
+|---|---|---|
+| `change-value` | Field payload | On every keystroke. |
+| `commit-value` | Field payload | On blur and on Enter. |
+| `update:value` | `string \| null` | Alongside both of the above, which is what makes `v-model:value` work. |
+
+The payload is the same object the text field atom emits, so `payload.value`, `payload.trimmedValue`, `payload.hasEnteredText()` and `payload.hasEnteredTrimmedText()` all read the same as anywhere else. `hasEnteredTrimmedText()` is the one to reach for before firing a query, because a field holding only spaces is an empty search.
+
+## Slots
+
+| Slot | Scope | Purpose |
+|---|---|---|
+| `icon` | — | Replaces the leading mark. Default: a magnifier icon. |
+| `trailing` | — | Content after the control, for a clear button, a shortcut hint, or a result count. |
+
+## States
+
+| State | What changes |
+|---|---|
+| Rest | Border in the input tone, placeholder in the caption tone. |
+| Focus | Border turns the focus-ring tone. The whole wrapper reacts, because focus lands on the control inside it. |
+| Filled | Nothing structural; the text simply reads in the body tone instead of the caption tone. |
+| Invalid | Border turns the destructive tone, and stays destructive while focused. |
+| Disabled | The wrapper dims and takes a not-allowed cursor. |
+
+## Styling
+
+| Part | Class | Notes |
+|---|---|---|
+| Root | `.unit-form-control.search` | Gains `.invalid` and `.disabled` |
+| The leading mark | `.leading` | `aria-hidden`, so the magnifier is not announced |
+| The magnifier | `.leading-icon` | Only rendered by the default slot content |
+| The control | `.unit-form-control.text` | The text field atom, stripped of its own border and padding |
+
+The wrapper draws the border, the radius, the height and the background; the control inside draws only text. That is the one place this molecule reaches into the atom it composes, and it is unavoidable: a shared box around an icon and an input cannot have two borders.
+
+## Read from the design
+
+| Part | Design value | Token |
+|---|---|---|
+| The box | `#ffffff` | `--color-background` |
+| Its border | `1px` `#c4c7cf` | `--size-thinnest`, `--color-input` |
+| Its border, focused | `#3b82f6` | `--color-ring` |
+| Its corners | `8px` | `--size-border-radius-medium` |
+| Its height | `32px` | `--size-input-height` |
+| Between the mark and the text | `8px` | `--size-space-small` |
+| Its inline padding | `12px` | `0.75rem` |
+| The magnifier | `16px`, `#8b93a2` | `1rem`, `--color-foreground-glyph` |
+| The placeholder | `#8b93a2`, regular 13.5px/20 | `--color-foreground-tertiary`, `--font-body-medium` |
+| The entered text | `#424752`, regular 13.5px/20 | `--color-foreground`, `--font-body-medium` |
+
+The design's `8px` block padding is carried by the `32px` height plus vertical centring rather than by a `padding-block`, which is the same `32px` every other single-line control in the library stands at.
+
+The design draws no clear affordance and no hover state for the field itself, so neither is invented here; the `trailing` slot is where a clear button goes. It also draws the field appearing from a magnifier button and disappearing on a click outside. That is a disclosure the consumer composes, not a behaviour of the field: a molecule that opened and closed itself would be deciding when an application searches.
+
+## Accessibility
+
+The wrapper is a plain `div` and carries no landmark role, because a landmark is a claim about the page rather than about the control. Give the input an `aria-label` (or an associated `<label>` through `FuroControlBlock`) so the field is announced; the magnifier is `aria-hidden` and says nothing.

package/docs/furo-section-header.md

@@ -0,0 +1,135 @@
+# `<FuroSectionHeader>` Interface Specification
+
+## Overview
+
+`<FuroSectionHeader>` is a **shipped** section-header molecule in the Furo-Vue component system. It names a region of a long form or a detail panel and closes it off from what follows with a rule, so every group boundary in an application is drawn the same way.
+
+It is purely presentational: it carries no value and emits nothing.
+
+**Public SFC prop:** `parcel` only. HTML attributes pass through to the root.
+
+## Summary
+
+| Field | Value |
+|---|---|
+| **Layer** | Molecule |
+| **Path** | `lib/components/molecules/FuroSectionHeader/` |
+| **Base primitive** | None; a heading beside a trailing region |
+| **Value** | None |
+| **Emits** | None |
+| **Composes** | `FuroSeparator` |
+
+## `parcel` keys
+
+| Key | Type | Default | Meaning |
+|---|---|---|---|
+| `title` | `string` | `''` | Text the heading renders. |
+| `headingLevel` | `number` | `2` | Depth of the heading in the consumer's document outline. Values outside one to six are clamped to the nearest level HTML defines. |
+| `size` | `'large' \| 'medium'` | `'large'` | Type step the title renders at, matching the two the design draws. |
+| `divided` | `boolean` | `true` | Whether a rule closes the header off from what follows it. |
+
+## The heading is a real heading
+
+The title renders as `h1` through `h6`, chosen by `headingLevel`, not as a styled `div`. A consumer therefore keeps a document outline a screen-reader user can navigate by heading, and the library never forces markup that reads as decoration.
+
+The level is a parcel key rather than a fixed choice because only the consumer knows how deep the section sits. The default of two suits a section inside a page that already carries an `h1`.
+
+## The rule is the separator, not a border
+
+`divided` renders `FuroSeparator` across the block-end edge rather than a `border-block-end` on the root, so every rule in the library is the same object and changes in one place. The rule is marked decorative: the heading already tells a screen reader where the boundary is, and announcing it twice adds nothing.
+
+`divided` defaults to `true` because the divider is what the component is for. A header sitting at the top of a surface whose content draws its own top border passes `divided: false`.
+
+## Slots
+
+| Slot | Scope | Purpose |
+|---|---|---|
+| `leading` | none | Content before the heading, for example the back control the design draws on a sub-section. |
+| `title` | none | Replaces the heading's text. Default: `parcel.title`. |
+| `actions` | none | The trailing region. The region is dropped entirely when the slot is empty, so it takes no space. |
+
+The trailing region is a slot rather than a list of button parcels. A header carries whatever controls the screen needs, and a parcel key per control would grow one key per screen while still not covering the next one.
+
+## Styling
+
+| Part | Class | Notes |
+|---|---|---|
+| Root | `.unit-section-header` | Also carries `size-large` or `size-medium` |
+| The row | `.row` | Heading and trailing region, spaced apart |
+| Heading side | `.lead` | The `leading` slot beside the heading |
+| The heading | `.title` | The `h1` to `h6` element |
+| Trailing region | `.actions` | Only rendered when the `actions` slot carries content |
+
+## Usage
+
+```vue
+<!-- A list panel header, its rule left to the table below it -->
+<FuroSectionHeader
+  :parcel="{
+    title: 'Employees',
+    divided: false,
+  }"
+>
+  <template #actions>
+    <FuroButton :parcel="{ variant: 'ghost' }">New Program</FuroButton>
+    <FuroSeparator :parcel="{ orientation: 'vertical' }" />
+    <FuroButton :parcel="{ variant: 'ghost' }">New Product</FuroButton>
+  </template>
+</FuroSectionHeader>
+
+<!-- A sub-section of a detail panel, with a back control -->
+<FuroSectionHeader
+  :parcel="{
+    title: 'Customize View',
+    size: 'medium',
+    headingLevel: 3,
+  }"
+>
+  <template #leading>
+    <FuroButton
+      :parcel="{ variant: 'ghost', size: 'icon' }"
+      @click="context.goBack()"
+    >
+      <FuroIcon name="ph:caret-left" />
+    </FuroButton>
+  </template>
+</FuroSectionHeader>
+```
+
+## Read from the design
+
+Every value is a semantic token. Nothing is transcribed as a hex or a raw size:
+
+| Design value | Token |
+|---|---|
+| `Grayscale/Text/Title` | `--color-foreground-title` |
+| `white` surface | `--color-card` |
+| `Corner/3xl (16)`, top corners | `--size-border-radius-2x-large` |
+| `Spacing/lg (20)`, inline padding | `1.25rem` |
+| `Spacing/sm (12)`, block padding | `0.75rem` |
+| `Spacing/xxs (4)`, beside the heading | `--size-space-tiny` |
+| `Spacing/sm (12)`, between trailing controls | `--size-space-compact` |
+| `Label/Large` | `--font-label-large` |
+| `Label/Medium` | `--font-label-medium` |
+
+Two values are recorded rather than matched:
+
+- The row is 56px tall in both instances the design draws. There is no height token for it, so it is a plain `3.5rem` minimum, the same treatment the other non-scale dimensions get.
+- The design draws the rule in `Grayscale/Border/Disabled` (`#f1f2f4`), one step lighter than `Grayscale/Border/Default` (`#e0e2e6`) which `--color-border` carries. `FuroSeparator` has no colour channel, so the rule renders at the library's default border. Giving the separator a colour channel is a change to that component and is recorded here rather than made from this one.
+
+The design draws no supporting text under the title, so no key carries one.
+
+## Composition notes
+
+- Imports nothing from a higher layer and nothing from the app: no GraphQL, PrimeVue, Vue Router, or Nuxt-specific imports.
+- The root is a `div` rather than a `header`. A `header` placed outside sectioning content becomes a `banner` landmark, and a library component cannot know how a consumer nests it.
+- All logic lives in `FuroSectionHeaderContext`; the template only calls context members.
+- CSS is wrapped in `@layer furo`, references semantic tokens only, and uses `--size-space-*` for `gap` and `rem` everywhere else.
+
+## Testing
+
+`FuroSectionHeaderContext` is covered by jsdom unit tests: the title, size and heading-level getters including the clamp at both ends, `isDivided()` and `hasActions()` split into truthy and falsy blocks, the heading tag, the separator parcel, the root class map, and the passthrough filter that withholds the Furo-owned keys.
+
+## Playground
+
+`/samples/components/playground` → **Section Header** tab. Demonstrates both type steps, the header with and without its rule, a trailing action region, and a leading control.