srcdev-nuxt-components 9.5.0 → 9.5.2

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

@@ -41,7 +41,7 @@ No slots.
 ```vue
 <template>
   <div class="my-field">
-    <input :id :aria-describedby :aria-invalid="fieldHasError" />
+    <input :id :aria-describedby="ariaDescribedby()" :aria-invalid="fieldHasError" />
     <InputError :id="errorId" :error-message :show-error="fieldHasError" :is-detached="false" :input-variant />
   </div>
 </template>

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

@@ -100,7 +100,7 @@ full table with defaults.
 ### ToggleSwitchWithLabel
 
 `ToggleSwitchWithLabel` (`ToggleSwitchWithLabel.vue`) composes `ToggleSwitchCore` with
-`InputLabel`, an optional `description` slot, and `InputError`.
+`InputLabel`, an optional description (rendered by `InputDescription`, the same as every other labelled form field), and `InputError`.
 
 **Additional props over ToggleSwitchCore:**
 
@@ -113,7 +113,9 @@ Note this wrapper passes `id`/`name`/`required`/`field-has-error`/`true-value`/`
 `theme`/`round`/`aria-describedby` straight through to `ToggleSwitchCore`; `id` is a self-generated
 `useId()` value, not a prop — consumers don't set it directly.
 
-**Slots**: `description`, `iconOn`, `iconOff` (the latter two forwarded to `ToggleSwitchCore`).
+**Slots**: `descriptionText` / `descriptionHtml` (help text between the label and the switch, via `InputDescription`), `iconOn`, `iconOff` (the latter two forwarded to `ToggleSwitchCore`).
+
+The switch's `aria-describedby` lists the description id when a description slot is present and the error id when `field-has-error` is true, both together when both apply.
 
 ```vue
 <ToggleSwitchWithLabel
@@ -123,10 +125,27 @@ Note this wrapper passes `id`/`name`/`required`/`field-has-error`/`true-value`/`
   :error-message="errors.notifications"
   :field-has-error="!!errors.notifications"
 >
-  <template #description>Turn this on to receive notifications</template>
+  <template #descriptionText>Turn this on to receive notifications</template>
 </ToggleSwitchWithLabel>
 ```
 
+#### Breaking change 2026-09-29: description slot
+
+The `description` slot is removed. Use `descriptionText` (plain text, wrapped in a `<p>`) or
+`descriptionHtml` (rich markup) instead. The old slot rendered into a bare `<div>` with no class,
+spacing or tokens, so its content sat flush against the switch; it now goes through
+`InputDescription` like every other labelled form field, styled by the `--input-description-*`
+tokens (see `input-description` CONSUMER-STYLING.md) and targetable as
+`.toggle-switch-description`. `aria-describedby` also used to drop the description id whenever
+the field had an error; it now lists both.
+
+```vue
+<!-- before -->
+<template #description>Sends at most one email a week.</template>
+<!-- after -->
+<template #descriptionText>Sends at most one email a week.</template>
+```
+
 ### ToggleSwitchWithLabelInline
 
 `ToggleSwitchWithLabelInline` (`ToggleSwitchWithLabelInline.vue`) composes

package/.claude/skills/index.md

@@ -149,7 +149,7 @@ Each skill is a single markdown file named `<area>-<task>.md`.
     ├── 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
     ├── 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
     ├── 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
-    ├── 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/ToggleSwitchWithLabelInline
+    ├── 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
     ├── 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?"

package/.vscode/srcdev-component-toggle-switch.code-snippets

@@ -20,7 +20,9 @@
       "  label=\"$3Field label\"",
       "  :error-message=\"$4errors.fieldName\"",
       "  :field-has-error=\"!!$4errors.fieldName\"",
-      "/>"
+      ">",
+      "  <template #descriptionText>$5Help text</template>",
+      "</ToggleSwitchWithLabel>"
     ]
   },
   "SRCDEV ToggleSwitchWithLabelInline": {

package/app/components/05.forms/input-checkbox/MultipleCheckboxes.vue

@@ -39,7 +39,7 @@
             :theme
             :input-variant
             :direction
-            :aria-describedby
+            :aria-describedby="ariaDescribedby()"
             :display-as-disc
             :is-pill="isPill"
           >
@@ -64,7 +64,7 @@
             :true-value="item.value"
             :theme
             :input-variant
-            :aria-describedby
+            :aria-describedby="ariaDescribedby()"
             :display-as-disc
           >
             <template #checkedIcon>

package/app/components/05.forms/input-checkbox/SingleCheckbox.vue

@@ -35,7 +35,7 @@
           :false-value
           :theme
           :input-variant
-          :aria-describedby
+          :aria-describedby="ariaDescribedby()"
         >
           <template #checkedIcon>
             <slot name="checkedIcon"></slot>

package/app/components/05.forms/input-number/InputNumberField.vue

@@ -43,7 +43,7 @@
       :input-variant
       :field-has-error
       :style-class-passthrough
-      :aria-describedby
+      :aria-describedby="ariaDescribedby()"
     >
       <template v-if="slots.left" #left>
         <InputButton

package/app/components/05.forms/input-radio/MultipleRadiobuttons.vue

@@ -40,7 +40,7 @@
             :theme
             :input-variant
             :direction
-            :aria-describedby
+            :aria-describedby="ariaDescribedby()"
             :is-pill="isPill"
           >
             <template #checkedIcon>
@@ -63,7 +63,7 @@
             :true-value="item.value"
             :theme
             :input-variant
-            :aria-describedby
+            :aria-describedby="ariaDescribedby()"
           >
             <template #checkedIcon>
               <slot name="checkedIcon"></slot>

package/app/components/05.forms/input-range/InputRangeDefault.vue

@@ -39,7 +39,7 @@
       :required
       :weight
       :field-has-error
-      :aria-describedby="ariaDescribedby"
+      :aria-describedby="ariaDescribedby()"
       :style-class-passthrough="styleClassPassthrough"
     >
       <template v-if="slots.datalist" #datalist>

package/app/components/05.forms/input-select/InputSelectWithLabel.vue

@@ -44,7 +44,7 @@
         :required
         :style-class-passthrough
         :theme="FormUiTheme"
-        :aria-describedby
+        :aria-describedby="ariaDescribedby()"
         :input-variant
       />
 

package/app/components/05.forms/input-text/InputTextAsNumberWithLabel.vue

@@ -45,7 +45,7 @@
       :style-class-passthrough="elementClasses"
       :theme
       inputmode="numeric"
-      :aria-describedby
+      :aria-describedby="ariaDescribedby()"
       :input-variant
     >
       <template v-if="slots.left" #left>

package/app/components/05.forms/input-text/InputTextWithLabel.vue

@@ -49,7 +49,7 @@
         :required
         :style-class-passthrough
         :theme
-        :aria-describedby
+        :aria-describedby="ariaDescribedby()"
         :input-variant
       >
         <template v-if="slots.left" #left>

package/app/components/05.forms/input-text/tests/InputTextWithLabel.spec.ts

@@ -2,6 +2,7 @@
 import type { VueWrapper } from "@vue/test-utils";
 import { mountSuspended } from "@nuxt/test-utils/runtime";
 import ComponentUnderTest from "../InputTextWithLabel.vue";
+import { defineComponent, nextTick, ref } from "vue";
 
 const initialPropsData = {
   type: "text" as const,
@@ -44,4 +45,27 @@ describe("InputTextWithLabel", () => {
     expect(input.attributes("min")).toBe("2026-01-01");
     expect(input.attributes("max")).toBe("2026-12-31");
   });
+
+  it("points aria-describedby at the description once it appears after mount", async () => {
+    const Host = defineComponent({
+      components: { ComponentUnderTest },
+      setup() {
+        return { modelValue: ref(""), showDescription: ref(false) };
+      },
+      template: `
+        <ComponentUnderTest v-model="modelValue" type="text" name="email" label="Email" error-message="">
+          <template v-if="showDescription" #descriptionText>We never share it.</template>
+        </ComponentUnderTest>
+      `,
+    });
+    const host = await mountSuspended(Host);
+    const input = () => host.find("input");
+    expect(input().attributes("aria-describedby")).toBeFalsy();
+    (host.vm as unknown as { showDescription: boolean }).showDescription = true;
+    await nextTick();
+    expect(input().attributes("aria-describedby")).toMatch(/-description$/);
+    (host.vm as unknown as { showDescription: boolean }).showDescription = false;
+    await nextTick();
+    expect(input().attributes("aria-describedby")).toBeFalsy();
+  });
 });

package/app/components/05.forms/input-textarea/InputTextareaWithLabel.vue

@@ -44,7 +44,7 @@
         :style-class-passthrough
         :theme
         :input-variant
-        :aria-describedby
+        :aria-describedby="ariaDescribedby()"
       >
         <template v-if="slots.left" #left>
           <slot name="left"></slot>

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

@@ -55,6 +55,21 @@ fixed width independent of symbol size).
 
 ---
 
+## Description (ToggleSwitchWithLabel)
+
+`ToggleSwitchWithLabel`'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:
+
+```css
+.toggle-switch-description {
+  --input-description-slot-margin-block-end: 1.2rem;
+}
+```
+
 ## Global theming
 
 ```css

package/app/components/05.forms/toggle-switch/ToggleSwitchWithLabel.vue

@@ -10,9 +10,18 @@
       <template #textLabel>{{ label }}</template>
     </InputLabel>
 
-    <div v-if="slots.description" :id="descriptionId">
-      <slot name="description"></slot>
-    </div>
+    <InputDescription
+      :description-id
+      :field-has-error
+      :style-class-passthrough="['toggle-switch-description']"
+    >
+      <template v-if="slots.descriptionHtml" #descriptionHtml>
+        <slot name="descriptionHtml"></slot>
+      </template>
+      <template v-if="slots.descriptionText" #descriptionText>
+        <slot name="descriptionText"></slot>
+      </template>
+    </InputDescription>
     <ToggleSwitchCore
       :id
       v-model="modelValue"
@@ -77,9 +86,15 @@ const toggleSwitchId = computed(() => `toggle-switch-${id}`);
 const descriptionId = computed(() => `${id}-description`);
 const errorId = computed(() => `${id}-error-message`);
 
+// A plain function, like useAriaDescribedById's: slots aren't reactive, so a computed would keep
+// its first answer if a description slot is added or removed after mount (Claude.md pitfall #25).
+// Lists both ids when there's a description and an error, so the description is still announced
+// while the field is invalid.
 const ariaDescribedby = () => {
-  const ariaDescribedbyId = slots.description ? descriptionId.value : undefined;
-  return props.fieldHasError ? errorId.value : ariaDescribedbyId;
+  const ids: string[] = [];
+  if (slots.descriptionText || slots.descriptionHtml) ids.push(descriptionId.value);
+  if (props.fieldHasError) ids.push(errorId.value);
+  return ids.join(" ");
 };
 
 const modelValue = defineModel<string | number | boolean>({ required: true });

package/app/components/05.forms/toggle-switch/stories/ToggleSwitchWithLabel.stories.ts

@@ -166,9 +166,7 @@ const Template: StoryFn<ToggleSwitchWithLabelStoryArgs> = (_args, { argTypes })
       :theme="args.theme"
       :round="args.round"
     >
-      <template v-if="args.useDescription" #description>
-        <div style="color: #666; font-size: 0.875rem;">{{ args.descriptionContent }}</div>
-      </template>
+      <template v-if="args.useDescription" #descriptionText>{{ args.descriptionContent }}</template>
       <template v-if="args.useCustomIcons" #iconOn>
         <span v-html="args.iconOnContent"></span>
       </template>

package/app/components/05.forms/toggle-switch/tests/ToggleSwitchWithLabel.spec.ts

@@ -49,9 +49,26 @@ describe("ToggleSwitchWithLabel", () => {
     expect(wrapper.text()).toContain("You must accept");
   });
 
-  it("renders the description slot", async () => {
-    wrapper = await wrapperFactory({}, { description: () => "Turn this on to receive notifications" });
-    expect(wrapper.text()).toContain("Turn this on to receive notifications");
+  it("renders descriptionText through InputDescription", async () => {
+    wrapper = await wrapperFactory({}, { descriptionText: () => "Turn this on to receive notifications" });
+    const description = wrapper.find(".input-description.toggle-switch-description");
+    expect(description.exists()).toBe(true);
+    expect(description.find(".input-description-text").text()).toBe("Turn this on to receive notifications");
+  });
+
+  it("renders descriptionHtml through InputDescription", async () => {
+    wrapper = await wrapperFactory({}, { descriptionHtml: () => "Rich description" });
+    expect(wrapper.find(".toggle-switch-description .input-description-html").text()).toBe("Rich description");
+  });
+
+  it("renders no description element without a description slot", async () => {
+    wrapper = await wrapperFactory();
+    expect(wrapper.find(".input-description").exists()).toBe(false);
+  });
+
+  it("no longer renders the removed description slot", async () => {
+    wrapper = await wrapperFactory({}, { description: () => "Old slot content" });
+    expect(wrapper.text()).not.toContain("Old slot content");
   });
 
   it("forwards required to the underlying input", async () => {
@@ -84,7 +101,7 @@ describe("ToggleSwitchWithLabel", () => {
       },
       template: `
         <ComponentUnderTest v-model="modelValue" name="notifications" label="Enable notifications" error-message="">
-          <template v-if="showDescription" #description>Sends at most one email a week.</template>
+          <template v-if="showDescription" #descriptionText>Sends at most one email a week.</template>
         </ComponentUnderTest>
       `,
     });
@@ -100,4 +117,17 @@ describe("ToggleSwitchWithLabel", () => {
     wrapper = await wrapperFactory({ fieldHasError: true, errorMessage: "Required" });
     expect(wrapper.find("input[type='checkbox']").attributes("aria-describedby")).toMatch(/-error-message$/);
   });
+
+  it("points aria-describedby at both the description and the error when both are present", async () => {
+    wrapper = await wrapperFactory(
+      { fieldHasError: true, errorMessage: "Required" },
+      { descriptionText: () => "Sends at most one email a week." }
+    );
+    const describedBy = wrapper.find("input[type='checkbox']").attributes("aria-describedby") ?? "";
+    const ids = describedBy.split(" ");
+    expect(ids).toHaveLength(2);
+    expect(ids[0]).toMatch(/-description$/);
+    expect(ids[1]).toMatch(/-error-message$/);
+    expect(wrapper.find(`[id="${ids[0]}"]`).exists()).toBe(true);
+  });
 });

package/app/composables/tests/useAriaDescribedById.spec.ts

@@ -38,7 +38,7 @@ describe("useAriaDescribedById", () => {
   describe("ariaDescribedby", () => {
     it("is null when no slots and no error", () => {
       const { ariaDescribedby } = useAriaDescribedById("email", ref(false), noSlots);
-      expect(ariaDescribedby.value).toBeNull();
+      expect(ariaDescribedby()).toBeNull();
     });
 
     it("includes descriptionId when descriptionText slot is present", () => {
@@ -47,7 +47,7 @@ describe("useAriaDescribedById", () => {
         ref(false),
         withSlot("descriptionText")
       );
-      expect(ariaDescribedby.value).toContain(descriptionId);
+      expect(ariaDescribedby()).toContain(descriptionId);
     });
 
     it("includes descriptionId when descriptionHtml slot is present", () => {
@@ -56,7 +56,7 @@ describe("useAriaDescribedById", () => {
         ref(false),
         withSlot("descriptionHtml")
       );
-      expect(ariaDescribedby.value).toContain(descriptionId);
+      expect(ariaDescribedby()).toContain(descriptionId);
     });
 
     it("includes descriptionId when description slot is present", () => {
@@ -65,17 +65,17 @@ describe("useAriaDescribedById", () => {
         ref(false),
         withSlot("description")
       );
-      expect(ariaDescribedby.value).toContain(descriptionId);
+      expect(ariaDescribedby()).toContain(descriptionId);
     });
 
     it("includes errorId when fieldHasError is true", () => {
       const { errorId, ariaDescribedby } = useAriaDescribedById("email", ref(true), noSlots);
-      expect(ariaDescribedby.value).toContain(errorId);
+      expect(ariaDescribedby()).toContain(errorId);
     });
 
     it("does not include errorId when fieldHasError is false (value is null)", () => {
       const { ariaDescribedby } = useAriaDescribedById("email", ref(false), noSlots);
-      expect(ariaDescribedby.value).toBeNull();
+      expect(ariaDescribedby()).toBeNull();
     });
 
     it("does not include errorId when slot is present but fieldHasError is false", () => {
@@ -84,7 +84,7 @@ describe("useAriaDescribedById", () => {
         ref(false),
         withSlot("descriptionText")
       );
-      expect(ariaDescribedby.value).not.toContain(errorId);
+      expect(ariaDescribedby()).not.toContain(errorId);
     });
 
     it("includes both descriptionId and errorId when slot present and error active", () => {
@@ -94,8 +94,8 @@ describe("useAriaDescribedById", () => {
         fieldHasError,
         withSlot("descriptionText")
       );
-      expect(ariaDescribedby.value).toContain(descriptionId);
-      expect(ariaDescribedby.value).toContain(errorId);
+      expect(ariaDescribedby()).toContain(descriptionId);
+      expect(ariaDescribedby()).toContain(errorId);
     });
 
     it("descriptionId appears before errorId in the combined string", () => {
@@ -105,7 +105,7 @@ describe("useAriaDescribedById", () => {
         fieldHasError,
         withSlot("descriptionText")
       );
-      const value = ariaDescribedby.value!;
+      const value = ariaDescribedby()!;
       expect(value.indexOf(descriptionId)).toBeLessThan(value.indexOf(errorId));
     });
   });
@@ -116,19 +116,35 @@ describe("useAriaDescribedById", () => {
     it("ariaDescribedby updates when fieldHasError changes to true", async () => {
       const fieldHasError = ref(false);
       const { errorId, ariaDescribedby } = useAriaDescribedById("email", fieldHasError, noSlots);
-      expect(ariaDescribedby.value).toBeNull();
+      expect(ariaDescribedby()).toBeNull();
       fieldHasError.value = true;
       await nextTick();
-      expect(ariaDescribedby.value).toContain(errorId);
+      expect(ariaDescribedby()).toContain(errorId);
     });
 
     it("ariaDescribedby updates when fieldHasError changes back to false", async () => {
       const fieldHasError = ref(true);
       const { ariaDescribedby } = useAriaDescribedById("email", fieldHasError, noSlots);
-      expect(ariaDescribedby.value).toBeTruthy();
+      expect(ariaDescribedby()).toBeTruthy();
       fieldHasError.value = false;
       await nextTick();
-      expect(ariaDescribedby.value).toBeNull();
+      expect(ariaDescribedby()).toBeNull();
+    });
+
+    it("picks up a description slot added after setup", () => {
+      const slots: Slots = {};
+      const { descriptionId, ariaDescribedby } = useAriaDescribedById("email", ref(false), slots);
+      expect(ariaDescribedby()).toBeNull();
+      slots.descriptionText = () => [];
+      expect(ariaDescribedby()).toBe(descriptionId);
+    });
+
+    it("drops a description slot removed after setup", () => {
+      const slots: Slots = withSlot("descriptionText");
+      const { ariaDescribedby } = useAriaDescribedById("email", ref(false), slots);
+      expect(ariaDescribedby()).toBeTruthy();
+      delete slots.descriptionText;
+      expect(ariaDescribedby()).toBeNull();
     });
   });
 });

package/app/composables/useAriaDescribedById.ts

@@ -5,7 +5,11 @@ export function useAriaDescribedById(name: string | Ref<string>, fieldHasError:
   const errorId = `${id}-error-message`;
   const descriptionId = `${id}-description`;
 
-  const ariaDescribedby = computed(() => {
+  // A plain function, not a computed: the slots object isn't reactive, so a computed would cache
+  // its first answer and keep pointing at (or away from) the description after a description slot
+  // is added or removed post-mount (Claude.md pitfall #25). Call it from the template,
+  // `:aria-describedby="ariaDescribedby()"`, so it's re-evaluated on every render.
+  const ariaDescribedby = () => {
     const hasDescription = slots.descriptionText || slots.descriptionHtml || slots.description;
     const ids = [];
 
@@ -13,7 +17,7 @@ export function useAriaDescribedById(name: string | Ref<string>, fieldHasError:
     if (fieldHasError.value) ids.push(errorId);
 
     return ids.length ? ids.join(" ") : null;
-  });
+  };
 
   return { id, errorId, descriptionId, ariaDescribedby };
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "srcdev-nuxt-components",
   "type": "module",
-  "version": "9.5.0",
+  "version": "9.5.2",
   "main": "nuxt.config.ts",
   "types": "types.d.ts",
   "license": "MIT",