@pnx-mixtape/mxds 0.1.0-rc.2 → 0.1.0-rc.3

package/src/Component/Steps/steps.css

@@ -2,6 +2,8 @@
  * Steps
  */
 
+@import "../../Utility/_mixins.css";
+
 @layer design-system.components {
   .mx-steps {
     counter-reset: step;
@@ -73,6 +75,8 @@
       inset-inline-start: calc((var(--counter-size, 2rem) / 2) + (var(--line-width, 2px)));
       inset-block: 0;
       position: absolute;
+
+      @add-mixin forced-colors-paint;
     }
   }
 
@@ -89,6 +93,15 @@
   .mx-steps--fill:where(:not(:has(.mx-steps--fill))) {
     --background: var(--line-colour, var(--colour-border));
     --foreground: var(--counter-foreground, var(--colour-foreground));
+
+    @media (--forced-colors) {
+      &.mx-steps__panel::before,
+      & .mx-steps__panel::before {
+        forced-color-adjust: none;
+        background-color: CanvasText;
+        border-color: CanvasText;
+      }
+    }
   }
 
   .mx-steps--counters {

package/src/Component/Tabs/Tabs.stories.ts

@@ -12,6 +12,7 @@ import "../Popover/popover.css"
 import "../DropMenu/drop-menu.css"
 import Heading from "../../Atom/Heading/heading.twig"
 import { modes } from "../../../.storybook/modes"
+import { runScreenReaderWalkthrough } from "../../../tools/test-utils/screen-reader"
 
 /**
  * A Tabs component built from a list of TabItems.
@@ -177,6 +178,27 @@ export const Tabs: Story = {
   },
 }
 
+/**
+ * Steps a virtual screen reader through the tab list and asserts on what it announces.
+ */
+export const ScreenReaderAnnouncements: Story = {
+  play: async () => {
+    const log = await runScreenReaderWalkthrough()
+    await expect(log).toEqual([
+      "document",
+      "tablist, orientated horizontally",
+      "tab, Funk, selected, 1 control, position 1, set size 3",
+      "tab, Soul, not selected, 1 control, position 2, set size 3",
+      "tab, Motown, not selected, 1 control, position 3, set size 3",
+      "end of tablist, orientated horizontally",
+      "tabpanel, Funk",
+      "Funk is the ipsum dolor sit amet, consectetur adipiscing elit. Proin at finibus velit. Curabitur consequat, dolor venenatis ullamcorper commodo, quam mi iaculis sem, non varius massa risus et enim. Interdum et malesuada fames ac ante ipsum primis in faucibus. Phasellus non mi lorem. Morbi semper sagittis euismod. Vestibulum non ornare orci.",
+      "end of tabpanel, Funk",
+      "end of document",
+    ])
+  },
+}
+
 /**
  * Can have a heading above the tabs for extra context.
  */

package/src/Component/Tabs/Tabs.stories.tsx

@@ -11,6 +11,7 @@ import "./tabs.css"
 import "../DropMenu/drop-menu.css"
 import { TabStyles } from "../../enums"
 import { Page } from "../../../.storybook-react/decorators"
+import { runScreenReaderWalkthrough } from "../../../tools/test-utils/screen-reader"
 
 const defaultChildren = (
   <Fragment>
@@ -114,3 +115,26 @@ export const Default: StoryObj<typeof meta> = {
     })
   },
 }
+
+/**
+ * Steps a virtual screen reader through the tab list and asserts on what it announces.
+ */
+export const ScreenReaderAnnouncements: StoryObj<typeof meta> = {
+  play: async () => {
+    const log = await runScreenReaderWalkthrough()
+    await expect(log).toEqual([
+      "document",
+      "tablist, orientated horizontally",
+      "tab, Tab 1, selected, 1 control, position 1, set size 3",
+      "tab, Tab 2, not selected, 1 control, position 2, set size 3",
+      "tab, Tab 3, not selected, 1 control, position 3, set size 3",
+      "end of tablist, orientated horizontally",
+      "tabpanel, Tab 1",
+      "paragraph",
+      "This is tab 1",
+      "end of paragraph",
+      "end of tabpanel, Tab 1",
+      "end of document",
+    ])
+  },
+}

package/src/Component/Tabs/Tabs.tsx

@@ -8,7 +8,6 @@ import React, {
   createContext,
   use,
   useState,
-  useEffect,
   useMemo,
   useId,
   useRef,
@@ -17,6 +16,7 @@ import React, {
 } from "react"
 import classNames from "classnames"
 import DropMenuProvider from "../DropMenu/Components/DropMenuContext"
+import useIsomorphicLayoutEffect from "../../Utility/Hooks/useIsomorphicLayoutEffect"
 import { TabStyles } from "../../enums"
 
 type TabContextValues = {
@@ -54,7 +54,7 @@ const Tabs = ({ children, active, modifier, id }: TabsProps): JSX.Element => {
     window.history.replaceState({}, "", `${window.location.pathname}?${urlParams.toString()}`)
   }
 
-  useEffect(() => {
+  useIsomorphicLayoutEffect(() => {
     if (typeof window === "undefined") return
     const tabParam = new URLSearchParams(window.location.search).get("tab")
     if (tabParam && tabParam !== activeTab) {

package/src/Component/Tabs/__snapshots__/Tabs.stories.ts.snap

@@ -1,5 +1,23 @@
 // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
+exports[`Screen Reader Announcements 1`] = `
+"
+
+<mx-tabs class="mx-tabs mx-tabs--lined" id="tab-example"><mx-dropmenu closeonclick="true"><button id="unique-3" class="mx-popover__trigger mx-button mx-icon mx-icon--chevron-down mx-icon--end" popovertarget="tab-example" style="anchor-name: --tab-example" hidden="">Funk</button><div class="mx-popover mx-drop-menu" id="tab-example" aria-describedby="unique-0" style="position-anchor: --tab-example" data-placement="bottom-start" popover="" role="tablist"><button type="button" role="tab" aria-controls="unique-1" aria-selected="true">Funk</button><button type="button" role="tab" aria-controls="unique-2" aria-selected="false">Soul</button><button type="button" role="tab" aria-controls="unique-3" aria-selected="false">Motown</button></div></mx-dropmenu><div class="mx-tabs__list" role="tablist"><button type="button" role="tab" aria-controls="unique-4" aria-selected="true" tabindex="0">Funk</button><button type="button" role="tab" aria-controls="unique-5" aria-selected="false" tabindex="-1">Soul</button><button type="button" role="tab" aria-controls="unique-6" aria-selected="false" tabindex="-1">Motown</button></div>
+  <div class="mx-tabs__panel mx-vertical-flow mx-container" id="unique-0" data-tab="Funk" role="tabpanel" tabindex="-1" aria-label="Funk">
+  Funk is the ipsum dolor sit amet, consectetur adipiscing elit. Proin at finibus velit. Curabitur consequat, dolor venenatis ullamcorper commodo, quam mi iaculis sem, non varius massa risus et enim. Interdum et malesuada fames ac ante ipsum primis in faucibus. Phasellus non mi lorem. Morbi semper sagittis euismod. Vestibulum non ornare orci.
+</div>
+<div class="mx-tabs__panel mx-vertical-flow mx-container" id="unique-1" data-tab="Soul" role="tabpanel" tabindex="-1" aria-label="Soul" inert="">
+  Soul music ipsum dolor sit amet, consectetur adipiscing elit. Proin at finibus velit. Curabitur consequat, dolor venenatis ullamcorper commodo, quam mi iaculis sem, non varius massa risus et enim. Interdum et malesuada fames ac ante ipsum primis in faucibus. Phasellus non mi lorem.
+</div>
+<div class="mx-tabs__panel mx-vertical-flow mx-container" id="unique-2" data-tab="Motown" role="tabpanel" tabindex="-1" aria-label="Motown" inert="">
+  Motown lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin at finibus velit. Curabitur consequat, dolor venenatis ullamcorper commodo, quam mi iaculis sem, non varius massa risus et enim. Interdum et malesuada fames ac ante ipsum primis in faucibus. Phasellus non mi lorem. Morbi semper sagittis euismod. Vestibulum non ornare orci.
+</div>
+
+</mx-tabs>
+"
+`;
+
 exports[`Tabs 1`] = `
 "
 

package/src/Component/Tabs/__snapshots__/Tabs.stories.tsx.snap

@@ -1,3 +1,5 @@
 // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
-exports[`Default 1`] = `"<div class="mx-tabs"><div class="mobile-only"><button id="tabs-storybook-target" type="button" class="mx-button mx-icon mx-icon--chevron-down mx-icon--end mx-popover__trigger" popovertarget="tabs-storybook" style="anchor-name: --drop-menu-tabs-storybook;">Tab 1</button><div id="tabs-storybook" class="mx-popover mx-drop-menu" popover="" aria-labelledby="tabs-storybook-target" aria-describedby="tabs-storybook-description" role="tablist" style="position-anchor: --drop-menu-tabs-storybook;"><div id="tabs-storybook-description" class="sr-only">Results will update when you make a selection. Press escape to close.</div><span data-focus-scope-start="true" hidden=""></span><button type="button" data-id="tab-1" aria-checked="true" role="tab" aria-controls="tab-1" aria-selected="true">Tab 1</button><button type="button" data-id="tab-2" aria-checked="false" role="tab" aria-controls="tab-2" aria-selected="false">Tab 2</button><button type="button" data-id="tab-3" aria-checked="false" role="tab" aria-controls="tab-3" aria-selected="false">Tab 3</button><span data-focus-scope-end="true" hidden=""></span></div></div><div class="mx-tabs__list desktop-only" role="tablist"><span data-focus-scope-start="true" hidden=""></span><button id="tab-1-button" aria-controls="tab-1" role="tab" aria-selected="true" tabindex="0" type="button">Tab 1</button><button id="tab-2-button" aria-controls="tab-2" role="tab" aria-selected="false" tabindex="-1" type="button">Tab 2</button><button id="tab-3-button" aria-controls="tab-3" role="tab" aria-selected="false" tabindex="-1" type="button">Tab 3</button><span data-focus-scope-end="true" hidden=""></span></div><div id="tab-1" class="mx-tabs__panel mx-vertical-flow mx-section--l" aria-labelledby="tab-1-button" role="tabpanel" tabindex="0"><p>This is tab 1</p></div><div id="tab-2" class="mx-tabs__panel mx-vertical-flow mx-section--l" aria-labelledby="tab-2-button" role="tabpanel" tabindex="0" inert=""><p>This is tab 2</p></div><div id="tab-3" class="mx-tabs__panel mx-vertical-flow mx-section--l" inert="" aria-labelledby="tab-3-button" role="tabpanel" tabindex="0"><p>This is tab 3</p></div></div>"`;
+exports[`Default 1`] = `"<div class="mx-tabs"><div class="mobile-only"><button id="tabs-storybook-target" type="button" class="mx-button mx-icon mx-icon--chevron-down mx-icon--end mx-popover__trigger" popovertarget="tabs-storybook" style="anchor-name: --drop-menu-tabs-storybook;">Tab 1</button><div id="tabs-storybook" class="mx-popover mx-drop-menu" popover="" aria-labelledby="tabs-storybook-target" aria-describedby="tabs-storybook-description" role="tablist" style="position-anchor: --drop-menu-tabs-storybook;"><div id="tabs-storybook-description" class="sr-only" aria-hidden="true">Results will update when you make a selection. Press escape to close.</div><span data-focus-scope-start="true" hidden=""></span><button type="button" data-id="tab-1" aria-checked="true" role="tab" aria-controls="tab-1" aria-selected="true">Tab 1</button><button type="button" data-id="tab-2" aria-checked="false" role="tab" aria-controls="tab-2" aria-selected="false">Tab 2</button><button type="button" data-id="tab-3" aria-checked="false" role="tab" aria-controls="tab-3" aria-selected="false">Tab 3</button><span data-focus-scope-end="true" hidden=""></span></div></div><div class="mx-tabs__list desktop-only" role="tablist"><span data-focus-scope-start="true" hidden=""></span><button id="tab-1-button" aria-controls="tab-1" role="tab" aria-selected="true" tabindex="0" type="button">Tab 1</button><button id="tab-2-button" aria-controls="tab-2" role="tab" aria-selected="false" tabindex="-1" type="button">Tab 2</button><button id="tab-3-button" aria-controls="tab-3" role="tab" aria-selected="false" tabindex="-1" type="button">Tab 3</button><span data-focus-scope-end="true" hidden=""></span></div><div id="tab-1" class="mx-tabs__panel mx-vertical-flow mx-section--l" aria-labelledby="tab-1-button" role="tabpanel" tabindex="0"><p>This is tab 1</p></div><div id="tab-2" class="mx-tabs__panel mx-vertical-flow mx-section--l" aria-labelledby="tab-2-button" role="tabpanel" tabindex="0" inert=""><p>This is tab 2</p></div><div id="tab-3" class="mx-tabs__panel mx-vertical-flow mx-section--l" inert="" aria-labelledby="tab-3-button" role="tabpanel" tabindex="0"><p>This is tab 3</p></div></div>"`;
+
+exports[`Screen Reader Announcements 1`] = `"<div class="mx-tabs"><div class="mobile-only"><button id="tabs-storybook-target" type="button" class="mx-button mx-icon mx-icon--chevron-down mx-icon--end mx-popover__trigger" popovertarget="tabs-storybook" style="anchor-name: --drop-menu-tabs-storybook;">Tab 1</button><div id="tabs-storybook" class="mx-popover mx-drop-menu" popover="" aria-labelledby="tabs-storybook-target" aria-describedby="tabs-storybook-description" role="tablist" style="position-anchor: --drop-menu-tabs-storybook;"><div id="tabs-storybook-description" class="sr-only" aria-hidden="true">Results will update when you make a selection. Press escape to close.</div><span data-focus-scope-start="true" hidden=""></span><button type="button" data-id="tab-1" aria-checked="true" role="tab" aria-controls="tab-1" aria-selected="true">Tab 1</button><button type="button" data-id="tab-2" aria-checked="false" role="tab" aria-controls="tab-2" aria-selected="false">Tab 2</button><button type="button" data-id="tab-3" aria-checked="false" role="tab" aria-controls="tab-3" aria-selected="false">Tab 3</button><span data-focus-scope-end="true" hidden=""></span></div></div><div class="mx-tabs__list desktop-only" role="tablist"><span data-focus-scope-start="true" hidden=""></span><button id="tab-1-button" aria-controls="tab-1" role="tab" aria-selected="true" tabindex="0" type="button">Tab 1</button><button id="tab-2-button" aria-controls="tab-2" role="tab" aria-selected="false" tabindex="-1" type="button">Tab 2</button><button id="tab-3-button" aria-controls="tab-3" role="tab" aria-selected="false" tabindex="-1" type="button">Tab 3</button><span data-focus-scope-end="true" hidden=""></span></div><div id="tab-1" class="mx-tabs__panel mx-vertical-flow mx-section--l" aria-labelledby="tab-1-button" role="tabpanel" tabindex="0"><p>This is tab 1</p></div><div id="tab-2" class="mx-tabs__panel mx-vertical-flow mx-section--l" inert="" aria-labelledby="tab-2-button" role="tabpanel" tabindex="0"><p>This is tab 2</p></div><div id="tab-3" class="mx-tabs__panel mx-vertical-flow mx-section--l" inert="" aria-labelledby="tab-3-button" role="tabpanel" tabindex="0"><p>This is tab 3</p></div></div>"`;

package/src/Component/Tabs/tabs.css

@@ -50,6 +50,8 @@
       &[aria-selected="true"] {
         background-color: var(--tab-active-background, var(--colour-background-alt));
         color: var(--tab-active-foreground, var(--colour-foreground));
+        font-weight: var(--font-weight-bold);
+        text-decoration-line: underline;
       }
     }
   }

package/src/Form/Autocomplete/Autocomplete.stories.ts

@@ -4,6 +4,7 @@ import Component from "./autocomplete.twig"
 import "./autocomplete.css"
 import "./Elements/Autocomplete"
 import type { AutocompleteSearchEvent } from "./Elements/Autocomplete"
+import { runScreenReaderWalkthrough } from "../../../tools/test-utils/screen-reader"
 
 const fruits = [
   "Apple",
@@ -59,7 +60,7 @@ type AutocompleteTwigProps = {
 // covers the part that can be shared - each play function still calls
 // `mount()` itself before wiring this up.
 const wireSearchDemo = (canvasElement: HTMLElement, id: string): void => {
-  const root = canvasElement.querySelector<HTMLElement>("mx-autocomplete")
+  const root = canvasElement.querySelector("mx-autocomplete")
   const listbox = root?.querySelector<HTMLUListElement>('[role="listbox"]')
   if (!root || !listbox) return
 
@@ -67,17 +68,23 @@ const wireSearchDemo = (canvasElement: HTMLElement, id: string): void => {
   // pending response so a stale, since-superseded query can't land after a
   // newer one, which would yank the currently-tracked active option out from
   // under the widget mid-interaction.
-  let pending: ReturnType<typeof setTimeout> | null = null
+  let pendingTimeout: ReturnType<typeof setTimeout> | null = null
 
   root.addEventListener("mx-autocomplete-search", event => {
-    if (pending) clearTimeout(pending)
+    if (pendingTimeout) clearTimeout(pendingTimeout)
     const { query } = (event as AutocompleteSearchEvent).detail
     const matches = query
       ? fruits.filter(fruit => fruit.label.toLowerCase().includes(query.toLowerCase()))
       : []
 
+    // `pending` is fully consumer-controlled (see Elements/Autocomplete.ts) -
+    // set it before the simulated request starts, clear it once it settles.
+    // Only the most recent timeout ever fires (earlier ones were cleared
+    // above), so this can't be cleared out of order by a stale response.
+    root.pending = true
+
     // Simulate the latency of a real search API.
-    pending = setTimeout(() => {
+    pendingTimeout = setTimeout(() => {
       listbox.replaceChildren(
         ...matches.map((option, index) => {
           const li = document.createElement("li")
@@ -90,6 +97,7 @@ const wireSearchDemo = (canvasElement: HTMLElement, id: string): void => {
           return li
         }),
       )
+      root.pending = false
     }, 150)
   })
 }
@@ -216,3 +224,72 @@ export const Search: Story = {
     type: "search",
   },
 }
+
+// Demonstrates the built-in pending state: `wireSearchDemo` above toggles the
+// consumer-controlled `pending` property around its simulated search delay,
+// which the Web Component reflects as `aria-busy` on the control - the same
+// attribute React's implementation sets. A single generic CSS rule
+// (`[aria-busy="true"]` in Utility/utilities.css) drives the spinner for
+// both, and for any other component that reflects `aria-busy`.
+export const Pending: Story = {
+  args: {
+    type: "search",
+  },
+  play: async ({ canvasElement, args, mount, canvas, userEvent, step }) => {
+    await mount()
+    wireSearchDemo(canvasElement, args.id)
+    const input = canvas.getByRole("combobox", { name: "Choose a fruit" })
+    const control = canvasElement.querySelector(".mx-autocomplete__control")
+    if (!control) throw new Error("mx-autocomplete__control not found")
+
+    await step("Shows a pending state while the simulated search resolves", async () => {
+      await userEvent.type(input, "lu")
+      await expect(control).toHaveAttribute("aria-busy", "true")
+    })
+
+    await step("Clears pending once the search settles", async () => {
+      await waitFor(
+        () => {
+          expect(control).toHaveAttribute("aria-busy", "false")
+          expect(canvas.getByRole("option", { name: "Blueberry" })).toBeInTheDocument()
+        },
+        { timeout: 2000 },
+      )
+    })
+  },
+}
+
+/**
+ * Steps a virtual screen reader through the page with matching results open, and asserts on what it announces.
+ */
+export const ScreenReaderAnnouncements: Story = {
+  play: async ({ canvasElement, args, mount, canvas, userEvent }) => {
+    await mount()
+    wireSearchDemo(canvasElement, args.id)
+    const input = canvas.getByRole("combobox", { name: "Choose a fruit" })
+
+    // "lu" matches exactly two fruits: Blueberry, then Plum.
+    await userEvent.type(input, "lu")
+    await waitFor(() => expect(input).toHaveAttribute("aria-expanded", "true"), { timeout: 2000 })
+
+    const log = await runScreenReaderWalkthrough()
+    await expect(log).toEqual([
+      "document",
+      "not busy",
+      "combobox, Choose a fruit, lu, has popup listbox, expanded, autocomplete in list, 1 control",
+      "end, not busy",
+      "listbox, orientated vertically",
+      "option, Blueberry, not selected, position 1, set size 2",
+      "option, Plum, not selected, position 2, set size 2",
+      "end of listbox, orientated vertically",
+      "status",
+      "2 results available",
+      "end of status",
+      "end of document",
+    ])
+
+    await userEvent.clear(input)
+    await expect(input).toHaveAttribute("aria-expanded", "false")
+    await userEvent.click(canvasElement)
+  },
+}

package/src/Form/Autocomplete/Autocomplete.stories.tsx

@@ -1,10 +1,11 @@
 import { useState } from "react"
 import { Meta, StoryObj } from "@storybook/react-vite"
-import { expect } from "storybook/test"
+import { expect, waitFor } from "storybook/test"
 import Component, { AutocompleteOption } from "./Autocomplete"
 import "./autocomplete.css"
 import { Page } from "../../../.storybook-react/decorators"
 import { FormStatus } from "../../enums"
+import { runScreenReaderWalkthrough } from "../../../tools/test-utils/screen-reader"
 
 const fruits = [
   "Apple",
@@ -147,3 +148,86 @@ export const Search: StoryObj<typeof meta> = {
     type: "search",
   },
 }
+
+// Demonstrates the built-in pending state: `onSearch` returns a promise
+// (standing in for a real debounced REST/Elasticsearch call), so the
+// component sets `aria-busy` on the control until it resolves. A generic CSS
+// rule (`[aria-busy="true"]` in Utility/utilities.css) shows the spinner -
+// no component-specific markup or class needed.
+export const Pending: StoryObj<typeof meta> = {
+  render: args => {
+    const [options, setOptions] = useState<AutocompleteOption[]>([])
+
+    const handleSearch = (query: string): Promise<void> =>
+      new Promise(resolve => {
+        setTimeout(() => {
+          setOptions(
+            query
+              ? fruits.filter(fruit => fruit.label.toLowerCase().includes(query.toLowerCase()))
+              : [],
+          )
+          resolve()
+        }, 800)
+      })
+
+    return (
+      <Component {...args} options={options} onSearch={handleSearch}>
+        {null}
+      </Component>
+    )
+  },
+  play: async ({ canvas, userEvent, step }) => {
+    const input = canvas.getByRole("combobox", { name: "Choose a fruit" })
+    const control = input.closest(".mx-autocomplete__control")
+
+    await step("Shows a pending spinner while the pending resolves", async () => {
+      await userEvent.type(input, "lu")
+      await expect(control).toHaveAttribute("aria-busy", "true")
+    })
+
+    await step("Clears pending once the search settles", async () => {
+      await waitFor(
+        () => {
+          expect(control).toHaveAttribute("aria-busy", "false")
+          expect(canvas.getByRole("option", { name: "Blueberry" })).toBeInTheDocument()
+        },
+        { timeout: 2000 },
+      )
+    })
+  },
+}
+
+/**
+ * Steps a virtual screen reader through the page with matching results open, and asserts on what it announces.
+ *
+ * Kept as the last story in this file - see the note on ordering in
+ * `docs/Testing.md`'s Automated Screen Reader Testing section.
+ */
+export const ScreenReaderAnnouncements: StoryObj<typeof meta> = {
+  play: async ({ canvas, userEvent }) => {
+    const input = canvas.getByRole("combobox", { name: "Choose a fruit" })
+
+    // "lu" matches exactly two fruits: Blueberry, then Plum.
+    await userEvent.type(input, "lu")
+    await expect(input).toHaveAttribute("aria-expanded", "true")
+
+    const log = await runScreenReaderWalkthrough()
+    await expect(log).toEqual([
+      "document",
+      "not busy",
+      "combobox, Choose a fruit, lu, has popup listbox, expanded, autocomplete in list, 1 control, not invalid",
+      "end, not busy",
+      "listbox, orientated vertically",
+      "option, Blueberry, not selected, position 1, set size 2",
+      "option, Plum, not selected, position 2, set size 2",
+      "end of listbox, orientated vertically",
+      "status",
+      "2 results available",
+      "end of status",
+      "end of document",
+    ])
+
+    await userEvent.clear(input)
+    await expect(input).toHaveAttribute("aria-expanded", "false")
+  },
+}

package/src/Form/Autocomplete/Autocomplete.tsx

@@ -4,12 +4,13 @@ import {
   ChangeEventHandler,
   KeyboardEventHandler,
   MouseEventHandler,
-  useEffect,
   useRef,
+  useState,
   ReactNode,
 } from "react"
 import classNames from "classnames"
 import { useComboBoxState, Item } from "react-stately"
+import useIsomorphicLayoutEffect from "../../Utility/Hooks/useIsomorphicLayoutEffect"
 import { FormStatus } from "../../enums"
 
 export type AutocompleteOption = {
@@ -33,8 +34,8 @@ export type AutocompleteProps = Omit<ComponentPropsWithoutRef<"input">, "value"
   className?: string
   noResultsLabel?: string
   hideOnBlur?: boolean
-  /** Called on every keystroke with the trimmed input value — do the actual search here (debounce it yourself) and feed the results back in via `options`. */
-  onSearch?: (query: string) => void
+  /** Called on every keystroke with the trimmed input value — do the actual search here (debounce it yourself) and feed the results back in via `options`. Return a promise to drive the built-in pending state (`aria-busy` on the control, which also shows a spinner) while it resolves. */
+  onSearch?: (query: string) => void | Promise<void>
   onSelect?: (option: AutocompleteOption) => void
   onSubmit?: MouseEventHandler<HTMLButtonElement>
   children?: ReactNode
@@ -65,6 +66,11 @@ const Autocomplete = ({
 }: AutocompleteProps): JSX.Element => {
   const inputRef = useRef<HTMLInputElement>(null)
   const listboxRef = useRef<HTMLUListElement>(null)
+  // Tracks which `onSearch` call is the most recent, so an out-of-order
+  // (slower) earlier response can't clear pending after a newer search has
+  // already started.
+  const searchTokenRef = useRef<number>(0)
+  const [pending, setPending] = useState<boolean>(false)
 
   // `useComboBoxState` gives us the collection (for Home/End/next/prev key
   // lookups), focused-key tracking, and input-value tracking, replacing
@@ -106,7 +112,7 @@ const Autocomplete = ({
   const listboxId = `${id}-listbox`
   const activeId = activeIndex >= 0 ? `${id}-option-${activeIndex}` : undefined
 
-  useEffect(() => {
+  useIsomorphicLayoutEffect(() => {
     listboxRef.current
       ?.querySelector('[aria-selected="true"]')
       ?.scrollIntoView({ block: "nearest" })
@@ -126,7 +132,14 @@ const Autocomplete = ({
     state.selectionManager.setFocusedKey(null)
     if (currentTarget.value.trim().length > 0) state.open()
     else closeMenu()
-    onSearch?.(currentTarget.value.trim())
+    const result = onSearch?.(currentTarget.value.trim())
+    if (result) {
+      const token = ++searchTokenRef.current
+      setPending(true)
+      result.finally(() => {
+        if (searchTokenRef.current === token) setPending(false)
+      })
+    }
   }
 
   const handleFocus = (): void => {
@@ -200,7 +213,7 @@ const Autocomplete = ({
 
   return (
     <div className={classNames("mx-autocomplete", className)}>
-      <div className="mx-autocomplete__control mx-form--inline-button">
+      <div className="mx-autocomplete__control mx-form--inline-button" aria-busy={pending}>
         <input
           {...props}
           ref={inputRef}

package/src/Form/Autocomplete/Elements/Autocomplete.ts

@@ -8,6 +8,13 @@
  * Elasticsearch call). A MutationObserver watches the listbox for those DOM
  * changes and updates aria-expanded/aria-activedescendant/the status message
  * to match whatever options currently exist.
+ *
+ * The `pending` property is fully consumer-controlled — there's no promise to
+ * await here, only an event — so set `el.pending = true` before your search
+ * call and `= false` once it settles. It reflects `aria-busy` on the control,
+ * the same contract the React implementation exposes: one attribute drives
+ * both the assistive-tech signal and the spinner (see the generic
+ * `[aria-busy="true"]` utility in Utility/utilities.css).
  */
 
 export type AutocompleteSearchEvent = CustomEvent<{ query: string }>
@@ -191,8 +198,16 @@ export default class Autocomplete extends HTMLElement {
     return this.dataset.noResultsLabel || "No results found"
   }
 
+  get control(): HTMLDivElement {
+    const div = this.querySelector<HTMLDivElement>("[data-control]")
+    if (!div) {
+      throw new Error(`${this.localName} must contain a [data-control] element.`)
+    }
+    return div
+  }
+
   get input(): HTMLInputElement {
-    const input = this.querySelector<HTMLInputElement>('input[role="combobox"]')
+    const input = this.control.querySelector<HTMLInputElement>('input[role="combobox"]')
     if (!input) {
       throw new Error(`${this.localName} must contain an <input role="combobox">.`)
     }
@@ -222,6 +237,14 @@ export default class Autocomplete extends HTMLElement {
   get visibleOptions(): HTMLLIElement[] {
     return this.options.filter(option => !option.hidden)
   }
+
+  get pending(): boolean {
+    return this.control.getAttribute("aria-busy") === "true"
+  }
+
+  set pending(value: boolean) {
+    this.control.setAttribute("aria-busy", String(value))
+  }
 }
 
 if (!customElements.get("mx-autocomplete")) {

package/src/Form/Autocomplete/__snapshots__/Autocomplete.stories.ts.snap

@@ -3,7 +3,7 @@
 exports[`Autocomplete 1`] = `
 "
 <mx-autocomplete class="mx-autocomplete">
-  <div class="mx-autocomplete__control mx-form--inline-button">
+  <div class="mx-autocomplete__control mx-form--inline-button" data-control="" aria-busy="false">
     <input class="mx-input__text" id="autocomplete-fruit" name="unique-0" type="text" role="combobox" aria-expanded="false" aria-controls="unique-0" aria-autocomplete="list" aria-activedescendant="" aria-describedby="unique-0" aria-label="Choose a fruit" autocomplete="off" placeholder="Start typing a fruit…">
       </div>
   <div class="mx-autocomplete__suggestions">
@@ -18,7 +18,7 @@ exports[`Autocomplete 1`] = `
 exports[`Invalid 1`] = `
 "
 <mx-autocomplete class="mx-autocomplete">
-  <div class="mx-autocomplete__control mx-form--inline-button">
+  <div class="mx-autocomplete__control mx-form--inline-button" data-control="">
     <input class="mx-input__text" id="autocomplete-fruit" name="unique-0" type="text" role="combobox" aria-expanded="false" aria-controls="unique-0" aria-autocomplete="list" aria-activedescendant="" aria-describedby="unique-0" aria-label="Choose a fruit" autocomplete="off" placeholder="Start typing a fruit…" aria-invalid="true">
       </div>
   <div class="mx-autocomplete__suggestions">
@@ -31,10 +31,29 @@ exports[`Invalid 1`] = `
 "
 `;
 
+exports[`Pending 1`] = `
+"
+<mx-autocomplete class="mx-autocomplete">
+  <div class="mx-autocomplete__control mx-form--inline-button" data-control="" aria-busy="false">
+    <input class="mx-input__text" id="autocomplete-fruit" name="unique-0" type="search" role="combobox" aria-expanded="true" aria-controls="unique-0" aria-autocomplete="list" aria-activedescendant="" aria-describedby="unique-0" aria-label="Choose a fruit" autocomplete="off" placeholder="Start typing a fruit…">
+          <button class="mx-button mx-button--icon-only" type="button">
+        <span class="mx-icon mx-icon--search" aria-hidden="true"></span>
+        <span class="sr-only">Search</span>
+      </button>
+      </div>
+  <div class="mx-autocomplete__suggestions">
+    
+    <ul class="mx-autocomplete__listbox" id="unique-0" role="listbox"><li class="mx-autocomplete__option" id="autocomplete-fruit-option-0" role="option" aria-selected="false" data-value="blueberry">Blueberry</li><li class="mx-autocomplete__option" id="autocomplete-fruit-option-1" role="option" aria-selected="false" data-value="plum">Plum</li></ul>
+    <output class="sr-only" aria-live="polite" data-autocomplete-status="">2 results available</output>
+  </div>
+</mx-autocomplete>
+"
+`;
+
 exports[`Required 1`] = `
 "
 <mx-autocomplete class="mx-autocomplete">
-  <div class="mx-autocomplete__control mx-form--inline-button">
+  <div class="mx-autocomplete__control mx-form--inline-button" data-control="">
     <input class="mx-input__text" id="autocomplete-fruit" name="unique-0" type="text" role="combobox" aria-expanded="false" aria-controls="unique-0" aria-autocomplete="list" aria-activedescendant="" aria-describedby="unique-0" aria-label="Choose a fruit" autocomplete="off" placeholder="Start typing a fruit…" required="">
       </div>
   <div class="mx-autocomplete__suggestions">
@@ -47,10 +66,25 @@ exports[`Required 1`] = `
 "
 `;
 
+exports[`Screen Reader Announcements 1`] = `
+"
+<mx-autocomplete class="mx-autocomplete">
+  <div class="mx-autocomplete__control mx-form--inline-button" data-control="" aria-busy="true">
+    <input class="mx-input__text" id="autocomplete-fruit" name="unique-0" type="text" role="combobox" aria-expanded="false" aria-controls="unique-0" aria-autocomplete="list" aria-activedescendant="" aria-describedby="unique-0" aria-label="Choose a fruit" autocomplete="off" placeholder="Start typing a fruit…">
+      </div>
+  <div class="mx-autocomplete__suggestions">
+    
+    <ul class="mx-autocomplete__listbox" id="unique-0" role="listbox" hidden=""><li class="mx-autocomplete__option" id="autocomplete-fruit-option-0" role="option" aria-selected="false" data-value="blueberry">Blueberry</li><li class="mx-autocomplete__option" id="autocomplete-fruit-option-1" role="option" aria-selected="false" data-value="plum">Plum</li></ul>
+    <output class="sr-only" aria-live="polite" data-autocomplete-status=""></output>
+  </div>
+</mx-autocomplete>
+"
+`;
+
 exports[`Search 1`] = `
 "
 <mx-autocomplete class="mx-autocomplete">
-  <div class="mx-autocomplete__control mx-form--inline-button">
+  <div class="mx-autocomplete__control mx-form--inline-button" data-control="">
     <input class="mx-input__text" id="autocomplete-fruit" name="unique-0" type="search" role="combobox" aria-expanded="false" aria-controls="unique-0" aria-autocomplete="list" aria-activedescendant="" aria-describedby="unique-0" aria-label="Choose a fruit" autocomplete="off" placeholder="Start typing a fruit…">
           <button class="mx-button mx-button--icon-only" type="button">
         <span class="mx-icon mx-icon--search" aria-hidden="true"></span>

package/src/Form/Autocomplete/__snapshots__/Autocomplete.stories.tsx.snap

@@ -1,9 +1,13 @@
 // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
-exports[`Autocomplete 1`] = `"<div class="mx-autocomplete"><div class="mx-autocomplete__control mx-form--inline-button"><input placeholder="Start typing a fruit…" id="autocomplete-fruit" role="combobox" class="mx-input__text" autocomplete="off" aria-expanded="false" aria-controls="autocomplete-fruit-listbox" aria-autocomplete="list" aria-label="Choose a fruit" aria-describedby="help-autocomplete-fruit" aria-invalid="false" type="text" value="" name="fruit"></div><div class="mx-autocomplete__suggestions"><ul id="autocomplete-fruit-listbox" role="listbox" class="mx-autocomplete__listbox" hidden=""></ul><output class="sr-only" aria-live="polite"></output></div></div>"`;
+exports[`Autocomplete 1`] = `"<div class="mx-autocomplete"><div class="mx-autocomplete__control mx-form--inline-button" aria-busy="false"><input placeholder="Start typing a fruit…" id="autocomplete-fruit" role="combobox" class="mx-input__text" autocomplete="off" aria-expanded="false" aria-controls="autocomplete-fruit-listbox" aria-autocomplete="list" aria-label="Choose a fruit" aria-describedby="help-autocomplete-fruit" aria-invalid="false" type="text" value="" name="fruit"></div><div class="mx-autocomplete__suggestions"><ul id="autocomplete-fruit-listbox" role="listbox" class="mx-autocomplete__listbox" hidden=""></ul><output class="sr-only" aria-live="polite"></output></div></div>"`;
 
-exports[`Invalid 1`] = `"<div class="mx-autocomplete"><div class="mx-autocomplete__control mx-form--inline-button"><input placeholder="Start typing a fruit…" id="autocomplete-fruit" role="combobox" class="mx-input__text" autocomplete="off" aria-expanded="false" aria-controls="autocomplete-fruit-listbox" aria-autocomplete="list" aria-label="Choose a fruit" aria-describedby="help-autocomplete-fruit" aria-invalid="true" type="text" value="" name="fruit"></div><div class="mx-autocomplete__suggestions"><ul id="autocomplete-fruit-listbox" role="listbox" class="mx-autocomplete__listbox" hidden=""></ul><output class="sr-only" aria-live="polite"></output></div></div>"`;
+exports[`Invalid 1`] = `"<div class="mx-autocomplete"><div class="mx-autocomplete__control mx-form--inline-button" aria-busy="false"><input placeholder="Start typing a fruit…" id="autocomplete-fruit" role="combobox" class="mx-input__text" autocomplete="off" aria-expanded="false" aria-controls="autocomplete-fruit-listbox" aria-autocomplete="list" aria-label="Choose a fruit" aria-describedby="help-autocomplete-fruit" aria-invalid="true" type="text" value="" name="fruit"></div><div class="mx-autocomplete__suggestions"><ul id="autocomplete-fruit-listbox" role="listbox" class="mx-autocomplete__listbox" hidden=""></ul><output class="sr-only" aria-live="polite"></output></div></div>"`;
 
-exports[`Required 1`] = `"<div class="mx-autocomplete"><div class="mx-autocomplete__control mx-form--inline-button"><input placeholder="Start typing a fruit…" required="" id="autocomplete-fruit" role="combobox" class="mx-input__text" autocomplete="off" aria-expanded="false" aria-controls="autocomplete-fruit-listbox" aria-autocomplete="list" aria-label="Choose a fruit" aria-describedby="help-autocomplete-fruit" aria-invalid="false" type="text" value="" name="fruit"></div><div class="mx-autocomplete__suggestions"><ul id="autocomplete-fruit-listbox" role="listbox" class="mx-autocomplete__listbox" hidden=""></ul><output class="sr-only" aria-live="polite"></output></div></div>"`;
+exports[`Pending 1`] = `"<div class="mx-autocomplete"><div class="mx-autocomplete__control mx-form--inline-button" aria-busy="false"><input placeholder="Start typing a fruit…" id="autocomplete-fruit" role="combobox" class="mx-input__text" autocomplete="off" aria-expanded="true" aria-controls="autocomplete-fruit-listbox" aria-autocomplete="list" aria-label="Choose a fruit" aria-describedby="help-autocomplete-fruit" aria-invalid="false" type="text" value="lu" name="fruit"></div><div class="mx-autocomplete__suggestions"><ul id="autocomplete-fruit-listbox" role="listbox" class="mx-autocomplete__listbox"><li id="autocomplete-fruit-option-0" role="option" aria-selected="false" class="mx-autocomplete__option">Blueberry</li><li id="autocomplete-fruit-option-1" role="option" aria-selected="false" class="mx-autocomplete__option">Plum</li></ul><output class="sr-only" aria-live="polite">2 results available</output></div></div>"`;
 
-exports[`Search 1`] = `"<div class="mx-autocomplete"><div class="mx-autocomplete__control mx-form--inline-button"><input placeholder="Start typing a fruit…" id="autocomplete-fruit" role="combobox" class="mx-input__text" autocomplete="off" aria-expanded="false" aria-controls="autocomplete-fruit-listbox" aria-autocomplete="list" aria-label="Choose a fruit" aria-describedby="help-autocomplete-fruit" aria-invalid="false" type="search" value="" name="fruit"><button class="mx-button mx-button--icon-only" type="button"><span class="mx-icon mx-icon--search" aria-hidden="true"></span><span class="sr-only">Search</span></button></div><div class="mx-autocomplete__suggestions"><ul id="autocomplete-fruit-listbox" role="listbox" class="mx-autocomplete__listbox" hidden=""></ul><output class="sr-only" aria-live="polite"></output></div></div>"`;
+exports[`Required 1`] = `"<div class="mx-autocomplete"><div class="mx-autocomplete__control mx-form--inline-button" aria-busy="false"><input placeholder="Start typing a fruit…" required="" id="autocomplete-fruit" role="combobox" class="mx-input__text" autocomplete="off" aria-expanded="false" aria-controls="autocomplete-fruit-listbox" aria-autocomplete="list" aria-label="Choose a fruit" aria-describedby="help-autocomplete-fruit" aria-invalid="false" type="text" value="" name="fruit"></div><div class="mx-autocomplete__suggestions"><ul id="autocomplete-fruit-listbox" role="listbox" class="mx-autocomplete__listbox" hidden=""></ul><output class="sr-only" aria-live="polite"></output></div></div>"`;
+
+exports[`Screen Reader Announcements 1`] = `"<div class="mx-autocomplete"><div class="mx-autocomplete__control mx-form--inline-button" aria-busy="false"><input placeholder="Start typing a fruit…" id="autocomplete-fruit" role="combobox" class="mx-input__text" autocomplete="off" aria-expanded="false" aria-controls="autocomplete-fruit-listbox" aria-autocomplete="list" aria-label="Choose a fruit" aria-describedby="help-autocomplete-fruit" aria-invalid="false" type="text" value="" name="fruit"></div><div class="mx-autocomplete__suggestions"><ul id="autocomplete-fruit-listbox" role="listbox" class="mx-autocomplete__listbox" hidden=""></ul><output class="sr-only" aria-live="polite"></output></div></div>"`;
+
+exports[`Search 1`] = `"<div class="mx-autocomplete"><div class="mx-autocomplete__control mx-form--inline-button" aria-busy="false"><input placeholder="Start typing a fruit…" id="autocomplete-fruit" role="combobox" class="mx-input__text" autocomplete="off" aria-expanded="false" aria-controls="autocomplete-fruit-listbox" aria-autocomplete="list" aria-label="Choose a fruit" aria-describedby="help-autocomplete-fruit" aria-invalid="false" type="search" value="" name="fruit"><button class="mx-button mx-button--icon-only" type="button"><span class="mx-icon mx-icon--search" aria-hidden="true"></span><span class="sr-only">Search</span></button></div><div class="mx-autocomplete__suggestions"><ul id="autocomplete-fruit-listbox" role="listbox" class="mx-autocomplete__listbox" hidden=""></ul><output class="sr-only" aria-live="polite"></output></div></div>"`;