srcdev-nuxt-components 9.6.7 → 9.6.9

package/.claude/skills/components/{input-range-core.md → input-range.md}

@@ -1,15 +1,20 @@
-# InputRangeCore Component
+# InputRange Component
+
+> **Renamed 2026-10-16**: `InputRangeCore` → `InputRange`, `InputRangeDefault` → `InputRangeField`
+> (DOM classes `.input-range-core` → `.input-range`, `.input-range-with-label` →
+> `.input-range-field`; full class list in CONSUMER-STYLING.md). Skill doc renamed from
+> `input-range-core.md`. No consumer app used either old name.
 
 ## Overview
 
-`InputRangeCore` is the low-level native `<input type="range">` primitive for the `05.forms`
+`InputRange` is the low-level native `<input type="range">` primitive for the `05.forms`
 range-slider family. It renders a single native range input with left/right button slots (for
 step-down/step-up controls), an optional `markers` slot for custom tick marks overlaid on the
 track, and an optional `datalist` slot for native tick-mark snapping. It has no label,
-description, or error-message rendering of its own — that's composed by the `InputRangeDefault`
+description, or error-message rendering of its own — that's composed by the `InputRangeField`
 variant below.
 
-Most consumers should reach for **InputRangeDefault** rather than `InputRangeCore` directly.
+Most consumers should reach for **InputRangeField** rather than `InputRange` directly.
 
 ---
 
@@ -20,7 +25,7 @@ Most consumers should reach for **InputRangeDefault** rather than `InputRangeCor
 | Prop (template form) | Type | Default | Notes |
 |------|------|---------|-------|
 | `:id` | `string` | (required) | Applied to the native input. |
-| `:name` | `string` | (required) | Applied to the native input, and used to derive the `list` id when the `datalist` slot is used (`${name}-datalist`). |
+| `:name` | `string` | (required) | Applied to the native input. (Until 2026-10-16 it also built the datalist id, `${name}-datalist`; that id now comes from `useId()`.) |
 | `:min` | `number` | (required) | Native `min`. |
 | `:max` | `number` | (required) | Native `max`. |
 | `:step` | `number` | `1` | Native `step`. |
@@ -28,8 +33,8 @@ Most consumers should reach for **InputRangeDefault** rather than `InputRangeCor
 | `:placeholder` | `string` | `""` | Declared but not rendered — range inputs have no placeholder concept. Kept for prop-shape consistency with sibling `05.forms` components. |
 | `:theme` | `FormUiTheme` | `"default"` | Sets `data-theme` on the wrapper. |
 | `:weight` | `FormWeight` | `"normal"` | Adds an `input-range--{weight}` class to the input. **No CSS in the library currently styles this class — it's a no-op today**, kept for prop-shape consistency with sibling components. |
-| `:field-has-error` | `boolean` | `false` | Declared, but doesn't drive any visible state inside `InputRangeCore` itself — `InputRangeDefault` handles the actual error styling (`data-invalid`/`.error` class) on its own wrapper. |
-| `:style-class-passthrough` | `string \| string[]` | `[]` | Extra CSS classes applied to the input element. |
+| `:field-has-error` | `boolean` | `false` | `data-invalid` on the wrapper and `aria-invalid="true"` on the input (it did nothing here until 2026-10-16). |
+| `:style-class-passthrough` | `string \| string[]` | `[]` | Extra CSS classes applied to the input element. Reacts to changes. |
 | `:aria-describedby` | `string` | `""` | Forwarded to the native input. |
 
 ### v-model
@@ -50,8 +55,8 @@ disable, not a fake default).
 |------|-------|
 | `left` | Rendered before the track (e.g. a step-down button). |
 | `right` | Rendered after the track (e.g. a step-up button). |
-| `markers` | Rendered as an overlay on top of the track (`grid-area: element-stack`, same cell as the input). Adds a `has-markers` class to the input, which shrinks its visible track to a thin `0.2rem` strip and hides the native thumb, so your marker content becomes the primary visual. Expected shape: a `.input-range-markers` wrapper containing `.marker` elements (each optionally containing a `.marker-icon`) — see the component's own scoped CSS for the classes it pre-styles. |
-| `datalist` | Rendered after the input. Must contain a real `<datalist>` element whose `id` matches `${name}-datalist` for the browser to link it via the input's `list` attribute — the component computes that id string for the `list` attribute itself, but does not set the `id` on your slotted `<datalist>` for you. |
+| `markers` | Rendered as an overlay on top of the track (`grid-area: element-stack`, same cell as the input). Sets `data-has-markers` on the wrapper: a line joining the markers is drawn behind them, the input becomes a transparent layer over the whole marker row (so the row is draggable and clickable), and the thumb is restyled as a ring the size of one marker that circles the selected one. That lines up because markers are spaced `space-between` and given an explicit size (icon size + 2 × padding), the same as the thumb. Use one marker per step (`(max - min) / step + 1`). Expected shape: a `.input-range-markers` wrapper containing `.input-range-marker` elements (each optionally containing an `.input-range-marker-icon`); those classes are pre-styled (they were `.marker`/`.marker-icon` until 2026-10-16). |
+| `datalist` | Rendered after the input, with a `datalistId` slot prop: put it on your `<datalist>` (`<template #datalist="{ datalistId }"><datalist :id="datalistId">`) and the input's `list` points at it. The id comes from `useId()`, so two ranges sharing a `name` don't collide. `list` is omitted when the slot is empty. |
 
 ---
 
@@ -93,13 +98,13 @@ was itself commented out.
 
 ## Variants
 
-### InputRangeDefault
+### InputRangeField
 
-`InputRangeDefault` (`InputRangeDefault.vue`) composes `InputRangeCore` with `InputLabel`,
+`InputRangeField` (`InputRangeField.vue`) composes `InputRange` with `InputLabel`,
 `InputDescription`, and `InputError`, plus optional step-down/step-up buttons (`InputButton`)
 wired into the `left`/`right` slots.
 
-**Additional props over InputRangeCore:**
+**Additional props over InputRange:**
 
 | Prop (template form) | Type | Default | Notes |
 |------|------|---------|-------|
@@ -110,11 +115,11 @@ wired into the `left`/`right` slots.
 
 **Slots**: `descriptionHtml`, `descriptionText` (both forwarded to `InputDescription`), plus
 `left`/`right`/`markers`/`datalist` (forwarded straight through to the underlying
-`InputRangeCore` — the step-down/step-up buttons only render when you use the `left`/`right`
+`InputRange`; `markers` wasn't forwarded until 2026-10-16, and `datalist` passes `datalistId` on — the step-down/step-up buttons only render when you use the `left`/`right`
 slots yourself, since the button icon content itself is consumer-supplied via `#iconOnly`).
 
 ```vue
-<InputRangeDefault
+<InputRangeField
   name="priceRange"
   label="Price range"
   v-model="price"
@@ -126,17 +131,47 @@ slots yourself, since the button icon content itself is consumer-supplied via `#
 >
   <template #left><Icon name="mdi:minus" /></template>
   <template #right><Icon name="mdi:plus" /></template>
-</InputRangeDefault>
+</InputRangeField>
 ```
 
-`v-model` is `number`, **required** — same as `InputRangeCore` above.
+`v-model` is `number`, **required** — same as `InputRange` above.
+
+Each step-button press adds or subtracts `step` (its absolute value, or 1 when it's 0), rounds away
+floating-point drift (0.2 + 0.1 gives 0.3) and clamps to `min`/`max`; step-down goes read-only at or
+below `min`, step-up at or above `max`. `:style-class-passthrough` lands on the root
+`.input-range-field` only (it also reached the inner input until 2026-10-16) and reacts to changes.
+The root carries `data-theme` and `data-invalid` (its old `error` class is gone), and the label
+gets `input-range-label` (it was the number field's `input-number-label`, with a non-existent
+`body-normal-bold` utility).
 
 **Fixed 2026-09-21**: removed a dead `deepCssClassPassthrough` prop (declared, never consumed
 anywhere in the component or referenced elsewhere in the codebase) and a dead `<style>` block
 targeting `.input-range-label`/`.label-description` — classes that nothing in this component (or
 `InputLabel`/`InputDescription`) actually renders, so the block had no effect. Also removed two
 dead commented-out lines (`// const id = useId();`, a duplicate no-op `FormUiTheme` computed), and
-(same day, follow-up pass) a `const props = withDefaults(...)` in both `InputRangeCore` and
-`InputRangeDefault` that had become entirely unused once the dead `FormUiTheme` computed was
+(same day, follow-up pass) a `const props = withDefaults(...)` in both `InputRange` and
+`InputRangeField` that had become entirely unused once the dead `FormUiTheme` computed was
 removed — the template's `:id`/`:name`/etc. shorthand bindings resolve straight from `defineProps`
 automatically in `<script setup>`, no destructuring or `props.` reference needed.
+
+---
+
+## Stress pass 2026-10-16
+
+- **Stepping** (`InputRangeField`): 0.1 steps drifted (0.30000000000000004) and a step that didn't
+  divide the range overshot `min`/`max`; the read-only checks used `===`, so an overshot value
+  never disabled the button. Now rounded, clamped, and `<=`/`>=`. A zero or negative `step`
+  steps by its size, or 1.
+- **Datalist id**: was `${name}-datalist`, so two ranges sharing a `name` linked to the same list
+  (rule `ids-from-useid.md`). Now `useId()`, handed to the slot as `datalistId`.
+- **Error state**: `fieldHasError` did nothing on `InputRange`; it now sets `data-invalid` and
+  `aria-invalid`.
+- **Slots**: the Field didn't forward `markers`.
+- **Classes**: bare/generic classes became prefixed classes or data attributes, and the marker
+  defaults moved from dark-page colours to `--theme-*` tokens (CONSUMER-STYLING.md has the
+  mapping). The Field's passthrough no longer reaches the inner input as well as its root.
+- **Overflow**: the slider container gets `min-inline-size: 0` and the step buttons don't
+  shrink; the Field wraps long label, description and error copy.
+- Specs unmount in `afterEach`; stories moved to `StoryObj` with Docs descriptions, a
+  `DecimalSteps` story, `CanvasSwitcher` and a `StressTest` story on the Field. The bare
+  control's step-button demo uses `InputButton`, not raw buttons.

package/.claude/skills/components/input-select.md

@@ -0,0 +1,153 @@
+# InputSelect Component
+
+> **Renamed 2026-10-16**: `InputSelectCore` → `InputSelect`, `InputSelectWithLabel` →
+> `InputSelectField` (DOM classes `.input-select-core` → `.input-select`,
+> `.input-select-with-label` → `.input-select-field`; full class list in CONSUMER-STYLING.md).
+> Skill doc renamed from `input-select-core.md`. A consumer app uses both old names; list its edits
+> privately and apply them when it upgrades.
+
+## Overview
+
+`InputSelect` is the low-level native `<select>` primitive for the `05.forms` select family.
+It renders a native select with a data-driven list of `<option>`s (each optionally decorated with
+an icon), an optional placeholder option, and adopts the modern CSS Customizable Select API
+(`appearance: base-select`) for a fully styleable open-picker state where supported, with a
+graceful CSS fallback (see "Browser support" below). It has no label, description, or
+error-message rendering of its own — that's composed by the `InputSelectField` variant below.
+
+Most consumers should reach for **InputSelectField** rather than `InputSelect` directly.
+
+---
+
+## Props reference
+
+> **Hyphenation rule**: Vue's ESLint config enforces `vue/attribute-hyphenation`. Always write camelCase prop names hyphenated in templates: `:field-has-error`, `:style-class-passthrough`, `:aria-describedby`.
+
+| Prop (template form) | Type | Default | Notes |
+|------|------|---------|-------|
+| `:id` | `string` | (required) | Applied to the native select. |
+| `:name` | `string` | (required) | Applied to the native select. |
+| `:placeholder` | `string` | `""` | Renders a disabled placeholder `<option>`, selected while `modelValue` is `""`, `null` or `undefined` (not `0`). No option rendered at all when unset. |
+| `:title` | `string` | `"Please select an option"` | Native `title` attribute (tooltip). Visitor-facing copy: pass a translated string. |
+| `:required` | `boolean` | `false` | Native `required`. |
+| `:theme` | `FormUiTheme` | `"default"` | Sets `data-theme` on the wrapper. |
+| `:input-variant` | `InputUiVariant` | `"normal"` | Sets `data-input-variant` on the wrapper. `"normal"` (bordered box) and `"underlined"` (bottom border only) have CSS; `"outlined"` doesn't. |
+| `:field-has-error` | `boolean` | `false` | `data-invalid` on the wrapper and `aria-invalid="true"` on the select. |
+| `:style-class-passthrough` | `string \| string[]` | `[]` | Extra CSS classes applied to the select element. Reacts to changes. |
+| `:aria-describedby` | `string` | `""` | Forwarded to the native select; omitted when empty. |
+
+### v-models
+
+- `v-model` — `string | number | readonly number[]`, **required** (`defineModel({ required: true })`, satisfying `vue/require-default-prop` — see `project_ledger_eslint_issues_column` in memory).
+- `v-model:field-data` — `IFormMultipleOptions` (`{ data: IOptionsConfig[]; total; skip; limit }`), **required**. The `data` array drives the rendered `<option>`s; only `data` is read. The template dereferences `fieldData.data` unconditionally, so a consumer that doesn't bind it crashes on render. A one-way `:field-data` works too: the component never writes it.
+- `v-model:is-dirty` — `boolean`. Set to `true` on the native `change` event (never reset to `false` by this component). Reflected as `data-dirty` on the wrapper.
+- `v-model:is-active` — `boolean`. Tracks native focus/blur (`focusin`/`focusout`). Reflected as `data-active` on the wrapper.
+
+### Option icons
+
+An `IOptionsConfig` item with `icon` renders an `<Icon class="input-select-option-icon">`
+(`aria-hidden`) before its label. It only shows where `appearance: base-select` is supported; a
+native dropdown renders option text only. Labels render as text, never as markup.
+
+---
+
+## CSS token API
+
+See [CONSUMER-STYLING.md](../../app/components/05.forms/input-select/CONSUMER-STYLING.md) for the
+full table with defaults and the state hooks.
+
+**Common tokens:**
+
+- `--input-select-surface` / `-surface-hover` — wrapper/select background and option-row hover background
+- `--input-select-text-color` — select text colour
+- `--input-select-border` / `-border-hover` / `-border-focus` — border colour resting, mouse-hover outline, and `:focus-visible` outline (also the open picker's border/outline)
+- `--input-select-option-gap` / `-option-icon-size` — option icon spacing and size
+
+**State hooks** (on `.input-select-wrapper`): `data-input-variant`, `data-theme`, `data-invalid`,
+`data-dirty`, `data-active`.
+
+---
+
+## Browser support: `appearance: base-select`
+
+The open-picker styling (`&::picker(select)`, `:open`/`:not(:open)` states, the transition/opacity
+`@starting-style` reveal) relies on the CSS Customizable Select API
+(`appearance: base-select`/`::picker(select)`), a very new feature not yet supported everywhere.
+`appearance: none` is set first, then overridden by `appearance: base-select` only where the
+browser recognises that value, so elsewhere (including Safari 16) the select falls back to the
+browser's native dropdown with full functionality. This is decorative degradation, not a
+functional break like `ExpandingPanel`'s `::details-content` case (pitfall #19), but the
+open-picker styling should still be spot-checked on a real Safari session before treating it as
+visually final.
+
+---
+
+## Changed 2026-10-16: rename, state hooks, stress fixes
+
+- Renamed to the Control/Field convention (see the note at the top).
+- State classes (`.normal`/`.underlined`/`.outlined`, `.dirty`, `.active`, `.error`) became data
+  attributes, so a consumer's unlayered `.error` rule can't restyle the field.
+- The placeholder option used `:selected="!modelValue"`, so a model value of `0` also marked the
+  placeholder selected. It now checks for an empty value only.
+- `aria-describedby=""` was rendered when no description id was passed; it's now omitted.
+- `styleClassPassthrough` now reacts to prop changes (it was read once at setup).
+- `InputSelectField` applied its passthrough to the inner select; it now applies it to its own
+  root only. It also gained a `title` prop (forwarded), and its root is `.input-select-field`
+  itself rather than an unclassed outer `<div>` around it.
+- New public tokens: `--input-select-text-color`, `--input-select-option-gap`,
+  `--input-select-option-icon-size`.
+- Long option labels wrap in the open picker, and the Field wraps long label, description and
+  error copy. `StressTest` stories on both components.
+
+## Fixed 2026-09-22: dead functionality and prop-shape bugs
+
+Migrated from a `variants:true`, `eslint_issues:true`, score-2/5 state.
+
+- `required` and `styleClassPassthrough` were declared but never bound.
+- `isDirty`/`isActive` were read but nothing set them; `@focusin`/`@focusout`/`@change` added.
+- The placeholder option used `readonly` (not valid on `<option>`); switched to `disabled`.
+- `theme`/`inputVariant` moved to the shared `FormUiTheme`/`InputUiVariant` types; `fieldData`
+  moved from an `as Ref<T>` cast to `defineModel<T>("fieldData", { required: true })`.
+- Dead commented-out CSS and single-use private tokens removed (pitfall #20).
+
+---
+
+## Variants
+
+### InputSelectField
+
+`InputSelectField` (`InputSelectField.vue`) composes `InputSelect` with `InputLabel`,
+`InputDescription` (before the control, or after the control and error when
+`inputVariant === "outlined"`, matching `InputTextField`'s placement rule), and `InputError`.
+Ids for the label, description and error come from `useAriaDescribedById`.
+
+**Additional props over InputSelect** (it takes no `id`; the id is generated):
+
+| Prop (template form) | Type | Default | Notes |
+|------|------|---------|-------|
+| `:data-testid` | `string` | `"input-select-field"` | Sets `data-testid` on the root. (Was `"input-select-with-label"` until 2026-10-16.) |
+| `:label` | `string` | (required) | Rendered via `InputLabel`. |
+| `:error-message` | `object \| string` | (required) | Rendered via `InputError` when `field-has-error` is true. |
+| `:style-class-passthrough` | `string \| string[]` | `[]` | Applied to the `.input-select-field` root only, not the inner select. |
+
+`name`, `placeholder`, `title`, `required`, `field-has-error`, `theme` and `input-variant` are
+forwarded. While `field-has-error` is set, the inner `InputSelect` gets `theme="error"` whatever
+the `theme` prop says; the Field root's own `data-theme` keeps the prop value.
+
+**Slots**: `descriptionHtml`, `descriptionText` (both forwarded to `InputDescription`).
+
+```vue
+<InputSelectField
+  v-model="colour"
+  v-model:field-data="colourOptions"
+  name="colour"
+  label="Favourite colour"
+  placeholder="Choose a colour"
+  :error-message="errors.colour"
+  :field-has-error="!!errors.colour"
+>
+  <template #descriptionText>Pick the colour you like best</template>
+</InputSelectField>
+```
+
+`v-model` and `v-model:field-data` are both **required**, same as `InputSelect` above.

package/.claude/skills/components/input-text.md

@@ -0,0 +1,220 @@
+# InputText Component
+
+> **Renamed 2026-10-16**: `InputTextCore` → `InputText`, `InputTextWithLabel` → `InputTextField`,
+> `InputPasswordWithLabel` → `InputPasswordField`, `InputTextAsNumberWithLabel` →
+> `InputTextAsNumberField` (DOM classes `.input-text-core` → `.input-text`,
+> `.input-text-with-label` → `.input-text-field`; full class list in CONSUMER-STYLING.md). Skill
+> doc renamed from `input-text-core.md`. Consumer apps use the first three old names; list their
+> edits privately and apply them when each upgrades.
+
+## Overview
+
+`InputText` is the low-level native `<input>` primitive for the `05.forms` text-input family. It
+renders one styled text-like input with left/right slots, focus/dirty state models, and digit-only
+typing for `inputmode="numeric"`. It has no label, description or error rendering of its own:
+those come from the Field wrappers under **Variants**, or pair it with your own `<label for>`.
+
+Most consumers should reach for one of the Variants rather than `InputText` directly.
+
+---
+
+## Props reference
+
+> **Hyphenation rule**: Vue's ESLint config enforces `vue/attribute-hyphenation`. Always write camelCase prop names hyphenated in templates: `:input-variant`, `:aria-describedby`.
+
+| Prop (template form) | Type | Default | Notes |
+|---|---|---|---|
+| `:type` | `InputTypesText` (`"text" \| "email" \| "password" \| "number" \| "tel" \| "url" \| "date"`) | `"text"` | Native input type. |
+| `:inputmode` | `InputMode` | `"text"` | Virtual keyboard hint. `"numeric"` also adds `pattern="[0-9]+"` and blocks typing anything but digits (a `beforeinput` handler; deletions and paste without data pass). Sets `data-inputmode` on the wrapper. |
+| `:maxlength` | `number` | `255` | Native `maxlength`. |
+| `:min` / `:max` | `string \| number` | (optional) | Passed straight through, e.g. an ISO date for `type="date"`. Inert on text-like types. |
+| `:id` | `string` | (required) | Applied to the native input. |
+| `:name` | `string` | (required) | Applied to the native input. |
+| `:required` | `boolean` | `false` | Native `required`. |
+| `:readonly` | `boolean` | `false` | Native `readonly`; sets `data-readonly` on the wrapper. Added 2026-10-16: a `readonly` attribute used to fall through onto the wrapper div, not the input. |
+| `:autocomplete` | `string` | (unset) | Native `autocomplete` token (`email`, `name`, `new-password`...). Added 2026-10-16. |
+| `:placeholder` | `string` | `""` | Native placeholder. |
+| `:field-has-error` | `boolean` | `false` | `data-invalid` on the wrapper and `aria-invalid="true"` on the input. It does **not** change `theme`. |
+| `:style-class-passthrough` | `string \| string[]` | `[]` | Extra classes on the native input. Reacts to changes. |
+| `:theme` | `FormUiTheme` | `"default"` | Sets `data-theme` on the wrapper. |
+| `:aria-describedby` | `string` | `""` | Forwarded to the native input; omitted when empty. |
+| `:input-variant` | `InputUiVariant` | `"normal"` | Sets `data-input-variant`. `normal` (bordered box) and `underlined` have CSS; `outlined` doesn't. |
+
+### v-models
+
+| Model | Type | Notes |
+|---|---|---|
+| `v-model` | `string` | **Required** (`defineModel({ required: true })`). |
+| `v-model:is-dirty` | `boolean` | Read only: `InputText` never sets it. The Fields set it once the value is non-empty. Reflected as `data-dirty`. |
+| `v-model:is-active` | `boolean` | Tracks focus (`focusin`/`focusout`). Reflected as `data-active`. |
+
+---
+
+## Slots
+
+| Slot | Notes |
+|---|---|
+| `left` | Rendered before the input in `.input-text-slot-left`, inside the bordered wrapper (an icon, or `InputButton variant="inline"`, which the slot styles). Sets `data-has-left-slot`. |
+| `right` | Same, after the input, in `.input-text-slot-right`. Sets `data-has-right-slot`; a right-slot `InputButton` removes the wrapper's end padding so it sits flush. |
+
+---
+
+## CSS token API
+
+See [CONSUMER-STYLING.md](../../app/components/05.forms/input-text/CONSUMER-STYLING.md) for the
+full table with defaults and the state hooks.
+
+**Common tokens:**
+
+- `--input-text-surface` / `-surface-hover` — wrapper background, slot button hover
+- `--input-text-border` / `-border-hover` / `-border-focus` — border and outline colours
+- `--input-text-color` — input text colour (also the browser-autofill text colour, global rule)
+- `--input-text-placeholder-color` — placeholder colour
+
+**State hooks** (on `.input-text-wrapper`): `data-input-variant`, `data-theme`, `data-invalid`,
+`data-dirty`, `data-active`, `data-readonly`, `data-inputmode`, `data-has-left-slot`,
+`data-has-right-slot`.
+
+---
+
+## Using `min`/`max` for a native date picker
+
+```vue
+<InputText
+  id="appointment-date"
+  v-model="appointmentDate"
+  name="appointmentDate"
+  type="date"
+  :min="new Date().toISOString().split('T')[0]"
+  max="2027-12-31"
+/>
+```
+
+The browser enforces the range in its picker; validate the submitted value server-side as well.
+
+---
+
+## Changed 2026-10-16: rename, state hooks, wrapper fixes
+
+- Renamed to the Control/Field convention (note at the top).
+- State classes became data attributes (`.normal`/`.underlined` → `[data-input-variant]`,
+  `.dirty`/`.active`/`.error` → `[data-dirty]`/`[data-active]`/`[data-invalid]`,
+  `.has-left-slot`/`.has-right-slot` → `[data-has-*-slot]`); `.slot.left-slot`/`.right-slot` →
+  `.input-text-slot-left`/`-right`. The input no longer carries `dirty`/`active` classes.
+- Numeric filtering used a `beforeinput` listener added in `onMounted` that was never removed and
+  added a new `input` listener per keystroke (it reverted pattern mismatches after the fact). It's
+  now a template `@beforeinput` handler that cancels non-digit input up front, and it follows
+  `inputmode` changes after mount.
+- `aria-describedby=""` is no longer rendered when empty; an unused `FormUiTheme` computed is gone.
+- `InputTextField` passed `label` and `error-message` to `InputText`, which has no such props, so
+  they landed on `.input-text-wrapper` as HTML attributes. It also applied its passthrough to both
+  its root and the input; now its root only.
+- `InputPasswordField` forwarded both description slots unconditionally, so every password field
+  rendered an empty `InputDescription` and pointed `aria-describedby` at it. Slots now forward
+  only when filled. Its toggle icon class is `.input-password-field-icon` (was `.icon`).
+- `InputTextAsNumberField`: step buttons overshot `min`/`max` and drifted on fractional steps
+  (now round, clamp and start from 0 when empty, like `InputNumberField`); its own CSS read
+  `--theme-*` directly and now uses the `--input-text-*` tokens; the step buttons ignored `theme`;
+  `inputmode` follows `min`/`step` (a negative `min` or fractional `step` couldn't be typed); the
+  input's width is capped at `12em`; root class `.input-text-as-number-field` (it reused
+  `.input-text-with-label`), and `InputError` gets `input-variant`.
+- The global autofill rule in `04.elements/forms/00.element-defaults.css` read an undefined
+  `--_input-text-core-color`, so autofilled text lost its colour; it now uses `--input-text-color`.
+
+---
+
+## Variants
+
+Three wrappers compose `InputText` with `InputLabel`, `InputDescription` and `InputError`. Ids
+come from `useAriaDescribedById`, so they take `name`, not `id`. Each applies
+`style-class-passthrough` to its own root only.
+
+### InputTextField
+
+The general-purpose labelled text field. Root `.input-text-field`, with `data-theme`,
+`data-input-variant`, `data-invalid`, `data-dirty` (set once the value is non-empty) and
+`data-active`.
+
+```vue
+<InputTextField
+  v-model="email"
+  name="email"
+  type="email"
+  label="Email address"
+  autocomplete="email"
+  :error-message="errors.email"
+  :field-has-error="!!errors.email"
+>
+  <template #descriptionText>We only use it to reply to you.</template>
+</InputTextField>
+```
+
+Props: `type` (required), `inputmode`, `maxlength`, `min`, `max`, `name`, `placeholder`,
+`required`, `readonly`, `autocomplete`, `fieldHasError`, `theme`, `inputVariant`, plus `label`
+(required), `errorMessage: object | string` (required, pass `""` if unused) and
+`styleClassPassthrough`. Slots: `left`, `right`, `descriptionText`, `descriptionHtml`. The
+description renders before the input, or after the input and error for `outlined`.
+
+### InputPasswordField
+
+`InputTextField` (root `.input-text-field.input-password-field`) with a show/hide toggle
+(`InputButton variant="inline"` in the right slot) that swaps `type` between `password` and
+`text`.
+
+```vue
+<InputPasswordField
+  v-model="password"
+  name="password"
+  label="Password"
+  autocomplete="new-password"
+  :error-message="errors.password"
+  :field-has-error="!!errors.password"
+/>
+```
+
+Extra props: `showPasswordText`/`hidePasswordText` (defaults `"Show password"`/`"Hide password"`,
+the toggle's accessible name; pass translated strings), `autocomplete` (default
+`"current-password"`; use `"new-password"` on sign-up). A passed `type` is accepted and ignored.
+Slots: `descriptionText`, `descriptionHtml`.
+
+### InputTextAsNumberField
+
+A compact numeric stepper on a text input (no native spinner). Root
+`.input-text-as-number-field`.
+
+```vue
+<InputTextAsNumberField
+  v-model="quantity"
+  name="quantity"
+  label="Quantity"
+  :min="1"
+  :max="99"
+  step-down-text="Decrease quantity"
+  step-up-text="Increase quantity"
+  :error-message="errors.quantity"
+>
+  <template #left><Icon name="mdi:minus" /></template>
+  <template #right><Icon name="mdi:plus" /></template>
+</InputTextAsNumberField>
+```
+
+- `v-model` is `number | undefined`: clearing the field sets `undefined`; text that isn't a
+  finite number is ignored.
+- Step buttons appear when the `left`/`right` slots are filled (the slot content is the icon).
+  They step by `step`, round to its precision, clamp to `min`/`max` (pulling a typed
+  out-of-range value back in), start from 0 (clamped) when empty, and go read-only at the limits.
+- `inputmode` is `numeric` (digits only) for a whole-number, non-negative range, `decimal` for a
+  fractional `step`, `text` for a negative `min`.
+- Extra props: `min`, `max` (required), `step` (default `1`), `stepDownText`/`stepUpText`
+  (defaults `"Step down"`/`"Step up"`).
+
+---
+
+## Accessibility
+
+- `field-has-error` sets `aria-invalid="true"`; the Fields link the error and description via
+  `aria-describedby`.
+- Focus is shown on the wrapper with `:has(input:focus-visible, button:focus-visible)`.
+- The password and stepper buttons get accessible names through `InputButton`'s `buttonText`
+  (visually hidden in icon-only mode).
+- Use `autocomplete` on personal-data fields (WCAG 1.3.5).