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

package/docs/number-field.md

@@ -0,0 +1,137 @@
+<!-- index: ./index.md -->
+# number-field
+
+`data-ui="number-field"` · Number input with steppers and formatting.
+
+## Import
+
+```ts
+import {
+  provideNumberFieldDefaults,
+  SlNumberField,
+  SlNumberFieldEnd,
+  SlNumberFieldInput,
+  SlNumberFieldScrub,
+  SlNumberFieldStart,
+} from '@slotted/angular/number-field';
+```
+
+Selector: `[slNumberField]` · exportAs: `slNumberField`
+
+## Minimal example
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';
+import { SlNumberField, SlNumberFieldEnd, SlNumberFieldInput } from '@slotted/angular/number-field';
+
+@Component({
+  selector: 'app-number-field-basic',
+  imports: [
+    SlField,
+    SlFieldDescription,
+    SlFieldLabel,
+    SlNumberField,
+    SlNumberFieldEnd,
+    SlNumberFieldInput,
+  ],
+  template: `
+    <div slField required>
+      <label slFieldLabel>Reorder point</label>
+      <div slNumberField>
+        <input slNumberFieldInput defaultValue="25" min="0" max="500" step="5" />
+        <span slNumberFieldEnd>units</span>
+      </div>
+      <span slFieldDescription>Chai is reordered when stock falls to this level.</span>
+    </div>
+  `,
+})
+export class NumberFieldBasic {}
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | the element carrying slNumberField | yes |
+| `input` | input[slNumberFieldInput], as text with role="spinbutton" | yes |
+| `start` | any element carrying slNumberFieldStart | no |
+| `end` | any element carrying slNumberFieldEnd | no |
+| `scrub` | any element carrying slNumberFieldScrub, inside an adornment | no |
+| `stepper` | span, rendered by the frame | no |
+| `decrement` | button[type=button][tabindex=-1], rendered by the frame | no |
+| `increment` | button[type=button][tabindex=-1], rendered by the frame | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `value` | `number \| null` | — | input[slNumberFieldInput] | 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` | — | input[slNumberFieldInput] | The value an uncontrolled number field starts from. It is read once, in ngOnInit, because Angular binds inputs after it creates the directives. |
+| `min` | `number` | — | input[slNumberFieldInput] | The smallest value. The decrement button is disabled at it, Home moves to it, and the snapToStep grid is counted from it. |
+| `max` | `number` | — | input[slNumberFieldInput] | The largest value. The increment button is disabled at it, and End moves to it. |
+| `step` | `number` | 1 | input[slNumberFieldInput] | What the arrow keys and the two buttons add or subtract. |
+| `largeStep` | `number` | step × 10 | input[slNumberFieldInput] | 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 | input[slNumberFieldInput] | What Alt with an arrow adds or subtracts. |
+| `stepFrom` | `number` | min, or 0 | input[slNumberFieldInput] | The value the first step produces when the number field is empty. |
+| `snapToStep` | `boolean` | false | input[slNumberFieldInput] | 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 | input[slNumberFieldInput], provideNumberFieldDefaults | 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` | — | input[slNumberFieldInput] | 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 | input[slNumberFieldInput], provideNumberFieldDefaults | 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 provideSlotted, then en-US | input[slNumberFieldInput] | 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 | [slNumberField], provideNumberFieldDefaults | 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 | input[slNumberFieldInput] | 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 | [slNumberField], provideNumberFieldDefaults | The step of the control scale. When unset, the number field takes the size of its field, then of provideNumberFieldDefaults. Height, padding, type and glyphs come from the control scale the theme sets per density. |
+| `variant` | `'outline' \| 'subtle' \| 'plain'` | outline | [slNumberField], provideNumberFieldDefaults | How much frame the number field draws. plain draws no border at rest and keeps the same box, for a dense table cell. |
+| `start` | `slNumberFieldStart` | — | any projected element | Content before the value in the reading direction. It is never selected, copied or parsed with the number. |
+| `end` | `slNumberFieldEnd` | — | any projected element | Content after the value in the reading direction. |
+| `sensitivity` | `number` | 2 | slNumberFieldScrub | 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 | input[slNumberFieldInput] | 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. A disabled form control sets it too. |
+| `readOnly` | `boolean` | from the field, or false | input[slNumberFieldInput] | 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 | input[slNumberFieldInput] | 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` | — | input[slNumberFieldInput] | The element’s own attribute, written only by you. Inside a required field, the input receives aria-required instead, because the native attribute turns on the browser’s constraint validation. |
+| `name / form` | `string` | — | input[slNumberFieldInput] | Read as static attributes and moved to a hidden input beside the visible one, which submits the raw number: 1480, not "$1,480.00". |
+| `messages` | `Partial<NumberFieldMessages>` | — | [slNumberField] | Replaces words of the active language, key by key: increment and decrement are the accessible names of the two buttons. |
+| `exportAs` | `'slNumberField' / 'slNumberFieldInput'` | — | both directives | Hands the directive instance to the template. The input’s instance exposes inputElement, which has focus(), select() and setSelectionRange(), and increment() and decrement(), which move by one step within the bounds and report the reason programmatic. |
+| `ControlValueAccessor` | `NG_VALUE_ACCESSOR` | — | input[slNumberFieldInput] | Binds the input to a reactive or template-driven form, which receives the number rather than the formatted text. The directive provides no validator: min and max are reported through aria-invalid only under clamp="none", and when an error is shown is the form’s decision. |
+| `ng-content` | `[slNumberFieldStart], [slNumberFieldEnd], the input` | — | [slNumberField] | Projects your own elements into three slots, so a span, an icon or a kbd keeps its own semantics. The frame is a directive on your own element. |
+| `provideNumberFieldDefaults` | `{ size, variant, stepper, formatOn, clamp }` | — | an injector | Sets size, variant, stepper, formatOn and clamp once for every number field under the injector. A number field that states a value keeps it. The locale comes from provideSlotted, so every amount in the application is written and read the same way. |
+| `HostAttributeToken` | `id, name, form, inputmode, aria-describedby, aria-invalid, aria-required, readonly` | — | input[slNumberFieldInput] | Each is read before the host bindings run, so a static attribute you write is never overwritten. |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `(valueChange)` | `ChangeRequest<number \| null>` | Before the value changes. value is the new number and previous the number it replaces. 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 increment() and decrement(). source is the originating event, and cancel() refuses the change before it is applied. There is no [(value)], because a two-way binding carries only the value, without the reason or cancel(). |
+| `ControlValueAccessor` | `writeValue, registerOnChange, registerOnTouched, setDisabledState` | Whenever a reactive or template-driven form reads or writes the input. The form receives the number, never the formatted text, and a disabled form control disables the input and both buttons. |
+| `the element’s own events` | `(input), (keydown), (blur), (focus)` | Whenever the input fires them. Your listener runs alongside the directive’s, and calling preventDefault() on a key stops the directive 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
+
+- SlNumberField 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 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 inputs: 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.
+
+## 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/docs/otp-input.json

@@ -0,0 +1,479 @@
+{
+  "family": "otp-input",
+  "ui": "otp-input",
+  "binding": "angular",
+  "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 {\n  provideOtpInputDefaults,\n  SlOtpInput,\n  SlOtpInputControl,\n} from '@slotted/angular/otp-input';",
+        "selector": "[slOtpInput]",
+        "exportAs": "slOtpInput"
+      },
+      "anatomy": [
+        {
+          "part": "root",
+          "element": "the element carrying slOtpInput",
+          "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. A press anywhere on it puts the cursor in the box under the pointer."
+        },
+        {
+          "part": "input",
+          "element": "input[slOtpInputControl]",
+          "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. It is the ControlValueAccessor, so it belongs in a reactive form as it stands. With the frame’s mask it becomes type=\"password\"."
+        },
+        {
+          "part": "group",
+          "element": "div, drawn by the frame",
+          "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, drawn by the frame",
+          "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, drawn by the frame",
+          "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": "slOtpInputControl",
+          "description": "Present means the consumer owns the value. It is written into the element the way a form writes it; a form uses formControl instead"
+        },
+        {
+          "name": "defaultValue",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "slOtpInputControl",
+          "description": "What the control starts from when nobody else writes one, read once and cut to what the code accepts"
+        },
+        {
+          "name": "length",
+          "type": "number",
+          "defaultValue": "6",
+          "appliesTo": "slOtpInput, provideOtpInputDefaults",
+          "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": "slOtpInputControl, provideOtpInputDefaults",
+          "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 wrote one"
+        },
+        {
+          "name": "pattern",
+          "type": "RegExp",
+          "defaultValue": "—",
+          "appliesTo": "slOtpInputControl",
+          "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": "slOtpInputControl",
+          "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": "slOtpInput",
+          "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": "slOtpInput, provideOtpInputDefaults",
+          "description": "Joins the boxes of a group along one seam, with a corner only at the ends"
+        },
+        {
+          "name": "placeholder",
+          "type": "string",
+          "defaultValue": "",
+          "appliesTo": "slOtpInput, provideOtpInputDefaults",
+          "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": "slOtpInput",
+          "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": "slOtpInput, provideOtpInputDefaults",
+          "description": "The step the boxes sit at, read from the field first when there is one, then from the token. 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": "slOtpInput, provideOtpInputDefaults",
+          "description": "How much frame each box shows. There is no plain: a code is never a cell"
+        },
+        {
+          "name": "autoSubmit",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "slOtpInputControl",
+          "description": "Calls requestSubmit() on the owning form the moment the code is complete"
+        },
+        {
+          "name": "webOtp",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "slOtpInputControl",
+          "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 directive is destroyed. Opt-in, because the request opens a permission prompt"
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "defaultValue": "from the form, the field, or false",
+          "appliesTo": "slOtpInputControl",
+          "description": "Unstated rather than false, so the control defers to the form’s setDisabledState and then to the field. Stated, it wins, and it is the native attribute"
+        },
+        {
+          "name": "readOnly",
+          "type": "boolean",
+          "defaultValue": "from the field, or false",
+          "appliesTo": "slOtpInputControl",
+          "description": "Unstated rather than false. The native readonly, which stays focusable, selectable and submitted; a readonly attribute the consumer wrote is honoured"
+        },
+        {
+          "name": "invalid",
+          "type": "boolean",
+          "defaultValue": "from the field, or false",
+          "appliesTo": "slOtpInputControl",
+          "description": "Unstated rather than false. Writes aria-invalid on the control and data-invalid on the frame"
+        },
+        {
+          "name": "required",
+          "type": "boolean",
+          "defaultValue": "—",
+          "appliesTo": "slOtpInputControl",
+          "description": "The element’s own attribute, left where the consumer wrote it 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": "slOtpInputControl",
+          "description": "The element’s own attribute, read before the host binding computes; unwritten, the token that asks the keyboard for the code it just received"
+        }
+      ],
+      "composition": [
+        {
+          "name": "[slOtpInput]",
+          "type": "attribute selector",
+          "defaultValue": "—",
+          "appliesTo": "the consumer’s element",
+          "description": "The frame is the consumer’s own element rather than one the family creates, so a div, a fieldset or a label can carry it. The boxes are drawn by its template and are not projectable: they are paint over one input, and their geometry is what a press is mapped to"
+        },
+        {
+          "name": "input[slOtpInputControl]",
+          "type": "attribute selector",
+          "defaultValue": "—",
+          "appliesTo": "the consumer’s input",
+          "description": "The control is the consumer’s own input, so every native attribute is written where it belongs and read before the host bindings compute. It injects the frame without optional: an input written outside one fails at construction"
+        },
+        {
+          "name": "exportAs",
+          "type": "'slOtpInput' / 'slOtpInputControl'",
+          "defaultValue": "—",
+          "appliesTo": "a template",
+          "description": "The frame’s resolved step, variant and complete state, and the control’s code, selection and inputElement, for a template that reaches either"
+        },
+        {
+          "name": "provideOtpInputDefaults",
+          "type": "{ size, variant, attached, length, type, placeholder }",
+          "defaultValue": "—",
+          "appliesTo": "an injector",
+          "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": "SlOtpInputState",
+          "type": "abstract class",
+          "defaultValue": "—",
+          "appliesTo": "a frame of your own",
+          "description": "What the frame reads from the control: code, selection, focused, the three resolved states, and pressAt(). Provided by the control, so a frame that draws its own boxes can query for it"
+        }
+      ],
+      "events": [
+        {
+          "name": "(valueChange)",
+          "payload": "ChangeRequest<string>",
+          "when": "Before the value moves, on slOtpInputControl. 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": "(complete)",
+          "payload": "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": "(rejected)",
+          "payload": "{ text: string; source: Event }",
+          "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": "ControlValueAccessor",
+          "payload": "the form’s own value and touched state",
+          "when": "Whenever the value moves and the request was not cancelled, and on blur for touched. It is the two-way binding the ecosystem expects, and the reason there is no [(value)]: a two-way binding has one slot and can carry neither a reason nor cancel()."
+        }
+      ],
+      "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, and a form’s setDisabledState reaches the same attribute.",
+        "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; the autocomplete the consumer wrote 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": "html",
+      "source": "<div slField>\n  <label slFieldLabel>Código de verificação</label>\n  <div slOtpInput [groups]=\"[3, 3]\">\n    <input slOtpInputControl name=\"code\" (complete)=\"verify($event)\" />\n  </div>\n  <span slFieldDescription>Enviámos um SMS para +55 11 9••••-4821.</span>\n</div>\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": "html",
+      "source": "<div slOtpInput size=\"sm\" length=\"4\"><input slOtpInputControl /></div>\n<div slOtpInput size=\"md\"><input slOtpInputControl /></div>\n<div slOtpInput size=\"lg\"><input slOtpInputControl /></div>\n\n<!-- Inside a field the field decides, and the control follows. -->\n<div slField size=\"sm\">\n  <div slOtpInput><input slOtpInputControl /></div>\n</div>\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": "html",
+      "source": "<div slOtpInput variant=\"outline\"><input slOtpInputControl /></div>\n<div slOtpInput variant=\"subtle\"><input slOtpInputControl /></div>\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": "html",
+      "source": "<!-- The sum has to be length; a partition that does not add up draws one group. -->\n<div slOtpInput [groups]=\"[3, 3]\"><input slOtpInputControl /></div>\n<div slOtpInput [groups]=\"[4, 4]\" length=\"8\" attached>\n  <input slOtpInputControl type=\"alphanumeric\" />\n</div>\n<div slOtpInput length=\"4\" attached><input slOtpInputControl /></div>\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": "html",
+      "source": "<div slOtpInput><input slOtpInputControl type=\"numeric\" /></div>\n<div slOtpInput length=\"8\"><input slOtpInputControl type=\"alphanumeric\" /></div>\n\n<!-- A backup code is printed in uppercase with a prefix nobody types. -->\n<div slOtpInput length=\"8\">\n  <input\n    slOtpInputControl\n    type=\"alphanumeric\"\n    [transform]=\"stripPrefix\"\n    (rejected)=\"hint = $event.text + ' não faz parte do código'\"\n  />\n</div>\n\n<!-- Only the characters a hexadecimal code has. -->\n<div slOtpInput><input slOtpInputControl [pattern]=\"hex\" /></div>\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": "html",
+      "source": "<div slField>\n  <label slFieldLabel>PIN de autorização</label>\n  <div slOtpInput length=\"4\" mask attached>\n    <input slOtpInputControl autocomplete=\"off\" />\n  </div>\n</div>\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": "html",
+      "source": "<!-- Unstated rather than false, so the control defers to its field. -->\n<div slOtpInput><input slOtpInputControl invalid defaultValue=\"482910\" /></div>\n<div slOtpInput><input slOtpInputControl readOnly defaultValue=\"482915\" /></div>\n<div slOtpInput><input slOtpInputControl disabled defaultValue=\"48\" /></div>\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": "(complete) 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": "html",
+      "source": "<form (ngSubmit)=\"verify()\">\n  <div slOtpInput><input slOtpInputControl name=\"code\" autoSubmit /></div>\n</form>\n\n<!-- Or hold the value and react to it. -->\n<div slOtpInput>\n  <input slOtpInputControl [formControl]=\"code\" (complete)=\"verify($event)\" />\n</div>\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": "html",
+      "source": "<!-- \"12-3456789\" becomes \"123456\". -->\n<div slOtpInput><input slOtpInputControl defaultValue=\"12-3456789\" /></div>\n\n<!-- Paste \"482-915\": the hyphen is dropped and reported, the digits land. -->\n<div slOtpInput><input slOtpInputControl (rejected)=\"log($event.text)\" /></div>\n\n<!-- The row is left-to-right whatever the page does. -->\n<div dir=\"rtl\">\n  <div slOtpInput [groups]=\"[3, 3]\"><input slOtpInputControl /></div>\n</div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "form",
+      "title": "One control in a reactive form",
+      "note": "slOtpInputControl is the ControlValueAccessor: a FormControl writes it, a disabled control disables it, blur marks it touched, and validators see one string. name still works for a native form, and where the WebOTP API exists the code arrives from the SMS with reason \"programmatic\".",
+      "language": "html",
+      "source": "<form [formGroup]=\"form\" (ngSubmit)=\"submit()\">\n  <div slOtpInput [groups]=\"[3, 3]\">\n    <input slOtpInputControl formControlName=\"code\" webOtp />\n  </div>\n  <button slButton type=\"submit\">Confirmar</button>\n</form>\n\n<!-- form = new FormGroup({ code: new FormControl('', [Validators.minLength(6)]) }) -->\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. provideOtpInputDefaults sets the length once for an application whose codes are all four digits.",
+      "language": "html",
+      "source": "<div slField [invalid]=\"error() !== null\">\n  <label slFieldLabel>Código de verificação</label>\n  <div slOtpInput [groups]=\"[3, 3]\">\n    <input slOtpInputControl name=\"code\" (complete)=\"verify($event)\" />\n  </div>\n  <span slFieldDescription>Enviámos um SMS para +55 11 9••••-4821.</span>\n  <span slFieldError>{{ error() }}</span>\n</div>\n<button slButton variant=\"ghost\" [disabled]=\"seconds() > 0\" (click)=\"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     providers: [provideOtpInputDefaults({ length: 4, attached: true })] -->\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": "html",
+      "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<div slOtpInput [groups]=\"[3, 3]\">\n  <input slOtpInputControl defaultValue=\"482915\" />\n</div>\n",
+      "verdict": "excerpt"
+    }
+  ]
+}