@openreachtech/furo-vue 1.6.0 → 2.0.0

package/docs/furo-checkbox.md

@@ -0,0 +1,384 @@
+# `<FuroCheckbox>` Interface Specification
+
+## Overview
+
+`<FuroCheckbox>` is a **shipped** checkbox 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 checkbox primitive inside `lib/components/atoms/FuroCheckbox/*` only. That dependency is **not** part of the application API.
+
+Contract style aligns with [`FuroTextField`](./furo-text-field.md) and [`FuroAutocompleteField`](./furo-autocomplete-field.md):
+
+- behavior via `:parcel` (`FuroCheckboxParcel`)
+- HTML / form attributes via fallthrough (`name`, `id`, `aria-*`, …)
+- Furo emits (`change-value`, `update:value`, `update:indeterminate`)
+- `v-model:value` syncs checked state (`boolean`); `v-model:indeterminate` syncs the [-] UI flag
+
+**Public SFC prop:** `parcel` only.
+
+**Model shape:** **`boolean` checked** (`parcel.value` / `v-model:value`) plus **`boolean` indeterminate** (`parcel.indeterminate` / `v-model:indeterminate`). Tri-state is not encoded in `value`.
+
+`@change-value` fires on every committed toggle from the checkbox root (`@update:model-value`).
+
+Read [`FuroTextField`](./furo-text-field.md) for the shared `parcel` mental model.
+
+### Abstraction boundary
+
+| Layer | Responsibility |
+| ----- | -------------- |
+| Application | `parcel`, listeners, slots; controls `parcel.value` / `parcel.indeterminate` |
+| Atom (`FuroCheckbox`) | Maps parcel → the underlying checkbox 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 checkbox primitive in application code.
+3. Use `parcel.indeterminate` (or `v-model:indeterminate`) for the [-] state — not `null` or ad-hoc DOM attributes on `value`.
+
+**Source files:**
+
+- `lib/components/atoms/FuroCheckbox/FuroCheckbox.vue`
+- `lib/components/atoms/FuroCheckbox/FuroCheckboxContext.js`
+- `lib/components/atoms/FuroCheckbox/CheckboxEmitPayload.js`
+
+**Live samples:** `pages/samples/components/playground/FuroCheckboxPlayground/index.vue`
+
+---
+
+## Public API at a glance
+
+| Area | Status | Notes |
+| ---- | ------ | ----- |
+| **SFC surface** | | |
+| Public prop `parcel` only (+ attribute fallthrough) | **Implemented** | See [`FuroCheckboxParcel`](#furocheckboxparcel) |
+| **Value & state** | | |
+| Controlled `parcel.value` + `v-model:value` | **Implemented** | `Object.hasOwn(parcel, 'value')` |
+| Uncontrolled (no `parcel.value`) | **Implemented** | Internal ref starts `false`; parent toggle without `value` key |
+| Indeterminate (`parcel.indeterminate` + `v-model:indeterminate`) | **Implemented** | Separate boolean channel; default minus/check icons |
+| `invalid`, `disabled`, `required` | **Implemented** | `.invalid` class + `aria-invalid` / `disabled` / `required` on the checkbox root |
+| `parcel.size` | **Implemented** | CSS length (e.g. `1rem`, `1.5rem`) via `--furo-checkbox-size` |
+| **Emits** | | |
+| `change-value`, `update:value`, `update:indeterminate` | **Implemented** | No `commit-value` (no commit gesture) |
+| **Slots** | | |
+| `indicator`, `indeterminate-indicator` | **Implemented** | No built-in label — use external `<label>` |
+| Built-in `label` slot | **Not implemented** | Label must live outside `<FuroCheckbox>` |
+| **Spec debt (not in runtime)** | | |
+| Checkbox group fieldset API | **Not implemented** | v1 single checkbox only |
+| Closed `parcel` (reject unknown primitive keys) | **Not implemented** | Extra keys may pass via `extractRootAttributes()` |
+
+---
+
+## Props
+
+### Rule: `parcel` vs attributes
+
+| Mechanism | When to use | Application sees |
+| --------- | ----------- | ---------------- |
+| `:parcel` | Furo checkbox behavior | `FuroCheckboxParcel` (+ merged defaults) |
+| Attributes on `<FuroCheckbox>` | e.g. `name`, `id` | Vue fallthrough to the checkbox root (merged with `extractRootAttributes()`) |
+
+> **`parcel` must be JSON-serializable** — no functions inside `parcel`.
+
+```html
+<div class="unit-checkbox-field">
+  <FuroCheckbox
+    id="terms"
+    v-model:value="context.termsAcceptedRef.value"
+    :parcel="{
+      value: context.termsAcceptedRef.value,
+      invalid: context.statusReactive.isInvalidTerms,
+    }"
+    name="terms"
+    @change-value="context.onChangeTerms({ payload: $event })"
+  />
+  <label for="terms">
+    I accept the terms
+  </label>
+</div>
+```
+
+### Component props (public)
+
+| Prop | Type | Default | Description |
+| ---- | ---- | ------- | ----------- |
+| `parcel` | `FuroCheckboxParcel` or `null` | `null` | Furo behavior (see table below) |
+
+### `FuroCheckboxValue`
+
+`boolean` — checked state only (`true` / `false`). Indeterminate UI uses `parcel.indeterminate` (see below).
+
+### `FuroCheckboxParcel`
+
+Keys read in `FuroCheckboxContext` (defaults from `parcel` getter):
+
+| Key | Type | Default (getter) | Description |
+| --- | ---- | ---------------- | ----------- |
+| `value` | `FuroCheckboxValue` | — | Controlled checked state. Presence of this key (`Object.hasOwn`) enables controlled mode. |
+| `indeterminate` | `boolean` | `false` | When `true`, shows [-] indicator; `value` still reflects checked boolean (often `false` for partial “select all”) |
+| `invalid` | `boolean` | `false` | `.invalid` class + `aria-invalid` on the checkbox root |
+| `disabled` | `boolean` | `false` | Disables interaction (also respects fallthrough `disabled`) |
+| `required` | `boolean` | `false` | Forwarded to root (also respects fallthrough `required`) |
+| `size` | `string` | `1.125rem` (`DEFAULT_CHECKBOX_SIZE`) | Box width/height; icon uses `8/9` of box (`DEFAULT_CHECKBOX_ICON_SIZE` = `1rem`) |
+
+Furo-owned keys above are **not** forwarded via `extractRootAttributes()`.
+
+#### Size
+
+Pass any valid CSS length on `parcel.size` (`rem`, `px`, or `em`). The root sets `--furo-checkbox-size` and `--furo-checkbox-icon-size` (box × `8/9`). Default icons receive matching `Icon` `size` via `extractCheckboxIconSize()`.
+
+```html
+<FuroCheckbox
+  :parcel="{
+    value: context.flagRef.value,
+    size: '1.5rem',
+  }"
+/>
+``` Other JSON-serializable keys on `parcel` may pass through to the underlying primitive (unsupported for apps).
+
+#### Indeterminate state
+
+| Mechanism | Behavior |
+| --------- | -------- |
+| `parcel.indeterminate: true` | the underlying primitive's internal model is indeterminate; `parcel.value` stays boolean |
+| `v-model:indeterminate` | Two-way sync for `parcel.indeterminate` on user toggle |
+| `update:indeterminate` | Emits `boolean` on each toggle (with `update:value`) |
+| Default `#indeterminate-indicator` / `#indicator` slots | `ph:minus-bold` when indeterminate; `ph:check-bold` when checked and not indeterminate |
+
+Toggling from indeterminate follows the underlying checkbox primitive's rules (typically moves to checked / unchecked). After the user clicks, clear `parcel.indeterminate` when the parent adopts a definite selection (`update:indeterminate` emits `false`).
+
+> **Maintainers:** the underlying primitive uses an internal `'indeterminate'` sentinel (`FuroCheckboxContext.INDETERMINATE_VALUE`). Applications must not put that string in `parcel.value` or compare `v-model:value` to it.
+
+#### Migration (breaking)
+
+| Before | After |
+| ------ | ----- |
+| `v-model:value === 'indeterminate'` | `v-model:indeterminate === true` (keep `value` boolean, often `false`) |
+| `parcel.value: 'indeterminate'` | `parcel: { value: false, indeterminate: true }` |
+| `payload.value === 'indeterminate'` | `payload.isIndeterminate()` or `payload.indeterminate` |
+
+---
+
+## Controlled & uncontrolled
+
+```html
+<!-- Controlled -->
+<FuroCheckbox
+  v-model:value="context.flagRef.value"
+  :parcel="{ value: context.flagRef.value }"
+/>
+
+<!-- Uncontrolled (starts unchecked) -->
+<FuroCheckbox :parcel="{}" />
+```
+
+| Mode | Detection | Sync |
+| ---- | --------- | ---- |
+| Controlled | `'value' in parcel` (including `value: false`) | `watch` on `resolveSyncedValue()` updates `internalValueRef` |
+| Uncontrolled | no `value` key on `parcel` | Starts `false`; user toggles update internal ref only |
+| Fallthrough `value` attr | Used when controlled via attrs only | Same as `FuroTextField` fallback in `resolveSyncedValue()` |
+
+### State matrix
+
+| State | Source |
+| ----- | ------ |
+| Underlying primitive `model-value` | `internalValueRef` (may use internal indeterminate sentinel) |
+| Checked (boolean) | `parcel.value` / `v-model:value` |
+| Uncontrolled seed | `false` |
+| Indeterminate UI | `parcel.indeterminate` / `v-model:indeterminate` |
+| Invalid UI | `parcel.invalid` |
+| Disabled | `parcel.disabled` or fallthrough `disabled` |
+
+---
+
+## Emits
+
+| Event | Payload | When | Implemented |
+| ----- | ------- | ---- | ----------- |
+| `change-value` | `CheckboxEmitPayload` | Each primitive's model update | Yes |
+| `update:value` | `FuroCheckboxValue` | Checked boolean after toggle (`v-model:value`) | Yes |
+| `update:indeterminate` | `boolean` | Indeterminate flag after toggle (`v-model:indeterminate`) | Yes |
+
+### Parent handler style
+
+```js
+onChangeTerms ({
+  payload,
+}) {
+  this.statusReactive.isInvalidTerms = payload.isUnchecked()
+}
+```
+
+```html
+@change-value="context.onChangeTerms({ payload: $event })"
+```
+
+---
+
+## `CheckboxEmitPayload` API
+
+`CheckboxEmitPayload` extends [`BaseEmitPayload`](../lib/emit-payload/BaseEmitPayload.js). Built from `CustomEvent` `detail` on toggle.
+
+| Member | Type | Description |
+| ------ | ---- | ----------- |
+| `value` | `FuroCheckboxValue \| null` | Checked state after change |
+| `indeterminate` | `boolean` | Indeterminate flag after change |
+| `controlElement` | `HTMLElement \| null` | Checkbox root element when ref assigned |
+| `isIndeterminate()` | `boolean` | Same as `indeterminate` |
+| `isChecked()` | `boolean \| null` | `true` when `value` is boolean `true`; `null` when `value` is not a boolean |
+| `isUnchecked()` | `boolean \| null` | `true` when `value` is boolean `false`; `null` when `value` is not a boolean |
+
+---
+
+## `v-model` and state handling
+
+```html
+<FuroCheckbox
+  v-model:value="context.flagRef.value"
+  :parcel="{
+    value: context.flagRef.value,
+  }"
+/>
+```
+
+| Binding | Implemented | Notes |
+| ------- | ----------- | ----- |
+| `v-model:value` | **Yes** | Emits `true` / `false` only |
+| `v-model:indeterminate` | **Yes** | Emits `true` / `false` for [-] UI |
+
+---
+
+## Slots
+
+| Slot | Scoped props | Default |
+| ---- | ------------ | ------- |
+| `indicator` | — | `ph:check-bold` when `value === true` |
+| `indeterminate-indicator` | — | `ph:minus-bold` when `parcel.indeterminate` / indeterminate UI |
+
+The checkbox root and indicator are not slot-replaceable.
+
+There is **no** `label` slot. Associate copy with an external `<label for="…">` pointing at the checkbox `id` (fallthrough attribute on the checkbox root).
+
+---
+
+## Internal implementation (maintainers only)
+
+### Template composition
+
+```text
+checkbox root .unit-form-control.checkbox (model-value, aria-*, id for external label)
+  checkbox indicator
+    [#indeterminate-indicator] | [#indicator]
+```
+
+### Primitive mapping
+
+| Furo | Underlying primitive |
+| ---- | -------------------- |
+| `internalValueRef` | `model-value` / `@update:model-value` |
+| `parcel.indeterminate` | internal indeterminate sentinel (not public `value`) |
+
+---
+
+## Accessibility requirements
+
+- Provide an external `<label for="control-id">` (or wrap the atom in `<label>`) — set matching `id` on `<FuroCheckbox>`.
+- `aria-invalid` reflects `parcel.invalid`.
+- Checkbox roles and keyboard support are delegated to the underlying primitive ([checkbox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/checkbox/)).
+- Set `name` on the component for forms.
+
+---
+
+## Styling convention
+
+Styles in SFC `@layer furo`:
+
+- Root: the checkbox root `.unit-form-control.checkbox`
+- Parts: `.indicator`, `.indicator-icon`
+- Size: `--furo-checkbox-size`, `--furo-checkbox-icon-size` (from `parcel.size`, default box `1.125rem` / icon `1rem`)
+- Tokens: `--color-input`, `--color-background`, `--color-primary`, `--color-destructive`
+
+Use `data-state` / `data-disabled` from the underlying primitive for state styling.
+
+---
+
+## Examples
+
+### Basic controlled
+
+```html
+<div class="unit-checkbox-field">
+  <FuroCheckbox
+    id="accepted"
+    v-model:value="context.acceptedRef.value"
+    :parcel="{
+      value: context.acceptedRef.value,
+    }"
+    name="accepted"
+    @change-value="context.onChangeAccepted({ payload: $event })"
+  />
+  <label for="accepted">
+    Accept policy
+  </label>
+</div>
+```
+
+### Indeterminate (parent-driven)
+
+```html
+<div class="unit-checkbox-field">
+  <FuroCheckbox
+    id="select-all"
+    v-model:value="context.selectAllStateReactive.value"
+    v-model:indeterminate="context.selectAllStateReactive.isIndeterminate"
+    :parcel="{
+      value: context.selectAllStateReactive.value,
+      indeterminate: context.selectAllStateReactive.isIndeterminate,
+    }"
+    name="select-all"
+  />
+  <label for="select-all">
+    Select all
+  </label>
+</div>
+```
+
+### Invalid
+
+```html
+<FuroCheckbox
+  :parcel="{
+    value: false,
+    invalid: context.statusReactive.isInvalidTerms,
+  }"
+  name="terms"
+/>
+```
+
+---
+
+## Implementation status
+
+| Deliverable | Status |
+| ----------- | ------ |
+| `FuroCheckbox.vue` + context + payload | Shipped |
+| Public prop: `parcel` only | Shipped |
+| Indeterminate + boolean model + controlled/uncontrolled | Shipped |
+| Playground `FuroCheckboxPlayground` | Shipped |
+| Unit tests `FuroCheckboxContext.js`, `CheckboxEmitPayload.js` (jsdom) | Shipped |
+| Checkbox group | Pending |
+| Closed `parcel` | Pending |
+
+---
+
+## Future / spec debt
+
+- Checkbox group API for related checkbox groups
+- `commit-value` (not applicable unless blur/commit semantics added)
+- Strip unknown keys on `v-bind` to the underlying primitive
+
+---
+
+## Known gaps and follow-ups
+
+- **Indeterminate toggle:** after user clicks, the underlying primitive decides next state; bind `v-model:indeterminate` or clear `parcel.indeterminate` when adopting a definite selection.
+- **Group semantics:** multiple related checkboxes need separate instances or future group API.

package/docs/furo-collapsible.md

@@ -0,0 +1,104 @@
+# FuroCollapsible
+
+Single expand/collapse region. A trigger toggles the visibility of one associated content block. Built on a headless collapsible primitive that manages the open state, ARIA wiring, and the measured content height for smooth animation.
+
+## Summary
+
+| Field | Value |
+|---|---|
+| **Layer** | Molecule |
+| **Path** | `lib/components/molecules/FuroCollapsible/` |
+| **Base primitive** | Headless collapsible (`Root` + `Trigger` + `Content`) |
+| **Composes** | Nothing — one trigger + one content region |
+| **Model** | `value` (open boolean) via `v-model:value` |
+| **Emits** | `change-value`, `update:value` |
+
+---
+
+## Public API
+
+### Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `parcel` | `FuroCollapsibleParcel \| null` | `null` | Reactive data object holding the open value and disabled flag. |
+
+### Parcel keys
+
+| Key | Type | Default | Description |
+|---|---|---|---|
+| `value` | `boolean` | unset (`false`) | Open state. When present, the component is **controlled** — the parent owns the value. When absent, the component manages its own state (**uncontrolled**). |
+| `disabled` | `boolean` | `false` | Disables the trigger; the region stays in its current state. |
+
+### Emits
+
+| Event | Payload | Description |
+|---|---|---|
+| `change-value` | `CollapsibleEmitPayload` | Fired when the open state changes. `payload.value` is the new boolean; `payload.isOpen()` is a convenience predicate. |
+| `update:value` | `boolean` | `v-model:value` sync of the open state. |
+
+### Slots
+
+| Slot | Slot props | Description |
+|---|---|---|
+| `trigger` | `{ open: boolean }` | Trigger content (label + optional indicator). Rendered inside the toggle button. |
+| default | `{ open: boolean }` | The collapsible content revealed when open. |
+
+---
+
+## Behavior
+
+| Concern | Behavior |
+|---|---|
+| **Controlled vs uncontrolled** | `isControlled()` returns true when `parcel` owns a `value` key. A watcher syncs the controlled value into the internal open ref; uncontrolled instances start closed and track their own state. |
+| **Value mapping** | The public `value` boolean maps to the primitive's own open prop in the template (`:open` / `@update:open`); the primitive's prop name is not exposed in the public API. |
+| **Disabled** | `isDisabled()` reads `parcel.disabled` or a fallthrough `disabled` attribute. |
+| **Animation** | The content wrapper animates between `0` and the primitive's measured `--reka-collapsible-content-height` for a smooth expand/collapse. |
+| **Passthrough** | Non-Furo parcel keys and extra attributes fall through to the root (`inheritAttrs: false` + `v-bind="$attrs"`). |
+
+---
+
+## Usage
+
+```vue
+<!-- Uncontrolled -->
+<FuroCollapsible>
+  <template #trigger="{ open }">
+    <span>What is furo-vue?</span>
+    <Icon :name="open ? 'ph:caret-up' : 'ph:caret-down'" />
+  </template>
+
+  <p>furo-vue is a domain-agnostic Vue component library.</p>
+</FuroCollapsible>
+
+<!-- Controlled -->
+<FuroCollapsible
+  :parcel="{ value: isOpen }"
+  @update:value="isOpen = $event"
+>
+  <template #trigger>Release notes</template>
+  <p>...</p>
+</FuroCollapsible>
+```
+
+---
+
+## Composition notes
+
+- Imports nothing from the app — no GraphQL, PrimeVue, Vue Router, or Nuxt-specific imports.
+- All logic lives in `FuroCollapsibleContext`: extract-only getters, the controlled/uncontrolled sync, and the `extractRootClassNames()` / `extractRootAttributes()` mappers. The component template only binds context methods.
+- The public `value` key is value-oriented; the primitive's open prop name appears only in the template binding.
+- CSS is in `@layer furo`, scoped, with `unit-collapsible` root. Dimensions use `rem`; `gap` uses `--size-space-*`; colors reference semantic tokens only.
+
+---
+
+## Testing
+
+- Context logic is fully covered by jsdom unit tests: `parcel` defaults, `isControlled()`, `resolveSyncedValue()`, `isDisabled()` and `isOpen()` (split into truthy / falsy describe blocks), `extractRootClassNames()`, `extractRootAttributes()` passthrough, the controlled/uncontrolled `setupComponent()` sync, and `onChangeValue()` emit behavior.
+- No SFC mount test: behavior is declarative bindings over the tested context plus the headless primitive's own open handling, verified by manual QA in the playground.
+
+---
+
+## Playground
+
+`/samples/components/playground` → **Collapsible** tab. Demonstrates uncontrolled, controlled (with an outside toggle button), and disabled regions.

package/docs/furo-control-block.md

@@ -0,0 +1,102 @@
+# FuroControlBlock
+
+Presentational wrapper that frames a single form control with a **label** and **error messages**. The control is supplied through the default slot, so the block is domain-agnostic — it never knows which atom it wraps and emits nothing; the slotted control owns its own events. Intended as the per-field frame for the consumer-built ListView and DetailView forms (in `crm-kit-frontend`).
+
+## Summary
+
+| Field | Value |
+|---|---|
+| **Layer** | Molecule |
+| **Path** | `lib/components/molecules/FuroControlBlock/` |
+| **Composes** | Nothing — wraps an arbitrary control via the default slot |
+| **Emits** | None (the slotted control bubbles its own events to the consumer) |
+| **Orientation** | `vertical` (default) or `horizontal`, via a CSS modifier |
+
+---
+
+## Public API
+
+### Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `parcel` | `ControlBlockParcel \| null` | `null` | Reactive data object holding the label, control id, error messages, required flag, and orientation. |
+
+### Parcel keys
+
+| Key | Type | Default | Description |
+|---|---|---|---|
+| `label` | `string \| null` | `null` | Label text. When `null`, no `<label>` is rendered. |
+| `controlId` | `string \| null` | `null` | Id of the slotted control. Rendered as `<label for>` for a11y association; the consumer passes the same id to the control. When `null`, the label has no `for`. |
+| `errorMessages` | `Array<string>` | `[]` | Error messages. A non-empty array marks the block invalid and renders one line per message. |
+| `required` | `boolean` | `false` | When `true`, renders a required mark (`*`) after the label. |
+| `orientation` | `'vertical' \| 'horizontal'` | `'vertical'` | Layout of label vs control. `vertical` stacks; `horizontal` places the label beside the control. |
+
+### Emits
+
+None. The block is presentational; the control inside the slot emits its own `change-value` / `commit-value` / `update:value` events straight to the consumer.
+
+### Slots
+
+| Slot | Description |
+|---|---|
+| default | The control to frame (e.g. `FuroTextField`). Pass the same `id` as the parcel's `controlId` so `<label for>` resolves. |
+
+---
+
+## Behavior
+
+| Concern | Behavior |
+|---|---|
+| **Label** | Rendered only when `parcel.label` is set. Associated with the control via `<label :for="controlId">` when `controlId` is provided. |
+| **Required mark** | The `*` carries `aria-hidden="true"` — it is a visual cue only; convey required state on the control itself. |
+| **Invalid state** | When `errorMessages` is non-empty, the root gets the `invalid` modifier and the error list renders. |
+| **Error region** | Rendered as a `<ul role="alert">`, one `<li>` per message. |
+| **Orientation** | `parcel.orientation` maps to the `vertical` / `horizontal` root class; no JS branching. |
+| **Fallthrough class / style** | A consumer-supplied `class` and `style` compose onto the block's root element, so a layout selector like `.control.name { flex: 1 }` reaches the wrapper. The block uses `inheritAttrs: false` and explicitly composes `$attrs.class` / `$attrs.style` onto the root. |
+
+> **a11y note (deliberate):** the error region carries `role="alert"` only. The block does **not** auto-wire `aria-describedby` onto the slotted control, because it cannot set attributes on a slot child. Consumers that need the stronger association wire it themselves. Upgrade path: expose an `errorId` getter for consumers to bind.
+
+---
+
+## Usage
+
+```vue
+<FuroControlBlock
+  :parcel="{
+    label: 'Email address',
+    controlId: 'field-email',
+    required: true,
+    errorMessages: emailErrors,
+    orientation: 'vertical',
+  }"
+>
+  <FuroTextField
+    id="field-email"
+    :parcel="{ value: email }"
+    @update:value="onEmailChange({ value: $event })"
+  />
+</FuroControlBlock>
+```
+
+---
+
+## Composition notes
+
+- The block imports nothing — no atoms, no GraphQL, PrimeVue, Vue Router, or Nuxt-specific imports. It is a pure slot wrapper.
+- All logic lives in `FuroControlBlockContext` as extract-only getters (`label`, `controlId`, `errorMessages`, `orientation`) and two boolean methods (`isInvalid()`, `isRequired()`).
+- CSS is wrapped in `@layer furo`; `gap` uses `--size-space-*` tokens and all other dimensions use `rem`. Only semantic tokens are referenced (`--color-foreground`, `--color-destructive-text`, `--font-label-small`, `--font-body-small`). The label and the error text each carry a composite text style through the `font` shorthand per [ADR 0032](./adr/0032-composite-text-style-tokens-via-font-shorthand.md), so the label renders at weight `500` and no longer inherits the host page's typography.
+- `inheritAttrs: false`; a consumer-supplied `class` / `style` is composed onto the block root (via `$attrs.class` / `$attrs.style`), so a parent layout selector such as `.control.name { flex: 1 }` reaches the wrapper.
+
+---
+
+## Testing
+
+- Context logic (every getter and both boolean methods) is fully covered by jsdom unit tests.
+- No SFC mount test: this repo has no jsdom mount precedent for molecules, and the block's behavior is entirely declarative bindings over the tested context. The rendered output (label show/hide, required mark, error list, orientation class) is verified by **manual QA in the playground**.
+
+---
+
+## Playground
+
+`/samples/components/playground` → **Control Block** tab. Demonstrates labeled (vertical), required, invalid (multiple error messages), and horizontal layouts wrapping `FuroTextField`.