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

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">

package/src/Form/form.css

@@ -1,3 +1,5 @@
+@import "../Utility/_mixins.css";
+
 /**
  * Form
  */
@@ -65,6 +67,15 @@
     &[disabled] {
       opacity: var(--disabled-opacity, 0.6);
       cursor: not-allowed;
+
+      @media (--forced-colors) {
+        /* opt out so GrayText survives */
+        forced-color-adjust: none;
+        opacity: 1;
+        color: GrayText;
+        border-color: GrayText;
+        background-color: Canvas;
+      }
     }
   }
 
@@ -198,6 +209,7 @@
   .mx-checkbox [type="checkbox"] {
     box-shadow: none;
     appearance: none;
+    display: flex;
     inline-size: var(--control-size, var(--spacing-m));
     block-size: var(--control-size, var(--spacing-m));
     background-color: var(--background, var(--colour-background));
@@ -209,26 +221,44 @@
       --control-size: 2rem;
     }
 
-    &:checked {
-      background-image: url("./images/checkmark.svg");
-      background-size: 0.75rem;
-      background-position: center;
+    &:checked::after {
+      content: "";
+      display: block;
+      inline-size: 0.75rem;
+      block-size: 0.75rem;
+      margin: auto;
+      mask-image: url("./images/checkmark.svg");
+      mask-size: contain;
+      mask-position: center;
+      mask-repeat: no-repeat;
+      background-color: var(--checkbox-colour, currentcolor);
+
+      @add-mixin forced-colors-paint;
     }
 
     &[disabled] {
-      &::after {
-        opacity: var(--disabled-opacity, 0.6);
-        cursor: not-allowed;
-        content: "";
-        display: block;
-        inline-size: 100%;
-        block-size: 100%;
-        border-radius: var(--border-radius);
-      }
+      cursor: not-allowed;
 
       & + label {
         opacity: var(--disabled-opacity, 0.6);
         cursor: not-allowed;
+
+        @media (--forced-colors) {
+          /* opt out or the UA forces this straight back to CanvasText */
+          forced-color-adjust: none;
+          opacity: 1;
+          color: GrayText;
+        }
+      }
+
+      @media (--forced-colors) {
+        /* opt out so GrayText survives */
+        --forced-colour: GrayText;
+
+        forced-color-adjust: none;
+        color: GrayText;
+        border-color: GrayText;
+        background-color: Canvas;
       }
     }
   }
@@ -258,32 +288,41 @@
       --control-size: 2rem;
     }
 
-    &:checked {
-      &::after {
-        content: "";
-        display: block;
-        inline-size: 0.5rem;
-        block-size: 0.5rem;
-        margin: auto;
-        border-radius: 50%;
-        background-color: var(--radio-colour, var(--colour-primary));
-      }
+    &:checked::after {
+      content: "";
+      display: block;
+      inline-size: 0.5rem;
+      block-size: 0.5rem;
+      margin: auto;
+      border-radius: 50%;
+      background-color: var(--radio-colour, var(--colour-primary));
+
+      @add-mixin forced-colors-paint;
     }
 
     &[disabled] {
-      &::after {
-        opacity: var(--disabled-opacity, 0.6);
-        cursor: not-allowed;
-        content: "";
-        display: block;
-        inline-size: 100%;
-        block-size: 100%;
-        border-radius: 50%;
-      }
+      cursor: not-allowed;
 
       & + label {
         opacity: var(--disabled-opacity, 0.6);
         cursor: not-allowed;
+
+        @media (--forced-colors) {
+          /* opt out or the UA forces this straight back to CanvasText */
+          forced-color-adjust: none;
+          opacity: 1;
+          color: GrayText;
+        }
+      }
+
+      @media (--forced-colors) {
+        /* opt out so GrayText survives */
+        --forced-colour: GrayText;
+
+        forced-color-adjust: none;
+        color: GrayText;
+        border-color: GrayText;
+        background-color: Canvas;
       }
     }
   }
@@ -467,12 +506,25 @@
       }
     }
 
+    /* A <select> has no pseudo-element to mask, and the chevron asset is a
+       fixed black, so on the legacy path hand the arrow back to the UA under
+       forced colours. The base-select path masks ::picker-icon instead. */
+    @supports not (appearance: base-select) {
+      @media (--forced-colors) {
+        appearance: auto;
+        background-image: none;
+        padding-inline-end: revert;
+      }
+    }
+
     &::picker-icon {
       mask-image: url("./images/form-chevron-down.svg");
       mask-repeat: no-repeat;
       mask-position: center;
       background-color: currentcolor;
       aspect-ratio: 1 / 1;
+
+      @add-mixin forced-colors-paint;
     }
 
     &:open::picker-icon {
@@ -486,6 +538,8 @@
       display: block;
       mask-image: url("./images/checkmark.svg");
       background-color: currentcolor;
+
+      @add-mixin forced-colors-paint;
     }
 
     &[multiple] {
@@ -606,11 +660,15 @@
   .mx-error-message::before {
     mask-image: url("./images/form-error.svg");
     background-color: var(--error-foreground, var(--colour-error));
+
+    @add-mixin forced-colors-paint;
   }
 
   .mx-success-message::before {
     mask-image: url("./images/form-success.svg");
     background-color: var(--success-foreground, var(--colour-success));
+
+    @add-mixin forced-colors-paint;
   }
 }
 

package/src/Layout/Footer/__snapshots__/Footer.stories.ts.snap

@@ -78,28 +78,25 @@ exports[`Everything 1`] = `
   
   <nav class="mx-social-links" aria-label="Social media links">
   
-  
-<a href="#">
+        
+<a href="#" aria-label="Facebook">
   
 <span class="mx-icon mx-icon--facebook mx-icon--size-md"></span>
 
-  <span class="sr-only">Facebook</span>
     
 </a>
-
-<a href="#">
+      
+<a href="#" aria-label="Instagram">
   
 <span class="mx-icon mx-icon--instagram mx-icon--size-md"></span>
 
-  <span class="sr-only">Instagram</span>
     
 </a>
-
-<a href="#">
+      
+<a href="#" aria-label="LinkedIn">
   
 <span class="mx-icon mx-icon--linkedin mx-icon--size-md"></span>
 
-  <span class="sr-only">LinkedIn</span>
     
 </a>
 
@@ -112,14 +109,12 @@ exports[`Everything 1`] = `
       
 <a href="#">
   
-  <span>Accessibility</span>
-    
+  Accessibility  
 </a>
 
 <a href="#">
   
-  <span>Terms &amp; Conditions</span>
-    
+  Terms &amp; Conditions  
 </a>
 
     </nav>
@@ -169,14 +164,12 @@ exports[`Footer 1`] = `
       
 <a href="#">
   
-  <span>Accessibility</span>
-    
+  Accessibility  
 </a>
 
 <a href="#">
   
-  <span>Terms &amp; Conditions</span>
-    
+  Terms &amp; Conditions  
 </a>
 
     </nav>
@@ -226,14 +219,12 @@ exports[`Light 1`] = `
       
 <a href="#">
   
-  <span>Accessibility</span>
-    
+  Accessibility  
 </a>
 
 <a href="#">
   
-  <span>Terms &amp; Conditions</span>
-    
+  Terms &amp; Conditions  
 </a>
 
     </nav>
@@ -283,14 +274,12 @@ exports[`No Logo 1`] = `
       
 <a href="#">
   
-  <span>Accessibility</span>
-    
+  Accessibility  
 </a>
 
 <a href="#">
   
-  <span>Terms &amp; Conditions</span>
-    
+  Terms &amp; Conditions  
 </a>
 
     </nav>
@@ -313,14 +302,12 @@ exports[`No Menu 1`] = `
       
 <a href="#">
   
-  <span>Accessibility</span>
-    
+  Accessibility  
 </a>
 
 <a href="#">
   
-  <span>Terms &amp; Conditions</span>
-    
+  Terms &amp; Conditions  
 </a>
 
     </nav>
@@ -371,14 +358,12 @@ exports[`With Acknowledgment 1`] = `
       
 <a href="#">
   
-  <span>Accessibility</span>
-    
+  Accessibility  
 </a>
 
 <a href="#">
   
-  <span>Terms &amp; Conditions</span>
-    
+  Terms &amp; Conditions  
 </a>
 
     </nav>

package/src/Layout/Header/Header.stories.ts

@@ -18,6 +18,7 @@ import "../../Component/Navigation/Elements/Navigation"
 // css.
 import "../../Component/Navigation/navigation.css"
 import { modes } from "../../../.storybook/modes"
+import { runScreenReaderWalkthrough } from "../../../tools/test-utils/screen-reader"
 
 type MxHeaderType = Omit<HeaderType, "controls"> & {
   stacked: boolean
@@ -117,6 +118,38 @@ export const Header: Story = {
   },
 }
 
+/**
+ * Steps a virtual screen reader through the page and asserts on what it announces.
+ */
+export const ScreenReaderAnnouncements: Story = {
+  play: async () => {
+    const log = await runScreenReaderWalkthrough()
+    await expect(log).toEqual([
+      "document",
+      "banner",
+      "image, Mixtape",
+      "navigation, Primary navigation",
+      "list",
+      "listitem, level 1, position 1, set size 4",
+      "link, News",
+      "end of listitem, level 1, position 1, set size 4",
+      "listitem, level 1, position 2, set size 4",
+      "link, About us",
+      "end of listitem, level 1, position 2, set size 4",
+      "listitem, level 1, position 3, set size 4",
+      "link, Contact",
+      "end of listitem, level 1, position 3, set size 4",
+      "listitem, level 1, position 4, set size 4",
+      "link, Resources",
+      "end of listitem, level 1, position 4, set size 4",
+      "end of list",
+      "end of navigation, Primary navigation",
+      "end of banner",
+      "end of document",
+    ])
+  },
+}
+
 export const WithTitle: Story = {
   args: {
     title: "Design System",