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

package/src/Form/Autocomplete/Autocomplete.tsx

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

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

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

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

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

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

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

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

@@ -5,7 +5,7 @@
 {% 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/OneTimeCode/OneTimeCode.stories.ts

@@ -0,0 +1,20 @@
+import { Meta, StoryObj } from "@storybook/html-vite"
+import Component from "./one-time-code.twig"
+import "../form.css"
+import "./one-time-code.css"
+
+const meta: Meta<typeof Component> = {
+  tags: ["autodocs"],
+  component: Component,
+  args: {
+    id: "otp",
+    name: "otp",
+    label: "One-time code",
+    length: 6,
+  },
+}
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+export const OneTimeCode: Story = {}

package/src/Form/OneTimeCode/OneTimeCode.stories.tsx

@@ -0,0 +1,18 @@
+import { Meta, StoryObj } from "@storybook/react-vite"
+import Component from "./OneTimeCode"
+import "./one-time-code.css"
+import { Page } from "../../../.storybook-react/decorators"
+
+const meta: Meta<typeof Component> = {
+  decorators: [Page],
+  component: Component,
+  args: {
+    id: "otp",
+    name: "otp",
+    "aria-label": "One-time code",
+    length: 6,
+  },
+}
+
+export default meta
+export const OneTimeCode: StoryObj<typeof Component> = {}

package/src/Form/OneTimeCode/OneTimeCode.tsx

@@ -0,0 +1,56 @@
+import { JSX, ComponentPropsWithoutRef, useState, useMemo, ChangeEventHandler } from "react"
+import classNames from "classnames"
+import { FormStatus } from "../../enums"
+
+type OneTimeCodeProps = ComponentPropsWithoutRef<"input"> & {
+  value?: string
+  className?: string
+  status?: FormStatus
+  /** Number of digits the code contains. Drives `maxLength` and the field's width. */
+  length?: number
+}
+
+const OneTimeCode = ({
+  id,
+  required = false,
+  value = "",
+  status = FormStatus.DEFAULT,
+  name = null,
+  className = "",
+  length = 6,
+  style,
+  ...props
+}: OneTimeCodeProps): JSX.Element => {
+  const [inputValue, setInputValue] = useState<string>(value)
+  const handleChange: ChangeEventHandler<HTMLInputElement> = ({ currentTarget }) =>
+    setInputValue(currentTarget.value.replace(/\D/g, ""))
+
+  const classes = classNames("mx-input__text", "mx-one-time-code", "mx-validate", className)
+  const otpStyle = useMemo(
+    () => ({ ...style, "--one-time-code-length": length }) as never,
+    [style, length],
+  )
+
+  return (
+    <input
+      className={classes}
+      style={otpStyle}
+      onChange={handleChange}
+      id={id}
+      type="text"
+      inputMode="numeric"
+      autoComplete="one-time-code"
+      pattern="[0-9]*"
+      minLength={length}
+      maxLength={length}
+      name={name}
+      value={inputValue}
+      required={required}
+      aria-describedby={`help-${id}`}
+      aria-invalid={status === FormStatus.INVALID}
+      {...props}
+    />
+  )
+}
+
+export default OneTimeCode

package/src/Form/OneTimeCode/README.md

@@ -0,0 +1,83 @@
+# OneTimeCode
+
+A single `<input>` for one-time-code / 2FA entry — `autocomplete="one-time-code"` gets native SMS autofill and password-manager support, without splitting the field into six separate inputs. Centred, letter-spaced digits stand in for the usual per-box divider look. See [Form/README.md](../README.md#the-composition-pattern) for the surrounding `FormItem`/`FormLabel`/`FormDescription` pattern.
+
+---
+
+## CSS Import
+
+```css
+@import "@pnx-mixtape/mxds/src/Form/OneTimeCode/one-time-code.css";
+```
+
+---
+
+## Twig
+
+```twig
+{% include '@mixtape/Form/OneTimeCode/one-time-code.twig' with {
+  id: 'otp',
+  name: 'otp',
+  label: 'One-time code',
+  length: 6,
+} %}
+```
+
+---
+
+## HTML
+
+```html
+<input
+  class="mx-input__text mx-one-time-code mx-validate"
+  id="otp"
+  name="otp"
+  type="text"
+  inputmode="numeric"
+  autocomplete="one-time-code"
+  pattern="[0-9]*"
+  minlength="6"
+  maxlength="6"
+  aria-label="One-time code"
+/>
+```
+
+---
+
+## React
+
+```tsx
+import { OneTimeCode } from "@pnx-mixtape/mxds/react"
+
+;<OneTimeCode id="otp" name="otp" aria-label="One-time code" length={6} />
+```
+
+**`OneTimeCode` props:** all native `<input>` attributes + `status?: FormStatus` (default: `DEFAULT`) + `length?: number` (default: `6`, sets `minLength`/`maxLength` and the field's width — see Customisation)
+
+Renders `mx-input__text mx-one-time-code mx-validate`. Sets `aria-describedby` and `aria-invalid` automatically, same as `FormText`. Strips non-digit characters on change.
+
+### React ⇄ Twig parity
+
+- `id`/`name`/`required` flow through React via `ComponentPropsWithoutRef<"input">` (spread onto the `<input>`, not named in `OneTimeCodeProps`) rather than explicit props — same shape as `FormText`. Twig takes them as named template variables. Functionally identical, not a real divergence.
+- `label`/`hasDescription` are Twig-only helpers that build the `aria-label`/`aria-describedby` wiring from a single include call, matching `TextInput`'s Twig template. React expects those same ARIA attributes passed directly (`aria-label`, `aria-describedby`) since JSX has no template-include layer to generate them from.
+- `length` sizes the field via the `--one-time-code-length` custom property (React sets it through `style`, Twig through a `style` attribute on the `<input>`) — both stacks resolve `length` the same way. CSS can't read the `maxlength` attribute's value into a `calc()`, so this is the one place the component reaches for an inline style rather than a class.
+
+---
+
+## Modifiers
+
+This component has no BEM modifier classes — it composes `mx-input__text`'s shared border/background/status styling from `Form/form.css` (see [Form/README.md](../README.md#input-modifier-classes)) and adds `mx-one-time-code` for the centred, letter-spaced digit layout. Unlike `FormText`, `mx-validate` is always applied (not opt-in) — a code field's native constraints (`pattern`, `minlength`/`maxlength`, `required`) are worth surfacing live as the user types, and there's no plausible case for wanting a OneTimeCode field that never colours on completion.
+
+---
+
+## Accessibility
+
+- `autocomplete="one-time-code"` is what lets browsers/OSes autofill an SMS-delivered code into this single field — the reason to prefer one input over six. See [WHATWG HTML: autofill field `one-time-code`](https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#autofill-field-one-time-code).
+- `inputmode="numeric"` brings up a numeric keypad on mobile without changing the semantic `type="text"` (using `type="number"` would strip leading zeros and add spinner controls).
+- Always pair with a visible or `aria-label`led label; centred digits alone don't announce "one-time code" to screen readers.
+
+---
+
+## Customisation
+
+`--one-time-code-length` (default `6`) sizes the field and is set per-instance via the `length` prop/variable, not something you override directly in CSS — see React ⇄ Twig parity, above. Letter-spacing and `tabular-nums` digit width can be tuned by overriding `letter-spacing`/`font-variant-numeric` on `.mx-one-time-code` as with any other input.

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

@@ -0,0 +1,7 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`One Time Code 1`] = `
+"
+<input class="mx-input__text mx-one-time-code mx-validate" id="otp" name="otp" type="text" inputmode="numeric" autocomplete="one-time-code" pattern="[0-9]*" minlength="6" maxlength="6" style="--one-time-code-length: 6;" value="" aria-label="One-time code">
+"
+`;

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

@@ -0,0 +1,3 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`One Time Code 1`] = `"<input class="mx-input__text mx-one-time-code mx-validate" id="otp" inputmode="numeric" autocomplete="one-time-code" pattern="[0-9]*" minlength="6" maxlength="6" aria-describedby="help-otp" aria-invalid="false" aria-label="One-time code" type="text" value="" name="otp" style="--one-time-code-length: 6;">"`;

package/src/Form/OneTimeCode/one-time-code.css

@@ -0,0 +1,13 @@
+/**
+ * OneTimeCode
+ */
+
+@layer design-system.components {
+  /* @public --one-time-code-length */
+  .mx-one-time-code {
+    inline-size: calc((var(--one-time-code-length, 6) * 2.5ch) + 1ch);
+    text-align: center;
+    letter-spacing: 0.5ch;
+    font-variant-numeric: tabular-nums;
+  }
+}

package/src/Form/OneTimeCode/one-time-code.twig

@@ -0,0 +1,31 @@
+{% set classes = [
+  'mx-input__text',
+  'mx-one-time-code',
+  'mx-validate',
+] %}
+{% set attributes = (attributes ?? create_attribute()).addClass(classes) %}
+{% set status = status|default("default") %}
+{% set length = length|default(6) %}
+{% if hasDescription or status != "default" %}
+  {% set helpers = [
+    hasDescription ? "help-"~ id : null,
+    status != "default" ?  "status-"~ id : null,
+  ]|join(" ")|trim() %}
+{% endif %}
+
+<input{{ attributes }}
+    id="{{ id }}"
+    name="{{ name }}"
+    type="text"
+    inputmode="numeric"
+    autocomplete="one-time-code"
+    pattern="[0-9]*"
+    minlength="{{ length }}"
+    maxlength="{{ length }}"
+    style="--one-time-code-length: {{ length }};"
+    value="{{ value }}"
+    {% if label %} aria-label="{{ label }}"{% endif %}
+    {% if helpers is not empty %} aria-describedby="{{ helpers }}"{% endif %}
+    {% if status == "invalid" %} aria-invalid="true"{% endif %}
+    {% if required %} required{% endif %}
+/>

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

@@ -103,7 +103,7 @@ exports[`Validation 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-validate mx-input__text" id="unique-6" name="unique-2" type="text" role="combobox" aria-expanded="false" aria-controls="unique-2" aria-autocomplete="list" aria-activedescendant="" aria-describedby="unique-2" aria-label="Favourite fruit" autocomplete="off" required="">
       </div>
   <div class="mx-autocomplete__suggestions">