srcdev-nuxt-components 9.4.12 → 9.5.1

package/app/components/05.forms/pending-effect/stories/PendingEffect.stories.ts

@@ -0,0 +1,132 @@
+import type { Meta, StoryFn } from "@nuxtjs/storybook";
+import { computed } from "vue";
+import InputButton from "../../input-button/InputButton.vue";
+
+interface PendingEffectStoryArgs {
+  isPending: boolean;
+  theme: "default" | "success" | "error" | "warning";
+  variant: "primary" | "secondary" | "tertiary";
+  buttonText: string;
+  lineColor: string;
+  blurColor: string;
+  lineThickness: string;
+  lineLength: string;
+  blurSize: string;
+  offset: string;
+  animationDuration: string;
+}
+
+export default {
+  title: "Components/Forms/Pending Effect/PendingEffect",
+  argTypes: {
+    isPending: { control: "boolean", description: "InputButton is-pending", table: { category: "State" } },
+    theme: {
+      control: { type: "select" },
+      options: ["default", "success", "error", "warning"],
+      table: { category: "State" },
+    },
+    variant: {
+      control: { type: "select" },
+      options: ["primary", "secondary", "tertiary"],
+      table: { category: "Host button" },
+    },
+    buttonText: { control: "text", table: { category: "Host button" } },
+    lineColor: {
+      control: "color",
+      description: "--pending-effect-line-color (empty = theme colour, var(--theme-surface))",
+      table: { category: "Tokens" },
+    },
+    blurColor: {
+      control: "color",
+      description: "--pending-effect-blur-color (empty = theme colour; only visible when blurSize > 0rem)",
+      table: { category: "Tokens" },
+    },
+    lineThickness: {
+      control: { type: "select" },
+      options: ["0.1rem", "0.2rem", "0.3rem", "0.4rem", "0.6rem"],
+      description: "--pending-effect-line-thickness (default 0.1rem)",
+      table: { category: "Tokens" },
+    },
+    lineLength: {
+      control: { type: "select" },
+      options: ["1rem", "2rem", "3rem", "3.5rem", "4.5rem"],
+      description: "--pending-effect-line-length (default 2rem; the dash pattern repeats every 5rem)",
+      table: { category: "Tokens" },
+    },
+    blurSize: {
+      control: { type: "select" },
+      options: ["0rem", "0.2rem", "0.3rem", "0.4rem", "0.6rem"],
+      description: "--pending-effect-blur-size (default 0rem = no glow)",
+      table: { category: "Tokens" },
+    },
+    offset: {
+      control: { type: "select" },
+      options: ["0rem", "0.5rem", "1rem", "2rem", "3rem"],
+      description: "--pending-effect-offset (default 1rem, split across both sides)",
+      table: { category: "Tokens" },
+    },
+    animationDuration: {
+      control: { type: "select" },
+      options: ["800ms", "1200ms", "2000ms", "3000ms", "5000ms"],
+      description: "--pending-effect-animation-duration (default 3000ms)",
+      table: { category: "Tokens" },
+    },
+  },
+  args: {
+    isPending: true,
+    theme: "default",
+    variant: "primary",
+    buttonText: "Submitting",
+    lineColor: "",
+    blurColor: "",
+    lineThickness: "0.1rem",
+    lineLength: "2rem",
+    blurSize: "0rem",
+    offset: "1rem",
+    animationDuration: "3000ms",
+  },
+} as Meta<PendingEffectStoryArgs>;
+
+const Template: StoryFn<PendingEffectStoryArgs> = (args) => ({
+  components: { InputButton },
+  setup() {
+    const tokenStyle = computed(() => ({
+      ...(args.lineColor ? { "--pending-effect-line-color": args.lineColor } : {}),
+      ...(args.blurColor ? { "--pending-effect-blur-color": args.blurColor } : {}),
+      "--pending-effect-line-thickness": args.lineThickness,
+      "--pending-effect-line-length": args.lineLength,
+      "--pending-effect-blur-size": args.blurSize,
+      "--pending-effect-offset": args.offset,
+      "--pending-effect-animation-duration": args.animationDuration,
+    }));
+    return { args, tokenStyle };
+  },
+  template: `
+    <div style="margin: 3.6rem;">
+      <p style="font-size: 1.4rem; margin-block-end: 2.4rem;">
+        PendingEffect is rendered by InputButton when <code>has-pending-effect</code> is set, and animates while
+        <code>is-pending</code> is true. It is hidden under <code>prefers-reduced-motion: reduce</code>.
+      </p>
+      <div :style="tokenStyle">
+        <InputButton
+          :button-text="args.buttonText"
+          :variant="args.variant"
+          :theme="args.theme"
+          :is-pending="args.isPending"
+          :has-pending-effect="true"
+        />
+      </div>
+    </div>
+  `,
+});
+
+export const Default = Template.bind({});
+
+export const Exaggerated = Template.bind({});
+Exaggerated.args = {
+  lineThickness: "0.4rem",
+  lineLength: "3.5rem",
+  blurSize: "0.4rem",
+  offset: "2rem",
+  animationDuration: "1200ms",
+};

package/app/components/05.forms/pending-effect/tests/PendingEffect.spec.ts

@@ -0,0 +1,67 @@
+import { describe, it, expect } from "vitest";
+import { nextTick } from "vue";
+import { mountSuspended } from "@nuxt/test-utils/runtime";
+import PendingEffect from "../PendingEffect.vue";
+import InputButton from "../../input-button/InputButton.vue";
+
+describe("PendingEffect", () => {
+  it("mounts without error", async () => {
+    const wrapper = await mountSuspended(PendingEffect);
+    expect(wrapper.vm).toBeTruthy();
+  });
+
+  it("renders a prefixed svg container with blur and line rects", async () => {
+    const wrapper = await mountSuspended(PendingEffect);
+    const svg = wrapper.find("svg.pending-effect-container");
+    expect(svg.exists()).toBe(true);
+    expect(svg.find("rect.pending-effect-blur").exists()).toBe(true);
+    expect(svg.find("rect.pending-effect-line").exists()).toBe(true);
+  });
+
+  it("is hidden from assistive technology and not focusable", async () => {
+    const wrapper = await mountSuspended(PendingEffect);
+    const svg = wrapper.find("svg");
+    expect(svg.attributes("aria-hidden")).toBe("true");
+    expect(svg.attributes("focusable")).toBe("false");
+  });
+
+  it("defaults data-theme to default and reflects the theme prop", async () => {
+    const wrapper = await mountSuspended(PendingEffect);
+    expect(wrapper.find("svg").attributes("data-theme")).toBe("default");
+
+    await wrapper.setProps({ theme: "error" });
+    expect(wrapper.find("svg").attributes("data-theme")).toBe("error");
+  });
+
+  it("applies styleClassPassthrough and updates on change", async () => {
+    const wrapper = await mountSuspended(PendingEffect, { props: { styleClassPassthrough: ["one"] } });
+    expect(wrapper.find("svg").classes()).toContain("one");
+
+    await wrapper.setProps({ styleClassPassthrough: "two three" });
+    await nextTick();
+    const classes = wrapper.find("svg").classes();
+    expect(classes).toContain("two");
+    expect(classes).toContain("three");
+    expect(classes).not.toContain("one");
+  });
+
+  describe("inside InputButton", () => {
+    it("is rendered only when hasPendingEffect is true", async () => {
+      const without = await mountSuspended(InputButton, { props: { buttonText: "Save" } });
+      expect(without.find(".pending-effect-container").exists()).toBe(false);
+
+      const withEffect = await mountSuspended(InputButton, {
+        props: { buttonText: "Save", hasPendingEffect: true },
+      });
+      expect(withEffect.find(".pending-effect-container").exists()).toBe(true);
+      expect(withEffect.find("button").classes()).toContain("pending-effect");
+    });
+
+    it("passes the button theme through", async () => {
+      const wrapper = await mountSuspended(InputButton, {
+        props: { buttonText: "Save", hasPendingEffect: true, theme: "success" },
+      });
+      expect(wrapper.find(".pending-effect-container").attributes("data-theme")).toBe("success");
+    });
+  });
+});

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

@@ -55,7 +55,22 @@ fixed width independent of symbol size).
 
 ---
 
-## Global theming — app-level CSS file
+## 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
 :where(html) {
@@ -66,7 +81,15 @@ fixed width independent of symbol size).
 
 ---
 
-## Per-instance overrides
+## Local overrides
+
+Set the tokens above on an element you own (a page or section class, or a class added with
+`:style-class-passthrough`): they inherit down into the component. Keep the block **unlayered** (no
+`@layer` wrapper) so it beats the library's `@layer components`. If your own file uses
+`<style scoped>`, tokens set on your element still work, but selectors that reach inside the component need
+`:deep()`. Patterns and examples: `.claude/skills/component-local-style-override.md`.
+
+### One instance
 
 ```vue
 <ToggleSwitchCore id="notifications" name="notifications" style="--toggle-switch-symbol-surface-on: var(--gold-06);" />
@@ -93,3 +116,4 @@ fixed width independent of symbol size).
   `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`).
+

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

@@ -1,6 +1,6 @@
 <template>
   <div class="toggle-switch-core" :class="elementClasses" :data-theme="formUiTheme">
-    <div class="toggle-switch-wrapper" :class="wrapperClasses" @click="toggleSwitchValue">
+    <div class="toggle-switch-wrapper" :class="wrapperClasses()" @click="toggleSwitchValue">
       <input
         :id="inputId"
         v-model="modelValue"
@@ -8,7 +8,7 @@
         :true-value
         :false-value
         :aria-invalid="fieldHasError"
-        :aria-describedby="ariaDescribedbyId"
+        :aria-describedby="ariaDescribedby || undefined"
         :name
         :required
         :checked="isChecked"
@@ -60,7 +60,7 @@ const props = withDefaults(defineProps<Props>(), {
 });
 
 const slots = useSlots();
-const useDefaultIcons = computed(() => !slots.iconOn && !slots.iconOff);
+const useDefaultIcons = () => !slots.iconOn && !slots.iconOff;
 
 const formUiTheme = computed(() => {
   return props.fieldHasError ? "error" : props.theme;
@@ -72,16 +72,15 @@ const modelValue = defineModel<string | number | boolean>({ required: true });
 const { elementClasses } = useStyleClassPassthrough(props.styleClassPassthrough);
 
 const inputId = computed(() => `toggle-switch-${props.id}`);
-const ariaDescribedbyId = computed(() => `${props.id}-description`);
 
 const isChecked = computed(() => {
   return modelValue.value === props.trueValue;
 });
 
 // Optimized class computeds to reduce template reactivity
-const wrapperClasses = computed(() => ({
-  "use-default-icons": useDefaultIcons.value,
-}));
+const wrapperClasses = () => ({
+  "use-default-icons": useDefaultIcons(),
+});
 
 const symbolClasses = computed(() => ({
   checked: isChecked.value,
@@ -100,23 +99,6 @@ const toggleSwitchValue = () => {
     }
 
     .toggle-switch-wrapper {
-      /* --_icon-font-size, --_switch-padding, --_toggle-symbol-border-width are the only locals
-       actually read anywhere below — --_icon-on-opacity, --_icon-off-opacity,
-       --_symbol-background-color, --_symbol-margin-inline-start, --_symbol-checked-offset were
-       declared here but never referenced by any property in this file; removed as dead code
-       rather than migrated, since migrating an unread token would just create a new unread
-       public one. */
-      --_icon-font-size: 2.4rem;
-      --_switch-padding: 0.2rem;
-      --_toggle-symbol-border-width: 0.1rem;
-
-      /* Public --toggle-switch-* tokens, inline-fallback to the shared --theme-* tokens (see
-       theming-component-token-pattern.md) — overriding one here doesn't touch every other
-       themed input/control that also reads --theme-checkbox-symbol-surface/--theme-border. */
-      --_surface: var(--toggle-switch-surface, var(--theme-checkbox-symbol-surface));
-      --_surface-hover: var(--toggle-switch-surface-hover, var(--theme-surface-subtle));
-      --_border: var(--toggle-switch-border, var(--theme-border));
-      --_border-focus: var(--toggle-switch-border-focus, var(--theme-border-focus));
       --_border-radius: var(--toggle-switch-border-radius, v-bind(roundedRadiusDefault));
 
       display: flex;
@@ -129,7 +111,7 @@ const toggleSwitchValue = () => {
 
         &:focus-visible {
           + .symbol-wrapper {
-            outline: var(--form-element-outline-width-focus) solid var(--_border-focus);
+            outline: var(--form-element-outline-width-focus) solid var(--toggle-switch-border-focus, var(--theme-border-focus));
             outline-offset: var(--form-element-outline-offset-focus);
           }
         }
@@ -166,15 +148,15 @@ const toggleSwitchValue = () => {
           outline var(--theme-form-transition-duration) linear;
 
         /* UI */
-        background-color: var(--_surface);
-        border: var(--form-element-border-width) solid var(--_border);
+        background-color: var(--toggle-switch-surface, var(--theme-checkbox-symbol-surface));
+        border: var(--form-element-border-width) solid var(--toggle-switch-border, var(--theme-border));
         outline: var(--form-element-outline-width) solid transparent;
         border-radius: var(--_border-radius);
         width: var(--_track-width);
         padding: calc(var(--input-toggle-wrapper-padding) + var(--input-toggle-symbol-outline-width));
 
         &:hover {
-          background-color: var(--_surface-hover);
+          background-color: var(--toggle-switch-surface-hover, var(--theme-surface-subtle));
           cursor: pointer;
         }
 
@@ -190,7 +172,6 @@ const toggleSwitchValue = () => {
           aspect-ratio: 1/1;
 
           /* UI */
-          /* padding: calc(calc(var(--input-toggle-symbol-size) - var(--_icon-font-size)) / 2); */
           border: var(--input-toggle-symbol-border-width) solid var(--toggle-switch-symbol-border, var(--theme-text));
           outline: var(--input-toggle-symbol-outline-width) solid transparent;
           border-radius: var(--_border-radius);

package/app/components/05.forms/toggle-switch/{variants/ToggleSwitchWithLabel.vue → ToggleSwitchWithLabel.vue}

@@ -1,10 +1,8 @@
 <template>
   <div class="toggle-switch-with-label" :class="[elementClasses]" :data-theme="formUiTheme">
     <InputLabel
-      :id
-      :for="toggleSwitchId"
-      :theme
-      :name
+      :id="toggleSwitchId"
+      indicator="none"
       input-variant="normal"
       :field-has-error
       :style-class-passthrough="['input-switch-label', 'input-text-label', 'body-normal-bold']"
@@ -12,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"
@@ -25,7 +32,7 @@
       :false-value
       :theme
       :round
-      :aria-describedby
+      :aria-describedby="ariaDescribedby()"
     >
       <template v-if="slots.iconOn" #iconOn>
         <slot name="iconOn"></slot>
@@ -79,10 +86,16 @@ const toggleSwitchId = computed(() => `toggle-switch-${id}`);
 const descriptionId = computed(() => `${id}-description`);
 const errorId = computed(() => `${id}-error-message`);
 
-const ariaDescribedby = computed(() => {
-  const ariaDescribedbyId = slots.description ? descriptionId.value : undefined;
-  return props.fieldHasError ? errorId.value : ariaDescribedbyId;
-});
+// 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 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 });
 const { elementClasses } = useStyleClassPassthrough(props.styleClassPassthrough);

package/app/components/05.forms/toggle-switch/{variants/ToggleSwitchWithLabelInline.vue → ToggleSwitchWithLabelInline.vue}

@@ -1,10 +1,8 @@
 <template>
   <div class="toggle-switch-with-label-inline" :class="[elementClasses]" :data-theme="theme">
     <InputLabel
-      :id
-      :for="toggleSwitchId"
-      :theme
-      :name
+      :id="toggleSwitchId"
+      indicator="none"
       input-variant="normal"
       :style-class-passthrough="['input-switch-label', 'input-text-label', labelWeightClass]"
     >

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

@@ -1,6 +1,6 @@
 import type { Meta, StoryFn } from "@nuxtjs/storybook";
 import { ref } from "vue";
-import StorybookComponent from "../variants/ToggleSwitchWithLabel.vue";
+import StorybookComponent from "../ToggleSwitchWithLabel.vue";
 import type { FormUiTheme } from "~/types/forms/types.forms.d";
 
 interface ToggleSwitchWithLabelStoryArgs {
@@ -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/stories/ToggleSwitchWithLabelInline.stories.ts

@@ -1,6 +1,6 @@
 import type { Meta, StoryFn } from "@nuxtjs/storybook";
 import { ref } from "vue";
-import StorybookComponent from "../variants/ToggleSwitchWithLabelInline.vue";
+import StorybookComponent from "../ToggleSwitchWithLabelInline.vue";
 import type { FormUiTheme, LabelWeight } from "~/types/forms/types.forms.d";
 
 interface ToggleSwitchWithLabelInlineStoryArgs {
@@ -278,3 +278,6 @@ export const InlineFormExample: StoryFn = () => ({
     </div>
   `,
 });
+
+// Fixed showcase: hardcoded values, so Controls would do nothing here.
+InlineFormExample.parameters = { controls: { disable: true } };

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

@@ -0,0 +1,133 @@
+// https://nuxt.com/docs/getting-started/testing#unit-testing
+import type { VueWrapper } from "@vue/test-utils";
+import { mountSuspended } from "@nuxt/test-utils/runtime";
+import ComponentUnderTest from "../ToggleSwitchWithLabel.vue";
+import { defineComponent, nextTick, ref } from "vue";
+
+const initialPropsData = {
+  name: "notifications",
+  label: "Enable notifications",
+  errorMessage: "",
+  modelValue: false,
+};
+
+let wrapper: VueWrapper<InstanceType<typeof ComponentUnderTest>>;
+const wrapperFactory = (propsData = {}, slots = {}) => {
+  const mockPropsData = { ...initialPropsData, ...propsData };
+
+  return mountSuspended(ComponentUnderTest, {
+    attachTo: document.body,
+    props: mockPropsData,
+    slots,
+  });
+};
+
+describe("ToggleSwitchWithLabel", () => {
+  it("mounts without error", async () => {
+    wrapper = await wrapperFactory();
+    expect(wrapper.vm).toBeTruthy();
+  });
+
+  it("renders the label text", async () => {
+    wrapper = await wrapperFactory({ label: "Enable dark mode" });
+    expect(wrapper.text()).toContain("Enable dark mode");
+  });
+
+  it("renders a checkbox input", async () => {
+    wrapper = await wrapperFactory();
+    expect(wrapper.find("input[type='checkbox']").exists()).toBe(true);
+  });
+
+  it("associates the label with the checkbox via matching for/id", async () => {
+    wrapper = await wrapperFactory();
+    const inputId = wrapper.find("input[type='checkbox']").attributes("id");
+    expect(wrapper.find("label").attributes("for")).toBe(inputId);
+  });
+
+  it("renders the error message when fieldHasError is true", async () => {
+    wrapper = await wrapperFactory({ fieldHasError: true, errorMessage: "You must accept" });
+    expect(wrapper.text()).toContain("You must accept");
+  });
+
+  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 () => {
+    wrapper = await wrapperFactory({ required: true });
+    expect(wrapper.find("input").attributes("required")).toBeDefined();
+  });
+
+  it("applies the error theme to ToggleSwitchCore when fieldHasError is true", async () => {
+    wrapper = await wrapperFactory({ fieldHasError: true, theme: "default" });
+    expect(wrapper.find(".toggle-switch-core").attributes("data-theme")).toBe("error");
+  });
+
+  it("applies styleClassPassthrough to the root element", async () => {
+    wrapper = await wrapperFactory({ styleClassPassthrough: ["custom-toggle"] });
+    expect(wrapper.find(".toggle-switch-with-label").classes()).toContain("custom-toggle");
+  });
+
+  it("forwards round to ToggleSwitchCore without leaking it as a DOM attribute", async () => {
+    wrapper = await wrapperFactory({ round: false });
+    const core = wrapper.findComponent({ name: "ToggleSwitchCore" });
+    expect(core.props("round")).toBe(false);
+    expect(wrapper.find(".toggle-switch-core").attributes("round")).toBeUndefined();
+  });
+
+  it("points aria-describedby at the description once it appears after mount", async () => {
+    const Host = defineComponent({
+      components: { ComponentUnderTest },
+      setup() {
+        return { modelValue: ref(false), showDescription: ref(false) };
+      },
+      template: `
+        <ComponentUnderTest v-model="modelValue" name="notifications" label="Enable notifications" error-message="">
+          <template v-if="showDescription" #descriptionText>Sends at most one email a week.</template>
+        </ComponentUnderTest>
+      `,
+    });
+    const host = await mountSuspended(Host);
+    const input = () => host.find("input[type='checkbox']");
+    expect(input().attributes("aria-describedby")).toBeFalsy();
+    (host.vm as unknown as { showDescription: boolean }).showDescription = true;
+    await nextTick();
+    expect(input().attributes("aria-describedby")).toMatch(/-description$/);
+  });
+
+  it("points aria-describedby at the error message when the field has an error", async () => {
+    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);
+  });
+});