@openreachtech/furo-vue 1.6.0 → 2.0.0

package/docs/furo-toast.md

@@ -0,0 +1,217 @@
+# FuroToast
+
+Organism — a controlled notification stack built on a headless toast primitive
+(`Provider` + `Viewport` + per-toast `Root` + `Title` + `Description` + `Action`
++ `Close`). The **parent owns the queue** via `parcel.toasts`; FuroToast renders
+it and emits `dismiss` / `action` by key so the parent updates its own array.
+No internal queue, no imperative API, registry-free. Domain-agnostic: no
+GraphQL, router, or Nuxt imports.
+
+Location: `lib/components/organisms/FuroToast/`
+
+## Props
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `parcel` | `ToastParcel \| null` | `null` | Reactive behavior object (below) |
+
+### `parcel`
+
+| Key | Type | Default | Notes |
+|-----|------|---------|-------|
+| `toasts` | `Array<ToastEntry>` | `[]` | The queue, owned by the parent. Render order follows the array; remove an entry on `dismiss`. |
+| `position` | `'top-left' \| 'top-center' \| 'top-right' \| 'bottom-left' \| 'bottom-center' \| 'bottom-right'` | `'bottom-right'` | Viewport placement. |
+| `durationInMilliseconds` | `number` | `4000` | Default auto-dismiss in ms. Per-toast `durationInMilliseconds` overrides it. |
+| `swipeDirection` | `'right' \| 'left' \| 'up' \| 'down'` | derived from `position` | Swipe-to-dismiss direction. When unset, a left toast swipes left, a right toast swipes right, and a centered toast swipes toward its vertical edge. |
+| `label` | `string` | `'Notifications'` | Accessible name of the toast region, in the app's own language. It also prefixes the announcement of each toast. When unset, the region keeps its default name, `Notifications (F8)`. |
+| `hotkey` | `Array<string> \| null` | `null` | Keyboard shortcut to focus the viewport (e.g. `['F8']`). |
+| `maxVisible` | `number` | `3` | Caps how many toasts render at once (the most recent). The rest stay queued in your array until a visible one is dismissed. |
+
+### `ToastEntry`
+
+| Key | Type | Default | Notes |
+|-----|------|---------|-------|
+| `key` | `string \| number` | — | **Required, stable.** Identifies the toast in `dismiss` / `action` payloads. |
+| `title` | `string \| null` | `null` | Heading text (or use the `title` slot). |
+| `description` | `string \| null` | `null` | Body text (or use the `description` slot). |
+| `type` | `'info' \| 'success' \| 'warning' \| 'error' \| 'loading'` | `'info'` | Shown as a small Phosphor (`ph:`) icon. `info` is neutral grey; `success`/`warning`/`error` tint only the icon. `loading` shows a spinner and is held open (no auto-dismiss) — see the promise pattern below. |
+| `durationInMilliseconds` | `number \| null` | `null` | Per-toast auto-dismiss override; `null` uses `parcel.durationInMilliseconds`. Ignored while `loading`. |
+| `closeText` | `string` | `'Close'` | Accessible label for the close button. |
+| `actionText` | `string \| null` | `null` | When set, renders an action button. |
+| `actionPending` | `boolean` | `false` | While `true`, the action button shows a spinner and is disabled — set it during an async action. |
+
+## Events
+
+| Event | Payload | When |
+|-------|---------|------|
+| `dismiss` | `{ key }` | A toast closed (timeout, swipe, or close button). Remove it from your array. |
+| `action` | `{ key }` | The action button was clicked. The toast also dismisses afterward. |
+
+## Slots
+
+| Slot | Scope | Purpose |
+|------|-------|---------|
+| `title` | `{ toast }` | Overrides a toast's title region (falls back to `toast.title`). |
+| `description` | `{ toast }` | Overrides a toast's description region (falls back to `toast.description`). |
+
+## Usage
+
+```vue
+<script setup>
+import { ref } from 'vue'
+
+const toasts = ref([])
+let nextKey = 1
+
+function notify (entry) {
+  toasts.value = [...toasts.value, { key: nextKey++, ...entry }]
+}
+
+function onDismiss ({ key }) {
+  toasts.value = toasts.value.filter(toast => toast.key !== key)
+}
+</script>
+
+<template>
+  <button @click="notify({ type: 'success', title: 'Saved' })">Save</button>
+
+  <FuroToast
+    :parcel="{ toasts, position: 'bottom-right' }"
+    @dismiss="onDismiss"
+    @action="({ key }) => retry(key)"
+  />
+</template>
+```
+
+### Promise toast (loading → success/error)
+
+Add a `loading` toast, await your work, then patch the same entry by key:
+
+```js
+function notifyWithPromise () {
+  const key = nextKey++
+  toasts.value = [...toasts.value, { key, type: 'loading', title: 'Uploading…' }]
+
+  upload()
+    .then(() => patch(key, { type: 'success', title: 'Upload complete' }))
+    .catch(() => patch(key, { type: 'error', title: 'Upload failed', actionText: 'Retry' }))
+}
+```
+
+### Async action (e.g. Retry)
+
+The action button does **not** auto-dismiss the toast — clicking it only emits
+`action`. You decide what happens: keep the toast as a `loading` promise toast
+while the work runs, then **close it** or **show a success message** (your
+choice). Two ways to show progress:
+
+```js
+// A) Turn the toast into a loading promise toast, then close OR show success.
+async function onAction ({ key }) {
+  patch(key, { type: 'loading', title: 'Retrying…', actionText: null })
+  await retry()
+
+  // close immediately…
+  onDismiss({ key })
+  // …or show success (auto-dismisses after its duration):
+  // patch(key, { type: 'success', title: 'Done' })
+}
+
+// B) Keep the action button but show a spinner on it while pending.
+async function onAction ({ key }) {
+  patch(key, { actionPending: true })
+  await retry()
+  onDismiss({ key })
+}
+```
+
+## Imperative helper
+
+For global usage, mount `<FuroToaster />` once (e.g. in your app
+layout), then trigger toasts from anywhere. This is an **opt-in layer** on top
+of the controlled `FuroToast` — the organism itself stays controlled and
+registry-free; a `ToastQueue` singleton bridges function handlers to the parcel.
+
+The supported import is the package root:
+
+```js
+import { toast } from '@openreachtech/furo-vue'
+```
+
+The `@openreachtech/furo-vue/toast` subpath and the
+`@openreachtech/furo-vue/lib/components/organisms/FuroToast/toast.js` deep path
+reach the same helper. All three share one queue even when a bundler
+pre-bundles the package into a second copy of the module, because the queue is
+pinned to the realm under `Symbol.for('@openreachtech/furo-vue/toastQueue')`.
+
+```vue
+<!-- app layout, once -->
+<script setup>
+import { FuroToaster } from '@openreachtech/furo-vue'
+</script>
+<template>
+  <FuroToaster />
+</template>
+```
+
+```js
+import { toast } from '@openreachtech/furo-vue'
+
+const key = toast.show({
+  type: 'error',
+  title: 'Upload failed',
+  description: 'Could not upload the file.',
+  actions: [
+    { label: 'Retry', onClick: () => retry() },
+    { label: 'Dismiss', onClick: () => {} },
+  ],
+})
+
+toast.update(key, { type: 'success', title: 'Done' }) // loading → success
+toast.hide(key)
+toast.clear()
+toast.configure({ position: 'top-right', richColors: true })
+```
+
+| Method | Signature | Purpose |
+|--------|-----------|---------|
+| `toast.show` | `(options) => key` | Show a toast; returns its key. `options` mirrors a `ToastEntry` plus `actions: [{ label, onClick }]`. |
+| `toast.hide` | `(key) => void` | Dismiss a toast by key. |
+| `toast.update` | `(key, patch) => void` | Merge fields into a toast (promise pattern). |
+| `toast.clear` | `() => void` | Dismiss all toasts. |
+| `toast.configure` | `(config) => void` | Set viewport defaults (`position`, `durationInMilliseconds`, `maxVisible`, `richColors`, …). |
+
+Unlike the controlled API, `actions[].onClick` are **functions held in the
+queue** (not serialized). `<FuroToast>` stays JSON-serializable; `FuroToaster`
+routes its `action` event back to the matching handler.
+
+**SSR note:** the `toast` singleton is realm-global, so on a server it is
+shared across requests. Trigger `toast.*` on the client only (toasts are a
+client interaction).
+
+## Notes
+
+- **Collapsed stack.** Toasts stack on top of each other: the
+  newest sits in front and pushes older ones down/back (offset + 5%-per-level
+  scale, all sharing the front toast's height). Hovering or focusing the stack
+  expands it into a full list; leaving collapses it again. Heights are measured
+  per toast, so variable-height toasts stack and expand correctly.
+- **Direction-aware motion.** A toast enters by sliding in from its position's
+  edge, and on close / auto-dismiss it slides back out the same way (the reverse
+  of its entry). Swipe-to-dismiss follows the position: drag toward the left
+  edge for left positions, the right edge for right positions.
+- `dismiss` is emitted ~250ms *after* the timer/close fires, so the exit
+  animation can play before you remove the entry. Remove it in your handler as
+  usual — the delay is internal.
+- The parent is the single source of truth for the queue — FuroToast holds no
+  internal toast state. Always remove an entry in your `dismiss` handler, or the
+  toast reopens.
+- Keys must be stable and unique; they are the only identifier in the emit payloads.
+- The design uses a neutral surface, soft shadow, a single
+  small stroke icon per type, and a close button that fades in on hover.
+- Type accents map to `--furo-toast-{info|success|warning|error}-accent`
+  component tokens (the icon color only); override them to retheme.
+- The built-in close button takes its size from `--size-close-button-small`.
+- Toasts are portaled by the underlying primitive; the viewport carries
+  `unit-toast-viewport {position}` and each toast `unit-toast {type}` inside
+  `@layer furo`.

package/docs/furo-toggle-group.md

@@ -0,0 +1,123 @@
+# FuroToggleGroup
+
+A set of related toggles where the group manages selection — text alignment (single choice), text styles like bold/italic/underline (multiple choices), or a table↔sequential view switch. Built on a headless toggle-group primitive that owns roving focus and selection state. The selection is exposed through the value channel (`v-model:value`), the same surface as the other Furo form controls.
+
+## Summary
+
+| Field | Value |
+|---|---|
+| **Layer** | Molecule |
+| **Path** | `lib/components/molecules/FuroToggleGroup/` |
+| **Base primitive** | Headless toggle-group (`Root` + `Item`, roving focus, `data-state="on" / "off"`) |
+| **Value** | `string` (single) / `string[]` (multiple) via `v-model:value` / `parcel.value` |
+| **Emits** | `change-value`, `update:value` |
+| **Composes** | Toggle items styled to match `FuroToggle`; building block for `FuroToolBar` |
+
+---
+
+## Public API
+
+### Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `parcel` | `FuroToggleGroupParcel \| null` | `null` | Reactive data object holding the selection, options, selection mode, variant, size, orientation, and disabled flag. |
+
+### Parcel keys
+
+| Key | Type | Default | Description |
+|---|---|---|---|
+| `value` | `string \| string[]` | — | Controlled selection. Present → controlled; absent → uncontrolled. A single value in `single` mode, an array in `multiple` mode. |
+| `selectionMode` | `'single' \| 'multiple'` | `'single'` | Whether one or many options may be pressed at once. |
+| `options` | `Array<{ value, label?, disabled? }>` | `[]` | The toggle items. `label` falls back to `value` when omitted. |
+| `variant` | `'default' \| 'outline'` | `'default'` | Item styling — `outline` adds a border. |
+| `size` | `'default' \| 'sm' \| 'lg'` | `'default'` | Item height and padding. |
+| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Layout direction. |
+| `disabled` | `boolean` | `false` | Disables the whole group; a per-option `disabled` flag disables a single item. |
+
+### Emits
+
+| Event | Payload | When |
+|---|---|---|
+| `change-value` | `ToggleGroupEmitPayload` | On every selection change. Wraps a `CustomEvent` exposing `value` and the control element; `isSelected({ value })` reports per-option state. |
+| `update:value` | `string \| string[]` | v-model sync of the selection. |
+
+### Slots
+
+| Slot | Props | Description |
+|---|---|---|
+| `option` | `{ option, pressed }` | Custom item content (e.g. icons). Defaults to the option's label. `pressed` reflects whether the option is selected. |
+
+---
+
+## Behavior
+
+| Concern | Behavior |
+|---|---|
+| **Controlled vs uncontrolled** | When `parcel.value` is present the internal model mirrors it via a watcher, and a click only emits the new value, so the group keeps showing `parcel.value` until the parent writes the new one back. Otherwise the primitive self-manages from an empty start. |
+| **Domain-agnostic keys** | Public keys are `value` and `selectionMode`; the mapping to the primitive's `modelValue` / `type` happens inside the component. |
+| **Selection mode** | `single` keeps the value a string; `multiple` keeps it an array. The empty value is `null` (single) or `[]` (multiple). |
+| **Disabled** | `parcel.disabled` (or a fallthrough `disabled` attr) disables the group; `option.disabled` disables one item. |
+| **Pressed styling** | The primitive's `data-state="on"` drives the pressed appearance — no JS branching in the template. |
+| **Passthrough** | Non-Furo attributes (`aria-label`, …) fall through to the root (`inheritAttrs: false` + `v-bind="$attrs"`). |
+
+---
+
+## Usage
+
+```vue
+<!-- Single selection -->
+<FuroToggleGroup
+  v-model:value="alignment"
+  aria-label="Text alignment"
+  :parcel="{
+    selectionMode: 'single',
+    variant: 'outline',
+    options: [
+      { value: 'left', label: 'Left' },
+      { value: 'center', label: 'Center' },
+      { value: 'right', label: 'Right' },
+    ],
+  }"
+/>
+
+<!-- Multiple selection with custom icon content -->
+<FuroToggleGroup
+  v-model:value="textStyles"
+  aria-label="Text styles"
+  :parcel="{
+    selectionMode: 'multiple',
+    options: [
+      { value: 'bold' },
+      { value: 'italic' },
+      { value: 'underline' },
+    ],
+  }"
+>
+  <template #option="{ option }">
+    <Icon :name="`ph:text-${option.value}`" />
+  </template>
+</FuroToggleGroup>
+```
+
+---
+
+## Composition notes
+
+- Imports nothing from the app — no GraphQL, PrimeVue, Vue Router, or Nuxt-specific imports.
+- Uses the headless `Item` (not nested `FuroToggle`) so roving focus and single/multi selection come from the primitive; items only borrow `FuroToggle`'s visual tokens.
+- All logic lives in `FuroToggleGroupContext`: extract-only getters (`parcel`, `options`), boolean methods (`isControlled()`, `isMultiple()`, `isDisabled()`, `isSelected()`, `isOptionDisabled()`), and the change handler that emits both channels.
+- CSS is wrapped in `@layer furo`; dimensions use `rem`, `gap` uses `--size-space-*`, and colors reference semantic tokens (`--color-accent`, `--color-border`, `--color-ring`) only.
+
+---
+
+## Testing
+
+- `FuroToggleGroupContext` is fully covered by jsdom unit tests: parcel defaults, the boolean methods split into truthy / falsy describe blocks, `resolveSyncedValue()`, label / class / attribute extraction, controlled-value sync in `setupComponent()`, and the dual emit in `onChangeValue()` for both single and multiple modes.
+- No SFC mount test: rendering is declarative bindings over the tested context plus the headless primitive's own semantics, verified by manual QA in the playground.
+
+---
+
+## Playground
+
+`/samples/components/playground` → **Toggle Group** tab. Demonstrates single selection, multiple selection (`v-model:value`), vertical orientation, and disabled states.

package/docs/furo-toggle.md

@@ -0,0 +1,104 @@
+# FuroToggle
+
+Two-state pressed/unpressed button — bold/italic in an editor toolbar, a filter on/off switch, a view-mode flip. Built on a headless toggle primitive that owns the `aria-pressed` / `data-state` semantics. The pressed state is a boolean exposed through the value channel (`v-model:value`), the same surface as the other Furo form controls.
+
+## Summary
+
+| Field | Value |
+|---|---|
+| **Layer** | Atom |
+| **Path** | `lib/components/atoms/FuroToggle/` |
+| **Base primitive** | Headless toggle button (`aria-pressed`, `data-state="on" / "off"`) |
+| **Value** | `boolean` via `v-model:value` / `parcel.value` |
+| **Emits** | `change-value`, `update:value` |
+| **Building block for** | `FuroToggleGroup`, `FuroToolBar` |
+
+---
+
+## Public API
+
+### Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `parcel` | `FuroToggleParcel \| null` | `null` | Reactive data object holding the pressed value, variant, size, and disabled flag. |
+
+### Parcel keys
+
+| Key | Type | Default | Description |
+|---|---|---|---|
+| `value` | `boolean` | — | Controlled pressed state. Present → controlled; absent → uncontrolled (starts released). |
+| `variant` | `'default' \| 'outline'` | `'default'` | `default` is borderless and fills the accent surface when pressed; `outline` adds a border. |
+| `size` | `'default' \| 'sm' \| 'lg'` | `'default'` | Control height and padding. |
+| `disabled` | `boolean` | `false` | Blocks interaction; also honored from a fallthrough `disabled` attribute. |
+
+### Emits
+
+| Event | Payload | When |
+|---|---|---|
+| `change-value` | `ToggleEmitPayload` | On every press/release. Wraps a `CustomEvent` exposing `value` (boolean) and the control element. |
+| `update:value` | `boolean` | v-model sync of the pressed state. |
+
+### Slots
+
+| Slot | Props | Description |
+|---|---|---|
+| default | `{ pressed: boolean }` | Toggle label / icon. `pressed` reflects the current state for conditional content. |
+
+---
+
+## Behavior
+
+| Concern | Behavior |
+|---|---|
+| **Controlled vs uncontrolled** | When `parcel.value` is present the internal model mirrors it via a watcher; otherwise the headless primitive self-manages from a released start. |
+| **Domain-agnostic key** | The public key is `value` (not the primitive's `pressed`/`modelValue`); the mapping to the primitive happens inside the component. |
+| **Disabled** | `parcel.disabled` or a fallthrough `disabled` attr sets the disabled state and the `disabled` root class. |
+| **Pressed styling** | The primitive's `data-state="on"` drives the pressed appearance — no JS branching in the template. |
+| **Passthrough** | Non-Furo attributes (`aria-label`, `name`, …) fall through to the root (`inheritAttrs: false` + `v-bind="$attrs"`). |
+
+---
+
+## Usage
+
+```vue
+<!-- Uncontrolled, starts released -->
+<FuroToggle aria-label="Bold">
+  <Icon name="ph:text-b-bold" />
+</FuroToggle>
+
+<!-- Controlled via v-model:value -->
+<FuroToggle
+  v-model:value="isItalic"
+  aria-label="Italic"
+  @change-value="onChangeValue({ payload: $event })"
+>
+  Italic
+</FuroToggle>
+
+<!-- Outline variant, large -->
+<FuroToggle :parcel="{ variant: 'outline', size: 'lg' }">
+  Grid view
+</FuroToggle>
+```
+
+---
+
+## Composition notes
+
+- Imports nothing from the app — no GraphQL, PrimeVue, Vue Router, or Nuxt-specific imports.
+- All logic lives in `FuroToggleContext`: extract-only getters (`parcel`, `internalValueRef`), boolean methods (`isControlled()`, `isDisabled()`, `isPressed()`), and the change handler that emits both channels.
+- CSS is wrapped in `@layer furo`; dimensions use `rem`, `gap` uses `--size-space-*`, and colors reference semantic tokens (`--color-accent`, `--color-border`, `--color-ring`) only.
+
+---
+
+## Testing
+
+- `FuroToggleContext` is fully covered by jsdom unit tests: parcel defaults, `isControlled()` / `isDisabled()` / `isPressed()` split into truthy / falsy describe blocks, `resolveSyncedValue()`, class/attribute extraction, controlled-value sync in `setupComponent()`, and the dual emit in `onChangeValue()`.
+- No SFC mount test: rendering is declarative bindings over the tested context plus the headless primitive's own semantics, verified by manual QA in the playground.
+
+---
+
+## Playground
+
+`/samples/components/playground` → **Toggle** tab. Demonstrates uncontrolled, controlled (`v-model:value`), variants, sizes, and disabled states.

package/docs/furo-tool-bar.md

@@ -0,0 +1,88 @@
+# FuroToolBar
+
+Presentational container that groups interactive controls — buttons, toggles, separators — into a single keyboard-navigable region. Built on a headless toolbar primitive that provides roving focus (Arrow keys move between controls; Tab enters and leaves the toolbar as one stop). It carries no value and emits nothing.
+
+## Summary
+
+| Field | Value |
+|---|---|
+| **Layer** | Molecule |
+| **Path** | `lib/components/molecules/FuroToolBar/` |
+| **Base primitive** | Headless toolbar (`role="toolbar"` with roving focus) |
+| **Composes** | Slotted atoms/molecules (`FuroButton`, `FuroToggle`, `FuroToggleGroup`, `FuroSeparator`) |
+| **Emits** | None |
+| **Orientation** | `horizontal` (default) or `vertical` |
+
+---
+
+## Public API
+
+### Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `parcel` | `ToolBarParcel \| null` | `null` | Reactive data object holding orientation, text direction, and focus-wrap behavior. |
+
+### Parcel keys
+
+| Key | Type | Default | Description |
+|---|---|---|---|
+| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Layout axis. Also sets which Arrow keys move focus and the `aria-orientation`. |
+| `textDirection` | `'toRight' \| 'toLeft'` | `'toRight'` | Reading direction for the contents (`toRight` → left-to-right, `toLeft` → right-to-left). |
+| `loopFocus` | `boolean` | `false` | When `true`, roving focus wraps from the last control back to the first (and vice versa). |
+
+### Emits
+
+None. The toolbar is presentational.
+
+### Slots
+
+| Slot | Description |
+|---|---|
+| default | The controls to group — buttons, toggles, toggle groups, separators. |
+
+---
+
+## Behavior
+
+| Concern | Behavior |
+|---|---|
+| **Orientation** | `parcel.orientation` maps to the `horizontal` / `vertical` root class, the primitive's keyboard axis, and `aria-orientation`. |
+| **Roving focus** | The toolbar is a single Tab stop; Arrow keys move focus across controls. `loopFocus` decides whether focus wraps at the ends. |
+| **Text direction** | `parcel.textDirection` (`toRight` / `toLeft`) maps to the primitive's reading direction; defaults to left-to-right. |
+| **Passthrough** | Extra attributes fall through to the root element (`inheritAttrs: false` + `v-bind="$attrs"`). |
+
+---
+
+## Usage
+
+```vue
+<!-- Editor toolbar with a divider between groups (button text via slot) -->
+<FuroToolBar :parcel="{ orientation: 'horizontal', loopFocus: true }">
+  <FuroButton :parcel="{ variant: 'ghost', size: 'sm' }">Bold</FuroButton>
+  <FuroButton :parcel="{ variant: 'ghost', size: 'sm' }">Italic</FuroButton>
+  <FuroSeparator :parcel="{ orientation: 'vertical' }" />
+  <FuroButton :parcel="{ variant: 'ghost', size: 'sm' }">Link</FuroButton>
+</FuroToolBar>
+```
+
+---
+
+## Composition notes
+
+- Imports nothing from the app — no GraphQL, PrimeVue, Vue Router, or Nuxt-specific imports.
+- All logic lives in `FuroToolBarContext`: an extract-only getter (`orientation`), the direction mapper (`extractTextDirectionValue()`, `toRight`/`toLeft` → `ltr`/`rtl`), one boolean method (`isLoopingFocus()`), and the root class map (`extractRootClassNames()`).
+- CSS is wrapped in `@layer furo`; `gap` uses a `--size-space-*` token, other dimensions use `rem` / `--size-thinnest`, and colors reference semantic tokens only.
+
+---
+
+## Testing
+
+- Context logic (`orientation`, `textDirection`, `isLoopingFocus()`, `extractRootClassNames()`) 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 roving-focus semantics. Rendered output is verified by manual QA in the playground.
+
+---
+
+## Playground
+
+`/samples/components/playground` → **Tool Bar** tab. Demonstrates a horizontal toolbar with looping focus and a vertical toolbar.

package/docs/furo-tooltip.md

@@ -0,0 +1,107 @@
+# FuroTooltip
+
+Hover/focus hint surface shown next to a trigger element — truncated cells, icon-button labels, and action hints. Built on a headless tooltip primitive that handles delay, positioning, dismissal, and `aria-describedby` wiring. It carries a short text (or a rich content slot) and reacts only to open-state changes.
+
+## Summary
+
+| Field | Value |
+|---|---|
+| **Layer** | Molecule |
+| **Path** | `lib/components/molecules/FuroTooltip/` |
+| **Base primitive** | Headless tooltip (`Provider` + `Root` + `Trigger` + `Portal` + `Content`) |
+| **Composes** | The trigger slot content plus a portaled content surface |
+| **Emits** | `open:change` |
+| **Controlled** | Optional via `parcel.open` |
+
+---
+
+## Public API
+
+### Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `parcel` | `TooltipParcel \| null` | `null` | Reactive data object holding text, positioning, delay, disabled, and optional controlled open state. |
+
+### Parcel keys
+
+| Key | Type | Default | Description |
+|---|---|---|---|
+| `text` | `string` | `null` | Tooltip body shown when no `content` slot is supplied. |
+| `side` | `'top' \| 'right' \| 'bottom' \| 'left'` | `'top'` | Edge of the trigger the content prefers. |
+| `align` | `'start' \| 'center' \| 'end'` | `'center'` | Alignment along the chosen side. |
+| `sideOffset` | `number` | `4` | Gap in pixels between trigger and content. |
+| `delayDuration` | `number` | `200` | Delay in milliseconds before the tooltip opens on hover. |
+| `disabled` | `boolean` | `false` | When `true`, the tooltip never opens. |
+| `open` | `boolean \| null` | `null` | When set (non-null), open state is controlled by the consumer; otherwise the component manages it internally. |
+
+### Emits
+
+| Event | Payload | Description |
+|---|---|---|
+| `open:change` | `{ open: boolean }` | Fired whenever the open state changes (hover, focus, or dismissal). |
+
+### Slots
+
+| Slot | Description |
+|---|---|
+| `trigger` | The element the tooltip is anchored to. Focusable by default (rendered as a button). |
+| `content` | Rich tooltip body. Falls back to `parcel.text` when omitted. |
+
+---
+
+## Behavior
+
+| Concern | Behavior |
+|---|---|
+| **Open trigger** | Hover or keyboard focus on the trigger opens the tooltip after `delayDuration`. |
+| **Controlled / uncontrolled** | When `parcel.open` is non-null, the consumer owns the state; otherwise an internal ref tracks it. Either way `open:change` fires. |
+| **Disabled** | `parcel.disabled` forwards to the primitive root so the tooltip never opens. |
+| **Positioning** | `side` / `align` / `sideOffset` bind to the portaled content surface; the primitive flips to stay in view. A pointer arrow is rendered and tracks the trigger. |
+| **Motion** | Content fades + zooms (95% → 100%) on open, anchored to the trigger via the primitive's transform-origin, and fades out on close. Disabled under `prefers-reduced-motion: reduce`. |
+| **Passthrough** | Extra attributes fall through to the trigger (`inheritAttrs: false` + `v-bind="$attrs"`), so consumers can pass `as-child` / `as` to wrap non-button content. |
+
+---
+
+## Usage
+
+```vue
+<!-- Simple text hint -->
+<FuroTooltip :parcel="{ text: 'Copy to clipboard' }">
+  <template #trigger>
+    <FuroButton :parcel="{ label: 'Copy' }" />
+  </template>
+</FuroTooltip>
+
+<!-- Rich content on the right edge -->
+<FuroTooltip :parcel="{ side: 'right', delayDuration: 500 }">
+  <template #trigger>
+    Hover me
+  </template>
+  <template #content>
+    <strong>Last synced</strong> 2 minutes ago
+  </template>
+</FuroTooltip>
+```
+
+---
+
+## Composition notes
+
+- Imports nothing from the app — no GraphQL, PrimeVue, Vue Router, or Nuxt-specific imports.
+- Public parcel keys are value-oriented; none expose the underlying primitive's API.
+- All logic lives in `FuroTooltipContext`: extract-only getters (`text`, `delayDuration`), boolean methods (`isOpenControlled()`, `isDisabled()`), and the open-state resolver/handler (`extractOpenValue()`, `onOpenChange()`).
+- CSS is wrapped in `@layer furo`; dimensions use `rem` and reference only semantic tokens. The surface uses the inverted `--color-primary` / `--color-primary-foreground` pair so it stays high-contrast against white or dark containers in both themes.
+
+---
+
+## Testing
+
+- Context logic is fully covered by jsdom unit tests: `text` / `delayDuration` getters, `extractContentAttributes()`, `extractOpenValue()` (controlled + uncontrolled), and `onOpenChange()` (emits `open:change`, mutates the ref only when uncontrolled). Boolean methods are split into truthy / falsy describe blocks.
+- No SFC mount test: behavior is declarative bindings over the tested context plus the headless primitive's own hover/focus/dismiss semantics. Rendered output is verified by manual QA in the playground.
+
+---
+
+## Playground
+
+`/samples/components/playground` → **Tooltip** tab. Demonstrates default (top), delayed right-side, rich content slot, and disabled tooltips.

package/lib/components/atoms/FuroButton/FuroButtonContext.js

@@ -215,22 +215,22 @@ export default class FuroButtonContext extends BaseFuroContext {
    * Extract ARIA attributes for the button root.
    *
    * @returns {{
-   *   'aria-disabled': 'true' | undefined
-   *   'aria-busy': 'true' | undefined
+   *   'aria-disabled'?: 'true'
+   *   'aria-busy'?: 'true'
    * }}
    */
   extractAriaAttributes () {
     const ariaDisabled = this.isDisabled()
-      ? 'true'
-      : undefined
+      ? { 'aria-disabled': 'true' }
+      : {}
 
     const ariaBusy = this.isLoading()
-      ? 'true'
-      : undefined
+      ? { 'aria-busy': 'true' }
+      : {}
 
     return {
-      'aria-disabled': ariaDisabled,
-      'aria-busy': ariaBusy,
+      ...ariaDisabled,
+      ...ariaBusy,
     }
   }