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

package/docs/otp-input.md

@@ -0,0 +1,291 @@
+<!-- index: ./index.md -->
+# otp-input
+
+`data-ui="otp-input"` · One-time code split across several boxes.
+
+## Import
+
+```ts
+import {
+  provideOtpInputDefaults,
+  SlOtpInput,
+  SlOtpInputControl,
+} from '@slotted/angular/otp-input';
+```
+
+Selector: `[slOtpInput]` · exportAs: `slOtpInput`
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```html
+<div slField>
+  <label slFieldLabel>Código de verificação</label>
+  <div slOtpInput [groups]="[3, 3]">
+    <input slOtpInputControl name="code" (complete)="verify($event)" />
+  </div>
+  <span slFieldDescription>Enviámos um SMS para +55 11 9••••-4821.</span>
+</div>
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | the element carrying slOtpInput | yes |
+| `input` | input[slOtpInputControl] | yes |
+| `group` | div, drawn by the frame | yes |
+| `separator` | div, drawn by the frame | no |
+| `slot` | div, drawn by the frame | yes |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `value` | `string` | — | slOtpInputControl | Present means the consumer owns the value. It is written into the element the way a form writes it; a form uses formControl instead |
+| `defaultValue` | `string` | — | slOtpInputControl | What the control starts from when nobody else writes one, read once and cut to what the code accepts |
+| `length` | `number` | 6 | slOtpInput, provideOtpInputDefaults | How many characters the code has. It is the element’s maxlength and the number of boxes |
+| `type` | `'numeric' \| 'alphanumeric'` | numeric | slOtpInputControl, provideOtpInputDefaults | 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 |
+| `pattern` | `RegExp` | — | slOtpInputControl | Tested against each character; outranks type in what is accepted and leaves the keyboard to it. Never the element’s whole-value attribute |
+| `transform` | `(text: string) => string` | — | slOtpInputControl | Run over every edit before the filter — typing, paste, autofill — to strip a prefix or uppercase a code |
+| `groups` | `number[]` | [length] | slOtpInput | 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 |
+| `attached` | `boolean` | false | slOtpInput, provideOtpInputDefaults | Joins the boxes of a group along one seam, with a corner only at the ends |
+| `placeholder` | `string` |  | slOtpInput, provideOtpInputDefaults | What an empty box shows: one character repeats over every box, a string as long as the code distributes |
+| `mask` | `boolean` | false | slOtpInput | Makes the control type="password" and paints a bullet per character. The platform treats the value as a secret |
+| `size` | `'sm' \| 'md' \| 'lg'` | md | slOtpInput, provideOtpInputDefaults | 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 |
+| `variant` | `'outline' \| 'subtle'` | outline | slOtpInput, provideOtpInputDefaults | How much frame each box shows. There is no plain: a code is never a cell |
+| `autoSubmit` | `boolean` | false | slOtpInputControl | Calls requestSubmit() on the owning form the moment the code is complete |
+| `webOtp` | `boolean` | false | slOtpInputControl | 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 |
+| `disabled` | `boolean` | from the form, the field, or false | slOtpInputControl | 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 |
+| `readOnly` | `boolean` | from the field, or false | slOtpInputControl | Unstated rather than false. The native readonly, which stays focusable, selectable and submitted; a readonly attribute the consumer wrote is honoured |
+| `invalid` | `boolean` | from the field, or false | slOtpInputControl | Unstated rather than false. Writes aria-invalid on the control and data-invalid on the frame |
+| `required` | `boolean` | — | slOtpInputControl | 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 |
+| `autocomplete` | `string` | one-time-code | slOtpInputControl | The element’s own attribute, read before the host binding computes; unwritten, the token that asks the keyboard for the code it just received |
+| `[slOtpInput]` | `attribute selector` | — | the consumer’s element | 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 |
+| `input[slOtpInputControl]` | `attribute selector` | — | the consumer’s input | 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 |
+| `exportAs` | `'slOtpInput' / 'slOtpInputControl'` | — | a template | The frame’s resolved step, variant and complete state, and the control’s code, selection and inputElement, for a template that reaches either |
+| `provideOtpInputDefaults` | `{ size, variant, attached, length, type, placeholder }` | — | an injector | 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 |
+| `SlOtpInputState` | `abstract class` | — | a frame of your own | 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 | Payload | When |
+| --- | --- | --- |
+| `(valueChange)` | `ChangeRequest<string>` | 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. |
+| `(complete)` | `string` | 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. |
+| `(rejected)` | `{ text: string; source: Event }` | 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. |
+| `ControlValueAccessor` | `the form’s own value and touched state` | 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(). |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `size` | `sm`, `md`, `lg` | `md` |
+| `variant` | `outline`, `subtle` | `outline` |
+| `type` | `numeric`, `alphanumeric` | `numeric` |
+
+## Rules
+
+- 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
+
+### The step the boxes sit at
+
+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.
+
+Excerpt — not a complete module
+
+```html
+<div slOtpInput size="sm" length="4"><input slOtpInputControl /></div>
+<div slOtpInput size="md"><input slOtpInputControl /></div>
+<div slOtpInput size="lg"><input slOtpInputControl /></div>
+
+<!-- Inside a field the field decides, and the control follows. -->
+<div slField size="sm">
+  <div slOtpInput><input slOtpInputControl /></div>
+</div>
+```
+
+### How much frame each box shows
+
+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.
+
+Excerpt — not a complete module
+
+```html
+<div slOtpInput variant="outline"><input slOtpInputControl /></div>
+<div slOtpInput variant="subtle"><input slOtpInputControl /></div>
+```
+
+### Groups, separators and joined boxes
+
+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.
+
+Excerpt — not a complete module
+
+```html
+<!-- The sum has to be length; a partition that does not add up draws one group. -->
+<div slOtpInput [groups]="[3, 3]"><input slOtpInputControl /></div>
+<div slOtpInput [groups]="[4, 4]" length="8" attached>
+  <input slOtpInputControl type="alphanumeric" />
+</div>
+<div slOtpInput length="4" attached><input slOtpInputControl /></div>
+```
+
+### What the code accepts
+
+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.
+
+Excerpt — not a complete module
+
+```html
+<div slOtpInput><input slOtpInputControl type="numeric" /></div>
+<div slOtpInput length="8"><input slOtpInputControl type="alphanumeric" /></div>
+
+<!-- A backup code is printed in uppercase with a prefix nobody types. -->
+<div slOtpInput length="8">
+  <input
+    slOtpInputControl
+    type="alphanumeric"
+    [transform]="stripPrefix"
+    (rejected)="hint = $event.text + ' não faz parte do código'"
+  />
+</div>
+
+<!-- Only the characters a hexadecimal code has. -->
+<div slOtpInput><input slOtpInputControl [pattern]="hex" /></div>
+```
+
+### A code nobody should read over your shoulder
+
+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.
+
+Excerpt — not a complete module
+
+```html
+<div slField>
+  <label slFieldLabel>PIN de autorização</label>
+  <div slOtpInput length="4" mask attached>
+    <input slOtpInputControl autocomplete="off" />
+  </div>
+</div>
+```
+
+### The four states the frame paints
+
+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.
+
+Excerpt — not a complete module
+
+```html
+<!-- Unstated rather than false, so the control defers to its field. -->
+<div slOtpInput><input slOtpInputControl invalid defaultValue="482910" /></div>
+<div slOtpInput><input slOtpInputControl readOnly defaultValue="482915" /></div>
+<div slOtpInput><input slOtpInputControl disabled defaultValue="48" /></div>
+
+<!-- A control inside a disabled fieldset is painted too, because the
+     stylesheet matches :disabled beside the attribute. -->
+```
+
+### The sixth digit
+
+(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.
+
+Excerpt — not a complete module
+
+```html
+<form (ngSubmit)="verify()">
+  <div slOtpInput><input slOtpInputControl name="code" autoSubmit /></div>
+</form>
+
+<!-- Or hold the value and react to it. -->
+<div slOtpInput>
+  <input slOtpInputControl [formControl]="code" (complete)="verify($event)" />
+</div>
+```
+
+### Content the family did not choose
+
+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.
+
+Excerpt — not a complete module
+
+```html
+<!-- "12-3456789" becomes "123456". -->
+<div slOtpInput><input slOtpInputControl defaultValue="12-3456789" /></div>
+
+<!-- Paste "482-915": the hyphen is dropped and reported, the digits land. -->
+<div slOtpInput><input slOtpInputControl (rejected)="log($event.text)" /></div>
+
+<!-- The row is left-to-right whatever the page does. -->
+<div dir="rtl">
+  <div slOtpInput [groups]="[3, 3]"><input slOtpInputControl /></div>
+</div>
+```
+
+### One control in a reactive form
+
+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".
+
+Excerpt — not a complete module
+
+```html
+<form [formGroup]="form" (ngSubmit)="submit()">
+  <div slOtpInput [groups]="[3, 3]">
+    <input slOtpInputControl formControlName="code" webOtp />
+  </div>
+  <button slButton type="submit">Confirmar</button>
+</form>
+
+<!-- form = new FormGroup({ code: new FormControl('', [Validators.minLength(6)]) }) -->
+```
+
+### In a field, with a resend
+
+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.
+
+Excerpt — not a complete module
+
+```html
+<div slField [invalid]="error() !== null">
+  <label slFieldLabel>Código de verificação</label>
+  <div slOtpInput [groups]="[3, 3]">
+    <input slOtpInputControl name="code" (complete)="verify($event)" />
+  </div>
+  <span slFieldDescription>Enviámos um SMS para +55 11 9••••-4821.</span>
+  <span slFieldError>{{ error() }}</span>
+</div>
+<button slButton variant="ghost" [disabled]="seconds() > 0" (click)="resend()">
+  {{ seconds() > 0 ? 'Reenviar em 0:' + pad(seconds()) : 'Reenviar código' }}
+</button>
+
+<!-- Every code in this application is four digits:
+     providers: [provideOtpInputDefaults({ length: 4, attached: true })] -->
+```
+
+### One tab stop, every key the browser’s
+
+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.
+
+Excerpt — not a complete module
+
+```html
+<!-- Inside the value there is always one character selected: the one in
+     front of a collapsed cursor, the last one at the end of a full code. The
+     next key replaces it. A cursor after the last character inserts. -->
+<div slOtpInput [groups]="[3, 3]">
+  <input slOtpInputControl defaultValue="482915" />
+</div>
+```