@fusion.dev/helix-headless 0.0.0-dev

package/dist/pin-input/root/pin-input-root.d.ts

@@ -0,0 +1,292 @@
+import { AriaForwardController, HelixFormElement } from '@fusion.dev/helix-core';
+import { type PropertyValues, type TemplateResult } from 'lit';
+/** What a cell accepts, which decides the keyboard a phone offers. */
+export type PinType = 'alphanumeric' | 'numeric' | 'text';
+declare const HelixHeadlessPinInput_base: (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerValueInterface) & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinFieldInterface) & typeof HelixFormElement;
+/**
+ * @summary A short code, one character to a box.
+ *
+ * @description
+ * **One `<input>` per cell, rather than one input drawn as cells.** Both are
+ * built in the wild and the trade is real: a single field autofills perfectly
+ * and needs a drawn caret nobody can style well, and separate fields give every
+ * box a real focus ring, a real caret and a real tab stop for free. This takes
+ * the second, and then closes autofill's gap rather than living with it, below.
+ *
+ * **Anything longer than one character is treated as a paste, wherever it
+ * lands.** That covers the obvious case and two that are not: a browser
+ * autofilling an SMS code drops the whole thing into whichever box is focused,
+ * and a password manager does the same. So a six-character arrival in cell three
+ * fills from cell three rather than being truncated to its first character,
+ * which is what a per-cell `maxlength` would have done silently.
+ *
+ * **The code is one value to a form.** The cells are inside a shadow root and
+ * submit nothing on their own; the host is form-associated and reports the
+ * joined string, which is also what carries validity and answers a reset.
+ *
+ * `autocomplete="one-time-code"` is on the first cell only. It is a hint about
+ * the field as a whole, and repeating it on six boxes offers a browser six
+ * places to put one code.
+ *
+ * @since 0.1.0
+ * @status stable
+ * @category forms
+ * @aliases PinField, OTP, One-time code, Verification code, InputPin
+ * @documentation https://helix.fusion.dev/components/pin-input
+ *
+ * @event {Event} change - Announced with a filled code, and when an edited one loses focus.
+ * @event {HelixBeforeChangeEvent} helix-before-change - Fired as the code changes, and cancelable.
+ * @event {HelixCompleteEvent} helix-complete - Fired when the last box is filled.
+ * @event {Event} input - Announced once the value has moved.
+ *
+ * @csspart cell - One box.
+ * @csspart feedback - What is wrong with it.
+ * @csspart field - The row of boxes.
+ * @csspart hint - Help under the boxes, while nothing is wrong.
+ * @csspart label - The question, over the boxes.
+ */
+export declare class HelixHeadlessPinInput extends HelixHeadlessPinInput_base {
+    protected readonly aria: AriaForwardController;
+    /** Typed or dragged, so every edit is announced. See `announcesInput`. */
+    protected readonly announcesInput = true;
+    /**
+     * What the browser may autofill, reaching the first cell only.
+     *
+     * `one-time-code` is why this defaults to anything at all: it is the token
+     * that lets a phone offer the code out of a message. Later cells stay `off`
+     * for the reason in the class comment above, that six cells each offering
+     * the same code is one offer made six times.
+     */
+    autocomplete: string;
+    /**
+     * How many characters the code has.
+     */
+    length: number;
+    /**
+     * What a box accepts, which decides the keyboard a phone offers.
+     *
+     * `numeric` and `alphanumeric` also refuse anything else on the way in,
+     * because a code that is digits is digits: letting a letter into a box a
+     * reader cannot submit is a mistake they have to find and undo themselves.
+     * `text` refuses nothing and only trims, so it is the mode for a code with a
+     * hyphen in it.
+     *
+     * **`alphanumeric` is ASCII letters and digits**, which is narrower than the
+     * word is in general and is the right narrowness here. A code of this kind
+     * comes off a keypad, an SMS or an authenticator, and none of them emit `é`;
+     * a filter that accepted it would let through a character the service on the
+     * other end is going to reject. A consumer whose codes really do carry
+     * marked letters wants `text`, which judges nothing.
+     *
+     * **Not reflected**, and it was until this component's own server spec caught
+     * it: nothing selects on it, so all reflection did was write `type="numeric"`
+     * onto every `<helix-pin-input>` ever rendered, an attribute no consumer's
+     * markup had. That is the fault `Input`'s own `type` had and the reason the
+     * area rules carry the sentence "reflect only what CSS selects on". The real
+     * inputs take it as a binding, which is what makes the keyboard follow.
+     */
+    type: PinType;
+    /**
+     * Whether the characters are hidden, the way a password is.
+     */
+    mask: boolean;
+    /**
+     * What an empty box shows, usually a single dot.
+     *
+     * The platform's own placeholder, on each cell, rather than a character
+     * drawn behind the field: it clears the moment anything is typed, it is
+     * already excluded from the accessible value, and it works the same under
+     * `mask`, where the cell is a password input and a hand-drawn glyph would
+     * have to know that.
+     *
+     * Empty by default, because a row of boxes already reads as a row of boxes
+     * and a dot in each is a choice about how much the field should announce
+     * itself before anybody has touched it.
+     */
+    placeholder: string;
+    /**
+     * Whether the boxes refuse input while still submitting their value.
+     */
+    readOnly: boolean;
+    /**
+     * Accessible name for one box, with `{index}` and `{length}` filled in.
+     */
+    cellLabel: string;
+    /** Focus is delegated, so the host is never the focus target. */
+    static shadowRootOptions: ShadowRootInit;
+    /** How many boxes there are, clamped once so every reader agrees. */
+    private get count();
+    private get cells();
+    /** The code as characters, padded to the row so every box has one to show. */
+    private get characters();
+    /** Everything this box would accept, with the rest dropped. */
+    private clean;
+    /**
+     * Writes a run of characters from one box onward.
+     *
+     * The single path for typing, pasting and autofill alike, because they are
+     * the same act at different lengths and splitting them is how the three
+     * disagree about trimming, about the cursor, and about what happens at the
+     * end.
+     */
+    private write;
+    /**
+     * Puts the value back into the boxes.
+     *
+     * The cells are uncontrolled between renders, because Lit will not rewrite an
+     * input's `.value` when the bound string has not changed, and a refused
+     * keystroke leaves the box holding a character the element rejected. This is
+     * the same put-back `Input` does with `restoreValue`, once per box.
+     */
+    private paint;
+    private readonly handleInput;
+    private readonly handlePaste;
+    /**
+     * The keys that move between boxes, and the one that clears backwards.
+     *
+     * Backspace in an empty box goes back and clears the one it lands in, which
+     * is what makes a code correctable without the reader hunting for the box
+     * they meant. In a full box it does what it always does and is left alone.
+     */
+    private readonly handleKeydown;
+    /**
+     * The code as it stood when focus arrived, so a visit that changed nothing
+     * says nothing.
+     *
+     * **This is the platform's reading, and it was the other one until it was
+     * measured.** It held the value at the last *commit*, on the argument that
+     * recognizing an arrival is hard here: this component moves focus itself on
+     * every character, so most `focus` events are ones it caused, and telling
+     * those apart rests entirely on `relatedTarget`. That is true and it is not
+     * an obstacle, because `handleFocusOut` was already doing exactly that guard
+     * one method away. The reasoning had talked itself out of a check it had
+     * already written.
+     *
+     * **What the two readings do to a real browser**, measured in Chromium
+     * against a native `<input>` with real keystrokes:
+     *
+     * | | native | last commit | on arrival |
+     * |---|---|---|---|
+     * | types, leaves | `change` | `change` | `change` |
+     * | script assigns unfocused, visit with no edit | silent | **`change`** | silent |
+     * | script assigns unfocused, then edits | `change` | `change` | `change` |
+     * | types a character and deletes it | silent | silent | silent |
+     *
+     * One row differed and it is the one that matters: a consumer who assigns
+     * `value` and then has a reader tab through the row was told the reader had
+     * entered a code. `change` on a field means "the reader had a go at this",
+     * `MixinField` treats it as exactly that, and announcing a value the consumer
+     * set themselves is a false positive rather than the safe half of a trade.
+     *
+     * **The narrower divergence that is left** is a script assigning while the row
+     * is focused, where the platform stays silent because no user edit happened
+     * and this commits on the way out. Closing it needs a dirty flag set from real
+     * cell input rather than a baseline, which is more machinery than the case has
+     * earned: a consumer writing to a field the reader is inside is already in a
+     * fight with them.
+     *
+     * Seeded in `firstUpdated`, a code in the markup being committed by whoever
+     * wrote it, and re-taken on every arrival from outside the row.
+     */
+    private committed;
+    /** Selecting on focus, so typing replaces rather than appending. */
+    private readonly handleFocus;
+    /**
+     * Whether focus is currently somewhere inside the row.
+     *
+     * **The arrival is a transition, not a `relatedTarget` reading**, which is
+     * what the first version of this did and is what the exit still does. It does
+     * not work on the way in for two separate reasons and the second is the one
+     * that decides it. Every character moves focus to the next box, so an
+     * unguarded `focusin` re-baselines on each keystroke and the row can never
+     * report anything: measured, the three commit specs went silent at once. And
+     * `focusin` carries `relatedTarget` in a browser and not in happy-dom, so a
+     * guard written on it is a guard that holds in production and not in the
+     * specs, which is the worse half. This flag needs neither: entering is
+     * `focusin` while it is `false`, and nothing else is.
+     */
+    private within;
+    /**
+     * Takes the baseline when focus arrives from outside the row.
+     *
+     * The value at arrival is what the platform compares against, and the table
+     * on `committed` is why.
+     */
+    private readonly handleFocusIn;
+    /**
+     * Commits when focus leaves the row, which is the moment every other field in
+     * the library has and this one did not.
+     *
+     * `change` is one of the two events `MixinField` reads as "the reader has had
+     * a go at this", so a code that was never completed was never `touched` and
+     * its own `tooShort` message could not show: two boxes of four filled and
+     * tabbed away from was answered with nothing at all. `Input` gets this for
+     * free by relaying its control's own `change`; here the cells each fire one,
+     * none of them means the code is entered, and neither does any single one of
+     * them mean the reader has left.
+     *
+     * **Focus leaving the row, and not a cell.** Every character moves focus to
+     * the next box, so a per-cell blur would commit on every keystroke, which is
+     * the fault this exists to fix pointed the other way.
+     */
+    private readonly handleFocusOut;
+    /**
+     * Announces the code as entered, from whichever moment reached it first.
+     *
+     * **One writer, because the fact has two moments and only one meaning.** A
+     * filled code and a row being left are both "the reader is done with this",
+     * and they were two dispatch sites kept from disagreeing by both remembering
+     * to update `committed`. They are one call now, so a third moment cannot be
+     * added that fires without baselining, which is the way the pair would have
+     * drifted.
+     *
+     * Silent when nothing moved since the baseline, which is what makes it safe
+     * to call from both: completing a code that is already the committed one, or
+     * leaving a row nobody edited, says nothing.
+     *
+     * `composed: false`, like the native event this stands in for. It is
+     * dispatched on the host, so a consumer hears it.
+     */
+    private commit;
+    /**
+     * Reports the code and a verdict on it.
+     *
+     * **A half-entered code is invalid whether or not it is required, and that is
+     * the platform's answer rather than ours.** It looked like an oversight worth
+     * a question: `required` guards `valueMissing` and nothing guards `tooShort`,
+     * so an optional code is refused for being half filled. Measured in Chromium
+     * against a native `<input minlength="4">` with real keystrokes, which is the
+     * feature this is the same shape as:
+     *
+     * | | optional | required |
+     * |---|---|---|
+     * | typed `12` | `tooShort`, invalid | `tooShort`, invalid |
+     * | left empty | valid | `valueMissing` |
+     * | typed `1234` | valid | valid |
+     *
+     * So `required` decides whether *nothing* is acceptable, and the length rule
+     * applies to anything that is not nothing. That is the right split for a code
+     * as well: two of four characters is not an optional code omitted, it is a
+     * code got wrong, and submitting it would send a fragment. The gate on the
+     * message is `touched` rather than `required`, which is what stops a reader
+     * being told off before they have had a go.
+     *
+     * `execCommand('insertText')` is not enough to measure this: `tooShort`
+     * applies only to a value the user edited, and the first run of the probe
+     * reported every case valid because nothing had set that flag.
+     */
+    private sync;
+    /** Puts the caret in the first empty box, which is where a reader resumes. */
+    focus(options?: FocusOptions): void;
+    /** Empties every box and returns to the first. */
+    clear(): void;
+    protected firstUpdated(changed: PropertyValues): void;
+    protected updated(changed: PropertyValues): void;
+    protected render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-pin-input': HelixHeadlessPinInput;
+    }
+}
+export {};