@fusion.dev/helix-headless 0.145.0 → 0.147.0

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

@@ -4,123 +4,114 @@ 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 { AriaForwardController, customElement, fillTemplate, HelixCompleteEvent, HelixFormElement, MixinControllerValue, MixinField, } from '@fusion.dev/helix-core';
+import { AriaForwardController, customElement, fillTemplate, HelixCompleteEvent, HelixFormElement, MixinControllerValue, MixinField, restoreValue, submitImplicitly, } from '@fusion.dev/helix-core';
 import { html, nothing } from 'lit';
-import { property } from 'lit/decorators.js';
+import { property, state } from 'lit/decorators.js';
+import { cleanCode, overwriteCode, readTyped, } from '../code.js';
 import { separatorsAfter } from '../format.js';
+const UNSEEN = 'position:absolute;width:1px;height:1px;opacity:0;pointer-events:none;font-size:16px';
+const keepFocus = (event) => event.preventDefault();
 let HelixHeadlessPinInput = class HelixHeadlessPinInput extends MixinControllerValue(MixinField(HelixFormElement)) {
     constructor() {
         super(...arguments);
         this.aria = new AriaForwardController(this, {
-            target: () => this.partNamed('field'),
+            target: () => this.control,
         });
         this.announcesInput = true;
         this.autocomplete = 'one-time-code';
         this.autosubmit = false;
+        this.case = 'preserve';
         this.cellLabel = 'Character {index} of {length}';
         this.format = '';
         this.length = 6;
         this.mask = false;
+        this.maskCharacter = '•';
         this.placeholder = '';
         this.readOnly = false;
         this.type = 'numeric';
+        this.active = -1;
+        this.pressedAt = undefined;
         this.handleInput = (event) => {
             event.stopPropagation();
-            const cell = event.target;
-            const at = this.cells.indexOf(cell);
-            if (at === -1) {
-                return;
-            }
-            if (cell.value === '') {
-                const characters = this.characters;
-                characters[at] = '';
-                this.requestValue(characters.join(''));
-                this.updateComplete.then(() => {
-                    this.paint();
-                    this.cells[at]?.focus();
-                });
-                return;
-            }
-            this.write(at, cell.value);
-            this.updateComplete.then(() => this.paint());
+            const control = event.target;
+            this.take(readTyped(control.value, control.selectionStart ?? control.value.length, this.type, this.case, this.count));
         };
         this.handlePaste = (event) => {
-            const cell = event.target;
-            const at = this.cells.indexOf(cell);
-            if (at === -1 || this.isDisabled || this.readOnly) {
+            event.preventDefault();
+            const control = this.control;
+            if (!control || this.isDisabled || this.readOnly) {
                 return;
             }
-            event.preventDefault();
-            this.write(at, event.clipboardData?.getData('text') ?? '');
+            const text = cleanCode(event.clipboardData?.getData('text') ?? '', this.type, this.case);
+            if (text === '') {
+                return;
+            }
+            const start = control.selectionStart ?? this.end;
+            const end = control.selectionEnd ?? start;
+            const kept = end - start > 1 ? this.value.slice(0, start) + this.value.slice(end) : this.value;
+            this.take(overwriteCode(kept, start, text, this.count));
         };
         this.handleKeydown = (event) => {
-            const cell = event.target;
-            const at = this.cells.indexOf(cell);
-            if (at === -1 || this.isDisabled || this.readOnly) {
+            if (event.isComposing || this.isDisabled) {
                 return;
             }
-            const step = event.key === 'ArrowRight' ? 1 : event.key === 'ArrowLeft' ? -1 : 0;
-            const to = event.key === 'Home'
-                ? 0
-                : event.key === 'End'
-                    ? Math.min(this.value.length, this.count - 1)
-                    : at + step;
-            if (event.key === 'Delete' && at < this.value.length) {
-                const characters = this.characters;
-                characters.splice(at, 1);
-                this.requestValue(characters.join('').replace(/\s+$/, ''));
-                this.updateComplete.then(() => {
-                    this.paint();
-                    this.cells[at]?.focus();
-                });
-            }
-            else if (event.key === 'Backspace' && cell.value === '' && at > 0) {
-                const characters = this.characters;
-                characters[at - 1] = '';
-                this.requestValue(characters.join('').replace(/\s+$/, ''));
-                this.updateComplete.then(() => {
-                    this.paint();
-                    this.cells[at - 1]?.focus();
-                });
-            }
-            else if (to !== at && to >= 0 && to < this.count) {
-                this.cells[to]?.focus();
-                this.cells[to]?.select();
+            if (this.readOnly) {
+                if (event.key === 'Backspace' || event.key === 'Delete') {
+                    event.preventDefault();
+                }
+                return;
             }
-            else {
+            const to = event.key === 'ArrowRight'
+                ? this.caretBox + 1
+                : event.key === 'ArrowLeft'
+                    ? this.caretBox - 1
+                    : event.key === 'Home'
+                        ? 0
+                        : event.key === 'End'
+                            ? this.end
+                            : undefined;
+            if (to === undefined) {
                 return;
             }
             event.preventDefault();
+            this.active = Math.max(0, Math.min(to, this.end));
+            this.placeCaret(true);
         };
-        this.committed = '';
-        this.handleFocus = (event) => {
-            ;
-            event.target.select();
-        };
-        this.within = false;
-        this.handleFocusIn = () => {
-            if (this.within) {
+        this.handlePress = (event) => {
+            const control = this.control;
+            if (!control || this.isDisabled) {
                 return;
             }
-            this.within = true;
-            this.committed = this.value;
-        };
-        this.handleFocusOut = (event) => {
-            if (this.cells.includes(event.relatedTarget)) {
+            const boxes = [...this.renderRoot.querySelectorAll('[part~="cell"]')];
+            const box = event.target.closest('[part~="cell"]');
+            const at = box ? boxes.indexOf(box) : this.end;
+            if (this.shadowRoot?.activeElement === control) {
+                if (!this.readOnly) {
+                    this.active = Math.min(at, this.end);
+                    this.placeCaret(true);
+                }
                 return;
             }
-            this.within = false;
+            this.pressedAt = at;
+            control.focus();
+        };
+        this.committed = '';
+        this.handleFocus = () => {
+            this.committed = this.value;
+            this.active = this.readOnly ? -1 : Math.min(this.pressedAt ?? this.end, this.end);
+            this.pressedAt = undefined;
+            this.placeCaret(true);
+        };
+        this.handleBlur = () => {
+            this.active = -1;
             this.commit();
         };
         this.handleKeypress = (event) => {
             if (event.key === 'Enter' && !event.defaultPrevented) {
-                this.submitImplicitly();
+                submitImplicitly(this.form);
             }
         };
     }
-    get namedControl() {
-        return this.partNamed('field');
-    }
     static { this.shadowRootOptions = {
         ...HelixFormElement.shadowRootOptions,
         delegatesFocus: true,
@@ -128,56 +119,45 @@ let HelixHeadlessPinInput = class HelixHeadlessPinInput extends MixinControllerV
     get count() {
         return Math.max(1, Math.floor(this.length) || 1);
     }
-    get cells() {
-        return [...this.renderRoot.querySelectorAll('[part="cell"]')];
+    get control() {
+        return this.partNamed('control');
     }
-    get characters() {
-        return Array.from({ length: this.count }, (_, at) => this.value[at] ?? '');
+    get end() {
+        return Math.min(this.value.length, this.count - 1);
     }
-    clean(text) {
-        const trimmed = text.trim();
-        if (this.type === 'numeric') {
-            return trimmed.replace(/\D/g, '');
-        }
-        if (this.type === 'alphanumeric') {
-            return trimmed.replace(/[^0-9A-Za-z]/g, '');
-        }
-        return trimmed;
+    get caretBox() {
+        return this.active < 0 ? -1 : Math.min(this.active, this.end);
     }
-    write(from, text) {
-        const cleaned = this.clean(text);
-        if (cleaned === '') {
-            return;
+    take({ caret, code }) {
+        const applied = this.requestValue(code);
+        const control = this.control;
+        if (control) {
+            restoreValue(control, this.value);
         }
-        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) {
-            characters[start + at] = cleaned[at];
+        if (this.active >= 0 && applied) {
+            this.active = caret;
         }
-        const next = characters.join('');
-        const filled = Math.min(this.count - 1, start + cleaned.length);
-        const applied = this.requestValue(next);
-        this.updateComplete.then(() => {
-            this.paint();
-            this.cells[filled]?.focus();
-            this.cells[filled]?.select();
-            if (applied && this.value === next && next.length === this.count) {
-                this.dispatchEvent(new HelixCompleteEvent({ value: next }));
-                this.commit();
-                if (this.autosubmit) {
-                    this.submitImplicitly();
-                }
+        this.placeCaret(true);
+        if (applied && this.value === code && code.length === this.count) {
+            this.dispatchEvent(new HelixCompleteEvent({ value: code }));
+            this.commit();
+            if (this.autosubmit) {
+                submitImplicitly(this.form);
             }
-        });
+        }
     }
-    paint() {
-        const characters = this.characters;
-        for (const [at, cell] of this.cells.entries()) {
-            const want = characters[at] ?? '';
-            if (cell.value !== want) {
-                cell.value = want;
-            }
+    placeCaret(force = false) {
+        const control = this.control;
+        const at = this.caretBox;
+        if (!control || at < 0) {
+            return;
+        }
+        const start = control.selectionStart ?? 0;
+        const end = control.selectionEnd ?? start;
+        if (!force && end - start > 1) {
+            return;
         }
+        control.setSelectionRange(at, at < this.value.length ? at + 1 : at);
     }
     commit() {
         if (this.value === this.committed) {
@@ -188,34 +168,34 @@ let HelixHeadlessPinInput = class HelixHeadlessPinInput extends MixinControllerV
     }
     sync() {
         this.internals.setFormValue(this.value);
-        const first = this.cells[0];
-        if (!first) {
+        const control = this.control;
+        if (!control) {
             return;
         }
         if (this.required && this.value === '') {
-            this.internals.setValidity({ valueMissing: true }, this.valueMissingMessage || 'Please fill in this field.', first);
+            this.internals.setValidity({ valueMissing: true }, this.valueMissingMessage || 'Please fill in this field.', control);
         }
         else if (this.value !== '' && this.value.length < this.count) {
             this.internals.setValidity({ tooShort: true }, fillTemplate(this.tooShortMessage || 'Please enter all {length} characters.', {
                 length: this.count,
-            }), first);
+            }), control);
         }
         else {
-            this.internals.setValidity({}, '', first);
+            this.internals.setValidity({}, '', control);
         }
         this.refreshFeedback();
     }
     focus(options) {
-        const cells = this.cells;
-        const at = Math.min(this.value.length, cells.length - 1);
-        cells[at]?.focus(options);
+        this.control?.focus(options);
     }
     clear() {
         this.requestValue('');
-        this.updateComplete.then(() => {
-            this.paint();
-            this.cells[0]?.focus();
-        });
+        const control = this.control;
+        if (control) {
+            restoreValue(control, this.value);
+            this.pressedAt = 0;
+            control.focus();
+        }
     }
     firstUpdated(changed) {
         super.firstUpdated(changed);
@@ -223,44 +203,63 @@ let HelixHeadlessPinInput = class HelixHeadlessPinInput extends MixinControllerV
     }
     updated(changed) {
         super.updated(changed);
-        this.paint();
+        this.toggleState('complete', this.value.length >= this.count);
         this.sync();
+        this.placeCaret();
     }
     get blocksImplicitSubmission() {
         return true;
     }
+    renderBox(character, at) {
+        const caret = at === this.caretBox;
+        const content = character !== ''
+            ? this.mask
+                ? this.maskCharacter
+                : character
+            : caret
+                ? html `<span part="caret"></span>`
+                : this.placeholder
+                    ? html `<span part="placeholder">${this.placeholder}</span>`
+                    : nothing;
+        return html `<div
+      part="cell${caret ? ' cell-active' : ''}${character === '' ? '' : ' cell-filled'}"
+      aria-hidden="true"
+    >${content}</div>`;
+    }
     render() {
-        const characters = this.characters;
         const separators = separatorsAfter(this.format, this.count);
-        return html `${this.renderGroupLabel()}
+        return html `${this.renderLabel()}
       <div
         dir="ltr"
         part="field"
-        role="group"
-        aria-describedby=${this.describedBy ?? nothing}
-        aria-labelledby=${this.labeled ? this.labelId : nothing}
-        @focusin=${this.handleFocusIn}
-        @focusout=${this.handleFocusOut}
+        @click=${this.handlePress}
+        @mousedown=${keepFocus}
       >
-        ${characters.map((character, at) => html `<input
-            part="cell"
-            .value=${character}
-            type=${this.mask ? 'password' : 'text'}
-            placeholder=${this.placeholder || nothing}
-            inputmode=${this.type === 'numeric' ? 'numeric' : 'text'}
-            autocomplete=${at === 0 ? this.autocomplete || nothing : 'off'}
-            aria-label=${fillTemplate(this.cellLabel, { index: at + 1, length: this.count })}
-            aria-invalid=${this.invalidity ?? nothing}
-            ?disabled=${this.isDisabled}
-            ?readonly=${this.readOnly}
-            @focus=${this.handleFocus}
-            @input=${this.handleInput}
-            @keydown=${this.handleKeydown}
-            @keypress=${this.handleKeypress}
-            @paste=${this.handlePaste}
-          />${separators[at]
-            ? html `<span part="separator" aria-hidden="true">${separators[at]}</span>`
-            : nothing}`)}
+        <input
+          part="control"
+          id=${this.controlId}
+          style=${UNSEEN}
+          .value=${this.value}
+          type=${this.mask ? 'password' : 'text'}
+          inputmode=${this.type === 'numeric' ? 'numeric' : 'text'}
+          autocomplete=${this.autocomplete || nothing}
+          aria-describedby=${this.describedBy ?? nothing}
+          aria-invalid=${this.invalidity ?? nothing}
+          aria-required=${this.required ? 'true' : nothing}
+          ?disabled=${this.isDisabled}
+          ?readonly=${this.readOnly}
+          @blur=${this.handleBlur}
+          @focus=${this.handleFocus}
+          @input=${this.handleInput}
+          @keydown=${this.handleKeydown}
+          @keypress=${this.handleKeypress}
+          @paste=${this.handlePaste}
+        />${Array.from({ length: this.count }, (_, at) => {
+            const separator = separators[at];
+            return html `${this.renderBox(this.value[at] ?? '', at)}${separator
+                ? html `<span part="separator" aria-hidden="true">${separator}</span>`
+                : nothing}`;
+        })}
       </div>
       ${this.renderHint()}${this.renderFeedback()}`;
     }
@@ -271,6 +270,9 @@ __decorate([
 __decorate([
     property({ type: Boolean })
 ], HelixHeadlessPinInput.prototype, "autosubmit", void 0);
+__decorate([
+    property()
+], HelixHeadlessPinInput.prototype, "case", void 0);
 __decorate([
     property({ attribute: 'cell-label' })
 ], HelixHeadlessPinInput.prototype, "cellLabel", void 0);
@@ -283,6 +285,9 @@ __decorate([
 __decorate([
     property({ reflect: true, type: Boolean })
 ], HelixHeadlessPinInput.prototype, "mask", void 0);
+__decorate([
+    property({ attribute: 'mask-character' })
+], HelixHeadlessPinInput.prototype, "maskCharacter", void 0);
 __decorate([
     property()
 ], HelixHeadlessPinInput.prototype, "placeholder", void 0);
@@ -295,6 +300,9 @@ __decorate([
 __decorate([
     property()
 ], HelixHeadlessPinInput.prototype, "type", void 0);
+__decorate([
+    state()
+], HelixHeadlessPinInput.prototype, "active", void 0);
 HelixHeadlessPinInput = __decorate([
     customElement('helix-headless-pin-input')
 ], HelixHeadlessPinInput);

package/dist/popover/hide-outside.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Hides everything on the page from assistive technology except `kept`, and
+ * returns a function that shows it again.
+ *
+ * Climbs from each kept element to the top of the document, through any shadow
+ * root it is in, and marks every sibling on the way that holds no kept element
+ * with `aria-hidden="true"`. What already says `aria-hidden` is left as it is,
+ * and given back as it was. Live regions are kept, so a message that arrives
+ * while the page is hidden is still announced.
+ *
+ * What a modal popover rests on: `Tab` is kept inside the panel, and this keeps
+ * a screen reader's virtual cursor there too.
+ */
+export declare const hideOutside: (kept: readonly Element[]) => (() => void);

package/dist/popover/hide-outside.js

@@ -0,0 +1,34 @@
+import { deepContains } from '@fusion.dev/helix-core';
+const KEEP = 'script, style, template, link, meta, [aria-live], [role="alert"], [role="log"], [role="status"]';
+export const hideOutside = (kept) => {
+    const hidden = [];
+    const holds = (element) => kept.some((one) => deepContains(element, one));
+    const seen = new Set();
+    for (const start of kept) {
+        let node = start;
+        while (node && node !== document.documentElement) {
+            const parent = node.parentNode;
+            if (!parent || seen.has(parent)) {
+                break;
+            }
+            seen.add(parent);
+            for (const sibling of parent.children ?? []) {
+                if (sibling === node ||
+                    holds(sibling) ||
+                    sibling.matches(KEEP) ||
+                    sibling.hasAttribute('aria-hidden')) {
+                    continue;
+                }
+                sibling.setAttribute('aria-hidden', 'true');
+                hidden.push(sibling);
+            }
+            node = parent instanceof ShadowRoot ? parent.host : parent;
+        }
+    }
+    return () => {
+        for (const one of hidden) {
+            one.removeAttribute('aria-hidden');
+        }
+        hidden.length = 0;
+    };
+};

package/dist/popover/root/popover-root.d.ts

@@ -1,4 +1,4 @@
-import { AriaForwardController, CommandController, HelixElement, type Placement } from '@fusion.dev/helix-core';
+import { AriaForwardController, CommandController, HelixElement, OpenPhaseController, type Placement } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
 declare const HelixHeadlessPopover_base: (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerOpenInterface) & typeof HelixElement;
 /**
@@ -9,9 +9,11 @@ declare const HelixHeadlessPopover_base: (new (...args: any[]) => import("@fusio
  * commands, `Select` holds options, and `Tooltip` holds a description. Popover
  * holds any content you put in it, so it has no keyboard handling of its own.
  *
- * The trigger is slotted and stays your own element. The popover writes nothing
- * onto it, including `aria-expanded`, `id`, and `tabindex`, because changing
- * your markup after upgrade causes a React hydration mismatch.
+ * The trigger is slotted and stays your own element. A Helix trigger is told
+ * whether the popover is open inside its own shadow root. On a plain element,
+ * such as a `<button>`, the popover writes `aria-expanded` only once a reader
+ * has pressed it, which is after any hydration, and never where you wrote
+ * `aria-expanded` yourself. It writes nothing else onto your markup.
  *
  * The panel is in the top layer through the popover API, so it needs no
  * `z-index`, and an ancestor with `overflow: hidden`, `transform`, `filter`, or
@@ -28,7 +30,9 @@ declare const HelixHeadlessPopover_base: (new (...args: any[]) => import("@fusio
  *
  * `modal` keeps `Tab` inside the panel while it is open and says so with
  * `aria-modal`, for a panel that has to be answered before the page goes on.
- * Without it the popover does not trap focus.
+ * The rest of the page is hidden from screen readers with `aria-hidden` while
+ * it is open, so the virtual cursor stays in the panel too. Without it the
+ * popover does not trap focus.
  *
  * The panel's name is `label` when you set it. Otherwise it is the first
  * heading in the panel, or the elements an `aria-labelledby` on the host names.
@@ -65,6 +69,11 @@ declare const HelixHeadlessPopover_base: (new (...args: any[]) => import("@fusio
  * @csspart content - The scrolling region inside the panel.
  * @csspart popover - The panel.
  *
+ * @cssproperty --floating-anchor-inline-size - The trigger's width, written on the panel while it is open, as in `min-inline-size: var(--floating-anchor-inline-size)`. Read it; a value set here is written over.
+ * @cssproperty --floating-available-block-size - The room between the panel and the edge of the screen it opens toward, written on the panel while it is open. Read it; a value set here is written over.
+ *
+ * @cssstate entering - From the moment the panel shows until its entrance has finished.
+ * @cssstate exiting - From the moment the panel hides until its exit has finished.
  * @cssstate open - While the popover is open.
  * @cssstate placed-bottom - While the panel sits below its trigger.
  * @cssstate placed-left - While the panel sits to the left of its trigger.
@@ -85,8 +94,9 @@ export declare class HelixHeadlessPopover extends HelixHeadlessPopover_base {
      */
     label: string;
     /**
-     * Keeps `Tab` inside the panel while it is open, and marks the panel
-     * `aria-modal`. A press outside and Escape still close it.
+     * Keeps `Tab` inside the panel while it is open, marks the panel
+     * `aria-modal`, and hides the rest of the page from screen readers. A press
+     * outside and Escape still close it.
      */
     modal: boolean;
     protected readonly aria: AriaForwardController;
@@ -100,6 +110,7 @@ export declare class HelixHeadlessPopover extends HelixHeadlessPopover_base {
      * It moves if that side does not fit.
      */
     placement: Placement;
+    protected readonly phases: OpenPhaseController;
     private readonly panel;
     /**
      * The side of its trigger the panel last landed on, which names the arrow's
@@ -138,6 +149,26 @@ export declare class HelixHeadlessPopover extends HelixHeadlessPopover_base {
     show(): void;
     /** Closes the panel and puts focus back on the trigger. */
     hide(): void;
+    /**
+     * Closes the panel, giving focus back to the trigger where `giveBack` is set
+     * and focus is inside the panel that is going away. A popover dismissed by a
+     * press somewhere else has not taken focus with it, and pulling focus back to
+     * the trigger would move a reader who was already somewhere else on purpose.
+     */
+    private close;
+    /**
+     * Whether focus is in the panel, on the panel itself or on anything slotted
+     * into it. `deepActiveElement`, which walks into shadow roots:
+     * `document.activeElement` stops at the outermost host, so a popover living
+     * inside another component's shadow root would never see its own focus.
+     */
+    private get focusInside();
+    /**
+     * Whether the update under way closes the panel while focus is inside it,
+     * read before the panel is hidden and focus has fallen to the body.
+     */
+    private closingFromInside;
+    protected willUpdate(changed: PropertyValues): void;
     /**
      * Focus leaving the control closes the panel.
      *
@@ -149,10 +180,35 @@ export declare class HelixHeadlessPopover extends HelixHeadlessPopover_base {
      */
     private readonly handleFocusOut;
     connectedCallback(): void;
+    /**
+     * A press on the slotted trigger, heard on the host on the way down, before
+     * the trigger slot's own listener opens the panel and the update that
+     * schedules reads it in `tellTrigger`.
+     */
+    private readonly notePress;
     disconnectedCallback(): void;
     private readonly handleTriggerClick;
-    /** Tells a slotted trigger the disclosure state, by property. See `tellDisclosure`. */
+    /** Whether a reader has pressed the trigger, which is after any hydration. */
+    private pressed;
+    /** The plain trigger this popover writes `aria-expanded` on, once it may. */
+    private told;
+    /**
+     * Tells a slotted trigger the disclosure state.
+     *
+     * A Helix trigger by property, through `tellDisclosure`. A plain element,
+     * which has no shadow root to keep the state out of the markup, by
+     * `aria-expanded`, and only from a reader's first press on: by then a server
+     * or a framework has long finished writing the element, so the write cannot
+     * be a hydration mismatch. One that already carries `aria-expanded` is the
+     * consumer's to keep, and is left alone.
+     */
     private tellTrigger;
+    /** Whether the first update, which is the server's, has passed. */
+    private settled;
+    /** Shows the page again, while a modal panel has it hidden. */
+    private showOutside;
+    /** Hides the page outside a modal panel while it is open, and shows it again after. */
+    private hideAround;
     /**
      * Puts the panel where `open` says it should be, however it got there.
      *