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

package/src/Form/CheckboxCard/CheckboxCard.tsx

@@ -0,0 +1,102 @@
+import { createContext, JSX, PropsWithChildren, use, useId, useRef } from "react"
+import {
+  AriaCheckboxGroupItemProps,
+  AriaCheckboxProps,
+  useCheckbox,
+  useCheckboxGroup,
+  useCheckboxGroupItem,
+} from "react-aria"
+import {
+  CheckboxGroupProps,
+  CheckboxGroupState,
+  useCheckboxGroupState,
+  useToggleState,
+} from "react-stately"
+import classNames from "classnames"
+import FormItem from "../FormItem/FormItem"
+import { FormStatus } from "../../enums"
+
+const CheckboxCardContext = createContext<CheckboxGroupState>(null)
+
+type FormCheckboxCardProps = CheckboxGroupProps &
+  PropsWithChildren & {
+    label?: string
+  }
+
+const FormCheckboxCard = ({ label, children, ...props }: FormCheckboxCardProps): JSX.Element => {
+  const state = useCheckboxGroupState(props)
+  const { groupProps } = useCheckboxGroup(props, state)
+
+  return (
+    <FormItem fieldset {...groupProps} legend={label}>
+      <CheckboxCardContext value={state}>{children}</CheckboxCardContext>
+    </FormItem>
+  )
+}
+
+type CheckboxCardProps = AriaCheckboxGroupItemProps &
+  PropsWithChildren & {
+    hint?: string
+    status?: FormStatus
+    className?: string
+  }
+
+const CheckboxCard = ({
+  children,
+  hint = null,
+  status = FormStatus.DEFAULT,
+  className = "",
+  ...props
+}: CheckboxCardProps): JSX.Element => {
+  const id = useId()
+  const ref = useRef<HTMLInputElement>(null)
+  const state = use(CheckboxCardContext)
+  const { inputProps } = useCheckboxGroupItem(props, state, ref)
+
+  const classes = classNames("mx-checkbox", "mx-choice-card", className)
+
+  return (
+    <div className={classes}>
+      <input id={id} ref={ref} aria-invalid={status === FormStatus.INVALID} {...inputProps} />
+      <label htmlFor={id}>
+        {children}
+        {hint && <span className="mx-choice-card__hint">{hint}</span>}
+      </label>
+    </div>
+  )
+}
+
+type SingleCheckboxCardProps = AriaCheckboxProps &
+  PropsWithChildren & {
+    hint?: string
+    status?: FormStatus
+    className?: string
+  }
+
+const SingleCheckboxCard = ({
+  children,
+  hint = null,
+  status = FormStatus.DEFAULT,
+  className = "",
+  ...props
+}: SingleCheckboxCardProps): JSX.Element => {
+  const id = useId()
+  const ref = useRef<HTMLInputElement>(null)
+  const state = useToggleState(props)
+  const { inputProps } = useCheckbox(props, state, ref)
+
+  const classes = classNames("mx-checkbox", "mx-choice-card", className)
+
+  return (
+    <div className={classes}>
+      <input id={id} ref={ref} aria-invalid={status === FormStatus.INVALID} {...inputProps} />
+      <label htmlFor={id}>
+        {children}
+        {hint && <span className="mx-choice-card__hint">{hint}</span>}
+      </label>
+    </div>
+  )
+}
+
+export default CheckboxCard
+export { FormCheckboxCard, SingleCheckboxCard }

package/src/Form/CheckboxCard/README.md

@@ -0,0 +1,163 @@
+# CheckboxCard
+
+A card-style checkbox — a full padded, bordered, selectable card instead of a small inline control. Use for a small set of options that benefit from a larger tap target and optional secondary hint text (e.g. a high-stakes form question), rather than a dense list of ordinary checkboxes.
+
+> **HTML/Twig users:** use native `<input type="checkbox">` with both the `.mx-checkbox` and `.mx-choice-card` wrapper classes. The react-aria wiring is React-only.
+
+`.mx-choice-card` layers on top of `.mx-checkbox` rather than replacing it — the base class still supplies input reset/sizing, disabled state, and the spacing between stacked cards in a group; `.mx-choice-card`'s higher cascade layer (`design-system.components` vs. `.mx-checkbox`'s `design-system.atoms`) overrides only what the card treatment needs to change (position, padding, border).
+
+`.mx-choice-card` is shared with `RadioCard` — it lives in `src/Form/form.css` alongside the base `.mx-checkbox`/`.mx-radio` rules, not in a per-component CSS file, since the two components' card treatments were identical enough to not warrant separate copies.
+
+## CSS Import
+
+```css
+@import "@pnx-mixtape/mxds/src/Form/form.css";
+```
+
+---
+
+## Twig
+
+```twig
+{# Single card #}
+{% include '@mixtape/Form/CheckboxCard/checkbox-card.twig' with {
+  id: 'pay-carer',
+  name: 'payments',
+  value: 'Carer Payment or Allowance',
+  label: 'Carer Payment or Carer Allowance',
+} %}
+
+{# With a secondary hint line under the label #}
+{% include '@mixtape/Form/CheckboxCard/checkbox-card.twig' with {
+  id: 'pay-other',
+  name: 'payments',
+  value: 'Another income support payment',
+  label: 'Another income support payment',
+  hint: 'You will be asked which one before you submit',
+} %}
+```
+
+**checkbox-card.twig props:**
+
+| 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}">`                                                                       |
+| `hint`           | `string`          | No       | Secondary line rendered under the label, inside the card                                                              |
+| `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 mx-choice-card` (and the status class) is always merged on top |
+
+For a group of cards, compose several `checkbox-card.twig` includes inside a plain `<fieldset>`, same as `Checkbox` — see HTML below.
+
+---
+
+## HTML
+
+```html
+<fieldset class="mx-form-item mx-fieldset mx-fieldset--plain">
+  <legend class="mx-legend">Which payments do you currently receive?</legend>
+
+  <div class="mx-checkbox mx-choice-card">
+    <input type="checkbox" id="pay-age" name="payments" value="Age Pension" />
+    <label for="pay-age">Age Pension</label>
+  </div>
+
+  <div class="mx-checkbox mx-choice-card">
+    <input type="checkbox" id="pay-other" name="payments" value="Another income support payment" />
+    <label for="pay-other">
+      Another income support payment
+      <span class="mx-choice-card__hint">You will be asked which one before you submit</span>
+    </label>
+  </div>
+</fieldset>
+```
+
+### "Or" divider between two option groups
+
+`.mx-choice-divider` renders a horizontal rule with centred text — useful for splitting a set of card choices into "pick one of these — or — pick this other option" (see the source mockup's card question). It's plain markup, not tied to `CheckboxCard`/`RadioCard` specifically:
+
+```html
+<div class="mx-choice-divider">or</div>
+```
+
+---
+
+## React
+
+### Standalone card
+
+```tsx
+import { SingleCheckboxCard } from "@pnx-mixtape/mxds/react"
+
+;<SingleCheckboxCard value="carer">Carer Payment or Carer Allowance</SingleCheckboxCard>
+```
+
+### Card group
+
+Use `FormCheckboxCard` as the group wrapper and `CheckboxCard` for each option — same pattern as `FormCheckbox`/`Checkbox`.
+
+```tsx
+import { FormCheckboxCard, CheckboxCard } from "@pnx-mixtape/mxds/react"
+
+;<FormCheckboxCard label="Which payments do you currently receive?" onChange={setSelected}>
+  <CheckboxCard value="age">Age Pension</CheckboxCard>
+  <CheckboxCard value="dsp">Disability Support Pension</CheckboxCard>
+  <CheckboxCard value="other" hint="You will be asked which one before you submit">
+    Another income support payment
+  </CheckboxCard>
+</FormCheckboxCard>
+```
+
+**`FormCheckboxCard` props:** all `CheckboxGroupProps` from react-stately + `label: string`
+
+**`CheckboxCard` props:** all `AriaCheckboxGroupItemProps` + `hint?: string`, `status?: FormStatus`, `className?: string`
+
+**`SingleCheckboxCard` props:** all `AriaCheckboxProps` + `hint?: string`, `status?: FormStatus`, `className?: string`
+
+---
+
+### React ⇄ Twig parity
+
+The prop shapes intentionally diverge, same as `Checkbox`/`Radio`:
+
+- Twig's `label` becomes React `children` — react-aria composes the accessible name from rendered content, not a string prop.
+- Twig's `id`/`name`/`checked`/`required`/`value` are handled by the react-aria hooks (`useCheckboxGroupItem`/`useCheckbox`) via prop spread — they aren't declared as explicit props because react-aria owns generating/wiring them (e.g. `id` comes from `useId()`).
+- Twig's `hasDescription` manually wires `aria-describedby` to a `help-{id}` node; React doesn't need it because react-aria's hooks generate and wire that association themselves when a description is passed through their own props.
+
+---
+
+## Modifiers
+
+No BEM modifier classes — `error`/`success` are applied as plain (unprefixed) status classes, matching `Checkbox`'s convention, driven by the `status` prop/Twig var.
+
+---
+
+## Accessibility
+
+- The input stays a real, focusable `<input type="checkbox">` — only its default appearance is replaced (`appearance: none` plus a custom checked-state image), so it keeps native checkbox semantics, keyboard support (<kbd>Space</kbd> to toggle), and form submission behaviour.
+- The whole card is clickable because the `<label>` fills it — the input itself only needs to be as large as `--control-size` dictates, not the full card.
+- The focus ring (`:focus-visible`) renders on the input itself, inside the card, rather than around the whole card — keeps the indicator anchored to the actual interactive control.
+- `hint` text is inside the same `<label>` as the primary text, so both are announced together when the control receives focus — don't rely on `hint` to convey anything the primary `label` text doesn't already establish.
+
+---
+
+## Customisation
+
+| Custom property           | Applies to                                                        | Default                                             |
+| ------------------------- | ----------------------------------------------------------------- | --------------------------------------------------- |
+| `--choice-padding-block`  | `.mx-choice-card`                                                 | `var(--spacing-s)`                                  |
+| `--choice-padding-inline` | `.mx-choice-card`                                                 | `var(--spacing-m)`                                  |
+| `--choice-colour-active`  | `.mx-choice-card`                                                 | `var(--colour-primary)`                             |
+| `--control-size`          | `.mx-choice-card input`, and `.mx-checkbox`'s own input styling   | `var(--spacing-m)` (shared with `Checkbox`/`Radio`) |
+| `--line-width`            | `.mx-choice-card`'s border, and `.mx-checkbox`'s own input border | `2px`                                               |
+
+```css
+.theme--health-services .mx-choice-card {
+  --choice-colour-active: var(--colour-primary);
+}
+```

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

@@ -0,0 +1,63 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`Checkbox Card 1`] = `
+"
+<div class="mx-checkbox mx-choice-card">
+  <input id="pay-carer" type="checkbox" name="payments" value="Carer Payment or Allowance">
+  <label for="pay-carer">
+    Carer Payment or Carer Allowance
+      </label>
+</div>
+"
+`;
+
+exports[`Checked 1`] = `
+"
+<div class="mx-checkbox mx-choice-card">
+  <input id="pay-carer" type="checkbox" name="payments" value="Carer Payment or Allowance" checked="checked">
+  <label for="pay-carer">
+    Carer Payment or Carer Allowance
+      </label>
+</div>
+"
+`;
+
+exports[`Divider 1`] = `
+"
+<div class="mx-checkbox mx-choice-card">
+  <input id="card-yes" type="checkbox" name="card" value="Yes, I hold a card">
+  <label for="card-yes">
+    Yes, I hold a card
+    <span class="mx-choice-card__hint">Pensioner Concession, Health Care or DVA card</span>  </label>
+</div>
+<div class="mx-choice-divider">or</div>
+<div class="mx-checkbox mx-choice-card">
+  <input id="card-unsure" type="checkbox" name="card" value="Not sure">
+  <label for="card-unsure">
+    I am not sure
+    <span class="mx-choice-card__hint">We will ask a few more questions to work it out</span>  </label>
+</div>
+"
+`;
+
+exports[`Invalid 1`] = `
+"  
+<div class="mx-checkbox mx-choice-card">
+  <input id="pay-carer" type="checkbox" name="unique-0" value="Carer Payment or Allowance" aria-describedby="unique-0" aria-invalid="true">
+  <label for="pay-carer">
+    Carer Payment or Carer Allowance
+      </label>
+</div>
+"
+`;
+
+exports[`With Hint 1`] = `
+"
+<div class="mx-checkbox mx-choice-card">
+  <input id="pay-other" type="checkbox" name="payments" value="Another income support payment">
+  <label for="pay-other">
+    Another income support payment
+    <span class="mx-choice-card__hint">You will be asked which one before you submit</span>  </label>
+</div>
+"
+`;

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

@@ -0,0 +1,7 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`Group 1`] = `"<fieldset class="mx-form-item mx-fieldset" role="group" id="react-aria-_r_6_"><legend class="mx-legend">Which payments do you currently receive?</legend><div class="mx-checkbox mx-choice-card"><input id="_r_b_" data-react-aria-pressable="true" tabindex="0" type="checkbox" value="age"><label for="_r_b_">Age Pension</label></div><div class="mx-checkbox mx-choice-card"><input id="_r_e_" data-react-aria-pressable="true" tabindex="0" type="checkbox" value="dsp"><label for="_r_e_">Disability Support Pension</label></div><div class="mx-checkbox mx-choice-card"><input id="_r_h_" data-react-aria-pressable="true" tabindex="0" type="checkbox" value="carer"><label for="_r_h_">Carer Payment or Carer Allowance</label></div><div class="mx-checkbox mx-choice-card"><input id="_r_k_" data-react-aria-pressable="true" tabindex="0" type="checkbox" value="other"><label for="_r_k_">Another income support payment<span class="mx-choice-card__hint">You will be asked which one before you submit</span></label></div></fieldset>"`;
+
+exports[`Single 1`] = `"<div class="mx-checkbox mx-choice-card"><input id="_r_0_" data-react-aria-pressable="true" tabindex="0" type="checkbox" value="carer"><label for="_r_0_">Carer Payment or Carer Allowance</label></div>"`;
+
+exports[`With Hint 1`] = `"<div class="mx-checkbox mx-choice-card"><input id="_r_3_" data-react-aria-pressable="true" tabindex="0" type="checkbox" value="other"><label for="_r_3_">Another income support payment<span class="mx-choice-card__hint">You will be asked which one before you submit</span></label></div>"`;

package/src/Form/CheckboxCard/checkbox-card.twig

@@ -0,0 +1,29 @@
+{% set classes = [
+  'mx-checkbox',
+  'mx-choice-card',
+] %}
+{% set attributes = (attributes ?? create_attribute()).addClass(classes) %}
+{% set status = status|default("default") %}
+{% if hasDescription or status != "default" %}
+  {% set helpers = [
+    hasDescription ? "help-"~ id : null,
+    status != "default" ?  "status-"~ id : null,
+  ]|join(" ")|trim() %}
+{% endif %}
+
+<div{{ attributes }}>
+  <input
+      id="{{ id }}"
+      type="checkbox"
+      name="{{ name }}"
+      value="{{ value }}"
+      {% if checked %} checked="checked"{% endif %}
+      {% if helpers is not empty %} aria-describedby="{{ helpers }}"{% endif %}
+      {% if status == "invalid" %} aria-invalid="true"{% endif %}
+      {% if required %} required{% endif %}
+  >
+  <label for="{{ id }}">
+    {{ label }}
+    {% if hint %}<span class="mx-choice-card__hint">{{ hint }}</span>{% endif %}
+  </label>
+</div>

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

@@ -31,7 +31,7 @@ exports[`Error 1`] = `
 
   
     
-<input class="mx-input__text error" id="form-item" name="unique-0" type="text" value="Musicals" placeholder="eg. Funk, Soul, Blues.." aria-describedby="unique-0" aria-invalid="true">
+<input class="mx-input__text" id="form-item" name="unique-0" type="text" value="Musicals" placeholder="eg. Funk, Soul, Blues.." aria-describedby="unique-0" aria-invalid="true">
 
   <div class="mx-description" id="help-form-item">
   Help text that provides additional information about the field.
@@ -118,7 +118,7 @@ exports[`Success 1`] = `
 
   
     
-<input class="mx-input__text success" id="form-item" name="unique-0" type="text" value="Jazz" placeholder="eg. Funk, Soul, Blues.." aria-describedby="unique-0">
+<input class="mx-input__text" id="form-item" name="unique-0" type="text" value="Jazz" placeholder="eg. Funk, Soul, Blues.." aria-describedby="unique-0">
 
   <div class="mx-description" id="help-form-item">
   Help text that provides additional information about the field.

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 %}
+/>