D9Label help text is easier to read and has an id (<id>-help); D9Select passes aria-describedby to its button

src/Label/Label.stories.ts

@@ -1,4 +1,5 @@
 import D9Label from "./Label.vue";
+import D9Input from "../Input/Input.vue";
 
 export default {
   title: "Forms/Label",
@@ -21,3 +22,16 @@ export const WithDescription = (args: Record<string, unknown>) => ({
   template:
     '<D9Label id="name" label="Your name" description="Please use your full name." />',
 });
+
+export const LinkedToField = (args: Record<string, unknown>) => ({
+  components: { D9Label, D9Input },
+  setup() {
+    return { args };
+  },
+  // The help text gets the id "<id>-help": point the field at it with aria-describedby.
+  template: `
+    <div>
+      <D9Label id="name" label="Your name" description="Please use your full name." />
+      <D9Input id="name" aria-describedby="name-help" />
+    </div>`,
+});

src/Label/Label.vue

@@ -11,7 +11,8 @@
   >
     <label :id="id ? `${id}-label` : undefined" :for="id">{{ label }}</label>
     <span
-      class="block text-xs text-grey-400 font-normal mono-0 casual-60"
+      :id="id ? `${id}-help` : undefined"
+      class="block text-xs text-grey-500 dark:text-grey-400 font-normal mono-0 casual-60"
       v-if="description"
       >{{ description }}</span
     >

src/Select/Select.vue

@@ -5,11 +5,13 @@
     @update:model-value="onSelect"
     :by="by"
     :disabled="isDisabled"
+    v-bind="wrapperAttrs()"
   >
     <div class="relative">
       <ListboxButton
         :id="id"
         :aria-labelledby="labelledBy"
+        :aria-describedby="attrs['aria-describedby'] as string"
         class="w-full mono-50 bg-white text-grey-800 placeholder-grey-600 border border-grey-300 dark:bg-grey-800 dark:text-grey-100 dark:placeholder-grey-400 dark:border-grey-700 focus:ring-2 focus:border-blue-400 focus:ring-blue-400 focus:outline-none dark:focus:border-blue-800 dark:focus:ring-blue-800 cursor-default rounded font-normal text-left"
         :class="[inputClasses, textSizeClasses, disabledClasses]"
       >
@@ -120,7 +122,14 @@ import {
   ListboxOptions,
 } from "@headlessui/vue";
 import { Size } from "../types/types";
-import { computed, onMounted, ref, watch, withDefaults } from "vue";
+import {
+  computed,
+  onMounted,
+  ref,
+  useAttrs,
+  watch,
+  withDefaults,
+} from "vue";
 import { useFormClasses } from "../utils/useFormClasses";
 
 interface SelectOption {
@@ -150,8 +159,18 @@ const props = withDefaults(
   }
 );
 
+defineOptions({ inheritAttrs: false });
+
 const selected = ref(props.modelValue ?? null);
 
+// aria-describedby belongs on the button the screen reader focuses; other attrs stay on the wrapper.
+const attrs = useAttrs();
+// a function, not a computed: attrs isn't reactive, so a computed would miss attrs set later
+const wrapperAttrs = () =>
+  Object.fromEntries(
+    Object.entries(attrs).filter(([name]) => name !== "aria-describedby")
+  );
+
 const emit = defineEmits<{
   (e: "update:modelValue", value: SelectOption): void;
 }>();

tests/Label.spec.ts

@@ -0,0 +1,39 @@
+import { mount } from "@vue/test-utils";
+import { describe, expect, it } from "vitest";
+import { D9Label } from "../src";
+
+describe("D9Label help text", () => {
+  it("gets the id <id>-help next to <id>-label", () => {
+    const wrapper = mount(D9Label, {
+      props: { id: "name", label: "Name", description: "Full name." },
+    });
+
+    expect(wrapper.find("label").attributes("id")).toBe("name-label");
+    expect(wrapper.find("#name-help").text()).toBe("Full name.");
+  });
+
+  it("has no help id without an id", () => {
+    const wrapper = mount(D9Label, {
+      props: { label: "Name", description: "Full name." },
+    });
+
+    expect(wrapper.find("[id]").exists()).toBe(false);
+  });
+
+  it("renders no help element without a description", () => {
+    const wrapper = mount(D9Label, { props: { id: "name", label: "Name" } });
+
+    expect(wrapper.find("#name-help").exists()).toBe(false);
+  });
+
+  it("uses a text color with at least 4.5:1 contrast on white and grey-50", () => {
+    const wrapper = mount(D9Label, {
+      props: { id: "name", label: "Name", description: "Full name." },
+    });
+    const classes = wrapper.find("#name-help").classes();
+
+    // grey is slate: 500 is 4.76:1 on white, 4.55:1 on grey-50; 400 is only 2.56 / 2.45
+    expect(classes).toContain("text-grey-500");
+    expect(classes).not.toContain("text-grey-400");
+  });
+});

tests/Select.spec.ts

@@ -23,4 +23,28 @@ describe("D9Select", () => {
 
     expect(wrapper.emitted("update:modelValue")).toBeUndefined();
   });
+
+  it("puts aria-describedby on the button and other attrs on the wrapper", () => {
+    const wrapper = mount(D9Select, {
+      props: { options },
+      attrs: { "aria-describedby": "x-help", class: "mt-2", "data-a": "1" },
+    });
+
+    expect(wrapper.find("button").attributes("aria-describedby")).toBe(
+      "x-help"
+    );
+    // the wrapper's opening tag is the first line of the markup
+    const wrapperTag = wrapper.html().split("\n")[0];
+    expect(wrapperTag).toContain('class="mt-2"');
+    expect(wrapperTag).toContain('data-a="1"');
+    expect(wrapperTag).not.toContain("aria-describedby");
+  });
+
+  it("shows a class set after the first render on the wrapper", async () => {
+    const wrapper = mount(D9Select, { props: { options } });
+
+    await wrapper.setProps({ class: "mt-2" });
+
+    expect(wrapper.html().split("\n")[0]).toContain('class="mt-2"');
+  });
 });