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

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,17 +213,14 @@ 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}
           id={id}
           type={type}
           role="combobox"
-          className={classNames("mx-input__text", {
-            error: status === FormStatus.INVALID,
-            success: status === FormStatus.VALID,
-          })}
+          className="mx-input__text"
           value={state.inputValue}
           autoComplete="off"
           aria-expanded={state.isOpen}

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/README.md

@@ -32,18 +32,18 @@ This is a field-level component only — pair it with `FormItem` and `FormLabel`
 
 **autocomplete.twig props:**
 
-| Prop             | Type                                 | Required | Default              | Description                                                                                          |
-| ---------------- | ------------------------------------ | -------- | -------------------- | ---------------------------------------------------------------------------------------------------- |
-| `id`             | `string`                             | Yes      | —                    | `id` on the `<input>`; also used to derive the listbox/option ids                                    |
-| `name`           | `string`                             | No       | —                    | `name` attribute on the `<input>`                                                                    |
-| `label`          | `string`                             | No       | —                    | `aria-label` on the `<input>` (visually hidden)                                                      |
-| `type`           | `"text" \| "search"`                 | No       | `"text"`             | `"search"` also renders an icon-only submit button                                                   |
-| `options`        | `{ label: string, value: string }[]` | No       | —                    | The **current** suggestions to render as `<li role="option">` — not a full list to filter, see below |
-| `value`          | `string`                             | No       | —                    | Initial `<input>` value                                                                              |
-| `placeholder`    | `string`                             | No       | —                    | `<input>` placeholder                                                                                |
-| `required`       | `boolean`                            | No       | `false`              | Adds `required` to the `<input>`                                                                     |
-| `status`         | `"default" \| "valid" \| "invalid"`  | No       | `"default"`          | Adds `.error`/`.success` and `aria-invalid` to the `<input>`                                         |
-| `noResultsLabel` | `string`                             | No       | `"No results found"` | Message announced when there are zero current options and a query                                    |
+| Prop             | Type                                 | Required | Default              | Description                                                                                                                                     |
+| ---------------- | ------------------------------------ | -------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `id`             | `string`                             | Yes      | —                    | `id` on the `<input>`; also used to derive the listbox/option ids                                                                               |
+| `name`           | `string`                             | No       | —                    | `name` attribute on the `<input>`                                                                                                               |
+| `label`          | `string`                             | No       | —                    | `aria-label` on the `<input>` (visually hidden)                                                                                                 |
+| `type`           | `"text" \| "search"`                 | No       | `"text"`             | `"search"` also renders an icon-only submit button                                                                                              |
+| `options`        | `{ label: string, value: string }[]` | No       | —                    | The **current** suggestions to render as `<li role="option">` — not a full list to filter, see below                                            |
+| `value`          | `string`                             | No       | —                    | Initial `<input>` value                                                                                                                         |
+| `placeholder`    | `string`                             | No       | —                    | `<input>` placeholder                                                                                                                           |
+| `required`       | `boolean`                            | No       | `false`              | Adds `required` to the `<input>`                                                                                                                |
+| `status`         | `"default" \| "valid" \| "invalid"`  | No       | `"default"`          | Sets `aria-invalid` on the `<input>` (red border). Live `:user-*` colours need `mx-validate` on the `<input>` or the `.mx-autocomplete` wrapper |
+| `noResultsLabel` | `string`                             | No       | `"No results found"` | Message announced when there are zero current options and a query                                                                               |
 
 Registers as `<mx-autocomplete>` — import the element to activate its behaviour:
 
@@ -140,19 +140,19 @@ const Example = () => {
 
 **`Autocomplete` props:**
 
-| Prop             | Type                                   | Default              | Description                                                                                                          |
-| ---------------- | -------------------------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------- |
-| `id`             | `string`                               | —                    | `id` on the `<input>`; also used to derive the listbox/option ids                                                    |
-| `label`          | `string`                               | —                    | `aria-label` on the `<input>` (visually hidden)                                                                      |
-| `type`           | `"text" \| "search"`                   | `"text"`             | `"search"` also renders an icon-only submit button (`onSubmit`)                                                      |
-| `options`        | `AutocompleteOption[]`                 | —                    | The **current** results to display — not filtered further, see below                                                 |
-| `onSearch`       | `(query: string) => void`              | —                    | Called on every keystroke with the trimmed input value — debounce it yourself and feed matches back in via `options` |
-| `value`          | `string`                               | `""`                 | Initial `<input>` value (uncontrolled after that)                                                                    |
-| `status`         | `FormStatus`                           | `FormStatus.DEFAULT` | Adds `.error`/`.success` and `aria-invalid`                                                                          |
-| `noResultsLabel` | `string`                               | `"No results found"` | Message announced when `options` is empty and there's a query                                                        |
-| `onSelect`       | `(option: AutocompleteOption) => void` | —                    | Called when an option is chosen by click or <kbd>Enter</kbd>                                                         |
-| `hideOnBlur`     | `boolean`                              | `true`               | Close the listbox on blur                                                                                            |
-| `className`      | `string`                               | —                    | Extra class on the root                                                                                              |
+| Prop             | Type                                   | Default              | Description                                                                                                                                               |
+| ---------------- | -------------------------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `id`             | `string`                               | —                    | `id` on the `<input>`; also used to derive the listbox/option ids                                                                                         |
+| `label`          | `string`                               | —                    | `aria-label` on the `<input>` (visually hidden)                                                                                                           |
+| `type`           | `"text" \| "search"`                   | `"text"`             | `"search"` also renders an icon-only submit button (`onSubmit`)                                                                                           |
+| `options`        | `AutocompleteOption[]`                 | —                    | The **current** results to display — not filtered further, see below                                                                                      |
+| `onSearch`       | `(query: string) => void`              | —                    | Called on every keystroke with the trimmed input value — debounce it yourself and feed matches back in via `options`                                      |
+| `value`          | `string`                               | `""`                 | Initial `<input>` value (uncontrolled after that)                                                                                                         |
+| `status`         | `FormStatus`                           | `FormStatus.DEFAULT` | Sets `aria-invalid` (red border). Live `:user-*` colours need `mx-validate` on the `.mx-autocomplete` wrapper — `className` lands there, not on the input |
+| `noResultsLabel` | `string`                               | `"No results found"` | Message announced when `options` is empty and there's a query                                                                                             |
+| `onSelect`       | `(option: AutocompleteOption) => void` | —                    | Called when an option is chosen by click or <kbd>Enter</kbd>                                                                                              |
+| `hideOnBlur`     | `boolean`                              | `true`               | Close the listbox on blur                                                                                                                                 |
+| `className`      | `string`                               | —                    | Extra class on the root                                                                                                                                   |
 
 Any other native `<input>` prop (e.g. `placeholder`, `required`, `disabled`) is passed through to the `<input>`.
 
@@ -165,7 +165,7 @@ Any other native `<input>` prop (e.g. `placeholder`, `required`, `disabled`) is
 
 ## Modifiers
 
-This component has no BEM modifier classes — its only visual states (`error`/`success`) come from the shared `.mx-input__text` classes documented in `Form/form.css`.
+This component has no BEM modifier classes — its border states come from the shared validation rules in `Form/form.css`: `aria-invalid="true"` for explicit errors, and `:user-valid` / `:user-invalid` once `mx-validate` is added to the `<input>` (Twig, via `attributes`) or the `.mx-autocomplete` wrapper (React, via `className`).
 
 ---
 

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,8 +18,8 @@ exports[`Autocomplete 1`] = `
 exports[`Invalid 1`] = `
 "
 <mx-autocomplete class="mx-autocomplete">
-  <div class="mx-autocomplete__control mx-form--inline-button">
-    <input class="mx-input__text error" 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 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 error" 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>"`;

package/src/Form/Autocomplete/autocomplete.css

@@ -14,7 +14,7 @@
     max-inline-size: var(--container-max-width);
   }
 
-  /* @public --autocomplete-background --autocomplete-foreground --autocomplete-radius --autocomplete-shadow --autocomplete-max-height --autocomplete-padding-inline --autocomplete-padding-block */
+  /* @public --autocomplete-background --autocomplete-foreground --autocomplete-radius --autocomplete-shadow --autocomplete-max-height --autocomplete-padding-inline --autocomplete-padding-block --autocomplete-line-width --autocomplete-line-colour */
   .mx-autocomplete__listbox {
     position: absolute;
     z-index: 10;
@@ -23,6 +23,7 @@
     margin: 0;
     list-style: none;
     background-color: var(--autocomplete-background, var(--colour-background));
+    border: var(--autocomplete-line-width, 1px) solid var(--autocomplete-line-colour, transparent);
     color: var(--autocomplete-foreground, var(--colour-foreground));
     border-radius: var(--autocomplete-radius, var(--border-radius));
     box-shadow: var(--autocomplete-shadow, var(--box-shadow));
@@ -57,4 +58,14 @@
       outline-offset: var(--outline-offset, -2px);
     }
   }
+
+  .mx-autocomplete__control[aria-busy] {
+    & button {
+      order: 3;
+    }
+
+    &::after {
+      order: 2;
+    }
+  }
 }

package/src/Form/Autocomplete/autocomplete.twig

@@ -1,13 +1,11 @@
 {% set classes = [
   'mx-input__text',
-  status == "invalid" ? "error" : null,
-  status == "valid" ? "success" : null,
 ] %}
 {% set attributes = (attributes ?? create_attribute()).addClass(classes) %}
 {% set status = status|default("default") %}
 
 <mx-autocomplete class="mx-autocomplete"{% if noResultsLabel %} data-no-results-label="{{ noResultsLabel }}"{% endif %}>
-  <div class="mx-autocomplete__control mx-form--inline-button">
+  <div class="mx-autocomplete__control mx-form--inline-button" data-control>
     <input{{ attributes }}
         id="{{ id }}"
         name="{{ name }}"

package/src/Form/Checkbox/FormCheckbox.tsx

@@ -51,10 +51,7 @@ const Checkbox = ({
   const state = use(CheckboxContext)
   const { inputProps } = useCheckboxGroupItem(props, state, ref)
 
-  const classes = classNames("mx-checkbox", className, {
-    error: status === FormStatus.INVALID,
-    success: status === FormStatus.VALID,
-  })
+  const classes = classNames("mx-checkbox", className)
 
   return (
     <div className={classes}>
@@ -81,10 +78,7 @@ const SingleCheckbox = ({
   const state = useToggleState(props)
   const { inputProps } = useCheckbox(props, state, ref)
 
-  const classes = classNames("mx-checkbox", className, {
-    error: status === FormStatus.INVALID,
-    success: status === FormStatus.VALID,
-  })
+  const classes = classNames("mx-checkbox", className)
 
   return (
     <div className={classes}>

package/src/Form/Checkbox/README.md

@@ -24,8 +24,8 @@ Accessible checkbox and radio group components powered by [react-aria](https://r
   checked: true,
 } %}
 
-{# Required checkbox with invalid status — adds the "error" class
-   and aria-invalid, plus aria-describedby pointing at status-{id} #}
+{# Required checkbox with invalid status — adds aria-invalid (which paints
+   the red border), plus aria-describedby pointing at status-{id} #}
 {% include '@mixtape/Form/Checkbox/input-checkbox.twig' with {
   id: 'terms',
   name: 'terms',
@@ -39,17 +39,17 @@ Accessible checkbox and radio group components powered by [react-aria](https://r
 
 **input-checkbox.twig props** (composed from `FormControl` in `ids-shape` — checkbox/radio share the same template):
 
-| Prop             | Type              | Required | Description                                                                                                         |
-| ---------------- | ----------------- | -------- | ------------------------------------------------------------------------------------------------------------------- |
-| `id`             | `string`          | Yes      | Input id — also used to derive the `aria-describedby` ids (`help-{id}`, `status-{id}`)                              |
-| `name`           | `string`          | Yes      | `name` attribute on the input                                                                                       |
-| `value`          | `string`          | Yes      | `value` attribute on the input                                                                                      |
-| `label`          | `string`          | Yes      | Label text rendered inside `<label for="{id}">`                                                                     |
-| `checked`        | `boolean`         | No       | Adds `checked="checked"` to the input                                                                               |
-| `required`       | `boolean`         | No       | Adds the `required` attribute                                                                                       |
-| `status`         | `FormStatusTypes` | No       | `invalid` adds the `error` class and `aria-invalid="true"`; `valid` adds the `success` class. Defaults to `default` |
-| `hasDescription` | `boolean`         | No       | When `true`, `aria-describedby` is wired up to `help-{id}` (and `status-{id}` when `status` is set)                 |
-| `attributes`     | `Attribute`       | No       | Optional Drupal-style attributes object — `mx-checkbox` (and the status class) is always merged on top              |
+| Prop             | Type              | Required | Description                                                                                                                                        |
+| ---------------- | ----------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `id`             | `string`          | Yes      | Input id — also used to derive the `aria-describedby` ids (`help-{id}`, `status-{id}`)                                                             |
+| `name`           | `string`          | Yes      | `name` attribute on the input                                                                                                                      |
+| `value`          | `string`          | Yes      | `value` attribute on the input                                                                                                                     |
+| `label`          | `string`          | Yes      | Label text rendered inside `<label for="{id}">`                                                                                                    |
+| `checked`        | `boolean`         | No       | Adds `checked="checked"` to the input                                                                                                              |
+| `required`       | `boolean`         | No       | Adds the `required` attribute                                                                                                                      |
+| `status`         | `FormStatusTypes` | No       | `invalid` adds `aria-invalid="true"`, which paints the red border. Live `:user-*` colours need `mx-validate` on the wrapper. Defaults to `default` |
+| `hasDescription` | `boolean`         | No       | When `true`, `aria-describedby` is wired up to `help-{id}` (and `status-{id}` when `status` is set)                                                |
+| `attributes`     | `Attribute`       | No       | Optional Drupal-style attributes object — `mx-checkbox` is always merged on top                                                                    |
 
 The template renders `type="checkbox"` directly — for radio inputs use a sibling template (or hand-author the markup with `mx-radio` on the wrapper and `type="radio"` on the input).
 
@@ -164,11 +164,16 @@ Each input auto-generates its own `id` via `useId()` and wires its `<label htmlF
 
 ## Status states
 
-| `status`             | Class on wrapper | Effect                    |
-| -------------------- | ---------------- | ------------------------- |
-| `FormStatus.DEFAULT` | —                | Normal border             |
-| `FormStatus.INVALID` | `error`          | Red border on the input   |
-| `FormStatus.VALID`   | `success`        | Green border on the input |
+| `status`             | Attribute on input     | Effect                                     |
+| -------------------- | ---------------------- | ------------------------------------------ |
+| `FormStatus.DEFAULT` | `aria-invalid="false"` | Normal border                              |
+| `FormStatus.INVALID` | `aria-invalid="true"`  | Red border on the input                    |
+| `FormStatus.VALID`   | —                      | No border change — see `mx-validate` below |
+
+Add `mx-validate` to the `.mx-checkbox` wrapper to opt into live
+`:user-valid` / `:user-invalid` border colours as the user interacts. Without
+it, only an explicit `INVALID` status colours the border. See
+[Form/README.md](../README.md#validation-state).
 
 ## Touch target sizes
 

package/src/Form/Checkbox/input-checkbox.twig

@@ -1,7 +1,5 @@
 {% set classes = [
   'mx-checkbox',
-  status == "invalid" ? "error" : null,
-  status == "valid" ? "success" : null,
 ] %}
 {% set attributes = (attributes ?? create_attribute()).addClass(classes) %}
 {% set status = status|default("default") %}

package/src/Form/CheckboxCard/CheckboxCard.stories.ts

@@ -0,0 +1,90 @@
+import { Meta, StoryObj } from "@storybook/html-vite"
+import Component from "./checkbox-card.twig"
+import "../form.css"
+
+type CheckboxCardProps = {
+  id: string
+  name: string
+  value: string
+  label: string
+  hint?: string
+  checked?: boolean
+  required?: boolean
+  status?: "default" | "invalid" | "valid"
+}
+
+const meta: Meta<CheckboxCardProps> = {
+  tags: ["autodocs"],
+  component: Component,
+  args: {
+    id: "pay-carer",
+    name: "payments",
+    value: "Carer Payment or Allowance",
+    label: "Carer Payment or Carer Allowance",
+  },
+  parameters: {
+    a11y: {
+      config: {
+        rules: [
+          {
+            // ID's are not unique due to test-runner.
+            id: "label",
+            enabled: false,
+          },
+        ],
+      },
+    },
+  },
+}
+
+export default meta
+type Story = StoryObj<CheckboxCardProps>
+
+export const CheckboxCard: Story = {}
+
+export const WithHint: Story = {
+  args: {
+    id: "pay-other",
+    value: "Another income support payment",
+    label: "Another income support payment",
+    hint: "You will be asked which one before you submit",
+  },
+}
+
+export const Checked: Story = {
+  args: {
+    checked: true,
+  },
+}
+
+export const Invalid: Story = {
+  args: {
+    status: "invalid",
+  },
+}
+
+/**
+ * `.mx-choice-divider` splits a set of card choices into two groups — e.g.
+ * "pick one of these — or — pick this other option". Plain markup, not a
+ * component prop.
+ */
+export const Divider: Story = {
+  render: () =>
+    [
+      Component({
+        id: "card-yes",
+        name: "card",
+        value: "Yes, I hold a card",
+        label: "Yes, I hold a card",
+        hint: "Pensioner Concession, Health Care or DVA card",
+      }),
+      '<div class="mx-choice-divider">or</div>',
+      Component({
+        id: "card-unsure",
+        name: "card",
+        value: "Not sure",
+        label: "I am not sure",
+        hint: "We will ask a few more questions to work it out",
+      }),
+    ].join(""),
+}

package/src/Form/CheckboxCard/CheckboxCard.stories.tsx

@@ -0,0 +1,43 @@
+import { Meta, StoryObj } from "@storybook/react-vite"
+import CheckboxCard, { FormCheckboxCard, SingleCheckboxCard } from "./CheckboxCard"
+import "../form.css"
+import { Page } from "../../../.storybook-react/decorators"
+
+const meta: Meta<typeof SingleCheckboxCard> = {
+  decorators: [Page],
+  component: SingleCheckboxCard,
+}
+
+export default meta
+
+export const Single: StoryObj<typeof SingleCheckboxCard> = {
+  args: {
+    children: "Carer Payment or Carer Allowance",
+    value: "carer",
+  },
+}
+
+export const WithHint: StoryObj<typeof SingleCheckboxCard> = {
+  args: {
+    children: "Another income support payment",
+    hint: "You will be asked which one before you submit",
+    value: "other",
+  },
+}
+
+export const Group: StoryObj<typeof FormCheckboxCard> = {
+  render: ({ children, ...args }) => <FormCheckboxCard {...args}>{children}</FormCheckboxCard>,
+  args: {
+    label: "Which payments do you currently receive?",
+    children: (
+      <>
+        <CheckboxCard value="age">Age Pension</CheckboxCard>
+        <CheckboxCard value="dsp">Disability Support Pension</CheckboxCard>
+        <CheckboxCard value="carer">Carer Payment or Carer Allowance</CheckboxCard>
+        <CheckboxCard value="other" hint="You will be asked which one before you submit">
+          Another income support payment
+        </CheckboxCard>
+      </>
+    ),
+  },
+}