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

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

@@ -21,8 +21,7 @@ exports[`Bottom 1`] = `
         
 <a href="#" class="mx-link--more">
   
-  <span>Learn more</span>
-    
+  Learn more  
 </a>
 
     </div>
@@ -52,8 +51,7 @@ exports[`Bottom End 1`] = `
         
 <a href="#" class="mx-link--more">
   
-  <span>Learn more</span>
-    
+  Learn more  
 </a>
 
     </div>
@@ -83,8 +81,7 @@ exports[`Bottom Start 1`] = `
         
 <a href="#" class="mx-link--more">
   
-  <span>Learn more</span>
-    
+  Learn more  
 </a>
 
     </div>
@@ -114,8 +111,7 @@ exports[`Left 1`] = `
         
 <a href="#" class="mx-link--more">
   
-  <span>Learn more</span>
-    
+  Learn more  
 </a>
 
     </div>
@@ -145,8 +141,7 @@ exports[`Left End 1`] = `
         
 <a href="#" class="mx-link--more">
   
-  <span>Learn more</span>
-    
+  Learn more  
 </a>
 
     </div>
@@ -176,8 +171,7 @@ exports[`Left Start 1`] = `
         
 <a href="#" class="mx-link--more">
   
-  <span>Learn more</span>
-    
+  Learn more  
 </a>
 
     </div>
@@ -207,8 +201,7 @@ exports[`Popover 1`] = `
         
 <a href="#" class="mx-link--more">
   
-  <span>Learn more</span>
-    
+  Learn more  
 </a>
 
     </div>
@@ -238,8 +231,7 @@ exports[`Right 1`] = `
         
 <a href="#" class="mx-link--more">
   
-  <span>Learn more</span>
-    
+  Learn more  
 </a>
 
     </div>
@@ -269,8 +261,7 @@ exports[`Right End 1`] = `
         
 <a href="#" class="mx-link--more">
   
-  <span>Learn more</span>
-    
+  Learn more  
 </a>
 
     </div>
@@ -300,8 +291,7 @@ exports[`Right Start 1`] = `
         
 <a href="#" class="mx-link--more">
   
-  <span>Learn more</span>
-    
+  Learn more  
 </a>
 
     </div>
@@ -331,8 +321,7 @@ exports[`Top 1`] = `
         
 <a href="#" class="mx-link--more">
   
-  <span>Learn more</span>
-    
+  Learn more  
 </a>
 
     </div>
@@ -362,8 +351,7 @@ exports[`Top End 1`] = `
         
 <a href="#" class="mx-link--more">
   
-  <span>Learn more</span>
-    
+  Learn more  
 </a>
 
     </div>
@@ -393,8 +381,7 @@ exports[`Top Start 1`] = `
         
 <a href="#" class="mx-link--more">
   
-  <span>Learn more</span>
-    
+  Learn more  
 </a>
 
     </div>

package/src/Component/Popover/popover.css

@@ -3,6 +3,7 @@
  *
  * **Experimental** Using new CSS Anchoring and Popover API's, requires JS polyfill.
  */
+@import "../../Utility/_mixins.css";
 
 @layer design-system.defaults {
   mx-popover {
@@ -20,13 +21,14 @@
 
   /* @public --popover-padding --popover-background --popover-foreground --popover-radius --popover-width */
   :where(.mx-popover) {
+    @add-mixin transition;
+
     display: none;
-    opacity: 0;
     position: absolute;
     padding: var(--popover-padding, var(--spacing-xs));
     background-color: var(--popover-background, var(--colour-background));
     color: var(--popover-foreground, var(--colour-foreground));
-    border: var(--popover-line-width, 0) solid var(--popover-line-colour, var(--colour-border));
+    border: var(--popover-line-width, 1px) solid var(--popover-line-colour, transparent);
     border-radius: var(--popover-radius, var(--border-radius));
     box-shadow: var(--popover-shadow, var(--box-shadow));
     max-inline-size: var(--popover-width, 30ch);

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

@@ -8,8 +8,7 @@ exports[`Side Navigation 1`] = `
     
 <a href="#">
   
-  <span>About</span>
-    
+  About  
 </a>
 
   </div>

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

@@ -5,28 +5,25 @@ exports[`Social Links 1`] = `
                     
 <h2 class="mx-heading--m">Follow us</h2>
 
-  
-<a href="#">
+        
+<a href="#" aria-label="Facebook">
   
 <span class="mx-icon mx-icon--facebook mx-icon--size-md"></span>
 
-  <span class="sr-only">Facebook</span>
     
 </a>
-
-<a href="#">
+      
+<a href="#" aria-label="Instagram">
   
 <span class="mx-icon mx-icon--instagram mx-icon--size-md"></span>
 
-  <span class="sr-only">Instagram</span>
     
 </a>
-
-<a href="#">
+      
+<a href="#" aria-label="LinkedIn">
   
 <span class="mx-icon mx-icon--linkedin mx-icon--size-md"></span>
 
-  <span class="sr-only">LinkedIn</span>
     
 </a>
 

package/src/Component/Steps/Steps.stories.ts

@@ -31,7 +31,7 @@ const meta: Meta<StepsType> = {
   },
   argTypes: {
     modifiers: {
-      description: "Change the colour of the line and marker.",
+      description: "Change the colour of the line and marker (only one applies).",
       options: Object.values(StepsModifier),
       control: "check",
       type: "string",

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

@@ -1,6 +1,7 @@
 /**
  * Tabs
  */
+@import "../../Utility/_mixins.css";
 
 @layer design-system.defaults {
   mx-tabs {
@@ -46,21 +47,21 @@
       background-color: var(--tab-background, var(--background, var(--colour-background)));
       color: var(--tab-foreground, var(--foreground, var(--colour-foreground)));
       font-size: var(--tab-font-size, var(--font-size-xs));
+      cursor: pointer;
 
       &[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;
       }
     }
   }
 
   .mx-tabs__panel {
-    inline-size: 100%;
-    opacity: 1;
+    @add-mixin transition;
 
-    @starting-style {
-      opacity: 0;
-    }
+    inline-size: 100%;
 
     &[inert] {
       opacity: 0;

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")
+  },
+}