@openreachtech/furo-vue 1.5.0 → 1.7.0

package/docs/furo-file-field.md

@@ -0,0 +1,163 @@
+# `<FuroFileField>` Interface Specification
+
+`<FuroFileField>` follows the same **architectural split** as [`<FuroTextField>`](./furo-text-field.md): `:parcel` for Furo behavior, **fallthrough** for native `<input>` attributes. Read [`furo-text-field.md`](./furo-text-field.md) first for the `parcel` vs fallthrough rule and for **Event Handler Style in Context** (single object parameter destructuring).
+
+This page documents **only** what differs for a file input atom. The component is specified here; implementation may land in the codebase separately.
+
+---
+
+## Differences from `<FuroTextField>`
+
+### `type` attribute
+
+Always renders `type="file"`. The `type` fallthrough attribute is excluded — the underlying control is always an HTML file input (`<input type="file">`).
+
+### CSS class
+
+`.unit-form-control.file` instead of `.unit-form-control.text`.
+
+### No `parcel.value`
+
+`<FuroTextField>` uses `parcel.value` for a controlled string. **`<FuroFileField>` does not define `parcel.value`.**
+
+Browsers do not allow scripts to set the file input’s value to a user-chosen path for security reasons. Selection state therefore **cannot** be mirrored the same way as text. The parent learns the current `FileList` through **`@change-value`** and `FileFieldEmitPayload` only.
+
+### `parcel` shape
+
+Behavior-controlling props passed as a single object. **No `value` key.**
+
+| Key       | Type      | Required | Default | Description                         |
+|-----------|-----------|----------|---------|-------------------------------------|
+| `invalid` | `boolean` | No       | `false` | Applies invalid/error visual state. |
+
+> All values must be **JSON-serializable** (no functions, no class instances).
+
+### `multiple` selection
+
+Single or multiple files are supported according to the native **`multiple`** attribute. **`multiple` is only a fallthrough HTML attribute** on `<FuroFileField>` (forwarded to the `<input>`). It is **not** part of `parcel`.
+
+On each `@change-value`, the emitted `FileFieldEmitPayload` exposes **`isMultiple()`**, which reads the same **`multiple`** flag on the underlying control (see [`FileFieldEmitPayload` API](#filefieldemitpayload-api) below).
+
+---
+
+## Fallthrough attributes (recommended usage)
+
+Same fallthrough rules as `<FuroTextField>` for attributes that apply to `<input type="file">`. Typical and optional attributes:
+
+| Attribute   | Type      | Description |
+|-------------|-----------|-------------|
+| `name`      | `string`  | Form field name for submission. |
+| `id`        | `string`  | Use with `<label for="...">` for accessibility. |
+| `accept`    | `string`  | Hint for allowed file types (MIME types or extensions per HTML). |
+| `multiple`  | `boolean` | When true, the user may select more than one file. |
+| `required`  | `boolean` | Marks the field as required. |
+| `disabled`  | `boolean` | Disables user interaction. |
+| `capture`   | `string`  | Media capture intent where supported (e.g. mobile). |
+
+> **`placeholder`** and **`autocomplete`** are not listed for file inputs in the same way as text fields; use them only when product and browser behavior justify it.
+
+---
+
+## Emits
+
+Each emit passes a **`FileFieldEmitPayload` instance** directly as the event argument. In the template, `$event` is that `FileFieldEmitPayload` instance.
+
+```js
+// Inside <FuroFileField>
+emit('change-value', FileFieldEmitPayload.create({ rawEvent }))
+```
+
+```html
+<FuroFileField
+  :parcel="context.buildFileFieldParcel()"
+  @change-value="context.onChangeValue({ payload: $event })"
+/>
+```
+
+### `@change-value`
+
+Emitted when the set of selected files **changes** (maps to the native **`change`** event on the file `<input>`).
+
+> **Naming:** Same Furo intent as `<FuroTextField>` — parent reacts to “value changed,” not to raw DOM event names in the public API.
+
+> **Emitter responsibility:** `<FuroFileField>` **always emits** when the user changes the selection. The parent (Context) decides validation and side effects. The component does not cancel an emit based on file content.
+
+### No `@commit-value`
+
+`<FuroTextField>` uses `@commit-value` for blur / Enter. **`<FuroFileField>` does not define `@commit-value`** — there is no equivalent “commit” gesture separate from choosing files.
+
+### No `v-model:value` / `@update:value`
+
+`<FuroTextField>` supports `v-model:value` via `parcel.value` and `@update:value`. **`<FuroFileField>` does not support that pattern** because there is no serializable `parcel.value` and no symmetric “controlled FileList from parent” contract. Future sugar, if any, would be a separate, explicit API and version decision.
+
+---
+
+## Clearing the selection
+
+Because there is no `parcel.value`, the parent cannot “set value to empty” through `parcel` the way a text field does. **Recommended pattern:** remount the component with a changing **`:key`** when the form or step must reset the file input. An implementation may later expose an imperative clear API; this specification does not require it.
+
+---
+
+## Class naming
+
+| Role           | `FuroTextField`        | `FuroFileField`            |
+|----------------|------------------------|----------------------------|
+| Component      | `FuroTextField`        | `FuroFileField`            |
+| Context        | `FuroTextFieldContext` | `FuroFileFieldContext`     |
+| EmitPayload    | `TextFieldEmitPayload` | `FileFieldEmitPayload`     |
+| Parcel typedef | `FuroTextFieldParcel`  | `FuroFileFieldParcel`      |
+
+---
+
+## `FileFieldEmitPayload` API
+
+`FileFieldEmitPayload` extends [`BaseEmitPayload`](../lib/emit-payload/BaseEmitPayload.js). It exposes file selection helpers derived from the underlying `<input type="file">` (`controlElement` from the raw event).
+
+| Member                 | Type                         | Description |
+|------------------------|------------------------------|-------------|
+| `.files`               | `FileList \| Array<File>`    | `controlElement.files`, or an **empty array** if the control is missing. |
+| `.firstFile`           | `File \| null`               | The first selected file, or `null` when the selection is empty or the control is missing. Equivalent to the first element of `.extractFiles()`, or `null`. |
+| `.isMultiple()`        | `boolean`                    | `true` when the control’s **`multiple`** property is set so the user may choose more than one file; `false` when the control is missing or single-file selection only. |
+| `.extractFiles()`      | `Array<File>`                | Snapshot of selected files as a plain array (same order as `.files`). |
+| `.hasEmptySelection()` | `boolean`                    | `true` if there is no selected file (or the control is missing). |
+| `.hasSelectedFiles()`  | `boolean`                    | `true` if at least one file is selected. |
+
+Size limits, MIME checks, and server-side rules stay in the parent Context; `<FuroFileField>` only surfaces selection through the payload.
+
+---
+
+## Example
+
+```html
+<FuroFileField
+  :key="context.fileFieldRemountKey"
+  :parcel="{
+    invalid: context.statusReactive.isFileInvalid,
+  }"
+  name="attachment"
+  accept="image/png,image/jpeg"
+  :multiple="true"
+  :required="true"
+  @change-value="context.onChangeValue({
+    payload: $event
+  })"
+/>
+```
+
+```js
+onChangeValue ({
+  payload
+}) {
+  if (payload.hasEmptySelection()) {
+    this.statusReactive.isFileInvalid = true
+
+    return
+  }
+
+  this.statusReactive.isFileInvalid = !this.validatesSelectedFiles({
+    payload
+  })
+}
+```
+
+---

package/docs/furo-icon.md

@@ -0,0 +1,288 @@
+# FuroIcon
+
+Icon atom rendering the glyphs the library ships plus the ones the consuming application registers, resolved offline. An application that installs its own renderer reaches every other name too.
+
+## Summary
+
+| Field | Value |
+|---|---|
+| **Layer** | Atom |
+| **Path** | `lib/components/atoms/FuroIcon/` |
+| **Base primitive** | Headless offline icon renderer |
+| **Composes** | Nothing, a single glyph |
+| **Emits** | None |
+| **Built-in icon set** | 49 icons, one collection, registered at module load |
+| **Consumer icons** | Registered through `furoIconRegistry` (`@openreachtech/furo-vue/icons`) |
+| **Every other name** | Drawn by the renderer the application installs, registry first |
+
+Every other Furo component renders its icons through this atom, including the ones whose icon name comes from the consumer, such as a sidebar item. A consumer reaches for the atom directly mainly when overriding another component's icon slot.
+
+## Public API
+
+### Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `name` | `string` | required | Icon name including its collection prefix, for example `ph:check`. Resolvable when the library ships it, the application registered it, the installed resolver returns data for it, or the installed renderer draws it. |
+| `size` | `string \| number \| null` | `null` | One CSS length applied to both axes. When unset, the glyph is `1em` and scales with the surrounding text. |
+
+This atom takes `name` and `size` directly rather than a `parcel`, because it carries no value and has no state: a glyph identifier and a box are the whole input.
+
+### Slots
+
+None. `FuroIcon` is the leaf that renders the glyph; to swap an icon, override the slot on the component that renders it.
+
+### Events
+
+None.
+
+## Registering the application's own icons
+
+Resolution is offline, so an icon draws only from data the library holds. `furoIconRegistry` is the seam that lets an application hand over its own.
+
+```js
+import { furoIconRegistry } from '@openreachtech/furo-vue/icons'
+```
+
+The same registry is re-exported from the package root, so `import { furoIconRegistry } from '@openreachtech/furo-vue'` works too. Register once at application start, before the first render. On a server the registry is a module singleton shared across requests, so never register per request.
+
+### Register a whole icon set
+
+```js
+furoIconRegistry.registerIconSet({
+  iconSet: applicationIconSet,
+})
+```
+
+An icon set is a plain object, the interchange shape every published icon-data package already uses:
+
+```js
+const applicationIconSet = {
+  prefix: 'app-icons',
+  width: 256,
+  height: 256,
+  icons: {
+    house: { body: '<path fill="currentColor" d="…" />' },
+    gear: { body: '<path fill="currentColor" d="…" />' },
+  },
+  aliases: {
+    home: { parent: 'house' },
+  },
+}
+```
+
+Every name the set carries becomes `<prefix>:<name>`, so the example above registers `app-icons:house`, `app-icons:gear` and `app-icons:home`. A set with no `prefix` registers its keys verbatim, which is how a set of already-prefixed names is handed over.
+
+A set is stored whole or not at all: one icon carrying no `body`, or one alias whose `parent` is outside the set, costs the whole set its registration. Nothing it carried is recorded, so every one of its names fails loudly at render rather than drawing blank.
+
+A published set can run to thousands of icons, and all of it reaches the bundle once it is registered. Register the names the application actually draws:
+
+```js
+const drawnNames = ['house', 'users', 'envelope-simple', 'gear']
+
+furoIconRegistry.registerIconSet({
+  iconSet: {
+    ...publishedIconSet,
+    icons: Object.fromEntries(
+      drawnNames.map(drawnName => [drawnName, publishedIconSet.icons[drawnName]])
+    ),
+    aliases: {},
+  },
+})
+```
+
+### Register one icon
+
+```js
+furoIconRegistry.registerIcon({
+  name: 'app-icons:logo',
+  icon: {
+    body: '<path fill="currentColor" d="…" />',
+    width: 256,
+    height: 256,
+  },
+})
+```
+
+A single icon carries its own `width` and `height`, since it has no set to take defaults from. One carrying no `body` registers nothing, since the renderer would draw nothing for it.
+
+### Install a resolver
+
+A resolver answers for any name no registration covers, which suits an application holding a large set it would rather not register up front.
+
+```js
+furoIconRegistry.useIconResolver({
+  resolver: ({ name }) => applicationIconHash[name] ?? null,
+})
+```
+
+The resolver runs during render, so it must return synchronously: the icon data for a name it knows, `null` for one it does not. Passing `resolver: null` uninstalls it.
+
+Keep it cheap and free of side effects. One render asks it more than once, because the atom decides the renderer, the attributes and the root class map separately, and no result is cached between those questions.
+
+Data the renderer could not draw counts as no answer. A shape carrying no string `body`, or declaring a dimension that is not a number, is rejected exactly as `registerIcon()` rejects it, so a resolver returning junk still reports the name as unresolved rather than drawing a blank box.
+
+### Ask whether a name draws
+
+```js
+furoIconRegistry.hasIcon({ name: 'app-icons:house' })
+```
+
+`hasIcon()` answers for the whole registry: it reads the registrations, then asks the resolver for a name none of them carries. Call `hasRegisteredIcon()` to read the registrations alone, leaving the resolver unasked. To get what the atom would draw rather than whether it would, call `findRenderableIcon()`, which returns the registered name, the resolved icon data, or `null`.
+
+```js
+furoIconRegistry.findRenderableIcon({ name: 'app-icons:house' })
+```
+
+## Handing every other name to your own renderer
+
+Registration scales with the library's surface, not with yours. An application drawing icons from data, a sidebar reading its items from an API for instance, cannot register a name it has not seen yet. Install a renderer and every name the registry lacks goes to it.
+
+```js
+import { Icon } from '#components' // the application's own icon component
+import { furoIconRegistry } from '@openreachtech/furo-vue/icons'
+
+furoIconRegistry.useIconRenderer({
+  component: Icon,
+})
+```
+
+The renderer receives `name` and `size`, which are this atom's own props, so a component taking those two plugs in unchanged. A renderer naming them otherwise is wrapped by the application in a functional component.
+
+`component` takes either the component itself or the name it is globally registered under, so `component: 'Icon'` works wherever `<Icon>` resolves. A name is what the Nuxt module installs, since that is what survives an application renaming its icon component. Pass an extensible object: a component run through `Object.freeze()` cannot be marked raw, and Vue's reactive state would then proxy it.
+
+Resolution stays **registry first**: the registry answers every name it carries, and the installed renderer answers only the rest. The library's own 49 icons therefore keep drawing offline however the renderer is configured, and no application configuration can break them. Replace one built-in glyph with `registerIcon()`, which overwrites that name.
+
+Pass `component: null` to uninstall the renderer and return to registry-only resolution.
+
+### In a Nuxt application
+
+The module wires the application's icon component for you.
+
+```js
+// nuxt.config.js
+export default defineNuxtConfig({
+  modules: [
+    '@nuxt/icon',
+    '@openreachtech/furo-vue/nuxt',
+  ],
+})
+```
+
+It leaves an icon module the application already lists alone, keeping that configuration untouched. It registers a merely installed one. It fails, naming what to install, when the application has neither. Coverage then belongs to that module's configuration, not to this library: a collection outside its bundle costs whatever its own fallback costs.
+
+The module installs the icon component by name, reading `icon.componentName` so an application that renames the component keeps working. Point it somewhere else with its own option, which wins over what the icon module reports.
+
+```js
+// nuxt.config.js
+export default defineNuxtConfig({
+  furoVue: {
+    iconComponentName: 'AppIcon',
+  },
+})
+```
+
+### In a plain Vue application
+
+```js
+import { createIconifyRenderer } from '@openreachtech/furo-vue/icon-renderers'
+import { furoIconRegistry } from '@openreachtech/furo-vue/icons'
+
+furoIconRegistry.useIconRenderer({
+  component: createIconifyRenderer(),
+})
+```
+
+This renderer draws any name in the catalogue, fetching the data it holds none for. It lives at its own subpath so an application staying offline never pulls the fetching client into its bundle.
+
+## An unresolvable name fails loudly
+
+Outside a production build, a name neither registered nor resolved throws, naming the icon and the four ways to draw it. A typo cannot reach a reviewer.
+
+This holds while no renderer is installed. Once one is, the library can no longer tell a typo from a valid name, so it reports nothing: `isUnresolvedIcon()` is false, the `unresolved` class stays off, and the throw stays silent. Silence there is honest, and the diagnosis belongs to the renderer.
+
+In a production build the same name renders the built-in warning glyph, carries the `unresolved` class on the root host element, and colours itself with `--color-warning-text`. The fallback is deliberate. An icon that renders nothing is indistinguishable from an icon the consumer forgot to pass, so the failure hid in plain sight until someone compared the screen against the design.
+
+A nullish `name` is the one case neither mode reports. Nothing was asked for, so nothing draws, no throw fires and the `unresolved` class stays off. `name` is a required prop, so Vue already warns about it, and throwing on top would crash a render for the common case of a name arriving from an API a tick later.
+
+Register every icon set before the first render. An icon set registered after a `FuroIcon` has mounted throws in development, even though production would have drawn the glyph and recovered.
+
+```vue
+<!-- throws in development, draws the warning glyph in production -->
+<FuroIcon name="app-icons:not-registered-yet" />
+```
+
+## Why the property is called `name`
+
+Two properties are named differently by the two renderers, and passing the wrong one fails silently:
+
+| Renderer | Icon property | Size property |
+|---|---|---|
+| The underlying offline renderer | `icon` | `width` and `height` |
+| A framework icon module in a consumer app | `name` | `size` |
+| `FuroIcon` | `name` | `size` |
+
+`FuroIcon` deliberately exposes `name` and `size`, matching the framework module a consumer app is likely to have installed, not the renderer it wraps. `FuroIconContext.buildOfflineRendererAttributes()` holds the mapping for the atom, so the renderer's own property names never reach a call site. Its sibling `buildDelegatedRendererAttributes()` maps nothing, because an installed renderer already takes `name` and `size`. The adapter built by `createIconifyRenderer()` repeats the same mapping in `FuroIconifyRendererContext.extractRendererAttributes()`, being a standalone component rather than something the atom's context drives.
+
+The size mapping matters more than it looks. The offline renderer has no `size` property: passing one would land on the `<svg>` as a meaningless attribute and the glyph would silently fall back to `1em` instead of the size asked for. `FuroIcon` maps `size` onto both `width` and `height`, and omits both when no size is given so the `1em` default still applies.
+
+## Offline resolution
+
+The library's own icon data is registered when the module loads, before the first render, so a built-in icon never flickers in while a lookup is in flight, and no request is made to a remote icon API. The renderer is imported from its offline entry point, which holds no code path that could fetch. The fetching entry point lives only behind the `icon-renderers` subpath, which an offline application never imports.
+
+The consequence is that the library resolves **only** the data it holds: its own 49 icons, plus whatever the application registers or resolves. Registration must go through `furoIconRegistry`, because that is what the atom reads to tell a drawable name from an undrawable one.
+
+An installed renderer changes what is offline, not what the library holds. Whether a delegated name costs a request is the renderer's business: a framework icon module bundling its collections draws offline too, while one falling back to a remote icon API does not.
+
+The renderer binding itself, the one line of the template that chooses between the two components, is verified by manual UAT on the playground rather than by a test. The checklist and the reason are below.
+
+## Adding an icon to the library
+
+Icon data for the library's own components is generated, not hand-written.
+
+```bash
+npm run icons:data
+```
+
+The generator scans `lib/` for icon names, resolves each against the icon collection, and rewrites `lib/components/atoms/FuroIcon/furoIconData.js`. Reference a new icon in a component and then regenerate. Skipping the second step fails the test suite, which asserts that every name referenced under `lib/` has registered data.
+
+This step is for icons the library's own components render. An application's icons never enter this file; they go through `furoIconRegistry`.
+
+## Manual UAT for the renderer binding
+
+One line of `FuroIcon`'s template picks between the two renderers, and no test reaches it: a full SFC mount is infeasible under jest, because the SFC compiles to CommonJS and cannot load the ESM context module. Run this on the playground (`npm run dev`, then the FuroIcon tab) whenever that binding or the module changes.
+
+| # | Step | Expected |
+|---|---|---|
+| 1 | Open the "Registered icons" section | All 49 glyphs draw, no network request for any of them |
+| 2 | Open the "Delegated icons" section | `mdi:`, `lucide:`, `simple-icons:` and `material-symbols:` names all draw |
+| 3 | Read the network panel while step 2 loads | The collections outside the server bundle arrive over the icon API, the library's own do not |
+| 4 | Look at `ph:no-such-icon-anywhere` | Draws nothing and does not throw. The `unresolved` class stays off. Any console output comes from the icon module, not from this library |
+| 5 | Remove `'~/nuxt/index.js'` from `nuxt.config.js` and reload | Step 4's name now throws in development, naming the icon. Every `ph:` name outside the shipped 49 throws with it, because the playground has no resolver of its own |
+| 6 | With the module still removed, reload the "Registered icons" section | All 49 still draw, proving the registry never depended on the renderer |
+| 7 | Restore the module, set `icon: { componentName: 'AppIcon' }` and reload | The delegated names still draw, proving the renderer follows the configured name rather than a hardcoded `Icon` |
+| 8 | Drop `'@nuxt/icon'` from `modules` but keep the package installed | The build succeeds: the module registers the merely installed package. This is the second of its three branches |
+| 9 | Uninstall the package too (`npm rm @nuxt/icon`) | The build fails naming the package to install. Dropping it from `modules` alone never reaches this branch, because the package stays resolvable |
+| 10 | Install a resolver answering one name with undrawable data (`() => ({})`) | That name reports as unresolved and throws in development, proving junk data is not mistaken for an answer |
+
+## Styling
+
+The glyph is filled with `currentColor` and takes its box from `font-size`, so it is styled like text rather than through props.
+
+```vue
+<FuroIcon
+  name="ph:warning"
+  style="font-size: 1.5rem; color: var(--color-warning-text)"
+/>
+```
+
+## Accessibility
+
+- An icon carries no accessible name of its own. Add `aria-hidden="true"` when it is decorative beside a text label.
+- When the icon is the only content of a control, give the interactive ancestor an `aria-label`.
+- Colour comes from the container through `currentColor`, so the icon needs no token of its own.
+
+## Related
+
+- [ADR 0031](adr/0031-library-owned-icons-via-offline-renderer.md): why the library owns its icons, and why the consumer app keeps its own icon module.
+- [ADR 0037](adr/0037-icon-resolution-delegates-registry-first.md): why an installed renderer answers only the names the registry lacks, and what the delegated mode gives up.