srcdev-nuxt-components 9.6.8 → 9.6.9

package/app/components/05.forms/input-textarea/tests/InputTextareaField.spec.ts

@@ -0,0 +1,122 @@
+// https://nuxt.com/docs/getting-started/testing#unit-testing
+import { nextTick } from "vue";
+import type { VueWrapper } from "@vue/test-utils";
+import { mountSuspended } from "@nuxt/test-utils/runtime";
+import ComponentUnderTest from "../InputTextareaField.vue";
+
+const initialPropsData = {
+  name: "message",
+  label: "Message",
+  errorMessage: "",
+  modelValue: "",
+};
+
+let wrapper: VueWrapper<InstanceType<typeof ComponentUnderTest>>;
+const wrapperFactory = (propsData = {}, slots = {}) => {
+  const mockPropsData = { ...initialPropsData, ...propsData };
+
+  return mountSuspended(ComponentUnderTest, {
+    attachTo: document.body,
+    props: mockPropsData,
+    slots,
+  });
+};
+
+afterEach(() => {
+  wrapper?.unmount();
+  vi.restoreAllMocks();
+});
+
+describe("InputTextareaField", () => {
+  it("mounts without error", async () => {
+    wrapper = await wrapperFactory();
+    expect(wrapper.vm).toBeTruthy();
+  });
+
+  it("renders .input-textarea-field as the root", async () => {
+    wrapper = await wrapperFactory();
+    expect(wrapper.classes()).toContain("input-textarea-field");
+  });
+
+  it("renders the label text, linked to the textarea", async () => {
+    wrapper = await wrapperFactory({ label: "Feedback" });
+    const label = wrapper.find("label");
+
+    expect(label.text()).toContain("Feedback");
+    expect(label.attributes("for")).toBe(wrapper.find("textarea").attributes("id"));
+  });
+
+  it("does not leak label or error-message onto the control's wrapper", async () => {
+    wrapper = await wrapperFactory({ label: "Feedback", errorMessage: "Oops" });
+    const control = wrapper.find(".input-textarea-wrapper");
+
+    expect(control.attributes("label")).toBeUndefined();
+    expect(control.attributes("error-message")).toBeUndefined();
+  });
+
+  it("sets data-invalid on the root and links the error via aria-describedby", async () => {
+    wrapper = await wrapperFactory({ fieldHasError: true, errorMessage: "This field is required" });
+
+    expect(wrapper.attributes("data-invalid")).toBe("");
+    expect(wrapper.text()).toContain("This field is required");
+    expect(wrapper.find("textarea").attributes("aria-describedby")).toMatch(/-error-message$/);
+  });
+
+  it("renders the descriptionText slot before the textarea by default", async () => {
+    wrapper = await wrapperFactory({}, { descriptionText: () => "Please provide more detail" });
+    const html = wrapper.html();
+
+    expect(wrapper.text()).toContain("Please provide more detail");
+    expect(html.indexOf("Please provide more detail")).toBeLessThan(html.indexOf("<textarea"));
+  });
+
+  it("renders the description after the textarea for the outlined variant", async () => {
+    wrapper = await wrapperFactory({ inputVariant: "outlined" }, { descriptionText: () => "Hint text" });
+    const html = wrapper.html();
+    expect(html.indexOf("Hint text")).toBeGreaterThan(html.indexOf("<textarea"));
+  });
+
+  it("renders the left/right slots when provided", async () => {
+    wrapper = await wrapperFactory(
+      {},
+      {
+        left: '<span data-testid="left-slot">📝</span>',
+        right: '<span data-testid="right-slot">✨</span>',
+      }
+    );
+
+    expect(wrapper.find('[data-testid="left-slot"]').exists()).toBe(true);
+    expect(wrapper.find('[data-testid="right-slot"]').exists()).toBe(true);
+  });
+
+  it("marks the field dirty once the value is non-empty", async () => {
+    wrapper = await wrapperFactory();
+    expect(wrapper.attributes("data-dirty")).toBeUndefined();
+
+    await wrapper.setProps({ modelValue: "hello" });
+    await nextTick();
+    expect(wrapper.attributes("data-dirty")).toBe("");
+  });
+
+  it("sets data-input-variant on the root", async () => {
+    wrapper = await wrapperFactory({ inputVariant: "underlined" });
+    expect(wrapper.attributes("data-input-variant")).toBe("underlined");
+  });
+
+  it("forwards readonly and autocomplete", async () => {
+    wrapper = await wrapperFactory({ readonly: true, autocomplete: "off" });
+    expect(wrapper.find("textarea").attributes("readonly")).toBeDefined();
+    expect(wrapper.find("textarea").attributes("autocomplete")).toBe("off");
+  });
+
+  it("applies styleClassPassthrough to its root only and reacts to changes", async () => {
+    wrapper = await wrapperFactory({ styleClassPassthrough: "custom-textarea" });
+    expect(wrapper.classes()).toContain("custom-textarea");
+    expect(wrapper.find("textarea").classes()).not.toContain("custom-textarea");
+
+    await wrapper.setProps({ styleClassPassthrough: "other-textarea" });
+    await nextTick();
+    expect(wrapper.classes()).toContain("other-textarea");
+    expect(wrapper.classes()).not.toContain("custom-textarea");
+  });
+});

package/app/components/05.forms/patterns/stories/ContactForm.stories.ts

@@ -1,8 +1,8 @@
 import type { Meta, StoryFn } from "@nuxtjs/storybook";
 import { reactive, ref } from "vue";
-import InputTextWithLabel from "../../input-text/InputTextWithLabel.vue";
-import InputSelectWithLabel from "../../input-select/InputSelectWithLabel.vue";
-import InputTextareaWithLabel from "../../input-textarea/InputTextareaWithLabel.vue";
+import InputTextField from "../../input-text/InputTextField.vue";
+import InputSelectField from "../../input-select/InputSelectField.vue";
+import InputTextareaField from "../../input-textarea/InputTextareaField.vue";
 import MultipleCheckboxes from "../../input-checkbox/MultipleCheckboxes.vue";
 import InputButton from "../../input-button/InputButton.vue";
 import FormField from "../../form-field/FormField.vue";
@@ -14,7 +14,7 @@ interface ContactFormStoryArgs {
 }
 
 // Demo composition, not a component of its own — a richer variant of a typical contact page
-// pattern: name/phone/email + multi-select services + comments shape, plus an InputSelectWithLabel
+// pattern: name/phone/email + multi-select services + comments shape, plus an InputSelectField
 // "How did you hear about us?" field, to also exercise the select
 // component alongside the others in one composed form. No validation wiring
 // (useZodValidation/zod) here — that's the consuming app's concern, this is a visual/composition
@@ -36,9 +36,9 @@ export default {
 
 const Template: StoryFn<ContactFormStoryArgs> = (args) => ({
   components: {
-    InputTextWithLabel,
-    InputSelectWithLabel,
-    InputTextareaWithLabel,
+    InputTextField,
+    InputSelectField,
+    InputTextareaField,
     MultipleCheckboxes,
     InputButton,
     FormField,
@@ -91,7 +91,7 @@ const Template: StoryFn<ContactFormStoryArgs> = (args) => ({
 
       <form @submit.prevent>
         <FormField width="wide" :has-gutter="false">
-          <InputTextWithLabel
+          <InputTextField
             v-model="state.fullName"
             type="text"
             name="fullName"
@@ -104,7 +104,7 @@ const Template: StoryFn<ContactFormStoryArgs> = (args) => ({
         </FormField>
 
         <FormField width="wide" :has-gutter="false">
-          <InputTextWithLabel
+          <InputTextField
             v-model="state.telNumber"
             type="tel"
             inputmode="tel"
@@ -118,7 +118,7 @@ const Template: StoryFn<ContactFormStoryArgs> = (args) => ({
         </FormField>
 
         <FormField width="wide" :has-gutter="false">
-          <InputTextWithLabel
+          <InputTextField
             v-model="state.emailAddress"
             type="email"
             inputmode="email"
@@ -132,7 +132,7 @@ const Template: StoryFn<ContactFormStoryArgs> = (args) => ({
         </FormField>
 
         <FormField width="wide" :has-gutter="false">
-          <InputSelectWithLabel
+          <InputSelectField
             v-model="state.hearAboutUs"
             v-model:field-data="hearAboutUsOptions"
             name="hearAboutUs"
@@ -160,7 +160,7 @@ const Template: StoryFn<ContactFormStoryArgs> = (args) => ({
         </FormField>
 
         <FormField width="wide" :has-gutter="false">
-          <InputTextareaWithLabel
+          <InputTextareaField
             v-model="state.comments"
             name="comments"
             label="Comments"
@@ -169,7 +169,7 @@ const Template: StoryFn<ContactFormStoryArgs> = (args) => ({
             :input-variant="args.inputVariant"
           >
             <template #descriptionText>Optional — any extra information that might help us.</template>
-          </InputTextareaWithLabel>
+          </InputTextareaField>
         </FormField>
 
         <FormField width="wide" :has-gutter="false">

package/app/components/05.forms/patterns/stories/LoginForm.stories.ts

@@ -1,7 +1,7 @@
 import type { Meta, StoryFn } from "@nuxtjs/storybook";
 import { reactive } from "vue";
-import InputTextWithLabel from "../../input-text/InputTextWithLabel.vue";
-import InputPasswordWithLabel from "../../input-text/InputPasswordWithLabel.vue";
+import InputTextField from "../../input-text/InputTextField.vue";
+import InputPasswordField from "../../input-text/InputPasswordField.vue";
 import InputCheckboxRadioField from "../../input-checkbox-radio/InputCheckboxRadioField.vue";
 import InputButton from "../../input-button/InputButton.vue";
 import FormField from "../../form-field/FormField.vue";
@@ -35,8 +35,8 @@ export default {
 
 const Template: StoryFn<LoginFormStoryArgs> = (args) => ({
   components: {
-    InputTextWithLabel,
-    InputPasswordWithLabel,
+    InputTextField,
+    InputPasswordField,
     InputCheckboxRadioField,
     InputButton,
     FormField,
@@ -64,7 +64,7 @@ const Template: StoryFn<LoginFormStoryArgs> = (args) => ({
 
           <form @submit.prevent>
             <FormField width="wide" :has-gutter="false">
-              <InputTextWithLabel
+              <InputTextField
                 v-model="state.email"
                 type="email"
                 inputmode="email"
@@ -78,7 +78,7 @@ const Template: StoryFn<LoginFormStoryArgs> = (args) => ({
             </FormField>
 
             <FormField width="wide" :has-gutter="false">
-              <InputPasswordWithLabel
+              <InputPasswordField
                 v-model="state.password"
                 name="password"
                 label="Password"

package/app/components/05.forms/patterns/stories/MigratedFieldsForm.stories.ts

@@ -1,15 +1,14 @@
 import type { Meta, StoryFn } from "@nuxtjs/storybook";
 import { reactive, ref } from "vue";
-import InputTextWithLabel from "../../input-text/InputTextWithLabel.vue";
-import InputPasswordWithLabel from "../../input-text/InputPasswordWithLabel.vue";
-import InputTextAsNumberWithLabel from "../../input-text/InputTextAsNumberWithLabel.vue";
+import InputTextField from "../../input-text/InputTextField.vue";
+import InputPasswordField from "../../input-text/InputPasswordField.vue";
+import InputTextAsNumberField from "../../input-text/InputTextAsNumberField.vue";
 import InputRangeField from "../../input-range/InputRangeField.vue";
 import InputNumberField from "../../input-number/InputNumberField.vue";
 import InputOtpField from "../../input-otp/InputOtpField.vue";
-import InputTextareaWithLabel from "../../input-textarea/InputTextareaWithLabel.vue";
-import InputSelectWithLabel from "../../input-select/InputSelectWithLabel.vue";
-import ToggleSwitchWithLabel from "../../toggle-switch/ToggleSwitchWithLabel.vue";
-import ToggleSwitchWithLabelInline from "../../toggle-switch/ToggleSwitchWithLabelInline.vue";
+import InputTextareaField from "../../input-textarea/InputTextareaField.vue";
+import InputSelectField from "../../input-select/InputSelectField.vue";
+import ToggleSwitchField from "../../toggle-switch/ToggleSwitchField.vue";
 import MultipleCheckboxes from "../../input-checkbox/MultipleCheckboxes.vue";
 import SingleCheckbox from "../../input-checkbox/SingleCheckbox.vue";
 import MultipleRadiobuttons from "../../input-radio/MultipleRadiobuttons.vue";
@@ -27,11 +26,11 @@ interface MigratedFieldsFormStoryArgs {
 // Living reference, not a component of its own: every 05.forms component that scores 5/5 in the
 // Component Ledger (.claude/component-ledger/audit.json) appears here, either as its own field or
 // rendered inside one. As of 2026-10-04 every 05.forms component is 5/5, so all of them are in:
-// - Own field: InputTextWithLabel (InputTextCore; plus one per type/inputmode pair for checking
-//   on-device keyboards), InputPasswordWithLabel,
-//   InputTextAsNumberWithLabel, InputRangeField (InputRange), InputNumberField
-//   (InputNumber), InputOtpField (InputOtp), InputTextareaWithLabel (InputTextareaCore), InputSelectWithLabel
-//   (InputSelectCore), ToggleSwitchWithLabel and ToggleSwitchWithLabelInline (ToggleSwitchCore),
+// - Own field: InputTextField (InputText; plus one per type/inputmode pair for checking
+//   on-device keyboards), InputPasswordField,
+//   InputTextAsNumberField, InputRangeField (InputRange), InputNumberField
+//   (InputNumber), InputOtpField (InputOtp), InputTextareaField (InputTextarea), InputSelectField
+//   (InputSelect), ToggleSwitchField, stacked and inline (ToggleSwitch),
 //   MultipleCheckboxes, SingleCheckbox, MultipleRadiobuttons, TripleToggleSwitch ("Theme
 //   preference": no Field wrapper or error state, so it sits under a plain caption).
 // - Rendered inside other fields: FormWrapper (wraps the form), FormField (wraps every field),
@@ -60,16 +59,15 @@ export default {
 
 const Template: StoryFn<MigratedFieldsFormStoryArgs> = (args) => ({
   components: {
-    InputTextWithLabel,
-    InputPasswordWithLabel,
-    InputTextAsNumberWithLabel,
+    InputTextField,
+    InputPasswordField,
+    InputTextAsNumberField,
     InputRangeField,
     InputNumberField,
     InputOtpField,
-    InputTextareaWithLabel,
-    InputSelectWithLabel,
-    ToggleSwitchWithLabel,
-    ToggleSwitchWithLabelInline,
+    InputTextareaField,
+    InputSelectField,
+    ToggleSwitchField,
     MultipleCheckboxes,
     SingleCheckbox,
     MultipleRadiobuttons,
@@ -97,7 +95,7 @@ const Template: StoryFn<MigratedFieldsFormStoryArgs> = (args) => ({
       terms: false,
     });
 
-    // One InputTextWithLabel per type/inputmode pair, for checking each on-screen keyboard on a real device.
+    // One InputTextField per type/inputmode pair, for checking each on-screen keyboard on a real device.
     const textVariants: { name: string; label: string; type: InputTypesText; inputmode: InputMode; placeholder: string }[] = [
       { name: "variantEmail", label: "Email", type: "email", inputmode: "email", placeholder: "eg. jane@example.com" },
       { name: "variantTel", label: "Phone", type: "tel", inputmode: "tel", placeholder: "eg. 07700 900123" },
@@ -251,7 +249,7 @@ const Template: StoryFn<MigratedFieldsFormStoryArgs> = (args) => ({
       <FormWrapper width="medium">
         <form novalidate @submit.prevent="submit">
           <FormField width="wide" :has-gutter="false">
-            <InputTextWithLabel
+            <InputTextField
               v-model="state.fullName"
               type="text"
               name="fullName"
@@ -263,11 +261,11 @@ const Template: StoryFn<MigratedFieldsFormStoryArgs> = (args) => ({
               :input-variant="args.inputVariant"
             >
               <template #descriptionText>As it appears on your ID</template>
-            </InputTextWithLabel>
+            </InputTextField>
           </FormField>
 
           <FormField width="wide" :has-gutter="false">
-            <InputPasswordWithLabel
+            <InputPasswordField
               v-model="state.password"
               name="password"
               label="Password"
@@ -277,11 +275,11 @@ const Template: StoryFn<MigratedFieldsFormStoryArgs> = (args) => ({
               :input-variant="args.inputVariant"
             >
               <template #descriptionText>At least 8 characters</template>
-            </InputPasswordWithLabel>
+            </InputPasswordField>
           </FormField>
 
           <FormField v-for="variant in textVariants" :key="variant.name" width="wide" :has-gutter="false">
-            <InputTextWithLabel
+            <InputTextField
               v-model="textVariantValues[variant.name]"
               :type="variant.type"
               :inputmode="variant.inputmode"
@@ -292,7 +290,7 @@ const Template: StoryFn<MigratedFieldsFormStoryArgs> = (args) => ({
               :input-variant="args.inputVariant"
             >
               <template #descriptionText>type="{{ variant.type }}", inputmode="{{ variant.inputmode }}"</template>
-            </InputTextWithLabel>
+            </InputTextField>
           </FormField>
 
           <FormField width="wide" :has-gutter="false">
@@ -341,7 +339,7 @@ const Template: StoryFn<MigratedFieldsFormStoryArgs> = (args) => ({
           </FormField>
 
           <FormField width="wide" :has-gutter="false">
-            <InputTextAsNumberWithLabel
+            <InputTextAsNumberField
               v-model="state.guests"
               name="guests"
               label="Guests"
@@ -353,11 +351,11 @@ const Template: StoryFn<MigratedFieldsFormStoryArgs> = (args) => ({
             >
               <template #left><span aria-hidden="true">−</span></template>
               <template #right><span aria-hidden="true">+</span></template>
-            </InputTextAsNumberWithLabel>
+            </InputTextAsNumberField>
           </FormField>
 
           <FormField width="wide" :has-gutter="false">
-            <InputTextareaWithLabel
+            <InputTextareaField
               v-model="state.notes"
               name="notes"
               label="Notes"
@@ -369,7 +367,7 @@ const Template: StoryFn<MigratedFieldsFormStoryArgs> = (args) => ({
           </FormField>
 
           <FormField width="wide" :has-gutter="false">
-            <InputSelectWithLabel
+            <InputSelectField
               v-model="state.colour"
               v-model:field-data="colourOptions"
               name="colour"
@@ -382,11 +380,11 @@ const Template: StoryFn<MigratedFieldsFormStoryArgs> = (args) => ({
           </FormField>
 
           <FormField width="wide" :has-gutter="false">
-            <ToggleSwitchWithLabel v-model="state.subscribe" name="subscribe" label="Subscribe to updates" />
+            <ToggleSwitchField v-model="state.subscribe" name="subscribe" label="Subscribe to updates" />
           </FormField>
 
           <FormField width="wide" :has-gutter="false">
-            <ToggleSwitchWithLabelInline v-model="state.reminders" name="reminders" label="Email me appointment reminders" />
+            <ToggleSwitchField v-model="state.reminders" name="reminders" label="Email me appointment reminders" layout="inline" />
           </FormField>
 
           <FormField width="wide" :has-gutter="false">

package/app/components/05.forms/toggle-switch/CONSUMER-STYLING.md

@@ -1,68 +1,98 @@
-# ToggleSwitchCore — Consumer Styling Guide
+# ToggleSwitch — Consumer Styling Guide
+
+> **Renamed 2026-10-16**: `ToggleSwitchCore` → `ToggleSwitch`, `ToggleSwitchWithLabel` →
+> `ToggleSwitchField`, `ToggleSwitchWithLabelInline` → `ToggleSwitchField layout="inline"`. Class
+> changes are listed under "State hooks" below.
 
 ## Public token API
 
 Every colour token below is `var(--toggle-switch-*, {default})` — set the `--toggle-switch-*`
 name to override just this component; leave it unset and it inherits the shared `--theme-*` token
 every other themed component also falls back to. See `theming-component-token-pattern.md` for why
-this two-tier shape exists. Defaults are unchanged from before this migration — this is a
-token-rename pass, not a redesign.
+this two-tier shape exists.
+
+### Track and thumb
 
-| Token | Falls back to | Controls |
+| Token | Default | Controls |
 |---|---|---|
 | `--toggle-switch-surface` | `var(--theme-checkbox-symbol-surface)` | Track background (resting) |
 | `--toggle-switch-surface-hover` | `var(--theme-surface-subtle)` | Track background on hover |
 | `--toggle-switch-border` | `var(--theme-border)` | Track border colour |
 | `--toggle-switch-border-focus` | `var(--theme-border-focus)` | Track outline colour on `:focus-visible` |
 | `--toggle-switch-symbol-border` | `var(--theme-text)` | Thumb border colour |
-| `--toggle-switch-symbol-surface-off` | `var(--theme-on-surface)` | Thumb background, unchecked |
-| `--toggle-switch-symbol-surface-on` | `var(--theme-surface)` | Thumb background, checked |
+| `--toggle-switch-symbol-surface-off` | `var(--theme-on-surface)` | Thumb background, off |
+| `--toggle-switch-symbol-surface-on` | `var(--theme-surface)` | Thumb background, on |
 | `--toggle-switch-icon-on-color` | `var(--theme-on-surface)` | "On" icon colour |
 | `--toggle-switch-icon-off-color` | `var(--theme-surface)` | "Off" icon colour |
+| `--toggle-switch-border-radius` | `100vw` (`round`), `0.4rem` (`round: false`) | Track and thumb shape |
+| `--toggle-switch-track-width` | derived from the thumb size | Track width (see below) |
+
+### Field
+
+| Token | Default | Controls |
+|---|---|---|
+| `--toggle-switch-field-inline-gap` | `1.2rem` | Space between label and switch with `layout="inline"` |
 
 Geometry (`--input-toggle-*`, `--form-element-*`) is shared across every `05.forms` component and
 untouched by this — see `theming-form-geometry-tokens.md`.
 
-### Shape (`round` prop)
-
-`--toggle-switch-border-radius` controls the track and thumb's shared `border-radius`. Left unset,
-it defaults to `100vw` (pill shape) when the `round` prop is `true` (the default), or `0.4rem`
-(a rounded-square shape) when `round` is `false` — see the `SquareShape` story. Set the token
-directly to override with an exact value the two-state default doesn't produce.
+Private (not public API): `--_border-radius` (from `round` and the token above, read by track and
+thumb) and `--_track-width` (the derived width).
 
 ### Track width
 
-`--toggle-switch-track-width` overrides the track's width directly. Left unset, the track derives
-its width from the shared `--input-toggle-*`/`--form-element-*` geometry tokens so it always scales
-with `--input-toggle-symbol-size` — resize the thumb and the track resizes to match, no separate
-width to keep in sync:
+Left unset, the track width is worked out from the shared `--input-toggle-*`/`--form-element-*`
+geometry tokens, so it scales with `--input-toggle-symbol-size`:
 
 ```css
 .my-compact-toggle {
   --input-toggle-symbol-size: 2.2rem;
-  /* Track width now follows automatically — no --toggle-switch-track-width override needed. */
 }
 ```
 
-Only set `--toggle-switch-track-width` if you need a width the formula doesn't produce (e.g. a
-fixed width independent of symbol size).
+Only set `--toggle-switch-track-width` for a width the formula doesn't produce.
 
-> Five private locals (`--_icon-on-opacity`, `--_icon-off-opacity`, `--_symbol-background-color`,
-> `--_symbol-margin-inline-start`, `--_symbol-checked-offset`) were removed during this migration —
-> declared but never actually read by any property in the component, confirmed by grep. Not part
-> of any public API, so nothing to update if you were relying on them (you weren't — they had zero
-> effect).
+---
+
+## State hooks
+
+| Attribute | On | When |
+|---|---|---|
+| `data-checked` | `.toggle-switch` | The value equals `true-value` |
+| `data-invalid` | `.toggle-switch`, `.toggle-switch-field` | `field-has-error` |
+| `data-theme` | `.toggle-switch`, `.toggle-switch-field` | Always; `error` while `field-has-error` is set |
+| `data-layout="stacked" \| "inline"` | `.toggle-switch-field` | Always, mirrors `layout` |
+
+Inner elements: `.toggle-switch-wrapper`, `.toggle-switch-input` (the hidden checkbox),
+`.toggle-switch-track`, `.toggle-switch-thumb`, `.toggle-switch-icon`, `.toggle-switch-icon-on`,
+`.toggle-switch-icon-off`, `.toggle-switch-label` (the Field's `InputLabel`),
+`.toggle-switch-description` (the Field's `InputDescription`).
+
+The thumb slide is turned off under `prefers-reduced-motion: reduce`.
+
+> **Changed 2026-10-16**: inner classes were generic names that a consumer's own CSS could hit,
+> and state was a class. Use the new names:
+>
+> - `.toggle-switch-core` → `.toggle-switch`; `.toggle-switch-with-label` → `.toggle-switch-field`;
+>   `.toggle-switch-with-label-inline` → `.toggle-switch-field[data-layout="inline"]`
+> - `.symbol-wrapper` → `.toggle-switch-track`; `.symbol` → `.toggle-switch-thumb`;
+>   `.symbol-icon` → `.toggle-switch-icon`; `.icon-on` / `.icon-off` → `.toggle-switch-icon-on` /
+>   `.toggle-switch-icon-off`; the bare `input` → `.toggle-switch-input`
+> - `.symbol.checked` and `.symbol-icon.active` → `.toggle-switch[data-checked]`
+> - the unused `.use-default-icons` class and the default icon's `.icon` class are gone
+> - the Field's label class `input-switch-label` → `toggle-switch-label`
+>
+> Also: the inline layout's label wraps instead of `nowrap`, and the inline row now supports a
+> description, an error and `required`.
 
 ---
 
-## Description (ToggleSwitchWithLabel)
+## Description
 
-`ToggleSwitchWithLabel`'s `descriptionText` / `descriptionHtml` slots render through
+`ToggleSwitchField`'s `descriptionText` / `descriptionHtml` slots render through
 `InputDescription`, so they're styled by its `--input-description-*` tokens (see
-`input-description/CONSUMER-STYLING.md`), the same as every other labelled form field. The
-spacing between the description and the switch is
-`--input-description-slot-margin-block-end` (default `0.8rem`). Scope an override to toggles only
-with the `.toggle-switch-description` class it adds:
+`input-description/CONSUMER-STYLING.md`). Scope an override to toggles with
+`.toggle-switch-description`:
 
 ```css
 .toggle-switch-description {
@@ -70,6 +100,8 @@ with the `.toggle-switch-description` class it adds:
 }
 ```
 
+---
+
 ## Global theming
 
 ```css
@@ -92,28 +124,17 @@ Set the tokens above on an element you own (a page or section class, or a class
 ### One instance
 
 ```vue
-<ToggleSwitchCore id="notifications" name="notifications" style="--toggle-switch-symbol-surface-on: var(--gold-06);" />
+<ToggleSwitchField
+  v-model="notifications"
+  name="notifications"
+  label="Notifications"
+  style="--toggle-switch-symbol-surface-on: var(--gold-06);"
+/>
 ```
 
 ---
 
-## Migration notes (2026-09-23)
-
-- **`round` prop was previously dead** — `ToggleSwitchWithLabel`/`ToggleSwitchWithLabelInline`
-  both accepted and forwarded it, but `ToggleSwitchCore` never declared the prop or read it, so
-  the Storybook `SquareShape` story rendered identically to `Default`. Fixed by adding `round` to
-  `ToggleSwitchCore` and wiring it to the new `--toggle-switch-border-radius` token (see Shape
-  above).
-- **`fieldHasError` didn't visually theme the component** — `ToggleSwitchCore` and
-  `ToggleSwitchWithLabel` both computed an error-aware theme value but bound `data-theme` to the
-  raw `theme` prop instead, so setting `fieldHasError` never applied this library's
-  `[data-theme="error"]` theme-token overrides (`_error.css`). Fixed by binding `data-theme` to the
-  computed value.
-- Custom `iconOn`/`iconOff` slot content could render as a non-square box (e.g. a 16×16 SVG
-  rendering as ~16×20), throwing off centering inside the thumb — fixed by adding
-  `line-height: 0` to `.symbol-icon`, which collapses inline leading for any slotted content.
-- Two dead, unread `--_transition-duration` private locals were removed from
-  `ToggleSwitchWithLabel`/`ToggleSwitchWithLabelInline` — nothing in either file's CSS or
-  `ToggleSwitchCore`'s ever read them (the actual transition durations are hardcoded `0.4s`
-  literals in `ToggleSwitchCore`).
+## Class passthrough
 
+`ToggleSwitch`'s `:style-class-passthrough` lands on its root `.toggle-switch`, and
+`ToggleSwitchField`'s on its root `.toggle-switch-field`.