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

package/src/Component/Tag/README.md

@@ -39,14 +39,15 @@ A small inline label used to categorise content. Renders as plain text metadata,
 
 **tags.twig props** (`Tags` type from `ids-shape`):
 
-| Prop            | Type                                  | Description                                                                                                                                  |
-| --------------- | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
-| `type`          | `TagTypes`                            | Controls which markup is rendered per item. One of `text`, `link`, `checkbox`. Changing the type also changes the required shape of `items`. |
-| `items`         | `string[] \| Link[] \| FormControl[]` | List of tag items. Shape depends on `type` — see below.                                                                                      |
-| `attributes`    | `Attribute`                           | Extra attributes on the outer `<ul class="mx-tags">`                                                                                         |
-| `tagAttributes` | `Attribute`                           | Extra attributes on each `.mx-tag` element                                                                                                   |
-| `dismissible`   | `boolean`                             | When true, plain (`text`) tags render a remove button (`mx-tag--dismissible`). Wire up removal behaviour in the consuming app.               |
-| `removeLabel`   | `string`                              | Accessible label for the remove button. Defaults to `"Remove"`.                                                                              |
+| Prop            | Type                                  | Description                                                                                                                                     |
+| --------------- | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `type`          | `TagTypes`                            | Controls which markup is rendered per item. One of `text`, `link`, `checkbox`. Changing the type also changes the required shape of `items`.    |
+| `items`         | `string[] \| Link[] \| FormControl[]` | List of tag items. Shape depends on `type` — see below.                                                                                         |
+| `attributes`    | `Attribute`                           | Extra attributes on the outer `<ul class="mx-tags">`                                                                                            |
+| `tagAttributes` | `Attribute`                           | Extra attributes on each `.mx-tag` element                                                                                                      |
+| `dismissible`   | `boolean`                             | When true, plain (`text`) tags render a remove button (`mx-tag--dismissible`). Wire up removal behaviour in the consuming app.                  |
+| `removeLabel`   | `string`                              | Accessible label for the remove button. Defaults to `"Remove"`.                                                                                 |
+| `variant`       | `TagVariants`                         | Colour variant: `info`, `success`, `warning`, `error`, `featured`. Applied per-item via `tag-item.twig`. Defaults to the neutral, unstyled tag. |
 
 **Item shapes per `type`:**
 
@@ -78,20 +79,20 @@ Link tags:
 </ul>
 ```
 
-Checkbox tags (the `<input>` is visually hidden off-screen; the `<label>` is the click target):
+Checkbox tags (the `<input>` is visually hidden off-screen; the `<label>` is the click target). The `mx-icon mx-icon--tick` classes on the label render the shared checkmark icon (from `@pnx-mixtape/mxds/src/Atom/Icon/icon.css`) — its space is always reserved, but it's only visible once the input is checked, so checking a tag doesn't change its size:
 
 ```html
 <ul class="mx-tags">
   <li>
     <div class="mx-tag">
       <input type="checkbox" id="music" name="tag" value="music" />
-      <label for="music">Music</label>
+      <label class="mx-icon mx-icon--tick" for="music">Music</label>
     </div>
   </li>
   <li>
     <div class="mx-tag">
       <input type="checkbox" id="news" name="tag" value="news" checked />
-      <label for="news">News</label>
+      <label class="mx-icon mx-icon--tick" for="news">News</label>
     </div>
   </li>
 </ul>
@@ -131,7 +132,7 @@ import { AsTags } from "@pnx-mixtape/mxds/src/enums"
   <li>
     <div className="mx-tag">
       <input type="checkbox" id="music" name="tag" value="music" />
-      <label htmlFor="music">Music</label>
+      <label className="mx-icon mx-icon--tick" htmlFor="music">Music</label>
     </div>
   </li>
 </ul>
@@ -139,13 +140,14 @@ import { AsTags } from "@pnx-mixtape/mxds/src/enums"
 
 **`Tag` props:**
 
-| Prop          | Type         | Default    | Description                                                                                     |
-| ------------- | ------------ | ---------- | ----------------------------------------------------------------------------------------------- |
-| `as`          | `AsTags`     | `div`      | Semantic element for the tag: `div`, `li`, `article`, `aside`, `section`                        |
-| `className`   | `string`     | —          | Extra class on the tag element                                                                  |
-| `children`    | `ReactNode`  | —          | Tag label content                                                                               |
-| `onRemove`    | `() => void` | —          | When set, renders a remove button (`mx-tag--dismissible`). Consumer removes the tag from state. |
-| `removeLabel` | `string`     | `"Remove"` | Accessible label for the remove button                                                          |
+| Prop          | Type          | Default    | Description                                                                                               |
+| ------------- | ------------- | ---------- | --------------------------------------------------------------------------------------------------------- |
+| `as`          | `AsTags`      | `div`      | Semantic element for the tag: `div`, `li`, `article`, `aside`, `section`                                  |
+| `className`   | `string`      | —          | Extra class on the tag element                                                                            |
+| `children`    | `ReactNode`   | —          | Tag label content                                                                                         |
+| `onRemove`    | `() => void`  | —          | When set, renders a remove button (`mx-tag--dismissible`). Consumer removes the tag from state.           |
+| `removeLabel` | `string`      | `"Remove"` | Accessible label for the remove button                                                                    |
+| `variant`     | `TagVariants` | —          | Colour variant: `info`, `success`, `warning`, `error`, `featured`. Defaults to the neutral, unstyled tag. |
 
 > For filter UIs, tag removal can also be handled upstream (e.g. via the checkbox type toggling its checked state, or via the Filters component). Use `onRemove` when you need a self-contained dismissible chip.
 
@@ -155,11 +157,11 @@ import { AsTags } from "@pnx-mixtape/mxds/src/enums"
 
 The `type` prop on the Twig template maps to `TagTypes` values from `@pnx-mixtape/ids-shape`. The same base `mx-tag` class is used for all variants — the variant changes the inner element, not the class.
 
-| `TagTypes` value | Element rendered                                                      | Visual intent                                                                                        |
-| ---------------- | --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
-| `text`           | `<span class="mx-tag">`                                               | Read-only metadata label (e.g. category shown on a Card)                                             |
-| `link`           | `<a class="mx-tag" href>`                                             | Navigational tag — clicking takes the user to a filtered / category view                             |
-| `checkbox`       | `<div class="mx-tag">` wrapping `<input type="checkbox">` + `<label>` | Toggleable filter tag inside a form; checked state is visually indicated via the primary link colour |
+| `TagTypes` value | Element rendered                                                      | Visual intent                                                                                                                                                            |
+| ---------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `text`           | `<span class="mx-tag">`                                               | Read-only metadata label (e.g. category shown on a Card)                                                                                                                 |
+| `link`           | `<a class="mx-tag" href>`                                             | Navigational tag — clicking takes the user to a filtered / category view                                                                                                 |
+| `checkbox`       | `<div class="mx-tag">` wrapping `<input type="checkbox">` + `<label>` | Toggleable filter tag inside a form; checked state fills the tag with the primary link colour (or the variant's own colour) and prefixes the label with a checkmark icon |
 
 ---
 
@@ -168,7 +170,7 @@ The `type` prop on the Twig template maps to `TagTypes` values from `@pnx-mixtap
 - **Text tags** are plain `<span>` elements — they are metadata, not interactive. Do not add click handlers or `role` attributes; if a tag needs to be clickable, use the `link` or `checkbox` variant.
 - **Link tags** use a real `<a href>`. Ensure the destination makes sense out of context — the visible label is the accessible name, so labels like "Music" should lead to an unambiguous page (e.g. `/category/music`).
 - **Checkbox tags** rely on a native `<input type="checkbox">` paired with a `<label for="…">`. The `<input>` is positioned off-screen (not `display: none`) so it remains focusable and announceable. The whole `.mx-tag` gets a focus outline via `:has(input:focus)` — do not remove this selector.
-- The checked state is communicated by colour alone in the default styling. When rendering checkbox tags in a form, ensure surrounding context (a fieldset legend, heading, or `aria-label`) describes what group of filters the tags belong to.
+- The checked state is communicated by colour (a solid fill) **and** a checkmark icon prefixed to the label — not colour alone. When rendering checkbox tags in a form, ensure surrounding context (a fieldset legend, heading, or `aria-label`) describes what group of filters the tags belong to.
 - If you need to render a list of tags for assistive-tech as a single labelled group, add `aria-label` (or `aria-labelledby`) to the `<ul class="mx-tags">`:
 
 ```html
@@ -201,7 +203,31 @@ The `type` prop on the Twig template maps to `TagTypes` values from `@pnx-mixtap
 }
 ```
 
-Hover (on `a.mx-tag`) and checked (`:has(input:checked)`) states both set `--tag-foreground` to `--link-colour` (falls back to `--colour-primary`).
+Hover (on `a.mx-tag`) sets `--tag-foreground` to `--link-colour` (falls back to `--colour-primary`). Checked (`:has(input:checked)`) fills `--tag-background`/`--line-colour` with that same colour and switches `--tag-foreground` to `--colour-foreground-reverse`, plus prefixes the label with a checkmark icon — except on a colour variant (see below), where checked keeps the variant's own colours and hover darkens them instead.
+
+---
+
+## Colour variants — `TagVariants` enum
+
+Apply `mx-tag--{variant}` for `info`, `success`, `warning`, `error`, or `featured`. Each variant fills `--tag-background` and sets the border/outline to match; foreground uses `--colour-foreground-reverse` (`featured` excepted, which stays dark-on-light).
+
+```tsx
+<Tag variant={TagVariants.INFO}>New</Tag>
+```
+
+`tags.twig` itself only prints pre-rendered `items` markup — `variant`, like `dismissible`, is applied per item when building that markup with `tag-item.twig`:
+
+```twig
+{{ include('@mixtape/Component/Tag/tag-item.twig', {
+  type: 'text',
+  item: 'New',
+  variant: 'info',
+}) }}
+```
+
+- A checked variant tag keeps its own colours (the solid fill and "checked" link colour swap only apply to non-variant tags) — it's already a solid fill. The checkmark icon on checked still applies.
+- The focus outline (`:has(input:focus)`) on a variant tag uses the variant's own colour instead of the standard blue.
+- Hovering a variant **link** tag darkens its background/border by 20% (via `color-mix`) rather than switching to the link hover colour; the text colour is unchanged. `featured` only darkens by 10% — it keeps dark text on its light background, so a smaller step protects contrast.
 
 ---
 

package/src/Component/Tag/Tag.stories.tsx

@@ -2,6 +2,7 @@ import { Meta, StoryObj } from "@storybook/react-vite"
 import Component from "./Tag"
 import "./tag.css"
 import { Page } from "../../../.storybook-react/decorators"
+import { TagVariants } from "../../enums"
 
 const meta: Meta<typeof Component> = {
   component: Component,
@@ -9,7 +10,30 @@ const meta: Meta<typeof Component> = {
   args: {
     children: "Tag name",
   },
+  argTypes: {
+    variant: {
+      control: {
+        type: "select",
+        labels: { undefined: "default" },
+      },
+      options: [undefined, ...Object.values(TagVariants)],
+    },
+  },
 }
 
 export default meta
 export const Tag: StoryObj<typeof meta> = {}
+
+const variantsListStyle = { display: "flex", gap: "1rem" }
+
+export const Variants: StoryObj<typeof meta> = {
+  render: args => (
+    <div style={variantsListStyle}>
+      {Object.values(TagVariants).map(variant => (
+        <Component key={variant} {...args} variant={variant}>
+          {variant}
+        </Component>
+      ))}
+    </div>
+  ),
+}

package/src/Component/Tag/Tag.tsx

@@ -1,10 +1,12 @@
 import { JSX, PropsWithChildren } from "react"
 import classNames from "classnames"
-import { AsTags, Icons } from "../../enums"
+import { AsTags, Icons, TagVariants } from "../../enums"
 
 type TagProps = PropsWithChildren & {
   className?: string
   as?: AsTags
+  /** Colour variant. Defaults to the neutral, unstyled tag. */
+  variant?: TagVariants
   /**
    * When provided, renders a remove button. Called when the button is
    * activated — the consumer is responsible for removing the tag from state.
@@ -18,12 +20,20 @@ const Tag = ({
   children,
   className,
   as = AsTags.DIV,
+  variant,
   onRemove,
   removeLabel = "Remove",
 }: TagProps): JSX.Element => {
   const TagEl: JSX.ElementType = `${as}` as unknown as JSX.ElementType
   return (
-    <TagEl className={classNames("mx-tag", { "mx-tag--dismissible": onRemove }, className)}>
+    <TagEl
+      className={classNames(
+        "mx-tag",
+        { "mx-tag--dismissible": onRemove },
+        variant && `mx-tag--${variant}`,
+        className,
+      )}
+    >
       {children}
       {onRemove && (
         <button

package/src/Component/Tag/TagItem.stories.ts

@@ -2,6 +2,7 @@ import { Meta, StoryObj } from "@storybook/html-vite"
 import Component from "./tag-item.twig"
 import "./tag.css"
 import { TagTypes } from "@pnx-mixtape/ids-shape"
+import { TagVariants } from "../../enums"
 
 type TagItemType = {
   type: TagTypes
@@ -11,6 +12,7 @@ type TagItemType = {
     | { label: string; id: string; name: string; value: string; checked?: boolean }
   dismissible?: boolean
   removeLabel?: string
+  variant?: TagVariants
 }
 
 /**
@@ -49,6 +51,17 @@ const meta: Meta<TagItemType> = {
         "When true, plain (text) tags render a remove button. Wire up removal behaviour in the consuming app.",
       control: "boolean",
     },
+    variant: {
+      description: "Colour variant.",
+      control: {
+        type: "select",
+        labels: { undefined: "default" },
+      },
+      options: [undefined, ...Object.values(TagVariants)],
+      table: {
+        type: { summary: "enum" },
+      },
+    },
   },
   render: args => {
     return `<ul class="mx-tags">${Component({ ...args })}</ul>`
@@ -99,3 +112,15 @@ export const Checkbox: Story = {
     },
   },
 }
+
+/**
+ * Colour variants for conveying status or emphasis.
+ */
+export const Variants: Story = {
+  render: () => {
+    const items = Object.values(TagVariants)
+      .map(variant => Component({ type: TagTypes.TEXT, item: variant, variant }))
+      .join("")
+    return `<ul class="mx-tags">${items}</ul>`
+  },
+}

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

@@ -6,13 +6,13 @@ exports[`Checkbox 1`] = `
   <li>
           <div class="mx-tag">
         <input type="checkbox" id="music" name="tag" value="music">
-        <label for="music">Music</label>
+        <label class="mx-icon mx-icon--tick" for="music">Music</label>
       </div>
     </li>
 <li>
           <div class="mx-tag">
         <input type="checkbox" id="news" name="tag" value="news">
-        <label for="news">News</label>
+        <label class="mx-icon mx-icon--tick" for="news">News</label>
       </div>
     </li>
 

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

@@ -1,3 +1,5 @@
 // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
 exports[`Tag 1`] = `"<div class="mx-tag">Tag name</div>"`;
+
+exports[`Variants 1`] = `"<div style="display: flex; gap: 1rem;"><div class="mx-tag mx-tag--info">info</div><div class="mx-tag mx-tag--success">success</div><div class="mx-tag mx-tag--warning">warning</div><div class="mx-tag mx-tag--error">error</div><div class="mx-tag mx-tag--featured">featured</div></div>"`;

package/src/Component/Tag/tag-item.twig

@@ -1,4 +1,4 @@
-{% set tagClasses = ['mx-tag', dismissible ? 'mx-tag--dismissible' : null] %}
+{% set tagClasses = ['mx-tag', dismissible ? 'mx-tag--dismissible' : null, variant ? 'mx-tag--' ~ variant : null] %}
 {% set tagAttributes = (tagAttributes ?? create_attribute()).addClass(tagClasses) %}
 <li>
     {% if type == "link" %}
@@ -10,7 +10,7 @@
                name="{{ item.name }}"
                value="{{ item.value }}"
             {% if item.checked %} checked{% endif %}>
-        <label for="{{ item.id }}">{{ item.label }}</label>
+        <label class="mx-icon mx-icon--tick" for="{{ item.id }}">{{ item.label }}</label>
       </div>
     {% else %}
         <span{{ tagAttributes }}>

package/src/Component/Tag/tag.css

@@ -3,7 +3,7 @@
  */
 
 @layer design-system.components {
-  /* @public --tag-background --tag-foreground --tag-font-size --tags-gap */
+  /* @public --tag-background --tag-foreground --tag-font-size --tags-gap --tag-letter-spacing */
   .mx-tag {
     display: inline-flex;
     inline-size: fit-content;
@@ -16,6 +16,7 @@
     line-height: var(--line-height, 2);
     border-radius: var(--border-radius);
     border: var(--line-width, 1px) solid var(--line-colour, currentcolor);
+    letter-spacing: var(--tag-letter-spacing, 0);
     text-decoration: none;
     overflow: clip;
     overflow-clip-margin: var(--spacing-xxxs);
@@ -36,12 +37,35 @@
       font-size: inherit;
       color: inherit;
       margin: 0;
+      gap: var(--spacing-xxxs);
     }
 
-    &:is(a:hover, :has(input:checked)) {
+    /* the checkmark icon (from the shared mx-icon set) is always reserved so
+       checking the tag doesn't change its size — only its visibility toggles */
+    & label.mx-icon--tick::before {
+      --icon-size: 1em;
+
+      opacity: 0;
+    }
+
+    &:is(a:hover):not(
+        :is(.mx-tag--info, .mx-tag--success, .mx-tag--warning, .mx-tag--error, .mx-tag--featured)
+      ) {
       --tag-foreground: var(--link-colour, var(--colour-primary));
     }
 
+    &:has(input:checked):not(
+        :is(.mx-tag--info, .mx-tag--success, .mx-tag--warning, .mx-tag--error, .mx-tag--featured)
+      ) {
+      --tag-background: var(--link-colour, var(--colour-primary));
+      --tag-foreground: var(--colour-foreground-reverse);
+      --line-colour: var(--tag-background);
+    }
+
+    &:has(input:checked) label.mx-icon--tick::before {
+      opacity: 1;
+    }
+
     &:empty {
       display: none;
     }
@@ -76,6 +100,56 @@
     }
   }
 
+  .mx-tag--info,
+  .mx-tag--success,
+  .mx-tag--warning,
+  .mx-tag--error,
+  .mx-tag--featured {
+    --line-colour: var(--tag-background);
+    --outline-color: var(--tag-background);
+  }
+
+  .mx-tag--info {
+    --tag-accent: var(--colour-info);
+    --tag-background: var(--tag-accent);
+    --tag-foreground: var(--colour-foreground-reverse);
+  }
+
+  .mx-tag--success {
+    --tag-accent: var(--colour-success);
+    --tag-background: var(--tag-accent);
+    --tag-foreground: var(--colour-foreground-reverse);
+  }
+
+  .mx-tag--warning {
+    --tag-accent: var(--colour-warning);
+    --tag-background: var(--tag-accent);
+    --tag-foreground: var(--colour-foreground-reverse);
+  }
+
+  .mx-tag--error {
+    --tag-accent: var(--colour-error);
+    --tag-background: var(--tag-accent);
+    --tag-foreground: var(--colour-foreground-reverse);
+  }
+
+  .mx-tag--featured {
+    --tag-accent: var(--colour-featured, var(--colour-accent));
+    --tag-background: var(--tag-accent);
+    --tag-foreground: var(--colour-featured-foreground, var(--colour-foreground));
+  }
+
+  .mx-tag:is(.mx-tag--info, .mx-tag--success, .mx-tag--warning, .mx-tag--error):is(a:hover) {
+    --tag-background: color-mix(in oklch, var(--tag-accent), black 20%);
+    --line-colour: var(--tag-background);
+  }
+
+  .mx-tag--featured:is(a:hover) {
+    /* featured keeps dark text, so a smaller darken step protects contrast */
+    --tag-background: color-mix(in oklch, var(--tag-accent), black 10%);
+    --line-colour: var(--tag-background);
+  }
+
   .mx-tags {
     padding-inline: 0;
     list-style: none;

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)
   })
 }
@@ -185,9 +193,14 @@ export const Autocomplete: Story = {
       await userEvent.clear(input)
       await expect(input).toHaveValue("")
       await expect(input).toHaveAttribute("aria-expanded", "false")
-      await waitFor(() => expect(canvas.queryByRole("option")).not.toBeInTheDocument(), {
-        timeout: 2000,
-      })
+      // `hidden: true` includes the listbox even while it's closed (`hidden`
+      // attribute set) - otherwise this resolves immediately regardless of
+      // whether the stale options were actually removed, since closed
+      // elements are excluded from accessibility queries by default.
+      await waitFor(
+        () => expect(canvas.queryByRole("option", { hidden: true })).not.toBeInTheDocument(),
+        { timeout: 2000 },
+      )
       // Clear focus.
       await userEvent.click(canvasElement)
     })
@@ -211,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")
+  },
+}