srcdev-nuxt-components 9.5.0 → 9.5.1

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/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 rather than useAriaDescribedById's computed: 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/package.json

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