feat(cfasim-ui): add autocomplete mode to SelectBox

Author: k88hudson-cfa

cfasim-ui/components/src/SelectBox/SelectBox.md

@@ -1,12 +1,19 @@
+---
+keywords: [select, dropdown, autocomplete, combobox, filter, search, typeahead]
+---
+
 # SelectBox
 
-A dropdown select built on reka-ui.
+A single-select dropdown built on reka-ui. Set `autocomplete` to turn it into a
+filterable single-select combobox: type to narrow the options, just like
+[MultiSelect](./multi-select) but bound to a single `string`.
 
 ## Examples
 
 <script setup>
 import { ref } from 'vue'
 const interval = ref('weekly')
+const state = ref('')
 </script>
 
 <ComponentDemo>
@@ -83,6 +90,73 @@ DOM.
   </template>
 </ComponentDemo>
 
+### Autocomplete
+
+Add `autocomplete` to make the field filterable. Type to narrow the list; the
+selected option's label fills the input. `v-model` is still a single `string`.
+
+<ComponentDemo>
+  <div style="width: 240px">
+    <SelectBox
+      v-model="state"
+      autocomplete
+      label="State"
+      placeholder="Search states…"
+      :options="[
+        { value: 'ca', label: 'California' },
+        { value: 'ny', label: 'New York' },
+        { value: 'tx', label: 'Texas' },
+        { value: 'wa', label: 'Washington' },
+        { value: 'fl', label: 'Florida' },
+      ]"
+    />
+  </div>
+
+<template #code>
+
+```vue
+<script setup>
+import { ref } from "vue";
+const state = ref("");
+</script>
+
+<SelectBox
+  v-model="state"
+  autocomplete
+  label="State"
+  placeholder="Search states…"
+  :options="[
+    { value: 'ca', label: 'California' },
+    { value: 'ny', label: 'New York' },
+    { value: 'tx', label: 'Texas' },
+    { value: 'wa', label: 'Washington' },
+    { value: 'fl', label: 'Florida' },
+  ]"
+/>
+```
+
+  </template>
+</ComponentDemo>
+
+## Accessibility
+
+In the default mode the field is a reka-ui Select; with `autocomplete` it's a
+reka-ui Combobox following the
+[ARIA combobox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/):
+
+- The input has `role="combobox"` with `aria-expanded`, `aria-controls`, and
+  `aria-autocomplete="list"`; the popup is a `role="listbox"` and each option a
+  `role="option"` that reflects its state via `aria-selected`.
+- Keyboard support is handled for you: type to filter, ↑/↓ to move through the
+  list, Enter to select the highlighted option, and Escape to close.
+- Pass `label` so the field is named by a real `<label>`. In autocomplete mode
+  the label is also wired to the input via `for`/`id`, so clicking it focuses
+  the field; use `hide-label` to keep the label for screen readers while hiding
+  it visually, or `aria-label` when there's no visible label text.
+- The chevron is a labelled toggle (`aria-label="Toggle options"`) kept out of
+  the tab order, and native browser autofill is disabled so it can't cover the
+  option list.
+
 <!--@include: ./_api/select-box.md-->
 
 ### SelectOption

cfasim-ui/components/src/SelectBox/SelectBox.spec.ts

@@ -7,3 +7,46 @@ test("SelectBox page renders demos", async ({ page }) => {
   await expect(demos.first()).toBeVisible();
   await expect(demos.first().getByText("Interval")).toBeVisible();
 });
+
+test("SelectBox autocomplete filters and selects an option", async ({
+  page,
+}) => {
+  await page.goto("./cfasim-ui/components/select-box");
+  const demo = page.locator(".demo-preview", {
+    has: page.locator(".select-input"),
+  });
+  const input = demo.locator(".select-input").first();
+
+  await input.click();
+  await input.fill("tex");
+  await expect(page.getByRole("option", { name: "Texas" })).toBeVisible();
+  await expect(page.getByRole("option", { name: "California" })).toHaveCount(0);
+
+  await page.getByRole("option", { name: "Texas" }).click();
+  // The selected label fills the input and the list collapses.
+  await expect(input).toHaveValue("Texas");
+  await expect(page.getByRole("option")).toHaveCount(0);
+});
+
+test("SelectBox autocomplete is operable by keyboard", async ({ page }) => {
+  await page.goto("./cfasim-ui/components/select-box");
+  const demo = page.locator(".demo-preview", {
+    has: page.locator(".select-input"),
+  });
+  const input = demo.locator(".select-input").first();
+
+  // The combobox exposes the ARIA combobox pattern.
+  await expect(input).toHaveRole("combobox");
+  await expect(input).toHaveAttribute("aria-autocomplete", "list");
+
+  await input.click();
+  await expect(input).toHaveAttribute("aria-expanded", "true");
+  await expect(page.getByRole("listbox")).toBeVisible();
+
+  // Filter, then pick the highlighted option with the keyboard only.
+  await input.fill("wash");
+  await page.keyboard.press("ArrowDown");
+  await page.keyboard.press("Enter");
+  await expect(input).toHaveValue("Washington");
+  await expect(input).toHaveAttribute("aria-expanded", "false");
+});

cfasim-ui/components/src/SelectBox/SelectBox.test.ts

@@ -54,4 +54,92 @@ describe("SelectBox", () => {
     expect(trigger.attributes("role")).toBe("combobox");
     expect(trigger.attributes("aria-labelledby")).toBeDefined();
   });
+
+  describe("autocomplete", () => {
+    it("renders a combobox input instead of the select trigger", () => {
+      const wrapper = mount(SelectBox, {
+        props: {
+          label: "Interval",
+          options,
+          modelValue: "daily",
+          autocomplete: true,
+        },
+      });
+      expect(wrapper.find(".select-trigger").exists()).toBe(false);
+      const input = wrapper.find(".select-input");
+      expect(input.exists()).toBe(true);
+      expect(input.attributes("role")).toBe("combobox");
+    });
+
+    it("displays the selected option's label in the input", () => {
+      const wrapper = mount(SelectBox, {
+        props: { options, modelValue: "weekly", autocomplete: true },
+      });
+      expect(
+        (wrapper.find(".select-input").element as HTMLInputElement).value,
+      ).toBe("Weekly");
+    });
+
+    it("labels the input via aria-labelledby when a label is given", () => {
+      const wrapper = mount(SelectBox, {
+        props: {
+          label: "Interval",
+          options,
+          modelValue: "daily",
+          autocomplete: true,
+        },
+      });
+      expect(
+        wrapper.find(".select-input").attributes("aria-labelledby"),
+      ).toBeDefined();
+    });
+
+    it("associates the label with the input for click-to-focus", () => {
+      const wrapper = mount(SelectBox, {
+        props: {
+          label: "Interval",
+          options,
+          modelValue: "daily",
+          autocomplete: true,
+        },
+      });
+      const inputId = wrapper.find(".select-input").attributes("id");
+      expect(inputId).toBeTruthy();
+      expect(wrapper.find(".select-label").attributes("for")).toBe(inputId);
+    });
+
+    it("advertises list autocomplete and disables native autofill", () => {
+      const wrapper = mount(SelectBox, {
+        props: { options, modelValue: "daily", autocomplete: true },
+      });
+      const input = wrapper.find(".select-input");
+      expect(input.attributes("aria-autocomplete")).toBe("list");
+      // Suppress the browser's own autofill dropdown over reka's listbox.
+      expect(input.attributes("autocomplete")).toBe("off");
+    });
+
+    it("exposes the chevron as a labelled toggle outside the tab order", () => {
+      const wrapper = mount(SelectBox, {
+        props: { options, modelValue: "daily", autocomplete: true },
+      });
+      const toggle = wrapper.find(".select-icon-button");
+      expect(toggle.attributes("aria-label")).toBe("Toggle options");
+      expect(toggle.attributes("aria-haspopup")).toBe("listbox");
+      expect(toggle.attributes("tabindex")).toBe("-1");
+    });
+
+    it("falls back to ariaLabel when no label is given", () => {
+      const wrapper = mount(SelectBox, {
+        props: {
+          options,
+          modelValue: "",
+          autocomplete: true,
+          ariaLabel: "Pick interval",
+        },
+      });
+      expect(wrapper.find(".select-input").attributes("aria-label")).toBe(
+        "Pick interval",
+      );
+    });
+  });
 });