@openreachtech/furo-vue 1.5.0 → 1.7.0

package/docs/furo-editor.md

@@ -0,0 +1,304 @@
+# FuroEditor
+
+Rich-text editor organism for chatter-style composition. Built on a headless
+rich-text engine and composed from furo controls (`FuroToolBar`, `FuroButton`,
+`FuroTooltip`, `FuroDropdownMenu`, `FuroDialog`, `FuroTextField`).
+
+FuroEditor is domain-agnostic: it ships formatting, links, paste handling, and the
+mention/attachment *seams*, but never touches GraphQL, network, or domain schemas.
+Mentions are supplied through a search adapter; attachment UI is rendered by the
+consumer through a slot.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `parcel` | `object \| null` | `null` | Configuration + state (see below). |
+
+## Parcel
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `value` | `string` | `''` | HTML content. Controlled — pair with `update:value`. |
+| `placeholder` | `string` | `''` | Empty-state placeholder. |
+| `readOnly` | `boolean` | `false` | Hides the toolbar and makes content non-editable (keeps the bordered surface). |
+| `appearance` | `'editor' \| 'plain'` | `'editor'` | `'plain'` renders content as bare text — no toolbar, border, background, or padding. Implies display-only. |
+| `autofocus` | `boolean \| 'start' \| 'end' \| 'all' \| number` | `false` | Where the caret lands when the editor is created. Read once, at creation (see Focus). |
+| `contentAttributes` | `Record<string, string>` | `{}` | Attributes set on the writing area, for example `aria-label`. Read once, at creation (see Accessibility). |
+| `toolbar` | `Array<Array<string>>` | default | Toolbar layout as groups of action names; separators sit between groups. See Custom toolbar. |
+| `attachedFiles` | `Array<*>` | `[]` | Attachment records held for the consumer; shape is the consumer's own. |
+| `labels` | `object` | built-in | Partial overrides for toolbar tooltips and dialog text (any default label can be replaced). |
+| `mention` | `{ searchMentions }` | absent | Enables `@`-mentions when present (see Mentions). |
+| `image` | `{ uploadImage }` | absent | Enables inline images when present (see Inline images). |
+| `actionOverrides` | `Record<string, fn>` | `{}` | Override the click behavior of a built-in control by name (see Custom actions). |
+
+`mention.searchMentions` is `({ query }) => Promise<Array<{ id, label }>>`. Supplying
+it turns on the mention control and `@` trigger; omit it to disable mentions entirely.
+
+## Events
+
+| Event | Payload | When |
+|-------|---------|------|
+| `update:value` | `string` (HTML) | Content changed (v-model:value). |
+| `change-value` | `{ value }` | Content changed. |
+| `commit-value` | `{ value }` | Editor blurred. |
+| `update:attachedFiles` | `Array<*>` | Attachment list changed (e.g. a removal). |
+| `mention:add` | `{ id, label }` | A mention was inserted. |
+| `files:add` | `{ files }` | Files were dropped or pasted that the editor does not insert itself (see Dropped and pasted files). |
+| `image:error` | `{ file, error }` | An inline-image upload was refused; the rest of the batch continues. |
+
+## Slots
+
+| Slot | Props | Description |
+|------|-------|-------------|
+| `toolbar-start` | `{ command, editor }` | Custom controls prepended to the toolbar. |
+| `toolbar-end` | `{ command, editor, hiddenEntries }` | Custom controls appended to the toolbar. `hiddenEntries` carries the render descriptors for the actions no group named, for drawing a custom overflow menu. |
+| `attachments` | `{ attachedFiles, remove, isEditable }` | Render the attachment UI. `remove` is `({ index }) => void`. |
+| `footer` | — | Content rendered below the editor (e.g. submit row). |
+
+## Toolbar
+
+Formatting controls: text-style dropdown (normal / headings 1–4), text-color dropdown,
+alignment dropdown (left / center / right / justify), and toggles for bold, italic,
+underline, strikethrough, bullet list, numbered list, blockquote, link, and (when
+enabled) mention. Active state is reflected per control.
+
+## Content typography
+
+The writing surface renders Body/Medium, and each heading renders a composite text
+role at semibold weight, so a size never arrives paired with a line height the design
+does not draw.
+
+| Element | Role | Size | Line height |
+|---------|------|------|-------------|
+| Body text | `--font-body-medium` | `0.84375rem` | `1.25rem` |
+| `h1` | `--font-headline-large` | `1.5rem` | `2rem` |
+| `h2` | `--font-headline-medium` | `1.25rem` | `1.75rem` |
+| `h3` | `--font-headline-small` | `1.125rem` | `1.75rem` |
+| `h4` | `--font-label-medium` | `0.9375rem` | `1.5rem` |
+
+Every value is `rem`, so the whole surface scales with the reader's root font size.
+
+`h4` renders Label/Medium because the type ramp carries no `1rem` step; `0.9375rem` is
+the step below the `1.125rem` its `h3` renders. Override any of these by redefining the
+token, which re-themes every component that reads it, or by restyling the heading in
+your own layer.
+
+## Copy-paste behavior
+
+Paste is handled in layers so external content lands cleanly:
+
+1. **Plain-text normalization** — CRLF/CR collapse to LF; 3+ blank lines collapse to one.
+2. **HTML sanitization** — pasted `font-family` / `font-size` declarations are stripped so external typography does not override the editor.
+3. **Markdown auto-convert** — text that looks like Markdown is converted to HTML on paste.
+4. **Newline preservation** — multi-line plain text keeps its empty lines (the default engine collapses runs of newlines), and Markdown links / bare URLs in pasted text become real links.
+
+## Custom toolbar
+
+`parcel.toolbar` defines the toolbar as an array of **groups**, each group an array
+of action names. A vertical separator is rendered between groups, so reordering,
+adding, removing, and re-grouping actions (and thus separators) is fully declarative.
+
+Available names: `heading`, `color`, `align` (dropdowns); `bold`, `italic`,
+`underline`, `strike`, `bulletList`, `orderedList`, `blockquote`, `link`, `image`,
+`mention` (controls); `overflow` (menu). `mention` is dropped unless a mention
+adapter is supplied, and `image` is dropped unless an image adapter is supplied.
+
+Outside a production build, a name outside that vocabulary throws, naming the value
+and listing what the toolbar accepts. A production build drops it instead. Watch the
+two list controls in particular: they are named `bulletList` and `orderedList`, while
+the labels that title them are keyed `bullets` and `numbers`.
+
+```js
+// Bold/italic, then heading, then link/quote — three groups, two separators.
+toolbar: [
+  ['bold', 'italic'],
+  ['heading'],
+  ['link', 'blockquote'],
+]
+```
+
+When omitted, the default layout is:
+`[['heading','color','align'], ['bold','italic','underline','strike'], ['bulletList','orderedList','blockquote'], ['link', 'mention'?]]`.
+
+## Overflow
+
+A narrow toolbar parks the rest of its actions behind `overflow`, which renders a `…`
+menu holding every default action no group named. The commands, labels and active
+states stay inside the component, so a compact toolbar costs one word:
+
+```js
+// Bold and italic stay on the bar; heading, colour, align, underline, strike,
+// the two lists, quote and link move into the menu.
+toolbar: [
+  ['bold', 'italic'],
+  ['overflow'],
+]
+```
+
+A hidden dropdown becomes a submenu carrying its own options, and a hidden control
+becomes a single row. Each row draws the same icon the on-bar control would, a
+toggle row marks itself when its formatting is active, and colour rows keep their
+swatch. When the groups already name every action, `overflow` renders nothing rather
+than an empty menu. Override the `…` trigger's accessible name through the `overflow`
+key of `parcel.labels`.
+
+To draw the menu yourself instead, read `hiddenEntries` off the `toolbar-end` slot and
+leave `overflow` out of the groups. Both paths expose the same descriptors:
+
+```vue
+<template #toolbar-end="{ hiddenEntries }">
+  <MyOverflowMenu :entries="hiddenEntries" />
+</template>
+```
+
+## Custom actions
+
+Two seams let consumers extend or change the toolbar without forking the component:
+
+- **Add controls** — render your own buttons in the `toolbar-start` / `toolbar-end`
+  slots. Each slot exposes `command` (the command sub-context: `toggleNodeOrMark`,
+  `executeDropdownCommand`, `insertText`, `applyLink`, `isActive`, …) and `editor`
+  (the raw engine instance), so a custom control can drive the editor directly.
+- **Override built-ins** — `parcel.actionOverrides` maps a built-in control name
+  (`bold`, `italic`, `underline`, `strike`, `bulletList`, `orderedList`,
+  `blockquote`, `link`, `image`, `mention`) to `({ control, command, editor }) => void`.
+  When present, the override runs instead of the default behavior for that control.
+
+```vue
+<FuroEditor
+  :parcel="{
+    actionOverrides: {
+      link: ({ editor }) => myCustomLinkFlow(editor),
+    },
+  }"
+>
+  <template #toolbar-end="{ command }">
+    <FuroButton :parcel="{ variant: 'ghost', size: 'sm' }" @click="command.insertText({ text: '✦ ' })">
+      Insert ✦
+    </FuroButton>
+  </template>
+</FuroEditor>
+```
+
+## Inline images
+
+Supply `parcel.image.uploadImage` to enable embedding images **inside the content**
+(distinct from `attachedFiles`, which render below the editor via the slot). The
+adapter is `({ file }) => Promise<{ src, alt? }>` — the consumer uploads the file and
+returns the URL to embed; the library never uploads anything itself.
+
+When the adapter is present, an `image` toolbar control appears, and three triggers
+insert inline images:
+
+- **Toolbar button** — opens a native multi-image file picker.
+- **Paste** — image files on the clipboard are uploaded and inserted at the cursor.
+- **Drag & drop** — image files dropped onto the editor are inserted at the drop point.
+
+```js
+image: {
+  uploadImage: async ({ file }) => {
+    const url = await myUploadService.put(file)
+    return { src: url, alt: file.name }
+  },
+}
+```
+
+Available names include `image` for `parcel.toolbar` ordering. Omit the adapter to
+disable inline images entirely (the control and the paste/drop handlers stay off).
+
+An adapter that rejects refuses that one file: the editor emits `image:error` with
+`{ file, error }` and moves on to the next file in the batch, so four accepted pictures
+still land when the fifth is turned away.
+
+## Dropped and pasted files
+
+Files the editor does not embed itself reach the consumer through `files:add`, carrying
+`{ files }` as an array of `File`. That is every dropped or pasted file when no image
+adapter is supplied, and every non-image file when one is. Images the editor uploads and
+inserts inline never arrive this way, because it consumed them.
+
+A drop that carries files is claimed by the editor, so the browser never navigates away
+from the page. A paste is left alone, so pasted text and HTML still land as before.
+
+```vue
+<FuroEditor
+  :parcel="{ value: htmlRef }"
+  @files:add="attachFiles($event.files)"
+/>
+```
+
+## Focus
+
+`parcel.autofocus` says where the caret lands when the editor is created: `true`,
+`'start'`, `'end'`, `'all'`, a document position, or `false` (the default). It is read
+once, while the editor is being built, so changing it later focuses nothing. To focus an
+editor that already exists, call `focusChain()` on the command context.
+
+## Accessibility
+
+`parcel.contentAttributes` sets attributes on the writing area, which is how a consumer
+gives it an accessible name:
+
+```js
+contentAttributes: {
+  'aria-label': 'Write a comment',
+}
+```
+
+Like `placeholder`, it is read once while the editor is being built. Toolbar controls
+name themselves from their labels, so every icon-only control and dropdown ships an
+`aria-label` that `parcel.labels` overrides along with the tooltip text.
+
+## Mentions
+
+Supply `parcel.mention.searchMentions`. As the user types after `@`, the adapter is
+queried with `{ query }` and returns `{ id, label }` items shown in a popup; selecting
+one inserts a mention node and emits `mention:add`. The library performs no fetching —
+the consumer's adapter owns the data source.
+
+## Example
+
+```vue
+<FuroEditor
+  :parcel="{
+    value: htmlRef,
+    placeholder: 'Write something…',
+    mention: { searchMentions },
+    attachedFiles,
+  }"
+  @update:value="htmlRef = $event"
+  @update:attached-files="attachedFiles = $event"
+  @mention:add="onMentionAdd"
+>
+  <template #attachments="{ attachedFiles, remove, isEditable }">
+    <!-- consumer-owned attachment UI -->
+  </template>
+</FuroEditor>
+```
+
+## Future enhancements (planned)
+
+**Markdown-driven image input + extensibility (option C).** Not built yet — current
+inline-image support (toolbar / paste / drop) is considered sufficient for now. When
+this is picked up, do all three parts together:
+
+1. **Expose an extension seam** — surface `parcel.extensions: Array<AnyExtension>`
+   through to `buildEditorExtensions` (the internal `extraExtensions` param already
+   exists; it just isn't wired to the parcel/SFC yet). This lets consumers plug in any
+   future input style (markdown shortcuts, slash commands, emoji, …) without forking
+   the core. This is the primary lever for handling diverse input modes.
+2. **Decouple Image-node registration from the upload adapter** — e.g. allow
+   `parcel.image: true | { uploadImage }`. `true` registers the Image node so
+   URL-based images (markdown `![](url)`, pasted URLs) render *without* requiring an
+   upload adapter; the object form additionally enables file upload. Today the Image
+   node is registered only when `parcel.image.uploadImage` is present, which couples
+   plain URL images to the upload path.
+3. **Ship a markdown-image input rule** — an opt-in Tiptap input rule so typing
+   `![alt](url)` auto-converts to an image as you type (paste of `![alt](url)` already
+   works today via the markdown-paste layer + `marked`). Domain-agnostic; plugs in via
+   the seam from (1).
+
+Note: markdown image syntax refers to an existing URL, so it intentionally bypasses
+`uploadImage` (there is no file to upload) — which is why part (2) is needed for the
+markdown path to work independently of the upload adapter.

package/docs/furo-email-field.md

@@ -0,0 +1,93 @@
+# `<FuroEmailField>` Interface Specification
+
+`<FuroEmailField>` follows the same architecture as [`<FuroTextField>`](./furo-text-field.md). Read that document first — this page only lists the differences.
+
+---
+
+## Differences from `<FuroTextField>`
+
+### `type` attribute
+
+Always renders `type="email"`. The `type` fallthrough attribute is excluded — the underlying control is always an HTML email input (`<input type="email">`), which enables the browser’s built‑in email format hints and constraint validation API where supported.
+
+### CSS class
+
+`.unit-form-control.email` instead of `.unit-form-control.text`.
+
+### `parcel.value` type
+
+| Component           | `parcel.value` type        |
+|---------------------|----------------------------|
+| `<FuroTextField>`   | `string \| number \| null` |
+| `<FuroEmailField>`  | `string \| null`           |
+
+Email fields only accept textual values; numeric `parcel.value` is not supported.
+
+### Class naming
+
+All class and type names are prefixed with `Email` instead of `Text`:
+
+| Role           | `FuroTextField`           | `FuroEmailField`               |
+|----------------|---------------------------|--------------------------------|
+| Component      | `FuroTextField`           | `FuroEmailField`               |
+| Context        | `FuroTextFieldContext`    | `FuroEmailFieldContext`        |
+| EmitPayload    | `TextFieldEmitPayload`    | `EmailFieldEmitPayload`        |
+| Parcel typedef | `FuroTextFieldParcel`     | `FuroEmailFieldParcel`         |
+
+### `EmailFieldEmitPayload`
+
+`EmailFieldEmitPayload` extends [`BaseEmitPayload`](../lib/emit-payload/BaseEmitPayload.js) with no additional members beyond the shared text-field helpers. The API (`.value`, `.extractTrimmedValue()`, `.hasEmptyText()`, `.hasEnteredTrimmedText()`, etc.) matches [`TextFieldEmitPayload`](./furo-text-field.md#textfieldemitpayload-api), which also extends `BaseEmitPayload`.
+
+Structured email validation (format, domain rules, uniqueness) stays in the parent Context; `<FuroEmailField>` does not enforce a format beyond what the native `email` input type provides.
+
+---
+
+## Fallthrough attributes (recommended usage)
+
+Same fallthrough rules as `<FuroTextField>`. Typical pairings:
+
+| Attribute      | Typical value   | Notes |
+|----------------|-----------------|-------|
+| `autocomplete` | `email`         | Single email field; use `username` only when it doubles as login identifier per HTML autofill guidelines. |
+| `name`         | e.g. `email`    | Stable form field name for submission. |
+| `placeholder`  | Free text       | UX hint only — not a substitute for an accessible label. |
+
+Optional native attributes remain available when passed as fallthrough (for example `required`, `disabled`, `readonly`, `maxlength`, `pattern`) per project needs.
+
+---
+
+## Example
+
+```html
+<FuroEmailField
+  :parcel="{
+    value: context.emailRef.value,
+    invalid: context.statusReactive.isEmailInvalid,
+  }"
+  :required="true"
+  placeholder="you@example.com"
+  name="email"
+  autocomplete="email"
+  @change-value="context.onChangeValue({
+    payload: $event
+  })"
+/>
+```
+
+```js
+onChangeValue ({
+  payload
+}) {
+  if (payload.hasEmptyTrimmedText()) {
+    this.statusReactive.isEmailInvalid = true
+
+    return
+  }
+
+  this.statusReactive.isEmailInvalid = !this.validatesEmail({
+    payload
+  })
+}
+```
+
+---

package/docs/furo-empty-state.md

@@ -0,0 +1,97 @@
+# FuroEmptyState
+
+Presentational placeholder shown when a region has no content to display — no views, no records, or nothing found. Title and description text come from the parcel so the consumer owns the wording; an icon and action controls are supplied via slots. It carries no value and emits nothing.
+
+## Summary
+
+| Field | Value |
+|---|---|
+| **Layer** | Molecule |
+| **Path** | `lib/components/molecules/FuroEmptyState/` |
+| **Base primitive** | None — a styled centered block (no headless primitive needed) |
+| **Composes** | Nothing (action slot typically hosts `FuroButton`) |
+| **Emits** | None |
+
+---
+
+## Public API
+
+### Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `parcel` | `EmptyStateParcel \| null` | `null` | Reactive data object holding the title and description text. |
+
+### Parcel keys
+
+| Key | Type | Default | Description |
+|---|---|---|---|
+| `title` | `string` | — | Heading text. Rendered only when supplied; the consumer owns the wording. |
+| `description` | `string` | — | Supporting text under the title. Rendered only when supplied. |
+
+### Emits
+
+None. The empty state is presentational; wire actions through the `action` slot.
+
+### Slots
+
+| Slot | Description |
+|---|---|
+| `icon` | Leading icon or illustration above the title. |
+| `action` | Action controls (e.g. a "Create" `FuroButton`) below the text. |
+
+---
+
+## Behavior
+
+| Concern | Behavior |
+|---|---|
+| **Title / description** | `title` and `description` getters extract from `parcel` (null when absent). Each block renders only when its text is present, so there are no hardcoded strings. |
+| **Icon / action** | Rendered only when the matching slot is provided. |
+| **Semantics** | Plain visible content; the consumer announces the empty state on the surrounding region when needed. |
+| **Passthrough** | Extra attributes fall through to the root (`inheritAttrs: false` + `v-bind="$attrs"`). |
+
+---
+
+## Usage
+
+```vue
+<!-- No records, with icon and action -->
+<FuroEmptyState
+  :parcel="{
+    title: 'No records yet',
+    description: 'Create your first record to see it listed here.',
+  }"
+>
+  <template #icon>
+    <Icon name="ph:tray" />
+  </template>
+  <template #action>
+    <FuroButton>Create record</FuroButton>
+  </template>
+</FuroEmptyState>
+
+<!-- Title only -->
+<FuroEmptyState :parcel="{ title: 'Nothing to show' }" />
+```
+
+---
+
+## Composition notes
+
+- Imports nothing from the app — no GraphQL, PrimeVue, Vue Router, or Nuxt-specific imports.
+- All logic lives in `FuroEmptyStateContext` as extract-only getters (`title`, `description`).
+- CSS is wrapped in `@layer furo`; spacing uses `--size-space-*` for `gap`, text colors reference semantic `--color-foreground` / `--color-muted-foreground` tokens only.
+
+---
+
+## Testing
+
+- Context logic (`title` / `description` getters) is fully covered by jsdom unit tests, including the empty-parcel and null-parcel fallbacks.
+- No SFC mount test: behavior is declarative bindings over the tested context. Rendered output (icon / title / description / action) is verified by manual QA in the playground.
+
+---
+
+## Playground
+
+`/samples/components/playground` → **Empty State** tab. Demonstrates a no-records state with icon + action, a no-results state with icon only, and a title-only state.

package/docs/furo-error-state.md

@@ -0,0 +1,97 @@
+# FuroErrorState
+
+Presentational placeholder shown when a region fails to load — a fetch error or a failed request. Title and description text come from the parcel so the consumer owns the wording; an icon and action controls (typically a retry button) are supplied via slots. It carries no value and emits nothing.
+
+## Summary
+
+| Field | Value |
+|---|---|
+| **Layer** | Molecule |
+| **Path** | `lib/components/molecules/FuroErrorState/` |
+| **Base primitive** | None — a styled centered block (no headless primitive needed) |
+| **Composes** | Nothing (action slot typically hosts `FuroButton`) |
+| **Emits** | None |
+
+---
+
+## Public API
+
+### Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `parcel` | `ErrorStateParcel \| null` | `null` | Reactive data object holding the title and description text. |
+
+### Parcel keys
+
+| Key | Type | Default | Description |
+|---|---|---|---|
+| `title` | `string` | — | Heading text. Rendered only when supplied; the consumer owns the wording. |
+| `description` | `string` | — | Supporting text under the title. Rendered only when supplied. |
+
+### Emits
+
+None. The error state is presentational; wire the retry through the `action` slot.
+
+### Slots
+
+| Slot | Description |
+|---|---|
+| `icon` | Leading icon or illustration above the title. |
+| `action` | Action controls (e.g. a "Retry" `FuroButton`) below the text. |
+
+---
+
+## Behavior
+
+| Concern | Behavior |
+|---|---|
+| **Title / description** | `title` and `description` getters extract from `parcel` (null when absent). Each block renders only when its text is present, so there are no hardcoded strings. |
+| **Icon / action** | Rendered only when the matching slot is provided. |
+| **Semantics** | Root carries `role="alert"` so assistive technology announces the failure; the icon uses the destructive color token. |
+| **Passthrough** | Extra attributes fall through to the root (`inheritAttrs: false` + `v-bind="$attrs"`). |
+
+---
+
+## Usage
+
+```vue
+<!-- Fetch failed, with icon and retry action -->
+<FuroErrorState
+  :parcel="{
+    title: 'Failed to load records',
+    description: 'Check your connection and try again.',
+  }"
+>
+  <template #icon>
+    <Icon name="ph:warning-circle" />
+  </template>
+  <template #action>
+    <FuroButton @click="refetch">Retry</FuroButton>
+  </template>
+</FuroErrorState>
+
+<!-- Title only -->
+<FuroErrorState :parcel="{ title: 'Unable to load' }" />
+```
+
+---
+
+## Composition notes
+
+- Imports nothing from the app — no GraphQL, PrimeVue, Vue Router, or Nuxt-specific imports.
+- All logic lives in `FuroErrorStateContext` as extract-only getters (`title`, `description`).
+- CSS is wrapped in `@layer furo`; spacing uses `--size-space-*` for `gap`, the icon references the semantic `--color-destructive-text` token and text colors reference `--color-foreground` / `--color-muted-foreground` only.
+
+---
+
+## Testing
+
+- Context logic (`title` / `description` getters) is fully covered by jsdom unit tests, including the empty-parcel and null-parcel fallbacks.
+- No SFC mount test: behavior is declarative bindings over the tested context. Rendered output (icon / title / description / action) is verified by manual QA in the playground.
+
+---
+
+## Playground
+
+`/samples/components/playground` → **Error State** tab. Demonstrates a fetch-failed state with icon + retry action, a server-error state with icon only, and a title-only state.