srcdev-nuxt-components 9.6.8 → 9.6.10

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).

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

@@ -0,0 +1,147 @@
+# InputTextarea Component
+
+> **Renamed 2026-10-16**: `InputTextareaCore` → `InputTextarea`, `InputTextareaWithLabel` →
+> `InputTextareaField` (DOM classes `.input-textarea-core` → `.input-textarea`,
+> `.input-textarea-with-label` → `.input-textarea-field`; full class list in
+> CONSUMER-STYLING.md). Skill doc renamed from `input-textarea-core.md`. Consumer apps use the
+> Field's old name; list their edits privately and apply them when each upgrades.
+
+## Overview
+
+`InputTextarea` is the low-level native `<textarea>` primitive for the `05.forms` multi-line text
+family. It renders one native textarea with left/right decorative slots and grows with its
+content (`field-sizing: content`) between a minimum and an optional maximum height. It has no
+label, description or error rendering of its own; that's composed by `InputTextareaField` below.
+
+Most consumers should reach for **InputTextareaField** rather than `InputTextarea` 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 textarea. |
+| `:name` | `string` | (required) | Applied to the native textarea. |
+| `:maxlength` | `number` | `255` | Native `maxlength`. Raise it for free-text messages. |
+| `:placeholder` | `string` | `""` | Native `placeholder`. |
+| `:required` | `boolean` | `false` | Native `required`. |
+| `:readonly` | `boolean` | `false` | Native `readonly`. Added 2026-10-16. |
+| `:autocomplete` | `string` | (unset) | Native `autocomplete` token (e.g. `street-address`). Added 2026-10-16. |
+| `:theme` | `FormUiTheme` | `"default"` | Sets `data-theme` on the wrapper. |
+| `:input-variant` | `InputUiVariant` | `"normal"` | Sets `data-input-variant`. `normal` (bordered box) and `underlined` have CSS; `outlined` doesn't. |
+| `:field-has-error` | `boolean` | `false` | `data-invalid` on the wrapper and `aria-invalid="true"` on the textarea (omitted otherwise). |
+| `:style-class-passthrough` | `string \| string[]` | `[]` | Extra CSS classes on the textarea. Reacts to changes. |
+| `:aria-describedby` | `string` | `""` | Forwarded to the native textarea; omitted when empty. |
+
+### v-models
+
+- `v-model` — `string | number | readonly string[] | null | undefined`, **required**
+  (`defineModel({ required: true })`; `""` is a valid value, "required" means it must be bound).
+- `v-model:is-dirty` — `boolean`. Read only here: `InputTextareaField` sets it the first time 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 textarea in `.input-textarea-slot-left` (decorative, e.g. an icon). Sets `data-has-left-slot`. |
+| `right` | Same, after the textarea, in `.input-textarea-slot-right`. Sets `data-has-right-slot`. |
+
+The slots have no built-in `InputButton` styling, unlike `InputText`'s.
+
+---
+
+## CSS token API
+
+See [CONSUMER-STYLING.md](../../app/components/05.forms/input-textarea/CONSUMER-STYLING.md) for
+the full table with defaults and the state hooks.
+
+**Common tokens:**
+
+- `--input-textarea-surface` — wrapper background
+- `--input-textarea-border` / `-border-hover` / `-border-focus` — border and outline colours
+- `--input-textarea-text-color` / `-placeholder-color` — text colours
+- `--input-textarea-min-height` (default `6lh`) / `-max-height` (default `none`) — growth range
+- `--input-textarea-slot-gap` (default `1.2rem`) — gap between slots and textarea
+- `--input-textarea-slot-align` (default `center`) / `-slot-padding-block` (default `0`) — where
+  the slots sit against a tall textarea; `start` plus
+  `var(--form-textarea-padding-block)` lines an icon up with the first line
+
+**State hooks** (on `.input-textarea-wrapper`): `data-input-variant`, `data-theme`,
+`data-invalid`, `data-dirty`, `data-active`, `data-has-left-slot`, `data-has-right-slot`.
+
+`field-sizing: content` isn't supported in Safari 16 or Firefox; there the textarea keeps its
+minimum height and scrolls. That's degraded, not broken.
+
+---
+
+## Changed 2026-10-16: rename, state hooks, line breaks
+
+- 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-textarea-slot-left`/`-right`. The textarea no longer carries `dirty`/`active` classes.
+- `all: unset` on the textarea also reset the browser's `white-space: pre-wrap`, so it inherited
+  `normal` from the page. It now sets `white-space: pre-wrap` and `overflow-wrap: anywhere`
+  explicitly, and `min-inline-size: 0` so a long unbroken string can't widen the field.
+- `aria-invalid="false"` was rendered on every field without an error; it's now omitted.
+  `aria-describedby=""` likewise.
+- `InputTextareaField` applied its passthrough to both its root and the textarea; now its root
+  only, which is `.input-textarea-field` itself (the unclassed outer `<div>` is gone).
+- The hardcoded `gap: 12px` and `min-height: 6lh` became `--input-textarea-slot-gap` and
+  `--input-textarea-min-height`; `--input-textarea-max-height` is new.
+- Removed an unused `inputField` template ref.
+
+## Fixed 2026-09-22: undefined tokens and dead code
+
+Migrated from a score-1/5 state. Five undefined custom properties (wrapper padding and
+placeholder font) were replaced with the tokens `InputText` uses; public `--input-textarea-*`
+colour tokens were added (pitfall #14); a dead `FormUiTheme` computed, commented-out code and a
+`label` pass-through to the control were removed; `defineModel` got `{ required: true }`; and
+the Field story imported `reactive`, which it used without importing.
+
+---
+
+## Variants
+
+### InputTextareaField
+
+`InputTextareaField` composes `InputTextarea` with `InputLabel`, `InputDescription` (before the
+control, or after the control and error when `inputVariant === "outlined"`) and `InputError`. Ids
+come from `useAriaDescribedById`, so it takes `name`, not `id`. Root `.input-textarea-field`,
+with `data-theme`, `data-input-variant`, `data-invalid`, `data-dirty` and `data-active`.
+
+**Additional props over InputTextarea:**
+
+| Prop (template form) | Type | Default | Notes |
+|------|------|---------|-------|
+| `: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-textarea-field` root only. |
+
+`maxlength`, `name`, `placeholder`, `required`, `readonly`, `autocomplete`, `field-has-error`,
+`theme` and `input-variant` are forwarded.
+
+**Slots**: `descriptionHtml`, `descriptionText` (forwarded to `InputDescription`), plus
+`left`/`right` (forwarded to `InputTextarea`).
+
+```vue
+<InputTextareaField
+  v-model="message"
+  name="message"
+  label="Message"
+  :maxlength="1000"
+  :error-message="errors.message"
+  :field-has-error="!!errors.message"
+>
+  <template #descriptionText>Please describe your enquiry in detail</template>
+</InputTextareaField>
+```

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

@@ -3,7 +3,7 @@
 ## Overview
 
 `SelectMenu` is a trigger-and-popover component for selecting from a list of options — a custom,
-fully token-styled alternative to a native `<select>` or `InputSelectCore`, built for non-form
+fully token-styled alternative to a native `<select>` or `InputSelect`, built for non-form
 contexts (language switchers, category filters, faceted filter bars, multi-pick treatment lists).
 It reuses the same Popover API + CSS anchor-positioning mechanism as `ActionMenu` (see that skill
 doc), but its items carry a `value`/`label`/optional `icon`, and the whole thing is driven by
@@ -43,7 +43,7 @@ selected value(s). In single-select mode (default) it's the one selected option'
 `undefined` if nothing is selected — a valid, expected state that renders the placeholder. With
 `multiple`, it's an array of selected values (`[]` when nothing is selected). `{ default: undefined }`
 is this repo's fix for the `vue/require-default-prop` false positive on `defineModel`-declared
-props that are legitimately optional — unlike `InputSelectCore`'s `modelValue`, which uses
+props that are legitimately optional — unlike `InputSelect`'s `modelValue`, which uses
 `{ required: true }` because a native form field genuinely can't be meaningfully empty, this model
 is optional by design (see that rule's `defineModel` gap noted in the repo's ledger `eslint_issues`
 docs). For several independent single-select categories, place multiple `SelectMenu` instances
@@ -257,10 +257,10 @@ ellipsis. The `StressTest` story covers this at every canvas width.
 - **Chevron flip** (`scaleY(-1)`, was `rotate(180deg)` until 2026-10-07) keys off the trigger's `aria-expanded` (from the composable's `isOpen`), not
   `:has(...:popover-open)`, so it also works without the Popover API (changed 2026-10-05).
 - **No native `<select>`/`appearance: base-select` involved** — this is a from-scratch popover
-  listbox, not a styled native select, so it doesn't inherit `InputSelectCore`'s WebKit
+  listbox, not a styled native select, so it doesn't inherit `InputSelect`'s WebKit
   `appearance: base-select` constraints.
 - **Not a form field** — `SelectMenu` has no `fieldHasError`/`theme`/`inputVariant` props like the
-  `05.forms` inputs. Use `InputSelectCore` instead for an actual form field that needs validation
+  `05.forms` inputs. Use `InputSelect` instead for an actual form field that needs validation
   state and native `<select>` semantics.
 - **2026-10-08 stress-test pass**: root `max-inline-size: 100%` (a long trigger label overflowed
   narrow containers instead of truncating), popover `--select-menu-popover-max-width` and

package/.claude/skills/components/toggle-switch.md

@@ -0,0 +1,143 @@
+# ToggleSwitch Component
+
+> **Renamed 2026-10-16**: `ToggleSwitchCore` → `ToggleSwitch`, `ToggleSwitchWithLabel` →
+> `ToggleSwitchField`; `ToggleSwitchWithLabelInline` was removed in favour of
+> `layout="inline"` on `ToggleSwitchField`. DOM classes `.toggle-switch-core` → `.toggle-switch`,
+> `.toggle-switch-with-label` → `.toggle-switch-field` (full list in CONSUMER-STYLING.md). Skill
+> doc renamed from `toggle-switch-core.md`. Consumer apps use `ToggleSwitchWithLabel`; list their
+> edits privately and apply them when each upgrades.
+
+## Overview
+
+`ToggleSwitch` is the low-level on/off switch for the `05.forms` toggle family: a visually hidden
+native `<input type="checkbox" role="switch">` (real keyboard and form semantics) plus a
+decorative track and thumb (`aria-hidden`), with optional icon slots inside the thumb. It has no
+label, description or error rendering of its own; that's `ToggleSwitchField` below.
+
+Most consumers should reach for **ToggleSwitchField**.
+
+---
+
+## 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`, `:true-value`, `:false-value`.
+
+| Prop (template form) | Type | Default | Notes |
+|------|------|---------|-------|
+| `:id` | `string` | (required) | Builds the native input's id: `toggle-switch-${id}`. Point your own `<label for>` at that. |
+| `:name` | `string` | (required) | Applied to the native checkbox. |
+| `:required` | `boolean` | `false` | Native `required`. |
+| `:field-has-error` | `boolean` | `false` | `aria-invalid="true"` on the checkbox (omitted otherwise), `data-invalid` on the root, and `data-theme="error"` whatever `theme` says. |
+| `:true-value` / `:false-value` | `string \| number \| boolean` | `true` / `false` | The two values `v-model` toggles between. A model value equal to neither shows as off. |
+| `:style-class-passthrough` | `string \| string[]` | `[]` | Extra classes on the root. Reacts to changes. |
+| `:theme` | `FormUiTheme` | `"default"` | Sets `data-theme` on the root (unless `field-has-error`). |
+| `:round` | `boolean` | `true` | Pill (`100vw` radius) or rounded square (`0.4rem`); `--toggle-switch-border-radius` overrides both. |
+| `:aria-describedby` | `string` | `""` | Forwarded to the checkbox; omitted when empty. |
+
+### v-model
+
+- `v-model` — `string | number | boolean`, **required** (`defineModel({ required: true })`).
+
+### Slots
+
+- `iconOn` / `iconOff` — replace the default `material-symbols:circle-outline` icon shown inside
+  the thumb in each state. Decorative: the whole track is `aria-hidden`.
+
+### Interaction
+
+Clicking the track toggles the value. Clicks that land on the input itself (a label click, Space,
+or a click on the input) are left to `v-model`, so each action toggles exactly once.
+
+---
+
+## CSS token API
+
+See [CONSUMER-STYLING.md](../../app/components/05.forms/toggle-switch/CONSUMER-STYLING.md) for the
+full table with defaults and the state hooks.
+
+**Common tokens:**
+
+- `--toggle-switch-surface` / `-surface-hover` — track background resting/hover
+- `--toggle-switch-border` / `-border-focus` — track border, and the `:focus-visible` outline
+- `--toggle-switch-symbol-surface-off` / `-symbol-surface-on` — thumb background per state
+- `--toggle-switch-border-radius`, `--toggle-switch-track-width` — shape and width overrides
+- `--toggle-switch-field-inline-gap` — space between label and switch in the inline layout
+
+**State hooks** (on `.toggle-switch`): `data-checked`, `data-invalid`, `data-theme`. On
+`.toggle-switch-field`: `data-layout`, `data-invalid`, `data-theme`.
+
+The thumb's slide respects `prefers-reduced-motion`.
+
+---
+
+## Changed 2026-10-16: rename, switch role, inline layout
+
+- Renamed to the Control/Field convention (note at the top). `ToggleSwitchWithLabelInline` was
+  folded into `ToggleSwitchField` as `layout="inline"`, which also gives the inline row
+  description, error and `required` support it never had.
+- The checkbox now has `role="switch"`, so screen readers announce "switch, on/off" rather than
+  a checkbox. The decorative track is `aria-hidden`.
+- `aria-invalid="false"` was rendered on every switch without an error; now omitted.
+- Generic inner classes (`.symbol-wrapper`, `.symbol`, `.symbol-icon`, `.icon-on`/`.icon-off`,
+  state classes `.checked`/`.active`, the unused `.use-default-icons`) became
+  `.toggle-switch-track`, `-thumb`, `-icon`, `-icon-on`/`-icon-off` and `[data-checked]`
+  (pitfall #16). The input got `.toggle-switch-input`; the default icon lost its `.icon` class.
+- The Fields' label passthrough used `input-switch-label`, so the `.toggle-switch-label` rules
+  never matched; the label now gets `.toggle-switch-label`. The inline variant's `nowrap` (dead
+  for the same reason) is gone: long labels wrap.
+- Clicking the input bubbled to the wrapper's click handler as well as updating `v-model`; it
+  happened to land on the right value. The wrapper handler now ignores clicks on the input.
+- Removed a redundant `:checked` binding next to `v-model`, and a duplicate `outline` in the
+  track's transition list.
+- `styleClassPassthrough` reacts to prop changes on both components.
+
+## Fixed 2026-09-23
+
+Migrated from a score-3/5 state: the `round` prop was never declared on the control (added, with
+`--toggle-switch-border-radius`); `fieldHasError` didn't switch `data-theme`; an invalid `for` on
+a `<div>` was removed; `defineModel` got `{ required: true }`; dead `--_transition-duration`
+tokens were removed; `line-height: 0` on the icon holder keeps slotted icons square; story theme
+options were corrected to `FormUiTheme`.
+
+---
+
+## Variants
+
+### ToggleSwitchField
+
+`ToggleSwitchField` composes `ToggleSwitch` with `InputLabel` (no required/optional indicator), an
+optional description (`InputDescription`, class `.toggle-switch-description`) and `InputError`.
+DOM order is label, description, switch, error in both layouts. Root `.toggle-switch-field`.
+
+**Additional props over ToggleSwitch** (it takes no `id`; ids come from `useId()`):
+
+| Prop (template form) | Type | Default | Notes |
+|------|------|---------|-------|
+| `:label` | `string` | (required) | Rendered via `InputLabel` (class `.toggle-switch-label`). |
+| `:layout` | `"stacked" \| "inline"` | `"stacked"` | `stacked`: label, description, switch, error in one column. `inline`: label and switch on one row (a grid, `data-layout="inline"`), description and error below. |
+| `:label-weight` | `LabelWeight` | bold when stacked, normal when inline | `body-normal` / `body-normal-semibold` / `body-normal-bold` class on the label. |
+| `:error-message` | `object \| string` | `""` | Rendered via `InputError` when `field-has-error` is true. |
+| `:style-class-passthrough` | `string \| string[]` | `[]` | Applied to the root only. |
+
+`name`, `required`, `field-has-error`, `true-value`, `false-value`, `theme` and `round` are
+forwarded. The root's `data-theme` switches to `error` with `field-has-error`, like the control's.
+
+**Slots**: `descriptionText` / `descriptionHtml` (via `InputDescription`), `iconOn`, `iconOff`.
+The switch's `aria-describedby` lists the description id when a description slot is filled and the
+error id when `field-has-error` is true.
+
+```vue
+<ToggleSwitchField
+  v-model="notificationsEnabled"
+  name="notifications"
+  label="Enable notifications"
+  :error-message="errors.notifications"
+  :field-has-error="!!errors.notifications"
+>
+  <template #descriptionText>Sends at most one email a week.</template>
+</ToggleSwitchField>
+
+<ToggleSwitchField v-model="darkMode" name="darkMode" label="Dark mode" layout="inline" />
+```
+
+The `description` slot was removed on 2026-09-29; use `descriptionText` or `descriptionHtml`.

package/.claude/skills/composable-zod-validation.md

@@ -68,7 +68,7 @@ Pass `formRef` to the `<form>` and bind `formErrors` to each field's `error-mess
 
 ```vue
 <form ref="formRef" @submit.stop.prevent="submitForm()">
-  <InputTextWithLabel
+  <InputTextField
     id="fullName"
     v-model="state.fullName"
     name="fullName"

package/.claude/skills/css-nesting-conventions.md

@@ -28,7 +28,8 @@ This project uses **native CSS nesting** (W3C CSS Nesting spec), not Sass/SCSS.
 **Why it silently fails**: esbuild converts `&__heading` to `:is(__heading)`, which tries to match an HTML element named `__heading`. No such element exists, so the styles are never applied. There's no error — just missing styles.
 
 The build will show this warning:
-```
+
+```text
 ▲ [WARNING] Cannot use type selector "__heading" directly after nesting selector "&" [css-syntax-error]
   CSS nesting syntax does not allow the "&" selector to come before a type selector.
 ```
@@ -119,3 +120,23 @@ If you see `&__` or `&-` in a `.vue` `<style lang="css">` block, it's Sass synta
 
 - `CLAUDE.md` → Styling Methodology section
 - `css-grid-max-width-gutters.md` — example of correct native nesting in a grid utility
+
+## State rules and specificity
+
+Nesting multiplies specificity: `.toggle-switch { .toggle-switch-wrapper { .toggle-switch-track
+{ .toggle-switch-thumb {} } } }` compiles to a four-class selector. A state rule written once at
+the root level, `.toggle-switch[data-checked] .toggle-switch-thumb`, has only three, so the base
+rule wins and the state never shows. Nest the state rule inside the element's own block instead:
+
+```css
+.toggle-switch-thumb {
+  translate: 0 0;
+
+  .toggle-switch[data-checked] & {
+    translate: 100% 0;
+  }
+}
+```
+
+`.toggle-switch[data-checked] &` adds the root's class and attribute on top of the full nested
+selector, so it always outranks the base rule.

package/.claude/skills/icon-sets.md

@@ -25,7 +25,7 @@ The layer's `modules/icon-sets.ts` runs at dev/build time and logs an info messa
 | `lucide` | `@iconify-json/lucide` | ActionMenu, InputCopy, PopOver, SelectMenu |
 | `material-symbols` | `@iconify-json/material-symbols` | form components |
 | `mdi` | `@iconify-json/mdi` | Form components, ServicesCard |
-| `radix-icons` | `@iconify-json/radix-icons` | InputPasswordWithLabel, InputError, DisplayThemeSwitch |
+| `radix-icons` | `@iconify-json/radix-icons` | InputPasswordField, InputError, DisplayThemeSwitch |
 
 ## Fix: install missing packages
 

package/.claude/skills/icon-sizing.md

@@ -48,7 +48,7 @@ beat every layered one regardless of specificity, so any `width`/`height` in `@l
 on an icon showed struck through in DevTools and did nothing, and the rule was "use `font-size`".
 When the layer was added, the `width`/`height` declarations written against icons at the time
 (CanvasSwitcher, DisplayTooltip, PopOver, InputCopy, SelectMenu, CarouselFlip, ResponsiveHeader,
-ServiceDetail, InputSelectCore) started applying for the first time. If an icon in one of those
+ServiceDetail, InputSelect) started applying for the first time. If an icon in one of those
 looks a different size than it used to, that's the cause.
 
 ## Related notes

package/.claude/skills/index.md

@@ -126,7 +126,7 @@ Each skill is a single markdown file named `<area>-<task>.md`.
     ├── display-theme-switch.md — DisplayThemeSwitch: system/light/dark picker wrapping TripleToggleSwitch, wired to useSettingsStore, labels/icons props, small sizing variant
     ├── card-core.md            — CardCore: generic card container, dynamic named slots as rows, 4 variants, blurred backdrop layer, full CSS token API
     ├── action-menu.md          — ActionMenu + ActionMenuItem: ellipsis trigger + anchored popover menu, indexed item-{n} slots, link/button items, full CSS token API
-    ├── select-menu.md          — SelectMenu: v-model single-select listbox popover (ActionMenu's popover mechanics, InputSelectCore's selected-option semantics), icon/text/chevron trigger toggles, checkmark on selected option, options-array driven, full CSS token API
+    ├── select-menu.md          — SelectMenu: v-model single-select listbox popover (ActionMenu's popover mechanics, InputSelect's selected-option semantics), icon/text/chevron trigger toggles, checkmark on selected option, options-array driven, full CSS token API
     ├── display-dialog.md       — DisplayDialog: native <dialog> overlay, 5 variants (dialog/modal/confirm/alert/fullscreen), useDialogControls integration, CSS token API
     ├── display-chip.md         — DisplayChip: status indicator chip overlay, CSS trig positioning, circle/square shapes, status colours, icon/label content
     ├── display-pill.md         — DisplayPill: pill/badge label with icon slot, 6 variants, 3 sizes, reversible order, --display-pill-* tokens (variants fall back to base colour/border/ring tokens); data-size/data-variant/data-reversed hooks (2026-10-08, were bare classes), label line-clamp token, -02 ring and outlined-monochrome recipes, StressTest story
@@ -145,7 +145,7 @@ Each skill is a single markdown file named `<area>-<task>.md`.
     ├── display-tooltip.md         — DisplayTooltip: anchor-positioned popover trigger, browser support caveat, CSS token API
     ├── display-tooltip-defined.md — DisplayTooltipDefined: structured title/body/action tooltip content with close button, composes DisplayTooltip
     ├── pop-over.md                — PopOver: generic anchor-positioned disclosure panel, consumer-supplied trigger/content slots, placement prop, CSS token API
-    ├── input-text-core.md        — InputTextCore: native text/date/number input primitive, min/max pass-through (date-picker range), CSS token API; Variants section covers InputTextWithLabel/InputPasswordWithLabel/InputTextAsNumberWithLabel
+    ├── input-text.md            — InputText (bare control), InputTextField, InputPasswordField, InputTextAsNumberField: renamed from Core/WithLabel, data-* state hooks, readonly/autocomplete props, leak-free digit filtering, wrapper attr-leak/empty-description/passthrough fixes, rounded+clamped stepping, min/max pass-through, CSS token API, stress stories
     ├── input-button.md           — InputButton (renamed from InputButtonCore 2026-09-28): button/NuxtLink/a, variants, icon slots, readonly (aria-disabled, activation blocked), tokens
     ├── input-range.md            — InputRange: native range-slider primitive, markers/datalist slots, dead --theme-form-range-accent-color token fixed, CSS token API; Variants section covers InputRangeField; renamed from InputRangeCore/InputRangeDefault 2026-10-16, clamped stepping, useId datalist id, data-* hooks
     ├── input-number.md           — InputNumber: native number-input primitive, left/right step-button slots, missing base class/placeholder/mismatched slot-selector bugs fixed, CSS token API; Variants section covers InputNumberField; clamped, rounded stepping, data-* state hooks, min/step-aware inputmode
@@ -157,12 +157,12 @@ Each skill is a single markdown file named `<area>-<task>.md`.
     ├── input-label.md            — InputLabel: the <label> every labelled *Field wrapper renders (textLabel/htmlLabel slots), id is the control's id rendered as for, required/optional indicator (app.config srcdev.inputLabel, text or icon), dead name/theme props and fallthrough :for removed, data-input-variant/data-invalid hooks, CSS token API
     ├── form-wrapper.md           — FormWrapper: width-capped outer container for a whole form, data-width hook, named inline-size container, not centred by default (--form-wrapper-margin-inline), CSS token API
     ├── pending-effect.md         — PendingEffect: animated dashed border InputButton draws while is-pending (has-pending-effect), tokens renamed to --pending-effect-* and read at point of use, animation moved off the host button, aria-hidden
-    ├── input-textarea-core.md    — InputTextareaCore: native textarea primitive, left/right decorative slots, undefined-token/dead-code/label-leak bugs fixed, CSS token API; Variants section covers InputTextareaWithLabel
-    ├── input-select-core.md      — InputSelectCore: native select primitive, data-driven options with icon decorator, dead required/styleClassPassthrough/isDirty-isActive functionality fixed, appearance:base-select browser-support note, CSS token API; Variants section covers InputSelectWithLabel
+    ├── input-textarea.md        — InputTextarea (bare control), InputTextareaField (labelled): renamed from Core/WithLabel, data-* state hooks, line breaks kept (all:unset pre-wrap fix), readonly/autocomplete props, min/max-height + slot-gap tokens, aria-invalid=false fix, Field passthrough on root only, CSS token API, stress stories
+    ├── input-select.md          — InputSelect (bare control), InputSelectField (labelled): renamed from Core/WithLabel, data-input-variant/data-invalid/data-dirty/data-active hooks, data-driven options with icon decorator, placeholder-vs-0 fix, Field passthrough on root only, appearance:base-select browser-support note, CSS token API, stress stories
     ├── input-checkbox-radio.md   — InputCheckboxRadio (bare control), InputCheckboxRadioField (labelled), InputCheckboxRadioButton (button/pill option): renamed from Core/WithLabel, state classes → data-* hooks, type-switch v-model fix, no aria-checked, icon font-size sizing, button spacing tokens, long labels wrap (inline nowrap removed), optional useId button id
     ├── input-checkbox.md         — MultipleCheckboxes/SingleCheckbox: fieldset-wrapped checkbox group (data-driven, button or labelled) and single checkbox, per-box native-required/styleClassPassthrough/data-testid bugs fixed, spacing token API, wraps hostile content (fieldset min-inline-size, useId option ids)
     ├── input-radio.md            — MultipleRadiobuttons: fieldset radiogroup (data-driven, button or labelled), shared-name grouping bug fixed, dead label/placeholder/equalCols props removed, data-options-layout hook, spacing token API, useId button ids, wraps hostile content
-    ├── toggle-switch-core.md      — ToggleSwitchCore: pill/square checkbox-backed toggle primitive, dead round-prop/data-theme-error functionality and story theme-options bugs fixed, CSS token API; Variants section covers ToggleSwitchWithLabel (descriptionText/descriptionHtml via InputDescription, `description` slot removed 2026-09-29)/ToggleSwitchWithLabelInline
+    ├── toggle-switch.md         — ToggleSwitch (bare control), ToggleSwitchField (labelled, layout="stacked"|"inline", replaces ToggleSwitchWithLabelInline): renamed from Core/WithLabel, role="switch", prefixed inner classes + data-checked, single-toggle click handling, reduced motion, round prop + border-radius token, track width from geometry, CSS token API, stress stories
     ├── triple-toggle-switch.md    — TripleToggleSwitch (renamed from TripleToggleSwitchCore): three-option icon radio pill with sliding marker, radiogroup + ariaLabel, system/light/dark marker-gradient tokens, reduced-motion, CSS token API
     ├── entry-animation.md         — EntryAnimation: scroll-driven entry animation wrapper (slide-in/zoom-reveal/exit-blur utility classes), skipAnimation for above-the-fold loop items, reduced-motion handled at the CSS layer
     ├── column-flow-grid.md        — ColumnFlowGrid (renamed from MasonryGrid): CSS multi-column text-flow layout, named dynamic slots (no count/data prop), itemMinWidth/gap/unit sizing, CSS token API; not a true masonry, see "which one do I want?"