@slotted/react 0.0.0-stage → 0.1.0-beta.1

package/dist/docs/number-field.md

@@ -0,0 +1,115 @@
+<!-- index: ./index.md -->
+# number-field
+
+`data-ui="number-field"` · Number input with steppers and formatting.
+
+## Import
+
+```tsx
+import { NumberField, NumberFieldDefaultsProvider, NumberFieldScrub } from '@slotted/react';
+```
+
+## Minimal example
+
+Example
+
+```tsx
+import { Field, FieldDescription, FieldLabel } from '@slotted/react/field';
+import { NumberField } from '@slotted/react/number-field';
+
+export default function NumberFieldBasic() {
+  return (
+    <Field required>
+      <FieldLabel>Reorder point</FieldLabel>
+      <NumberField defaultValue={25} end="units" max={500} min={0} step={5} />
+      <FieldDescription>Chai is reordered when stock falls to this level.</FieldDescription>
+    </Field>
+  );
+}
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | div, or the element render returns | yes |
+| `input` | input[type=text][role=spinbutton] | yes |
+| `start` | span | no |
+| `end` | span | no |
+| `scrub` | span (NumberFieldScrub) | no |
+| `stepper` | span | no |
+| `decrement` | button[type=button][tabindex=-1] | no |
+| `increment` | button[type=button][tabindex=-1] | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `value` | `number \| null` | — | NumberField | Makes the value controlled for the life of the component. null is empty, and empty is not zero: a required amount left blank and an amount of zero are different values. |
+| `defaultValue` | `number \| null` | — | NumberField | The value an uncontrolled number field starts from. It is read once, and a native form reset returns to it. |
+| `min` | `number` | — | NumberField | The smallest value. The decrement button is disabled at it, Home moves to it, and the snapToStep grid is counted from it. |
+| `max` | `number` | — | NumberField | The largest value. The increment button is disabled at it, and End moves to it. |
+| `step` | `number` | 1 | NumberField | What the arrow keys and the two buttons add or subtract. |
+| `largeStep` | `number` | step × 10 | NumberField | What Shift with an arrow, Page Up and Page Down add or subtract, so a wide range is crossed without holding a key. |
+| `smallStep` | `number` | step ÷ 10 | NumberField | What Alt with an arrow adds or subtracts. |
+| `stepFrom` | `number` | min, or 0 | NumberField | The value the first step produces when the number field is empty. |
+| `snapToStep` | `boolean` | false | NumberField | Steps to multiples of step counted from min, so with min 2 and step 3 the values are 2, 5, 8 and 11. A typed value moves to the nearest multiple when the number field commits. |
+| `clamp` | `'blur' \| 'strict' \| 'none'` | blur | NumberField, NumberFieldDefaultsProvider | What happens to a value outside min and max. blur returns it to the range when the number field commits, strict refuses the keystroke that would leave the range, and none keeps the value and sets aria-invalid and data-invalid while it is out of range. |
+| `format` | `Intl.NumberFormatOptions` | — | NumberField | How the value is written and read back. Currency, percent and unit are formats of one number, and precision is set with minimumFractionDigits and maximumFractionDigits. When the number field commits, the number is rounded to the precision the input shows. |
+| `formatOn` | `'change' \| 'commit'` | change | NumberField, NumberFieldDefaultsProvider | When the text takes the format. change regroups it on every keystroke; commit keeps the typed text until blur, Enter, a stepper press or an arrow key. Under both, the number changes on every keystroke that parses. |
+| `locale` | `string` | the locale of SlottedProvider, then en-US | NumberField | A BCP 47 tag. It sets the decimal separator, the grouping and the digits, for the text written and the text read back. |
+| `stepper` | `'stacked' \| 'split' \| 'none'` | stacked | NumberField, NumberFieldDefaultsProvider | Where the two buttons sit. split places them at either end of the frame, and its targets are at least 24 CSS pixels in both directions; none removes them. |
+| `wheel` | `boolean` | false | NumberField | Lets the mouse wheel step the value while the input has focus and the pointer is over it. It is off by default, so scrolling a form never changes an amount. |
+| `size` | `'sm' \| 'md' \| 'lg'` | md | NumberField, NumberFieldDefaultsProvider | The step of the control scale. When unset, the number field takes the size of its field, then of the provider. Height, padding, type and glyphs come from the control scale the theme sets per density. |
+| `variant` | `'outline' \| 'subtle' \| 'plain'` | outline | NumberField, NumberFieldDefaultsProvider | How much frame the number field draws. plain draws no border at rest and keeps the same box, for a dense table cell. |
+| `start` | `ReactNode` | — | NumberField | Content before the value in the reading direction. It is never selected, copied or parsed with the number. |
+| `end` | `ReactNode` | — | NumberField | Content after the value in the reading direction. |
+| `NumberFieldScrub sensitivity` | `number` | 2 | NumberFieldScrub | Pixels of horizontal drag per step. Use fewer pixels for a wide range and more for a fine one. |
+| `disabled` | `boolean` | from the field, or false | NumberField | Unset rather than false, so the number field follows the field around it. When set, it wins over the field and writes the native disabled, which removes the input from the tab order and from form submission. |
+| `readOnly` | `boolean` | from the field, or false | NumberField | Unset rather than false, so the number field follows the field around it. Writes the native readonly: the input stays focusable, selectable and submitted, and both buttons are disabled. |
+| `invalid` | `boolean` | from the field, or false | NumberField | Unset rather than false, so the number field follows the field around it. Writes aria-invalid on the input and data-invalid on the frame. |
+| `required` | `boolean` | — | NumberField | The element’s own attribute, passed through unchanged; NumberField never writes it. Inside a required field, the input receives aria-required instead, because the native attribute turns on the browser’s constraint validation. |
+| `name / form` | `string` | — | NumberField | Reach a hidden input beside the visible one, which submits the raw number: 1480, not "$1,480.00". |
+| `messages` | `Partial<NumberFieldMessages>` | — | NumberField | Replaces words of the active language, key by key: increment and decrement are the accessible names of the two buttons. |
+| `render` | `(props: NumberFieldRootProps) => ReactNode` | — | NumberField | Renders another element in place of the frame and passes it every attribute. The props are typed as HTMLAttributes<HTMLElement>, so they spread onto any element. The input and the two buttons cannot be replaced. |
+| `ref` | `Ref<HTMLInputElement>` | — | NumberField | Reaches the input element. focus(), select() and setSelectionRange() are the element’s own. |
+| `handle` | `Ref<NumberFieldHandle>` | — | NumberField | Reaches increment() and decrement(), for a shortcut or a button elsewhere on the page. Both move by one step within the bounds and report the reason programmatic. |
+| `className / style` | `string / CSSProperties` | — | NumberField | Reach the frame. Every other native prop reaches the input. |
+| `NumberFieldDefaultsProvider` | `{ size, variant, stepper, formatOn, clamp }` | — | a subtree | Sets size, variant, stepper, formatOn and clamp once for every number field under it. A number field that states a value keeps it. The locale comes from SlottedProvider, so every amount in the application is written and read the same way. |
+| `useField()` | `() => FieldContextValue \| undefined` | — | inside a Field | What the number field reads to wire itself: the id, the description and the four shared states. |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `onValueChange` | `(value: number \| null, request: ChangeRequest<number \| null>)` | Before the value changes. request.value is the new number and request.previous the number it replaces. request.reason is keyboard for typing, an arrow, a page key, Home, End or Enter; pointer for a stepper press, a wheel turn or a scrub; blur for the commit that formats, rounds and clamps on blur; programmatic for handle.increment() and handle.decrement(). request.source is the originating event, and request.cancel() refuses the change before it is applied. A request for the number NumberField already holds is not emitted. |
+| `onChange, onBlur, onKeyDown, onFocus` | `the element’s own events` | Whenever the input fires them. NumberField composes your handler with its own instead of replacing it: yours runs first and always runs, and calling preventDefault() on a key stops NumberField from acting on it. |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `size` | `sm`, `md`, `lg` | `md` |
+| `variant` | `outline`, `subtle`, `plain` | `outline` |
+| `stepper` | `stacked`, `split`, `none` | `stacked` |
+| `clamp` | `blur`, `strict`, `none` | `blur` |
+| `formatOn` | `change`, `commit` | `change` |
+
+## Rules
+
+- NumberField follows the WAI-ARIA APG Spinbutton pattern: role="spinbutton" on the input with aria-valuenow, aria-valuemin, aria-valuemax and aria-valuetext, ArrowUp and ArrowDown to step, Home and End to reach the bounds, and Page Up and Page Down for the larger step.
+- aria-valuetext carries the formatted text, so a screen reader announces "$1,480.00" rather than 1480. When the number field is empty, neither aria-valuenow nor aria-valuetext is set: no value is not the value zero.
+- The frame has no role. WAI-ARIA requires the children of a spinbutton to be non-interactive, so the two buttons are siblings of the input inside a box that announces nothing.
+- The buttons are out of the tab order, as the APG pattern recommends, and stay in the accessibility tree with translatable names and aria-controls pointing at the input. A form of twenty amounts keeps twenty tab stops instead of sixty. A button at a bound is disabled, so its name is still announced and its appearance shows why it does nothing.
+- Inside a required field the input receives aria-required, never the native required, which would turn on the browser’s constraint validation. disabled and readonly are the native attributes.
+- The input is type="text", and its inputMode comes from the props: numeric for a whole number at or above zero, decimal when the format allows a fraction, and text when min allows a negative, because neither numeric keypad offers a minus sign on every platform.
+- The mouse wheel is not bound unless wheel is set, and Escape is not bound at all, so scrolling a form never changes an amount.
+- The invalid state is never conveyed by color alone: aria-invalid announces it and the field’s error states it in words. In the high-contrast scheme the border does not carry it.
+
+## Tokens
+
+`--slotted-border-subtle`, `--slotted-control-border-color`, `--slotted-control-border-width`, `--slotted-control-font-family`, `--slotted-control-font-size-lg`, `--slotted-control-font-size-md`, `--slotted-control-font-size-sm`, `--slotted-control-gap-lg`, `--slotted-control-gap-md`, `--slotted-control-gap-sm`, `--slotted-control-height-lg`, `--slotted-control-height-md`, `--slotted-control-height-sm`, `--slotted-control-icon-size-lg`, `--slotted-control-icon-size-md`, `--slotted-control-icon-size-sm`, `--slotted-control-inner-size-lg`, `--slotted-control-inner-size-md`, `--slotted-control-inner-size-sm`, `--slotted-control-invalid-edge-width`, `--slotted-control-padding-inline-lg`, `--slotted-control-padding-inline-md`, `--slotted-control-padding-inline-sm`, `--slotted-control-radius`, `--slotted-control-shadow`, `--slotted-control-shadow-focus-geometry`, `--slotted-control-surface`, `--slotted-control-transition-duration`, `--slotted-control-transition-easing`, `--slotted-disabled-background`, `--slotted-disabled-border`, `--slotted-disabled-foreground`, `--slotted-focus-ring-color`, `--slotted-focus-ring-color-invalid`, `--slotted-focus-ring-offset`, `--slotted-focus-ring-width`, `--slotted-number-field-action-size`, `--slotted-number-field-adornment-color`, `--slotted-number-field-background`, `--slotted-number-field-border-color`, `--slotted-number-field-color`, `--slotted-number-field-disabled-background`, `--slotted-number-field-disabled-border-color`, `--slotted-number-field-disabled-color`, `--slotted-number-field-hover-border-color`, `--slotted-number-field-icon-size-min`, `--slotted-number-field-invalid-border-color`, `--slotted-number-field-invalid-edge-width`, `--slotted-number-field-invalid-focus-ring-color`, `--slotted-number-field-placeholder-color`, `--slotted-number-field-plain-hover-background`, `--slotted-number-field-radius`, `--slotted-number-field-readonly-background`, `--slotted-number-field-readonly-border-color`, `--slotted-number-field-scrub-active-color`, `--slotted-number-field-shadow`, `--slotted-number-field-stepper-active-background`, `--slotted-number-field-stepper-color`, `--slotted-number-field-stepper-disabled-background`, `--slotted-number-field-stepper-disabled-color`, `--slotted-number-field-stepper-hover-background`, `--slotted-number-field-stepper-size`, `--slotted-number-field-subtle-background`, `--slotted-number-field-subtle-border-color`, `--slotted-number-field-subtle-hover-background`, `--slotted-radius-none`, `--slotted-radius-xs`, `--slotted-space-1`, `--slotted-space-2`, `--slotted-surface-sunken`, `--slotted-target-comfortable`, `--slotted-target-min`, `--slotted-text`, `--slotted-text-muted`, `--slotted-tone-accent-border`, `--slotted-tone-danger-border`, `--slotted-tone-secondary-subtle-active`, `--slotted-tone-secondary-subtle-hover`
+
+## Examples
+
+See [number-field.examples.md](./number-field.examples.md).

package/dist/docs/otp-input.json

@@ -0,0 +1,477 @@
+{
+  "family": "otp-input",
+  "ui": "otp-input",
+  "binding": "react",
+  "catalog": {
+    "group": "Forms",
+    "summary": "One-time code split across several boxes."
+  },
+  "axes": {
+    "size": [
+      "sm",
+      "md",
+      "lg"
+    ],
+    "variant": [
+      "outline",
+      "subtle"
+    ],
+    "type": [
+      "numeric",
+      "alphanumeric"
+    ]
+  },
+  "members": {
+    "otpInput": {
+      "nativeElement": "input",
+      "defaults": {
+        "size": "md",
+        "variant": "outline",
+        "attached": false,
+        "length": 6,
+        "type": "numeric",
+        "placeholder": "",
+        "mask": false,
+        "autoSubmit": false,
+        "webOtp": false
+      },
+      "capabilities": [
+        "value",
+        "appearance",
+        "size",
+        "content",
+        "disabled",
+        "invalid",
+        "required",
+        "readOnly",
+        "wiring"
+      ],
+      "states": [
+        "default",
+        "hover",
+        "focus-visible",
+        "disabled",
+        "invalid",
+        "readonly",
+        "complete",
+        "current"
+      ],
+      "parts": [
+        "root",
+        "input",
+        "group",
+        "separator",
+        "slot"
+      ]
+    }
+  },
+  "docs": {
+    "otpInput": {
+      "imports": {
+        "source": "import { OtpInput, OtpInputDefaultsProvider } from '@slotted/react';"
+      },
+      "anatomy": [
+        {
+          "part": "root",
+          "element": "div, or the element render returns",
+          "required": true,
+          "purpose": "The frame around the boxes. Carries data-ui=\"otp-input\", the axes, and data-disabled, data-invalid, data-readonly and data-complete. It has no role: the control inside is the only thing announced. className and style reach this element, and a press anywhere on it puts the cursor in the box under the pointer."
+        },
+        {
+          "part": "input",
+          "element": "input",
+          "required": true,
+          "purpose": "The control. One real text input laid over the boxes, transparent: it holds the value, name, form, autocomplete=\"one-time-code\", the identifier the field’s label points at, and it is the one tab stop. ref reaches it. With mask it becomes type=\"password\"."
+        },
+        {
+          "part": "group",
+          "element": "div",
+          "required": true,
+          "purpose": "A row of boxes, one per entry of groups. Hidden from assistive technology. With attached, its boxes share one seam and keep a corner only at the ends."
+        },
+        {
+          "part": "separator",
+          "element": "div",
+          "required": false,
+          "purpose": "A short rule between two groups, drawn in CSS and never a character — a dash in the DOM would be read by nothing and mirrored by nothing."
+        },
+        {
+          "part": "slot",
+          "element": "div",
+          "required": true,
+          "purpose": "One box: the character at data-index, or a bullet under mask, or the placeholder while empty. data-current marks the box where the cursor or the selection is while the control has focus; the caret and the selection tint are drawn there."
+        }
+      ],
+      "api": [
+        {
+          "name": "value",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "OtpInput",
+          "description": "Present means the consumer owns the value, for the life of the component. Absent, the element owns it and a native form reset restores it"
+        },
+        {
+          "name": "defaultValue",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "OtpInput",
+          "description": "What an uncontrolled control starts from, read once, cut to what the code accepts, and written to the element as the native attribute"
+        },
+        {
+          "name": "length",
+          "type": "number",
+          "defaultValue": "6",
+          "appliesTo": "OtpInput, OtpInputDefaultsProvider",
+          "description": "How many characters the code has. It is the element’s maxlength and the number of boxes"
+        },
+        {
+          "name": "type",
+          "type": "'numeric' | 'alphanumeric'",
+          "defaultValue": "numeric",
+          "appliesTo": "OtpInput, OtpInputDefaultsProvider",
+          "description": "Which characters the code takes — digits, or ASCII letters and digits — and which keyboard a phone offers: inputMode numeric or text, unless the consumer states one"
+        },
+        {
+          "name": "pattern",
+          "type": "RegExp",
+          "defaultValue": "—",
+          "appliesTo": "OtpInput",
+          "description": "Tested against each character; outranks type in what is accepted and leaves the keyboard to it. Never the element’s whole-value attribute"
+        },
+        {
+          "name": "transform",
+          "type": "(text: string) => string",
+          "defaultValue": "—",
+          "appliesTo": "OtpInput",
+          "description": "Run over every edit before the filter — typing, paste, autofill — to strip a prefix or uppercase a code"
+        },
+        {
+          "name": "groups",
+          "type": "number[]",
+          "defaultValue": "[length]",
+          "appliesTo": "OtpInput",
+          "description": "How the boxes are partitioned, with a separator between two groups. The sum has to be length; a partition that does not add up draws one group"
+        },
+        {
+          "name": "attached",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "OtpInput, OtpInputDefaultsProvider",
+          "description": "Joins the boxes of a group along one seam, with a corner only at the ends"
+        },
+        {
+          "name": "placeholder",
+          "type": "string",
+          "defaultValue": "",
+          "appliesTo": "OtpInput, OtpInputDefaultsProvider",
+          "description": "What an empty box shows: one character repeats over every box, a string as long as the code distributes"
+        },
+        {
+          "name": "mask",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "OtpInput",
+          "description": "Makes the control type=\"password\" and paints a bullet per character. The platform treats the value as a secret"
+        },
+        {
+          "name": "size",
+          "type": "'sm' | 'md' | 'lg'",
+          "defaultValue": "md",
+          "appliesTo": "OtpInput, OtpInputDefaultsProvider",
+          "description": "The step the boxes sit at, read from the field first when there is one, then from the provider. The box is the control height at that step; the type is the text scale’s step of the same name"
+        },
+        {
+          "name": "variant",
+          "type": "'outline' | 'subtle'",
+          "defaultValue": "outline",
+          "appliesTo": "OtpInput, OtpInputDefaultsProvider",
+          "description": "How much frame each box shows. There is no plain: a code is never a cell"
+        },
+        {
+          "name": "autoSubmit",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "OtpInput",
+          "description": "Calls requestSubmit() on the owning form the moment the code is complete"
+        },
+        {
+          "name": "webOtp",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "OtpInput",
+          "description": "Asks the platform for the code from the SMS where the WebOTP API exists, and abandons the request when the form submits or the control unmounts. Opt-in, because the request opens a permission prompt"
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "defaultValue": "from the field, or false",
+          "appliesTo": "OtpInput",
+          "description": "Unstated rather than false, so the control defers to the field around it. Stated, it wins, and it is the native attribute"
+        },
+        {
+          "name": "readOnly",
+          "type": "boolean",
+          "defaultValue": "from the field, or false",
+          "appliesTo": "OtpInput",
+          "description": "Unstated rather than false. The native readonly, which stays focusable, selectable and submitted"
+        },
+        {
+          "name": "invalid",
+          "type": "boolean",
+          "defaultValue": "from the field, or false",
+          "appliesTo": "OtpInput",
+          "description": "Unstated rather than false. Writes aria-invalid on the control and data-invalid on the frame"
+        },
+        {
+          "name": "required",
+          "type": "boolean",
+          "defaultValue": "—",
+          "appliesTo": "OtpInput",
+          "description": "The element’s own attribute, passed straight through and never written by the family. A field marks necessity with aria-required instead, because the native attribute engages browser constraint validation"
+        },
+        {
+          "name": "autoComplete",
+          "type": "string",
+          "defaultValue": "one-time-code",
+          "appliesTo": "OtpInput",
+          "description": "The element’s own attribute, defaulting to the token that asks the keyboard for the code it just received"
+        }
+      ],
+      "composition": [
+        {
+          "name": "render",
+          "type": "(props: OtpInputRootProps) => ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "OtpInput",
+          "description": "Substitutes the frame and hands it every attribute. The boxes are fixed: they are paint over one input, and their geometry is what a press is mapped to"
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLInputElement>",
+          "defaultValue": "—",
+          "appliesTo": "OtpInput",
+          "description": "Reaches the input. focus(), select() and setSelectionRange() are the element’s own, so no imperative handle is invented for what the platform already ships"
+        },
+        {
+          "name": "className / style",
+          "type": "string / CSSProperties",
+          "defaultValue": "—",
+          "appliesTo": "OtpInput",
+          "description": "Reach the frame, because the frame is what a consumer sees. Every other native prop — name, form, autoFocus, inputMode, aria-* — reaches the input"
+        },
+        {
+          "name": "OtpInputDefaultsProvider",
+          "type": "{ size, variant, attached, length, type, placeholder }",
+          "defaultValue": "—",
+          "appliesTo": "a subtree",
+          "description": "The six decisions an application takes once. size is the one a field outranks, so a control inside a field takes the field’s step"
+        },
+        {
+          "name": "useField()",
+          "type": "() => FieldContextValue | undefined",
+          "defaultValue": "—",
+          "appliesTo": "inside a Field",
+          "description": "What the control reads to wire itself: the identifier, the description, and the four shared states"
+        }
+      ],
+      "events": [
+        {
+          "name": "onValueChange",
+          "payload": "(value: string, request: ChangeRequest<string>)",
+          "when": "Before the value moves. The request carries the new value, the value it replaces, the reason — \"keyboard\" for an edit made in the control, including a paste and the keyboard’s own autofill; \"programmatic\" for a code the WebOTP API delivered — the originating event, and cancel(), which refuses the move before anything commits."
+        },
+        {
+          "name": "onComplete",
+          "payload": "(value: string)",
+          "when": "The moment the value reaches length characters, once per value. A full code edited into another full code reports again; a code emptied and retyped reports again."
+        },
+        {
+          "name": "onRejected",
+          "payload": "(text: string, event: SyntheticEvent<HTMLInputElement>)",
+          "when": "Before the value moves, with every character an edit lost to type, pattern or length, in order. Nothing is emitted when an edit lost nothing."
+        },
+        {
+          "name": "onChange, onFocus, onBlur, onPaste",
+          "payload": "the element’s own events",
+          "when": "Whenever the element fires them. The family composes with a consumer’s handler rather than replacing it: the consumer’s runs first, and always runs."
+        }
+      ],
+      "accessibility": [
+        "There is no WAI-ARIA APG pattern for a verification code: the APG lists no such entry, so the control is the platform’s own textbox and the sources are the HTML specification for the element, the autocomplete attribute’s one-time-code token, and the WebOTP API.",
+        "One control, one tab stop, one accessible name, one value. Ark, Chakra and Mantine render one input per box and pay for it with N tab stops and no real label; here the boxes are aria-hidden paint over one input, so a screen reader hears \"Código de verificação, edit text, 482\" and nothing about boxes.",
+        "The control takes its name from the field’s label, through for pointing at the identifier the field derived, and its description and error through aria-describedby merged after anything the consumer wrote.",
+        "aria-required, never the native required: the native attribute engages browser constraint validation and changes submit behaviour. disabled and readonly are native, because that is what those two words mean.",
+        "Every key is the browser’s. The family binds nothing — no Escape, no arrow handling — and only normalises the selection after the fact, so a reader who knows a text field knows this one; WCAG 2.1.4 exists for the class of defect single-key shortcuts produce.",
+        "The focus ring sits on the box where the cursor is, in the theme’s ring colour, and the invalid state retargets that colour rather than repainting it. Invalid is never colour alone: aria-invalid announces it and the field’s error says it in words.",
+        "mask is a platform decision, not paint: the control becomes type=\"password\", so the screen reader counts the characters instead of reading a PIN aloud and the keyboard keeps nothing. The cost is that a password manager may offer to save it; autoComplete on the control decides."
+      ]
+    }
+  },
+  "tokens": [
+    "--slotted-border-subtle",
+    "--slotted-border-width-thick",
+    "--slotted-border-width-thin",
+    "--slotted-control-border-color",
+    "--slotted-control-border-width",
+    "--slotted-control-font-family",
+    "--slotted-control-gap-lg",
+    "--slotted-control-gap-md",
+    "--slotted-control-gap-sm",
+    "--slotted-control-height-lg",
+    "--slotted-control-height-md",
+    "--slotted-control-height-sm",
+    "--slotted-control-invalid-edge-width",
+    "--slotted-control-radius",
+    "--slotted-control-shadow",
+    "--slotted-control-shadow-focus-geometry",
+    "--slotted-control-surface",
+    "--slotted-control-transition-duration",
+    "--slotted-control-transition-easing",
+    "--slotted-disabled-background",
+    "--slotted-disabled-border",
+    "--slotted-disabled-foreground",
+    "--slotted-duration-loop",
+    "--slotted-focus-ring-color",
+    "--slotted-focus-ring-color-invalid",
+    "--slotted-focus-ring-offset",
+    "--slotted-focus-ring-width",
+    "--slotted-font-size-2xl",
+    "--slotted-font-size-lg",
+    "--slotted-font-size-md",
+    "--slotted-font-size-sm",
+    "--slotted-font-weight-medium",
+    "--slotted-otp-input-autofill-background",
+    "--slotted-otp-input-background",
+    "--slotted-otp-input-border-color",
+    "--slotted-otp-input-caret-width",
+    "--slotted-otp-input-color",
+    "--slotted-otp-input-current-border-color",
+    "--slotted-otp-input-disabled-background",
+    "--slotted-otp-input-disabled-border-color",
+    "--slotted-otp-input-disabled-color",
+    "--slotted-otp-input-font-weight",
+    "--slotted-otp-input-group-gap",
+    "--slotted-otp-input-hover-border-color",
+    "--slotted-otp-input-invalid-border-color",
+    "--slotted-otp-input-invalid-edge-width",
+    "--slotted-otp-input-invalid-focus-ring-color",
+    "--slotted-otp-input-mask-size",
+    "--slotted-otp-input-placeholder-color",
+    "--slotted-otp-input-radius",
+    "--slotted-otp-input-readonly-background",
+    "--slotted-otp-input-selection-background",
+    "--slotted-otp-input-separator-color",
+    "--slotted-otp-input-separator-size",
+    "--slotted-otp-input-shadow",
+    "--slotted-otp-input-subtle-background",
+    "--slotted-otp-input-subtle-border-color",
+    "--slotted-otp-input-subtle-hover-background",
+    "--slotted-radius-full",
+    "--slotted-space-4",
+    "--slotted-surface-sunken",
+    "--slotted-text",
+    "--slotted-text-muted",
+    "--slotted-tone-accent-border",
+    "--slotted-tone-accent-surface",
+    "--slotted-tone-danger-border",
+    "--slotted-tone-secondary-subtle-hover"
+  ],
+  "examples": [
+    {
+      "id": "playground",
+      "title": "Playground",
+      "note": "The second step of a sign-in, driven by the controls below the canvas. Type into it: the value is one string, the boxes paint it, and the sixth digit completes it.",
+      "language": "tsx",
+      "source": "<Field>\n  <FieldLabel>Código de verificação</FieldLabel>\n  <OtpInput name=\"code\" groups={[3, 3]} onComplete={verify} />\n  <FieldDescription>Enviámos um SMS para +55 11 9••••-4821.</FieldDescription>\n</Field>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "sizes",
+      "title": "The step the boxes sit at",
+      "note": "A box is a square on the control height of its step, so a code beside a text field in the same form sits on the same row. Inside a field the control takes the field’s step rather than its own.",
+      "language": "tsx",
+      "source": "<OtpInput size=\"sm\" length={4} />;\n<OtpInput size=\"md\" />;\n<OtpInput size=\"lg\" />;\n\n// Inside a field the field decides, and the control follows.\n<Field size=\"sm\">\n  <OtpInput />\n</Field>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "variants",
+      "title": "How much frame each box shows",
+      "note": "outline takes the ground it is placed on; subtle sinks into the page. The same two steps text-field draws, with the same tokens, so a code under a text field in one form is one form.",
+      "language": "tsx",
+      "source": "<OtpInput variant=\"outline\" />;\n<OtpInput variant=\"subtle\" />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "groups",
+      "title": "Groups, separators and joined boxes",
+      "note": "groups partitions the boxes the way the SMS is written — 482-915 — and attached joins the boxes of a group along one seam, which is how a PIN pad reads.",
+      "language": "tsx",
+      "source": "// The sum has to be length; a partition that does not add up draws one group.\n<OtpInput groups={[3, 3]} />;\n<OtpInput groups={[4, 4]} length={8} type=\"alphanumeric\" attached />;\n<OtpInput length={4} attached />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "types",
+      "title": "What the code accepts",
+      "note": "type decides the characters and the keyboard a phone offers; pattern outranks it per character; transform runs over every edit before the filter. What an edit loses is reported, so the page can say why nothing appeared.",
+      "language": "tsx",
+      "source": "<OtpInput type=\"numeric\" />;\n<OtpInput type=\"alphanumeric\" length={8} />;\n\n// A backup code is printed in uppercase with a prefix nobody types.\n<OtpInput\n  type=\"alphanumeric\"\n  length={8}\n  transform={(text) => text.replace(/^G-/i, '').toUpperCase()}\n  onRejected={(text) => setHint(`\"${text}\" não faz parte do código`)}\n/>;\n\n// Only the characters a hexadecimal code has.\n<OtpInput pattern={/[0-9a-f]/i} />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "mask",
+      "title": "A code nobody should read over your shoulder",
+      "note": "mask makes the control type=\"password\": the platform treats the value as a secret — the screen reader counts characters instead of reading them — and each filled box shows a bullet.",
+      "language": "tsx",
+      "source": "<Field>\n  <FieldLabel>PIN de autorização</FieldLabel>\n  <OtpInput length={4} mask attached autoComplete=\"off\" />\n</Field>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "states",
+      "title": "The four states the frame paints",
+      "note": "Invalid keeps its danger edge on every box while the ring says where the cursor is; read-only keeps full-strength ink and only its ground changes; disabled is muted to a measured colour rather than faded, so a disabled form still says what it holds.",
+      "language": "tsx",
+      "source": "// Unstated rather than false, so the control defers to its field.\n<OtpInput invalid defaultValue=\"482910\" />;\n<OtpInput readOnly defaultValue=\"482915\" />;\n<OtpInput disabled defaultValue=\"48\" />;\n\n// A control inside a disabled fieldset is painted too, because the\n// stylesheet matches :disabled beside the attribute.\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "complete",
+      "title": "The sixth digit",
+      "note": "onComplete fires the moment the value reaches length, once per value; autoSubmit calls requestSubmit() on the owning form in the same moment. A code edited into another full code reports again.",
+      "language": "tsx",
+      "source": "<form action={verify}>\n  <OtpInput name=\"code\" autoSubmit />\n</form>;\n\n// Or hold the value and react to it.\n<OtpInput value={code} onValueChange={setCode} onComplete={verify} />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "content",
+      "title": "Content the family did not choose",
+      "note": "A value longer than the code is cut; a paste with hyphens and spaces keeps its digits; in a right-to-left page the boxes stay left-to-right, because a code is a number and a number does not mirror; and at 240 pixels the boxes give up width before the row overflows.",
+      "language": "tsx",
+      "source": "// \"12-3456789\" becomes \"123456\".\n<OtpInput defaultValue=\"12-3456789\" />;\n\n// Paste \"482-915\": the hyphen is dropped and reported, the digits land.\n<OtpInput onRejected={(text) => console.log(text)} />;\n\n// The row is left-to-right whatever the page does.\n<div dir=\"rtl\">\n  <OtpInput groups={[3, 3]} />\n</div>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "form",
+      "title": "One entry in FormData",
+      "note": "The control is one native input, so name and form work as they do on any input, a native reset restores defaultValue, and where the WebOTP API exists the code arrives from the SMS with reason \"programmatic\".",
+      "language": "tsx",
+      "source": "<form onSubmit={submit}>\n  <OtpInput name=\"code\" webOtp />\n  <Button type=\"submit\">Confirmar</Button>\n  <Button type=\"reset\" variant=\"ghost\">\n    Limpar\n  </Button>\n</form>;\n\n// new FormData(form).get('code') === '482915'\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "composition",
+      "title": "In a field, with a resend",
+      "note": "The field names the control, describes it and carries its error; the resend is a button and a countdown the page owns, because the family has no clock. The provider sets the length once for an application whose codes are all four digits.",
+      "language": "tsx",
+      "source": "<Field invalid={error !== null}>\n  <FieldLabel>Código de verificação</FieldLabel>\n  <OtpInput name=\"code\" groups={[3, 3]} onComplete={verify} />\n  <FieldDescription>Enviámos um SMS para +55 11 9••••-4821.</FieldDescription>\n  <FieldError>{error}</FieldError>\n</Field>;\n<Button variant=\"ghost\" disabled={seconds > 0} onClick={resend}>\n  {seconds > 0 ? `Reenviar em 0:${pad(seconds)}` : 'Reenviar código'}\n</Button>;\n\n// Every code in this application is four digits.\n<OtpInputDefaultsProvider length={4} attached>\n  <App />\n</OtpInputDefaultsProvider>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "keyboard",
+      "title": "One tab stop, every key the browser’s",
+      "note": "Tab lands on one control. Arrows move the cursor across the boxes, Backspace and Delete edit, Shift+arrows select a range, Ctrl+A selects all, and typing on a full code replaces the selected character instead of being refused.",
+      "language": "tsx",
+      "source": "// Inside the value there is always one character selected: the one in\n// front of a collapsed cursor, the last one at the end of a full code. The\n// next key replaces it. A cursor after the last character inserts.\n<OtpInput defaultValue=\"482915\" />;\n",
+      "verdict": "excerpt"
+    }
+  ]
+}