@fusion.dev/helix-headless 0.2.0 → 0.3.0

package/dist/pagination/summary/pagination-summary.js

@@ -7,116 +7,26 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 import { customElement, formatNumbers, HelixElement } from '@fusion.dev/helix-core';
 import { html } from 'lit';
 import { property } from 'lit/decorators.js';
-/**
- * @summary Reads out which items of how many are on show.
- *
- * @description
- * Its own element rather than a part of `Pagination`, so a consumer decides
- * where it goes. Inside the run it could only ever be at one end of one row;
- * beside it, it goes above, below, in a table's caption, or on the other side of
- * the page, and the direction and order of the whole footer are the consumer's.
- *
- * **It repeats `page`, `page-size` and `total`, and the cost of that is skew
- * rather than verbosity.** Those three come from the consumer's own query, so
- * writing them on two elements is one variable used twice; what it risks is the
- * two disagreeing, and a count reading `76-100 of 248` beside a run showing page
- * 7 is the same failure this element's own clamping exists to prevent, arriving
- * from the outside instead.
- *
- * **Nothing removes it at this level, and that was measured rather than
- * assumed.** A coordinating root can only reach children the consumer laid out
- * by writing attributes onto them, which a framework reports as a hydration
- * error, or through context, which is dead on a server: `@lit/context`
- * subscribes from `connectedCallback`, and Lit SSR does not call it, so every
- * value is `undefined` in exactly the render this element exists to be part of.
- * Confirmed against Lit SSR directly. The fork is real: children in the light
- * DOM mean the consumer owns the layout and no root can feed them; children in a
- * shadow root mean a root feeds them by ordinary binding and owns the layout.
- *
- * **It resolves one level up, at a composite, and the state is why.** `page`,
- * `page-size` and `total` are facts about a *result*, not about a pagination, so
- * the element that should hold them once is the one that holds the result: a
- * data table composing a pagination inside itself, rather than a pagination root
- * invented to hold three pagination elements together. That root would have been
- * plumbing; a table's paging state is the thing itself. And because a composite
- * renders its parts into its own shadow root, it lands on the side of the fork
- * where binding works and the server renders, at no cost to anyone.
- *
- * Renders nothing without a `total` and a `page-size`. A wrong count is worse
- * than none: it is the one number in a footer a reader cannot check against
- * anything else on screen.
- *
- * @since 0.1.0
- * @status experimental
- * @aliases Result count, Range
- * @documentation https://helix.fusion.dev/components/pagination
- */
 let HelixHeadlessPaginationSummary = class HelixHeadlessPaginationSummary extends HelixElement {
     constructor() {
         super(...arguments);
-        /**
-         * The reading, with `{from}`, `{to}` and `{total}` filled in.
-         *
-         * A template rather than a prefix and a suffix, because word order is not
-         * universal: `format="{total} 件中 {from}-{to} 件"` is one attribute here and
-         * three concatenations anywhere else.
-         *
-         * **`format`, not `label`, and the difference is worth the rename.** `label`
-         * across this library means the accessible name of a thing that has one:
-         * `Pagination.label` names the landmark and `Pagination.Size.label` is the
-         * words beside the control. This is neither. It is the whole visible content
-         * of the element, so calling it `label` put one word on three jobs inside one
-         * family. The root's templates are `pageLabel`, `statusLabel` and `gapLabel`,
-         * which each label something; this labels nothing, it *is* the thing.
-         */
         this.format = '{from}-{to} of {total}';
-        /**
-         * Locale for the numbers.
-         *
-         * Absent uses the runtime's own.
-         */
         this.locale = '';
-        /**
-         * The page on show, one-based.
-         */
         this.page = 1;
-        /**
-         * How many items are on a page.
-         */
         this.pageSize = 0;
-        /**
-         * How many items there are across every page.
-         */
         this.total = 0;
     }
-    /** Held across every component asking for the same locale. */
     get numbers() {
         return formatNumbers(this.locale);
     }
     render() {
-        /* An empty template rather than `nothing`, so the element generates a box
-           with no text in it: a footer laid out as a grid keeps its column, and a
-           count that appears when the total loads does not move the controls beside
-           it. */
         if (this.total <= 0 || this.pageSize <= 0) {
             return html ``;
         }
         const size = Math.max(1, Math.floor(this.pageSize));
-        /* **The page is clamped to the range, not just the window inside it.**
-           Only the end was, so a `page` past the last one produced a start past the
-           total and an end pinned to it: at page 99 of a 10-page result this read
-           "2,451-248 of 248", a range running backwards. That is the worst kind of
-           wrong here, because a count is the one number in a footer a reader cannot
-           check against anything else on screen.
-        
-           A page past the end is not far-fetched either: it is a bookmarked query
-           after the result shrank, and the run beside this clamps it silently, so
-           the two would disagree with only this one visibly broken. */
         const pages = Math.max(1, Math.ceil(this.total / size));
         const page = Math.min(pages, Math.max(1, Math.floor(this.page) || 1));
         const from = (page - 1) * size + 1;
-        /* And the end is clamped to the total, because the last page is rarely
-           full: 248 items at 25 a page end at 248, not at 250. */
         const to = Math.min(this.total, from + size - 1);
         return html `${this.format
             .replaceAll('{from}', this.numbers(from))

package/dist/pin-input/root/pin-input-root.js

@@ -7,141 +7,27 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 import { AriaForwardController, customElement, HelixCompleteEvent, HelixFormElement, MixinControllerValue, MixinField, } from '@fusion.dev/helix-core';
 import { html, nothing } from 'lit';
 import { property } from 'lit/decorators.js';
-/**
- * @summary A short code, one character to a box.
- *
- * @description
- * **One `<input>` per cell, rather than one input drawn as cells.** A single
- * field autofills perfectly and needs a drawn caret nobody can style well;
- * separate fields give every box a real focus ring, a real caret and a real tab
- * stop for free. Autofill's gap is closed below rather than lived with.
- *
- * **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.
- */
 let HelixHeadlessPinInput = class HelixHeadlessPinInput extends MixinControllerValue(MixinField(HelixFormElement)) {
     constructor() {
         super(...arguments);
-        /* A consumer's `aria-describedby` names ids in their own tree and the control
-           is in this shadow root, so the reference has to be carried down as an
-           element rather than copied as an id. See `AriaForwardController`: measured
-           in Chrome's own tree, the host held the description and the control the
-           reader is actually on was exposed without it. */
         this.aria = new AriaForwardController(this, {
             target: () => this.renderRoot?.querySelector('[part="cell"]') ?? null,
         });
-        /** Typed or dragged, so every edit is announced. See `announcesInput`. */
         this.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.
-         */
         this.autocomplete = 'one-time-code';
-        /**
-         * Accessible name for one box, with `{index}` and `{length}` filled in.
-         */
         this.cellLabel = 'Character {index} of {length}';
-        /**
-         * How many characters the code has.
-         */
         this.length = 6;
-        /**
-         * Whether the characters are hidden, the way a password is.
-         */
         this.mask = false;
-        /**
-         * 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.
-         */
         this.placeholder = '';
-        /**
-         * Whether the boxes refuse input while still submitting their value.
-         */
         this.readOnly = false;
-        /**
-         * 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**: nothing selects on it, so reflecting only writes
-         * `type="numeric"` onto every `<helix-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, which is what
-         * makes the keyboard follow.
-         */
         this.type = 'numeric';
         this.handleInput = (event) => {
-            // Stopped for the reason `Input.handleInput` gives: the inner control's own
-            // `input` is composed and would reach a consumer beside this element's.
             event.stopPropagation();
             const cell = event.target;
             const at = this.cells.indexOf(cell);
             if (at === -1) {
                 return;
             }
-            /* **An emptied box is a deletion, and without this branch it is
-               unreachable.** A Backspace in a *filled* box is the browser's own: the
-               keydown handler leaves it alone, the character goes, and `input` arrives
-               carrying "". That falls through to `write`, which returns early on empty,
-               and then `paint` puts the character straight back. Only real keystrokes
-               reproduce it: dispatched events do not, which is why the specs pass over
-               it.
-        
-               The rest collapse left, which is what the model already requires and what
-               a single text field does: "123456" with the 2 deleted is "13456", not a
-               hole. Focus stays where the reader was, so the box under the caret now
-               holds what followed. */
             if (cell.value === '') {
                 const characters = this.characters;
                 characters[at] = '';
@@ -152,11 +38,7 @@ let HelixHeadlessPinInput = class HelixHeadlessPinInput extends MixinControllerV
                 });
                 return;
             }
-            /* Longer than one character is a paste or an autofill, whichever box it
-               landed in. A per-cell `maxlength` would have silently truncated it to the
-               first character and lost the rest. */
             this.write(at, cell.value);
-            // And put the box back, in case what arrived was refused or filtered.
             this.updateComplete.then(() => this.paint());
         };
         this.handlePaste = (event) => {
@@ -165,18 +47,9 @@ let HelixHeadlessPinInput = class HelixHeadlessPinInput extends MixinControllerV
             if (at === -1) {
                 return;
             }
-            // Taken here rather than left to `input`, so the browser does not first put
-            // the whole string into one box and fire a change we then have to undo.
             event.preventDefault();
             this.write(at, event.clipboardData?.getData('text') ?? '');
         };
-        /**
-         * 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.
-         */
         this.handleKeydown = (event) => {
             const cell = event.target;
             const at = this.cells.indexOf(cell);
@@ -205,63 +78,12 @@ let HelixHeadlessPinInput = class HelixHeadlessPinInput extends MixinControllerV
             }
             event.preventDefault();
         };
-        /**
-         * The code as it stood when focus arrived, so a visit that changed nothing
-         * says nothing.
-         *
-         * **Baselined on arrival, not at the last commit**, which is the platform's
-         * reading. What the two 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.
-         */
         this.committed = '';
-        /** Selecting on focus, so typing replaces rather than appending. */
         this.handleFocus = (event) => {
             ;
             event.target.select();
         };
-        /**
-         * 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.
-         */
         this.within = false;
-        /**
-         * 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.
-         */
         this.handleFocusIn = () => {
             if (this.within) {
                 return;
@@ -269,21 +91,6 @@ let HelixHeadlessPinInput = class HelixHeadlessPinInput extends MixinControllerV
             this.within = true;
             this.committed = this.value;
         };
-        /**
-         * Commits when focus leaves the row.
-         *
-         * `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.
-         */
         this.handleFocusOut = (event) => {
             if (this.cells.includes(event.relatedTarget)) {
                 return;
@@ -292,23 +99,19 @@ let HelixHeadlessPinInput = class HelixHeadlessPinInput extends MixinControllerV
             this.commit();
         };
     }
-    /** Focus is delegated, so the host is never the focus target. */
     static { this.shadowRootOptions = {
         ...HelixFormElement.shadowRootOptions,
         delegatesFocus: true,
     }; }
-    /** How many boxes there are, clamped once so every reader agrees. */
     get count() {
         return Math.max(1, Math.floor(this.length) || 1);
     }
     get cells() {
         return [...this.renderRoot.querySelectorAll('[part="cell"]')];
     }
-    /** The code as characters, padded to the row so every box has one to show. */
     get characters() {
         return Array.from({ length: this.count }, (_, at) => this.value[at] ?? '');
     }
-    /** Everything this box would accept, with the rest dropped. */
     clean(text) {
         const trimmed = text.trim();
         if (this.type === 'numeric') {
@@ -319,29 +122,11 @@ let HelixHeadlessPinInput = class HelixHeadlessPinInput extends MixinControllerV
         }
         return trimmed;
     }
-    /**
-     * 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.
-     */
     write(from, text) {
         const cleaned = this.clean(text);
         if (cleaned === '') {
             return;
         }
-        /* **A code has no holes in it**, so a character cannot land past the end of
-           what is already there. Clamped rather than allowed, because the value is
-           one compact string and a gap in the middle of it does not exist: unclamped,
-           the boxes and the value disagree about where the reader typed.
-    
-           It reads correctly in both directions. Pasting a whole code while the
-           caret happens to sit in box three fills from the start, which is what a
-           reader pasting a code means. Pasting two characters into box three of a
-           field with two already in it fills from box three, because that is where
-           the end was. */
         const start = Math.min(from, this.value.length);
         const characters = this.characters;
         for (let at = 0; at < cleaned.length && start + at < this.count; at += 1) {
@@ -356,21 +141,10 @@ let HelixHeadlessPinInput = class HelixHeadlessPinInput extends MixinControllerV
             this.cells[filled]?.select();
             if (next.length === this.count) {
                 this.dispatchEvent(new HelixCompleteEvent({ value: next }));
-                /* And a native `change`, because a filled code is this control's
-                   commit. There is no inner control to relay one from: six boxes each
-                   fire their own, and none of them means the code is entered. */
                 this.commit();
             }
         });
     }
-    /**
-     * 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.
-     */
     paint() {
         const characters = this.characters;
         for (const [at, cell] of this.cells.entries()) {
@@ -380,21 +154,6 @@ let HelixHeadlessPinInput = class HelixHeadlessPinInput extends MixinControllerV
             }
         }
     }
-    /**
-     * 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".
-     * 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.
-     *
-     * `composed: false`, like the native event this stands in for. It is
-     * dispatched on the host, so a consumer hears it.
-     */
     commit() {
         if (this.value === this.committed) {
             return;
@@ -402,32 +161,6 @@ let HelixHeadlessPinInput = class HelixHeadlessPinInput extends MixinControllerV
         this.committed = this.value;
         this.dispatchEvent(new Event('change', { bubbles: true, composed: false }));
     }
-    /**
-     * 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.** `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.
-     */
     sync() {
         this.internals.setFormValue(this.value);
         const first = this.cells[0];
@@ -443,16 +176,13 @@ let HelixHeadlessPinInput = class HelixHeadlessPinInput extends MixinControllerV
         else {
             this.internals.setValidity({}, '', first);
         }
-        // Straight after, because validity moved without any property moving.
         this.refreshFeedback();
     }
-    /** Puts the caret in the first empty box, which is where a reader resumes. */
     focus(options) {
         const cells = this.cells;
         const at = Math.min(this.value.length, cells.length - 1);
         cells[at]?.focus(options);
     }
-    /** Empties every box and returns to the first. */
     clear() {
         this.requestValue('');
         this.updateComplete.then(() => {
@@ -471,12 +201,6 @@ let HelixHeadlessPinInput = class HelixHeadlessPinInput extends MixinControllerV
     }
     render() {
         const characters = this.characters;
-        /* `renderGroupLabel` and not `renderLabel`, which is what every other
-           grouped control here uses. `renderLabel` emits `for="control"` and no
-           element in this template carries that id, because a pin input is a row of
-           cells and not one control: the visible label pointed at nothing, so
-           pressing it focused nothing and the group had no accessible name at all.
-           The set names itself through `hostAria` instead. */
         return html `${this.renderGroupLabel()}
       <div
         part="field"