@fusion.dev/helix-headless 0.146.0 → 0.148.0

package/dist/pagination/size/pagination-size.js

@@ -4,7 +4,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
-import { customElement, formatNumbers, HelixBeforeChangeEvent, HelixFormElement, requestChange, } from '@fusion.dev/helix-core';
+import { customElement, formatNumbers, HelixBeforeChangeEvent, HelixFormElement, hostWords, requestChange, } from '@fusion.dev/helix-core';
 import { nothing } from 'lit';
 import { property } from 'lit/decorators.js';
 import { html } from 'lit/static-html.js';
@@ -89,6 +89,7 @@ let HelixHeadlessPaginationSize = class HelixHeadlessPaginationSize extends Heli
     renderSelect() {
         const select = this.tag('select');
         const option = this.tag('option');
+        const named = this.isConnected ? hostWords(this) : '';
         return html `<${select}
       part="control"
       exportparts="feedback: control-feedback, hint: control-hint, indicator: control-indicator,
@@ -97,9 +98,10 @@ let HelixHeadlessPaginationSize = class HelixHeadlessPaginationSize extends Heli
         listbox-filter-mark: control-listbox-filter-mark, listbox-hint: control-listbox-hint,
         listbox-items: control-listbox-items, listbox-label: control-listbox-label,
         listbox-live: control-listbox-live, listbox-loading: control-listbox-loading, listbox-search: control-listbox-search,
-        listbox-search-field: control-listbox-search-field, surface: control-surface,
+        listbox-search-field: control-listbox-search-field, live: control-live, surface: control-surface,
         trigger: control-trigger, value: control-value"
-      label=${this.label}
+      label=${named ? '' : this.label}
+      aria-label=${named || nothing}
       ?disabled=${this.isDisabled}
       .value=${String(this.current)}
       @helix-before-change=${this.handleChange}

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

@@ -1,4 +1,8 @@
-import type { PinCase, PinType } from './root/pin-input-root.js';
+import { type PickerVerdict } from '@fusion.dev/helix-core';
+/** What a box accepts, which decides the keyboard a phone offers. */
+export type PinType = 'alphanumeric' | 'numeric' | 'text';
+/** How typed letters are cased: as typed, or turned upper or lower case. */
+export type PinCase = 'lower' | 'preserve' | 'upper';
 /**
  * Typed or pasted text as the code's characters: trimmed, with what `type`
  * refuses dropped, and its letters cased as `letterCase` asks. Web Awesome's
@@ -8,3 +12,49 @@ import type { PinCase, PinType } from './root/pin-input-root.js';
  * `text` keeps everything.
  */
 export declare const cleanCode: (text: string, type: PinType, letterCase?: PinCase) => string;
+/** A code after an edit, and the box the caret is in after it. */
+export interface CodeEdit {
+    /** The box the caret is in, from 0, never past the last box. */
+    caret: number;
+    /** The code's characters, as many as there are boxes at most. */
+    code: string;
+}
+/**
+ * What the one field holds after the platform edited it, as a code: `raw` is
+ * the field's text with the caret at `caret`, cleaned and cut at `count`, and
+ * the caret is moved past only the characters the code kept before it.
+ */
+export declare const readTyped: (raw: string, caret: number, type: PinType, letterCase: PinCase, count: number) => CodeEdit;
+/**
+ * A run of characters written over `code` from box `at` onward, which is what a
+ * paste does: the boxes it reaches take its characters and the rest keep
+ * theirs, and anything past the last box is dropped.
+ *
+ * **A code has no holes in it**, so the run starts no later than the end of
+ * the code: a whole code pasted into an empty field fills from the first box
+ * wherever the caret was, and two characters pasted into box three of a field
+ * holding two fill from box three.
+ */
+export declare const overwriteCode: (code: string, at: number, text: string, count: number) => CodeEdit;
+/** The messages a code's verdict is written with, where the page set its own. */
+export interface CodeMessages {
+    /** For a code with no characters in a required field. */
+    missing?: string | undefined;
+    /** For a code with fewer characters than boxes; `{length}` is how many. */
+    short?: string | undefined;
+}
+/**
+ * What is wrong with a code, as a picker field reports it: a required field
+ * with nothing in it is missing, a code with fewer characters than boxes is
+ * too short, and anything else is fine (`''`). The platform's own words where
+ * the page set none.
+ */
+export declare const codeVerdict: (code: string, count: number, required: boolean, messages: CodeMessages) => PickerVerdict;
+/**
+ * The box a caret key moves to from `caret`, kept within the boxes up to
+ * `end`, or `undefined` for a key that moves nothing.
+ *
+ * Not `inlineStep`: the row is left to right whatever the page, so the key
+ * pointing right is the one that moves on in every script.
+ */
+export declare const caretTo: (key: string, caret: number, end: number) => number | undefined;

package/dist/pin-input/code.js

@@ -1,3 +1,4 @@
+import { fillTemplate } from '@fusion.dev/helix-core';
 export const cleanCode = (text, type, letterCase = 'preserve') => {
     const trimmed = text.trim();
     const kept = type === 'numeric'
@@ -11,3 +12,39 @@ export const cleanCode = (text, type, letterCase = 'preserve') => {
             ? kept.toLowerCase()
             : kept;
 };
+export const readTyped = (raw, caret, type, letterCase, count) => ({
+    caret: Math.min(cleanCode(raw.slice(0, caret), type, letterCase).length, count - 1),
+    code: cleanCode(raw, type, letterCase).slice(0, count),
+});
+export const overwriteCode = (code, at, text, count) => {
+    const start = Math.min(at, code.length);
+    const characters = [...code.slice(0, count)];
+    for (let offset = 0; offset < text.length && start + offset < count; offset += 1) {
+        characters[start + offset] = text[offset];
+    }
+    return { caret: Math.min(count - 1, start + text.length), code: characters.join('') };
+};
+export const codeVerdict = (code, count, required, messages) => {
+    if (required && code === '') {
+        return ['valueMissing', messages.missing || 'Please fill in this field.'];
+    }
+    if (code !== '' && code.length < count) {
+        return [
+            'tooShort',
+            fillTemplate(messages.short || 'Please enter all {length} characters.', { length: count }),
+        ];
+    }
+    return '';
+};
+export const caretTo = (key, caret, end) => {
+    const to = key === 'ArrowRight'
+        ? caret + 1
+        : key === 'ArrowLeft'
+            ? caret - 1
+            : key === 'Home'
+                ? 0
+                : key === 'End'
+                    ? end
+                    : undefined;
+    return to === undefined ? undefined : Math.max(0, Math.min(to, end));
+};

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

@@ -1,53 +1,56 @@
 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';
-/** How typed letters are cased: as typed, or turned upper or lower case. */
-export type PinCase = 'lower' | 'preserve' | 'upper';
+import { type PinCase, type PinType } from '../code.js';
+export type { PinCase, PinType } from '../code.js';
 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 field for a short code, with one box for each character.
  *
  * @description
- * Each cell is its own `<input>`, so every box has a real focus ring, caret,
- * and tab stop.
+ * One real `<input>` holds the code, and the boxes are drawn from it, as Web
+ * Awesome's OTP input does. A screen reader meets one field, named by the
+ * label, and the code never sits in a row of separate fields. The boxes are
+ * hidden from it.
  *
- * Input longer than one character is treated as a paste, in any cell. This
- * covers pasting, a browser autofilling an SMS code, and a password manager,
- * which all put the whole code into the focused box. A six-character code that
- * arrives in cell three fills from cell three.
+ * The caret is drawn in the box it is in, and the box is marked with
+ * `cell-active` while the field has focus. A filled box selects its character,
+ * so typing replaces it and moves on.
  *
- * The code is one value to a form. The cells are in a shadow root and submit
- * nothing. The host is form-associated and submits the joined string, which
- * also carries validity and responds to a form reset.
+ * Input longer than one character is treated as a paste. This covers pasting,
+ * a browser autofilling an SMS code, and a password manager. A six-character
+ * code pasted into an empty field fills from the first box.
  *
- * Only the first cell has `autocomplete="one-time-code"`, because the hint
- * applies to the whole field.
+ * The code is one value to a form. The field is in a shadow root and submits
+ * nothing. The host is form-associated and submits the code, which also
+ * carries validity and responds to a form reset. The field carries
+ * `autocomplete="one-time-code"`, which lets a phone offer the code from a
+ * message.
  *
  * `autosubmit` submits the form once the last box is filled, through the form's
  * default button where there is one. `format` draws separators between the
- * boxes, such as the dash in `###-###`, as text a screen reader skips. Delete
- * removes the character in the focused box and pulls the rest of the code
- * back, as Backspace removes the one before it.
+ * boxes, such as the dash in `###-###`, as text a screen reader skips. `mask`
+ * makes the field a password field and draws `mask-character` in each filled
+ * box, so the code is never drawn as text.
  *
- * The row of cells always runs left to right, with `dir="ltr"`, including in
+ * The row of boxes always runs left to right, with `dir="ltr"`, including in
  * Arabic and Hebrew. The first box is the leftmost, a paste fills to the right,
  * and the right arrow moves to the next box. The label, hint, and feedback
  * follow the page's direction.
  *
- * **Keyboard.** Each box is a tab stop of its own, as each is a real input.
+ * **Keyboard.** The field is one tab stop.
  *
  * | Key | What it does |
  * |---|---|
  * | A character | Fills the box and moves to the next one. A longer run is read as a paste. |
  * | Left, Right | Moves to the box before or after. |
  * | Home, End | Moves to the first box, or to the box after the last character. |
- * | Backspace | In an empty box, clears the box before it and moves there. |
+ * | Backspace | Removes the character in the box, or in an empty box the one before it, and moves there. |
  * | Delete | Removes the character in the box and pulls the rest of the code back. |
  * | Enter | Submits the form. |
  *
- * The row has `role="group"` and the field's name, and each box is named by
- * `cell-label`, such as "Character 2 of 6". `helix-complete` is a
+ * The field is a text field, or a password field under `mask`, named by the
+ * label and described by the hint and the message, with `aria-invalid` while
+ * a message shows and `aria-required` under `required`. `helix-complete` is a
  * `HelixCompleteEvent` sent once the last box is filled.
  *
  * @since 0.1.0
@@ -65,11 +68,16 @@ declare const HelixHeadlessPinInput_base: (new (...args: any[]) => import("@fusi
  * @event {HelixCompleteEvent} helix-complete - The last box was filled.
  * @event {Event} input - The code changed.
  *
+ * @csspart caret - The caret, drawn in the empty box it is in while the field has focus.
  * @csspart cell - One box.
+ * @csspart cell-active - The box the caret is in, while the field has focus. Set together with `cell`.
+ * @csspart cell-filled - A box that holds a character. Set together with `cell`.
+ * @csspart control - The one field that holds the code, out of sight: the boxes are drawn from it.
  * @csspart feedback - The message that says what is wrong with the code.
  * @csspart field - The row of boxes, ordered left to right in every language.
  * @csspart hint - The help under the boxes, shown while there is no feedback.
  * @csspart label - The label above the boxes.
+ * @csspart placeholder - The `placeholder` text in an empty box.
  * @csspart separator - The text `format` draws between two boxes.
  *
  * @cssstate complete - Every box holds a character.
@@ -77,17 +85,12 @@ declare const HelixHeadlessPinInput_base: (new (...args: any[]) => import("@fusi
  */
 export declare class HelixHeadlessPinInput extends HelixHeadlessPinInput_base {
     protected readonly aria: AriaForwardController;
-    /** @internal The element a missing name is checked on: the row of cells, so the name of one cell does not count as the name of the field. */
-    protected get namedControl(): HTMLElement | null;
-    /** Typed or dragged, so every edit is announced. See `announcesInput`. */
+    /** Typed or pasted, so every edit is announced. See `announcesInput`. */
     protected readonly announcesInput = true;
     /**
-     * The autofill hint for the browser, set on the first box 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.
+     * The autofill hint for the browser. `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.
      */
     autocomplete: string;
     /**
@@ -103,7 +106,11 @@ export declare class HelixHeadlessPinInput extends HelixHeadlessPinInput_base {
      */
     case: PinCase;
     /**
-     * Accessible name for one box, with `{index}` and `{length}` filled in.
+     * The name each box once had, with `{index}` and `{length}` filled in.
+     *
+     * @deprecated No longer read. The boxes are drawn from one field, which is
+     * named by `label`, and a screen reader does not meet the boxes. Removed in
+     * the next breaking release.
      */
     cellLabel: string;
     /**
@@ -117,23 +124,23 @@ export declare class HelixHeadlessPinInput extends HelixHeadlessPinInput_base {
      */
     length: number;
     /**
-     * Whether the characters are hidden, the way a password is.
+     * Whether the characters are hidden, the way a password is. The field is a
+     * password field, and each filled box draws `mask-character`.
      */
     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.
+     * What a filled box draws under `mask`, in place of its character, as Web
+     * Awesome's `--mask-char`.
+     */
+    maskCharacter: string;
+    /**
+     * What an empty box shows, usually a single dot. It is not shown in the box
+     * the caret is in. Empty by default, because a row of boxes already reads as
+     * a row of boxes.
      */
     placeholder: string;
     /**
-     * Whether the boxes block input. A read-only code still submits its value.
+     * Whether the field blocks input. A read-only code still submits its value.
      */
     readOnly: boolean;
     /**
@@ -159,51 +166,60 @@ export declare class HelixHeadlessPinInput extends HelixHeadlessPinInput_base {
      *
      * **Not reflected**: nothing selects on it, so reflecting only writes
      * `type="numeric"` onto every `<helix-headless-pin-input>` ever rendered, an
-     * attribute no consumer's markup had. The area rules carry the sentence
-     * "reflect only what CSS selects on". The real inputs take it as a binding,
+     * attribute no consumer's markup had. The field takes it as `inputmode`,
      * which is what makes the keyboard follow.
      */
     type: PinType;
     /** Focus is delegated, so the host is never the focus target. */
     static shadowRootOptions: ShadowRootInit;
+    /**
+     * The box the caret is in while the field has focus, and -1 while it does
+     * not or while the field is read-only, where there is nothing to type into.
+     */
+    private active;
+    /** The box a press asked for, taken when the focus it starts arrives. */
+    private pressedAt;
     /** 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 and cased. */
-    private clean;
+    private get control();
+    /** The furthest box the caret can be in: after the code, and the last box at most. */
+    private get end();
+    /** The box the caret is drawn in, kept within the code a script may have shortened. */
+    private get caretBox();
     /**
-     * Writes a run of characters from one box onward.
+     * Takes a code the field was edited to, and moves the caret to `caret`.
      *
      * 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.
+     * the same act at different lengths. Through `requestValue`, so a consumer
+     * who owns the code can refuse it, and a refused edit puts the field back.
      */
-    private write;
+    private take;
     /**
-     * Puts the value back into the boxes.
+     * Puts the field's selection on the box the caret is in: the character
+     * there, so typing replaces it, or the empty place after the code.
      *
-     * 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.
+     * Left alone while the reader holds a wider selection of their own, such as
+     * everything after Control+A, unless `force` says the caret moved.
      */
-    private paint;
+    private placeCaret;
     private readonly handleInput;
+    /**
+     * A paste writes over the boxes from the caret on, rather than into the
+     * field's text, so a code pasted into box three of a full code replaces the
+     * characters there instead of pushing them along.
+     */
     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.
+     * The keys that move between boxes. Backspace and Delete are the field's
+     * own: the selection on a filled box makes them remove its character, and
+     * the empty place after the code makes Backspace remove the one before.
      *
      * Home goes to the first box and End to the end of the code, the box after
      * its last character, which is where the caret goes in a single text field.
      */
     private readonly handleKeydown;
+    /** A press on a box puts the caret there, or after the code where the box is past it. */
+    private readonly handlePress;
     /**
      * The code as it stood when focus arrived, so a visit that changed nothing
      * says nothing.
@@ -220,72 +236,37 @@ export declare class HelixHeadlessPinInput extends HelixHeadlessPinInput_base {
      * | 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
+     * `value` and then has a reader tab through the field 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.
+     * wrote it, and re-taken on every arrival.
      */
     private committed;
-    /** Selecting on focus, so typing replaces rather than appending. */
+    /** Takes the baseline, and puts the caret in the box pressed or after the code. */
     private readonly handleFocus;
     /**
-     * Whether focus is currently somewhere inside the row.
-     *
-     * **The arrival is a transition, not a `relatedTarget` reading**, which is
-     * what the exit still does. `relatedTarget` does not work on the way in for
-     * two reasons and the second 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 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.
+     * Commits when focus leaves the field.
      *
      * `change` is one of the two events `MixinField` reads as "the reader has had
      * a go at this", so without this a code that was never completed is never
      * `touched` and its own `tooShort` message cannot show: two boxes of four
-     * filled and tabbed away from is 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.
+     * filled and tabbed away from is answered with nothing at all.
      */
-    private readonly handleFocusOut;
+    private readonly handleBlur;
     /**
      * 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".
+     * filled code and a field being left are both "the reader is done with this".
      * Dispatching from either site directly is how a moment gets added that fires
      * without baselining.
      *
      * 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.
+     * leaving a field 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.
@@ -307,20 +288,15 @@ export declare class HelixHeadlessPinInput extends HelixHeadlessPinInput_base {
      * | 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.
+     * applies to anything that is not nothing. 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.
      */
     private sync;
     /** Puts the caret in the first empty box. */
     focus(options?: FocusOptions): void;
-    /** Empties every box and moves focus to the first. */
+    /** Empties every box and puts the caret in the first. */
     clear(): void;
     protected firstUpdated(changed: PropertyValues): void;
     protected updated(changed: PropertyValues): void;
@@ -333,6 +309,8 @@ export declare class HelixHeadlessPinInput extends HelixHeadlessPinInput_base {
     private readonly handleKeypress;
     /** @internal A single line of text counts against implicit submission. */
     protected get blocksImplicitSubmission(): boolean;
+    /** What one box draws: its character, the mask, the caret, or the placeholder. */
+    private renderBox;
     protected render(): TemplateResult;
 }
 declare global {
@@ -340,4 +318,3 @@ declare global {
         'helix-headless-pin-input': HelixHeadlessPinInput;
     }
 }
-export {};