@openreachtech/furo-vue 1.6.0 → 2.0.0

package/docs/furo-alert-dialog.md

@@ -0,0 +1,107 @@
+# FuroAlertDialog
+
+Organism — a confirm / destructive overlay built on a headless alert-dialog
+primitive (`Root` + `Portal` + `Overlay` + `Content` + `Title` + `Description` +
+`Action` + `Cancel`). Unlike `FuroDialog`, it forces an explicit decision: there
+is no built-in close button, outside-click never dismisses it, and it ships with
+confirm / cancel action buttons. Domain-agnostic: no GraphQL, router, or Nuxt imports.
+
+Location: `lib/components/organisms/FuroAlertDialog/`
+
+## Props
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `parcel` | `FuroAlertDialogParcel \| null` | `null` | Reactive behavior object (below) |
+
+### `parcel`
+
+| Key | Type | Default | Notes |
+|-----|------|---------|-------|
+| `open` | `boolean` | — | Controlled open state. When set, the parent owns open/close. When omitted, the dialog manages its own state. |
+| `disabled` | `boolean` | `false` | Disables the trigger. |
+| `title` | `string \| null` | `null` | Heading text. Provide a title (or the `title` slot) for accessibility. |
+| `description` | `string \| null` | `null` | Sub-heading text below the title. |
+| `confirmText` | `string` | `'Confirm'` | Label for the built-in confirm button. |
+| `cancelText` | `string` | `'Cancel'` | Label for the built-in cancel button. |
+| `tone` | `'default' \| 'destructive'` | `'default'` | `destructive` renders the confirm button with the destructive variant. |
+| `closeOnEscape` | `boolean` | `true` | `false` ignores the Escape key. |
+| `size` | `'sm' \| 'default' \| 'lg'` | `'default'` | Content width variant. |
+| `busy` | `boolean` | `false` | While `true`, dismissal is blocked and the action buttons are disabled (confirm shows a loading state) — use during async confirm. |
+| `initialFocus` | `string \| null` | `null` | CSS selector (scoped to the content) of the element to focus on open. When unset, the cancel button is focused. |
+
+## Events
+
+| Event | Payload | When |
+|-------|---------|------|
+| `confirm` | — | The confirm action was chosen. |
+| `cancel` | — | The cancel action was chosen (button or Escape). |
+| `update:open` | `boolean` | Open state changed — enables `v-model:open`. |
+| `open:change` | `{ open: boolean }` | Open state changed (semantic form). |
+
+## Slots
+
+| Slot | Purpose |
+|------|---------|
+| `trigger` | Optional element that opens the dialog. Rendered via `as-child`. Omit when opened via controlled `open`. |
+| `title` | Overrides the heading (falls back to `parcel.title`). |
+| `description` | Overrides the description (falls back to `parcel.description`). |
+| default | Optional body content rendered between the heading and the footer. |
+| `footer` | Overrides the built-in confirm / cancel buttons. Receives `confirm()` and `cancel()` slot props. |
+
+## Usage
+
+### Basic confirm
+
+```vue
+<FuroAlertDialog
+  :parcel="{ title: 'Are you sure?', description: 'Confirm to continue.' }"
+  @confirm="onConfirm"
+  @cancel="onCancel"
+>
+  <template #trigger>
+    <button type="button">Open confirm</button>
+  </template>
+</FuroAlertDialog>
+```
+
+### Destructive
+
+```vue
+<FuroAlertDialog
+  :parcel="{
+    title: 'Delete record',
+    description: 'This action cannot be undone.',
+    tone: 'destructive',
+    confirmText: 'Delete',
+  }"
+  @confirm="deleteRecord"
+>
+  <template #trigger>
+    <button type="button">Delete…</button>
+  </template>
+</FuroAlertDialog>
+```
+
+### Controlled (`v-model:open`) with async confirm
+
+```vue
+<FuroAlertDialog
+  :parcel="{ open: isOpen, title: 'Saving…', busy: isSaving }"
+  @confirm="save"
+  @open:change="isOpen = $event.open"
+/>
+```
+
+While `busy` is `true`, the buttons are disabled and Escape is ignored, so the
+overlay stays open until the parent resolves the async work and clears `open`.
+
+## Notes
+
+- The content is portaled to the document body; overlay and content carry
+  `unit-alert-dialog-overlay` / `unit-alert-dialog-content` classes inside `@layer furo`.
+- Always provide a title (text or slot) — it is the dialog's accessible name.
+- A description is optional. Without `parcel.description` or a `description` slot the content declares no described-by target, so the headless primitive logs no accessibility warning.
+- Outside-click never dismisses an alert dialog (forced decision). Escape maps to
+  `cancel` unless `closeOnEscape` is `false`.
+- Overlay scrim color reuses the `--furo-dialog-overlay-background` component token.

package/docs/furo-attachment.md

@@ -0,0 +1,133 @@
+# `<FuroAttachment>` Interface Specification
+
+## Overview
+
+`<FuroAttachment>` is a **shipped** attachment molecule in the Furo-Vue component system. It renders a file held on a record the same way everywhere: a row carrying the file's name, its size and a type glyph, or the same file as an image preview.
+
+It is presentational. It carries no value, takes no primitive from a headless library, and never fetches or deletes anything: its two actions report that they were activated and leave the work to the consumer.
+
+**Public SFC prop:** `parcel` only. HTML attributes pass through to the root.
+
+## Summary
+
+| Field | Value |
+|---|---|
+| **Layer** | Molecule |
+| **Path** | `lib/components/molecules/FuroAttachment/` |
+| **Base primitive** | None; a `div` holding the glyph or the preview |
+| **Value** | None |
+| **Emits** | `download`, `remove` |
+| **Composes** | `FuroIcon` for the glyph and the spinner, `FuroButton` for the two actions |
+
+## The preview is a variant, not a second component
+
+The design draws one Attachment with an image axis. Off, it is a file row with a type glyph. On, it is the same file drawn as a preview. Both are this one component: setting `imageSource` turns the preview on.
+
+There is no separate thumbnail component. The reasoning is recorded in [ADR 0034](adr/0034-attachment-absorbs-thumbnail.md): a preview that only ever appears inside an attachment is one state of the attachment rather than a primitive with a contract of its own, and shipping both would leave a consumer choosing between two things the design means as one.
+
+The preview always renders at one size and crop, `9rem` square, cropped to fill. Consistency is the point, so it is not a parcel key; an application that has to move it overrides `--furo-attachment-preview-size`.
+
+## A broken preview shows the glyph
+
+An image source can rot. When the browser fails to load one, the component falls back to the file row and its type glyph rather than leaving a broken image in the layout, so a dead URL costs the reader the picture and nothing else.
+
+The failure is remembered per source. Changing `imageSource` clears it, so a retried upload or a regenerated URL gets a fresh attempt instead of inheriting the previous one's verdict.
+
+## `parcel` keys
+
+| Key | Type | Default | Meaning |
+|---|---|---|---|
+| `fileName` | `string` | `''` | Name shown on the row, and the accessible name of the preview when no alternative text is given. |
+| `fileSize` | `string` | `''` | Size shown under the name, already formatted for reading. Hidden while uploading. |
+| `imageSource` | `string` | `null` | Preview source. Setting it turns on the image shape. |
+| `imageAlternativeText` | `string` | the file name | Alternative text for the preview. |
+| `iconName` | `string` | `'ph:file'` | Glyph the row shows in place of a preview. |
+| `uploading` | `boolean` | `false` | Reports the file as still being sent. |
+| `uploadProgress` | `number \| null` | `null` | Share of the upload already sent, nought through one hundred. Values outside the range are clamped. `null` means the size is unknown. |
+| `downloadable` | `boolean` | `true` | Whether the download action renders. |
+| `removable` | `boolean` | `true` | Whether the remove action renders. |
+| `downloadLabel` | `string` | `'Download'` | Accessible name of the download action. |
+| `removeLabel` | `string` | `'Remove'` | Accessible name of the remove action. |
+| `uploadingLabel` | `string` | `'Uploading'` | Accessible name of the upload bar. |
+
+The size is taken already formatted rather than as a byte count. Formatting one is a locale decision, and an application that shows sizes anywhere else already owns that decision; taking a number here would give it a second, different answer.
+
+## An upload in flight
+
+`uploading` changes what sits under the name and what the actions offer.
+
+| Shape | While uploading |
+|---|---|
+| File row | The size caption is replaced by a bar reporting `uploadProgress`. Only the remove action renders, where it cancels. |
+| Preview | The picture is veiled and a spinner replaces both actions. The design reports no share here, because the preview has no room for a bar. |
+
+The actions are revealed by hover and by focus once the upload settles, but stay visible throughout an upload: a cancel a reader has to hunt for is not a cancel.
+
+## An upload of unknown size
+
+A transport reports how many bytes have left and how many there are in total, but it names the total only once the request announces a computable length. Until then the caller has no denominator and no share to report.
+
+Saying so is `uploadProgress: null`, which is also what an absent key means. The bar then drops `aria-valuenow`, which is what makes an ARIA progress bar indeterminate, drops its inline width, and sweeps a partial fill across the track. Assistive technology hears the bar as running with no share, and a reader sees the same.
+
+Nought is a share like any other, so `uploadProgress: 0` still draws a measured bar sitting at the start. A caller that means "nothing has left yet" passes `0`; a caller that means "nobody knows" passes `null`.
+
+An indeterminate bar carries no number to announce, so the bar takes its accessible name from `uploadingLabel`. The default is `Uploading` and every application overrides it, because the wording is the application's and the language may not be English.
+
+Under `prefers-reduced-motion: reduce` the sweep stops. The fill then spans the track at half opacity, which reads as pending rather than as a share, because a partial fill standing still would read as a share it does not have.
+
+## Events
+
+| Event | Payload | When |
+|---|---|---|
+| `download` | `{ fileName }` | The download action was activated. |
+| `remove` | `{ fileName }` | The remove action was activated, which cancels an upload in flight. |
+
+The payload carries the name so one handler can serve a list of attachments without closing over an index.
+
+## Slots
+
+| Slot | Scope | Purpose |
+|---|---|---|
+| `glyph` | — | Replaces the type glyph on the row. Default: the icon named by `iconName`. |
+| `actions` | — | Replaces the whole action cluster. Default: download, remove, and the upload spinner. |
+
+## Styling
+
+| Part | Class | Notes |
+|---|---|---|
+| Root | `.unit-attachment` | Gains `.image` while a preview renders and `.uploading` while one is in flight |
+| The glyph | `.glyph` | Only rendered by the default slot content |
+| The text column | `.body` | Holds the name and either the size or the bar |
+| The name | `.name` | |
+| The size | `.caption` | |
+| The bar | `.progress`, `.track`, `.fill` | The track is announced as a progress bar; the fill gains `.indeterminate` while the size is unknown |
+| The preview | `.preview` | Cropped to fill its square |
+| The veil | `.veil` | Hidden from assistive technology |
+| The actions | `.actions`, `.action` | A floating pill on the preview shape, an inline pair on the row |
+
+| Custom property | Default | Controls |
+|---|---|---|
+| `--furo-attachment-preview-size` | `9rem` | The side of the preview square |
+
+## Read from the design
+
+| Part | Design value | Token |
+|---|---|---|
+| The row's surface | `#f8fafc` | `--color-muted-subtle` |
+| The row's border | `#f1f2f4` | `--color-brand-border-subtle` |
+| The row's corner | `8px` | `--size-border-radius-medium` |
+| The name | `#22252a`, regular 15px/24 | `--color-foreground-title`, `--font-body-large` |
+| The size | `#646c7d`, regular 12px/20 | `--color-foreground-secondary`, `--font-body-small` |
+| The glyph | `#646c7d` | `--color-foreground-secondary` |
+| The bar's track | `#f1f2f4` | `--color-muted` |
+| The bar's fill | `#3b82f6` | `--color-info` |
+| The spinner | `#3b82f6` | `--color-info-text` |
+| The floating pill's surface | `#ffffff` | `--color-background` |
+| The floating pill's border | `#e0e2e6` | `--color-border` |
+| The pill and the action buttons | fully rounded | `--size-border-radius-full` |
+| The gap between glyph, text and actions | `12px` | `--size-space-compact` |
+| The gap between the two actions | `4px` | `--size-space-tiny` |
+
+The veil over an uploading preview is drawn in the design as white at eighty percent. It is rendered as `--color-background` at that opacity rather than as a fixed white, so it still veils under a dark theme.
+
+The blue the design binds to the bar is its action blue, whose own name in the design is the default surface of that family. The library has no progress role, so the bar takes `--color-info`, the semantic role that already carries that blue. `--color-selected` carries the same value but means "chosen", which a bar reporting an upload is not.