@fusion.dev/helix-core 0.142.0 → 0.143.0

package/dist/controllers/aria-forward-controller/aria-forward-controller.d.ts

@@ -1,6 +1,34 @@
 import type { ReactiveController, ReactiveControllerHost } from 'lit';
 /** What the controller needs to know: which element inside is the control. */
 export interface AriaForwardOptions {
+    /**
+     * Whether a host `aria-label` names the control too.
+     *
+     * For a control named by its content, a button or a switch, which has no
+     * `label` to render it into. A field renders its `aria-label` as a clipped
+     * label already, so it leaves this off. A function is asked on every
+     * forward, for a subclass that names the control itself.
+     */
+    label?: boolean | (() => boolean);
+    /**
+     * Elements read after whatever names the control from outside, the host's
+     * `aria-labelledby` or its `<label>`.
+     *
+     * For a control whose name is the label and then what it shows, as a
+     * native `<select>` is named. Added only where the host gives a name, so a
+     * control named by its own template keeps its own.
+     */
+    labelledByAfter?: () => Element[];
+    /**
+     * Whether the control has a name of its own, where its own labels do not
+     * say.
+     *
+     * A file input is labeled by the trigger that opens its picker, "Choose
+     * files", which is an action rather than a name, so a page's `<label>`
+     * should still name it. Absent, the control's own `aria-label`,
+     * `aria-labelledby` and labels with words in them decide.
+     */
+    named?: () => boolean;
     /** The focusable thing in the shadow root, or null before it renders. */
     target: () => HTMLElement | null;
 }
@@ -42,6 +70,13 @@ export interface AriaForwardOptions {
  * a framework rendering a tooltip after this element upgrades, or a consumer
  * pointing `aria-describedby` at a different id, changes an attribute and
  * nothing schedules a Lit update.
+ *
+ * **A `<label>` that names the host names the control too**, when the control
+ * has no name of its own. The platform gives a form-associated host its labels
+ * and the host is a generic the reader never lands on, so a `<label for>` or a
+ * wrapping `<label>` left the textbox unnamed. The labels travel the same way a
+ * forwarded `aria-labelledby` does, as element references, and are read again
+ * when focus arrives, since a label can be added without the host hearing.
  */
 export declare class AriaForwardController implements ReactiveController {
     private readonly host;
@@ -51,7 +86,25 @@ export declare class AriaForwardController implements ReactiveController {
     private readonly forwarded;
     /** The control the record above is about, so a replacement resets it. */
     private recorded;
+    /** Whether a host `aria-label` is carried down. See the option. */
+    private readonly asked;
+    private get label();
+    /** The component's own answer to whether the control is named. See the option. */
+    private readonly named;
+    /** What is read after the host's names. See the option. */
+    private readonly after;
     constructor(host: ReactiveControllerHost & HTMLElement, options: AriaForwardOptions);
+    /**
+     * Whether the control has a name that did not come from this controller: an
+     * `aria-label`, an `aria-labelledby` of its own, or a label of its own with
+     * words in it.
+     */
+    private namedByItself;
+    /**
+     * The labels the platform associated with the host, for a control with no
+     * name of its own, and none otherwise.
+     */
+    private hostLabels;
     /**
      * Resolves the host's references and hands them to the control.
      *
@@ -65,5 +118,7 @@ export declare class AriaForwardController implements ReactiveController {
     forward(): void;
     hostConnected(): void;
     hostDisconnected(): void;
+    /** Forwards again as focus arrives, for a label added since the last update. */
+    private readonly refresh;
     hostUpdated(): void;
 }

package/dist/controllers/aria-forward-controller/aria-forward-controller.js

@@ -1,16 +1,61 @@
 import { elementById } from '../../utils/element-by-id/element-by-id.js';
+const shownText = (node) => {
+    if (node instanceof HTMLSlotElement) {
+        return node.assignedNodes({ flatten: true }).map(shownText).join('');
+    }
+    if (node.nodeType === Node.TEXT_NODE) {
+        return node.textContent ?? '';
+    }
+    if (node instanceof HTMLElement && node.hidden) {
+        return '';
+    }
+    return [...node.childNodes].map(shownText).join('');
+};
 const RELATIONSHIPS = [
     ['aria-describedby', 'ariaDescribedByElements'],
     ['aria-labelledby', 'ariaLabelledByElements'],
 ];
-const STATES = ['aria-expanded', 'aria-haspopup', 'aria-controls', 'aria-invalid'];
+const STATES = [
+    'aria-expanded',
+    'aria-haspopup',
+    'aria-controls',
+    'aria-invalid',
+    'aria-pressed',
+];
 export class AriaForwardController {
+    get label() {
+        return typeof this.asked === 'function' ? this.asked() : this.asked;
+    }
     constructor(host, options) {
         this.forwarded = new Set();
+        this.refresh = () => {
+            this.forward();
+        };
         this.host = host;
         this.target = options.target;
+        this.asked = options.label ?? false;
+        this.named = options.named;
+        this.after = options.labelledByAfter;
         host.addController(this);
     }
+    namedByItself(target) {
+        if (target.getAttribute('aria-label')) {
+            return true;
+        }
+        if (!this.forwarded.has('aria-labelledby') && target.hasAttribute('aria-labelledby')) {
+            return true;
+        }
+        const own = target.labels;
+        return [...(own ?? [])].some((label) => shownText(label).trim() !== '');
+    }
+    hostLabels(target) {
+        const labels = this.host.labels;
+        const named = this.named ? this.named() : this.namedByItself(target);
+        if (!labels || labels.length === 0 || named) {
+            return [];
+        }
+        return [...labels].filter((label) => label instanceof HTMLElement);
+    }
     forward() {
         const target = this.target();
         if (!target) {
@@ -20,17 +65,34 @@ export class AriaForwardController {
             this.forwarded.clear();
             this.recorded = target;
         }
+        for (const attribute of this.label ? [...STATES, 'aria-label'] : STATES) {
+            const value = this.host.getAttribute(attribute);
+            if (value === null) {
+                if (this.forwarded.has(attribute)) {
+                    target.removeAttribute(attribute);
+                    this.forwarded.delete(attribute);
+                }
+                continue;
+            }
+            target.setAttribute(attribute, value);
+            this.forwarded.add(attribute);
+        }
         for (const [attribute, property] of RELATIONSHIPS) {
             if (!(property in target)) {
                 continue;
             }
             const ids = (this.host.getAttribute(attribute) ?? '').split(/\s+/).filter(Boolean);
-            const elements = ids
+            const referenced = ids
                 .map((id) => elementById(this.host, id))
                 .filter((element) => element !== null);
+            const elements = referenced.length === 0 && attribute === 'aria-labelledby'
+                ? this.hostLabels(target)
+                : referenced;
             const reflect = target;
             if (elements.length > 0) {
-                reflect[property] = elements;
+                const after = attribute === 'aria-labelledby' ? (this.after?.() ?? []) : [];
+                const named = elements;
+                reflect[property] = [...named, ...after.filter((one) => !named.includes(one))];
                 this.forwarded.add(attribute);
                 continue;
             }
@@ -39,28 +101,22 @@ export class AriaForwardController {
                 this.forwarded.delete(attribute);
             }
         }
-        for (const attribute of STATES) {
-            const value = this.host.getAttribute(attribute);
-            if (value === null) {
-                if (this.forwarded.has(attribute)) {
-                    target.removeAttribute(attribute);
-                    this.forwarded.delete(attribute);
-                }
-                continue;
-            }
-            target.setAttribute(attribute, value);
-            this.forwarded.add(attribute);
-        }
     }
     hostConnected() {
         this.observer = new MutationObserver(() => this.forward());
         this.observer.observe(this.host, {
-            attributeFilter: [...RELATIONSHIPS.map(([attribute]) => attribute), ...STATES],
+            attributeFilter: [
+                ...RELATIONSHIPS.map(([attribute]) => attribute),
+                ...STATES,
+                ...(this.asked === false ? [] : ['aria-label']),
+            ],
         });
+        this.host.addEventListener('focusin', this.refresh);
     }
     hostDisconnected() {
         this.observer?.disconnect();
         this.observer = undefined;
+        this.host.removeEventListener('focusin', this.refresh);
     }
     hostUpdated() {
         this.forward();

package/dist/controllers/arrival-controller/arrival-controller.d.ts

@@ -5,6 +5,11 @@ export interface ArrivalOptions {
     text: () => string;
     /** Whether the element is arriving now, rather than with the page. */
     arriving: () => boolean;
+    /**
+     * How long the region keeps the words once it has said them, in
+     * milliseconds. Defaults to seven seconds.
+     */
+    hold?: number;
 }
 /**
  * The words of an element that is announced when it appears, for a region that
@@ -24,6 +29,12 @@ export interface ArrivalOptions {
  * second time on the headless tier, which has no sheet to clip the region, and
  * a served page changed its picture on hydrating.
  *
+ * **And emptied again once it has been heard.** The words stay in the element
+ * itself, so a region that kept its copy put the message in the accessibility
+ * tree twice, and a reader moving through the page met it twice. The region
+ * keeps the copy for `hold` and then lets it go, which a polite region does not
+ * read out, removals being no news.
+ *
  * The component renders `said` into its region and calls `say` when what it
  * holds changes, from a `slotchange`.
  */
@@ -35,6 +46,7 @@ export declare class ArrivalController implements ReactiveController {
     /** The words last accounted for, said or not. */
     private heard;
     private frame;
+    private timer;
     constructor(host: ReactiveControllerHost, options: ArrivalOptions);
     hostConnected(): void;
     hostDisconnected(): void;

package/dist/controllers/arrival-controller/arrival-controller.js

@@ -1,3 +1,4 @@
+const HOLD = 7000;
 export class ArrivalController {
     constructor(host, options) {
         this.host = host;
@@ -22,6 +23,9 @@ export class ArrivalController {
     hostDisconnected() {
         cancelAnimationFrame(this.frame);
         this.frame = 0;
+        clearTimeout(this.timer);
+        this.timer = undefined;
+        this.said = '';
     }
     say() {
         const next = this.options.text();
@@ -31,5 +35,11 @@ export class ArrivalController {
         this.heard = next;
         this.said = next;
         this.host.requestUpdate();
+        clearTimeout(this.timer);
+        this.timer = setTimeout(() => {
+            this.timer = undefined;
+            this.said = '';
+            this.host.requestUpdate();
+        }, this.options.hold ?? HOLD);
     }
 }

package/dist/controllers/chart-pointer-controller/chart-pointer-controller.d.ts

@@ -110,6 +110,16 @@ export declare class ChartPointerController implements ReactiveController {
      * can change its direction without the chart updating.
      */
     get mirrored(): boolean;
+    /**
+     * Whether a pointer event may move the reading, which only a mouse or a pen
+     * may.
+     *
+     * Public for a chart that hears the pointer itself, a donut's slices and a
+     * heatmap's cells, so the rule a coarse pointer gets is this one everywhere.
+     * Heard unfiltered, a touch opened the bubble under the finger and left it
+     * there after the finger lifted.
+     */
+    accepts(event: Event): boolean;
     /** Puts the pointer on a reading, for a chart that resolves it some other way. */
     set(at: number): void;
     private readonly move;

package/dist/controllers/chart-pointer-controller/chart-pointer-controller.js

@@ -5,7 +5,7 @@ export class ChartPointerController {
         this.at = -1;
         this.axis = 'inline';
         this.move = (event) => {
-            if (this.axis === 'none' || (event.pointerType !== 'mouse' && event.pointerType !== 'pen')) {
+            if (this.axis === 'none' || !this.accepts(event)) {
                 return;
             }
             const box = this.box();
@@ -63,6 +63,10 @@ export class ChartPointerController {
     get mirrored() {
         return isRtl(this.host);
     }
+    accepts(event) {
+        const type = event.pointerType;
+        return type === 'mouse' || type === 'pen';
+    }
     set(at) {
         if (at !== this.at) {
             this.at = at;

package/dist/controllers/copy-controller/copy-controller.js

@@ -1,4 +1,5 @@
 import { HelixCopyEvent } from '../../events/events.js';
+import { deepActiveElement } from '../../utils/focusable-elements/focusable-elements.js';
 const write = async (text) => {
     try {
         await navigator.clipboard.writeText(text);
@@ -6,6 +7,7 @@ const write = async (text) => {
     }
     catch {
     }
+    const had = deepActiveElement();
     const carrier = document.createElement('textarea');
     carrier.value = text;
     carrier.setAttribute('readonly', '');
@@ -22,6 +24,9 @@ const write = async (text) => {
         wrote = false;
     }
     carrier.remove();
+    if (had instanceof HTMLElement || had instanceof SVGElement) {
+        had.focus({ preventScroll: true });
+    }
     return wrote;
 };
 export class CopyController {

package/dist/controllers/dismiss-controller/dismiss-controller.js

@@ -8,6 +8,35 @@ const deepDepth = (node) => {
     }
     return depth;
 };
+const modalAround = (event) => {
+    for (const node of event.composedPath()) {
+        if (node instanceof HTMLDialogElement && node.open) {
+            try {
+                if (node.matches(':modal')) {
+                    return node;
+                }
+            }
+            catch {
+                return undefined;
+            }
+        }
+    }
+    return undefined;
+};
+const flatContains = (container, node) => {
+    let at = node;
+    while (at) {
+        if (at === container) {
+            return true;
+        }
+        at =
+            at.assignedSlot ??
+                at.parentNode ??
+                at.host ??
+                null;
+    }
+    return false;
+};
 const REGISTRY = Symbol.for('fusion.helix.dismiss.listening');
 const globals = globalThis;
 if (globals[REGISTRY] === undefined) {
@@ -26,15 +55,23 @@ export class DismissController {
                 return;
             }
             taken.helixDismissTaken = true;
-            let deepest = this;
-            let found = deepDepth(this.host);
-            for (const other of listening) {
+            const modal = modalAround(event);
+            let deepest;
+            let found = -1;
+            for (const other of [this, ...listening]) {
+                if (modal && !flatContains(modal, other.host)) {
+                    continue;
+                }
                 const depth = deepDepth(other.host);
                 if (depth > found) {
                     found = depth;
                     deepest = other;
                 }
             }
+            if (!deepest) {
+                return;
+            }
+            event.preventDefault();
             deepest.onDismiss();
         };
         this.handleWindowBlur = () => {

package/dist/controllers/keyboard-navigation-controller/keyboard-navigation-controller.d.ts

@@ -62,6 +62,15 @@ export interface KeyboardNavigationOptions {
      * could not be opened from the keyboard at all.
      */
     reserved?: () => string[];
+    /**
+     * The words of an item, which turns on typeahead: a printable key moves to
+     * the next item whose words start with what was typed.
+     *
+     * Off unless given. A set whose items have no words a reader would type, or
+     * that holds a text field of its own, leaves it out. See `Typeahead` for how
+     * the letters are matched.
+     */
+    typeahead?: (item: NavigableItem) => string;
     /**
      * Whether the ends join up, which they do unless a set says otherwise.
      *
@@ -82,6 +91,54 @@ export interface KeyboardNavigationOptions {
      */
     wrap?: boolean;
 }
+/**
+ * Whether a press types a character, which is what typeahead reads.
+ *
+ * One character with no Control, Command or Alt held, so a shortcut such as
+ * Control+A is never taken for the letter A. Shift is allowed, because a
+ * capital is still a letter.
+ */
+export declare const typesCharacter: (event: KeyboardEvent) => boolean;
+/**
+ * Finds an item by the letters a reader types at a set, the way a native
+ * `<select>` does.
+ *
+ * Letters typed within `timeout` milliseconds of each other build one search,
+ * so typing "ca" moves to "Canada" past "Cambodia". The same letter typed again
+ * moves to the next item that starts with it, so pressing "c" three times visits
+ * the first three. A pause starts a new search.
+ *
+ * Matching ignores case and leading spaces, and searches from the reader's
+ * position, wrapping at the end. A search that matches nothing moves nothing.
+ *
+ * Holds only the letters, so one instance serves any set: the caller passes the
+ * words of the items and where the reader is on every key.
+ */
+export declare class Typeahead {
+    private letters;
+    private last;
+    private readonly timeout;
+    constructor({ timeout }?: {
+        timeout?: number;
+    });
+    /**
+     * Whether a search is under way.
+     *
+     * A set that chooses on Space asks this first, because a Space typed in the
+     * middle of a search is part of the words, as in "New York".
+     */
+    typing(now?: number): boolean;
+    /**
+     * Adds a character to the search, and returns the index of the item it
+     * matches, or `-1` where none does.
+     *
+     * `texts` are the words of the items a reader can reach, in order, and
+     * `from` is the index of the item the reader is on, or `-1`.
+     */
+    match(key: string, texts: readonly string[], from: number, now?: number): number;
+    /** Ends the search, so the next letter starts a new one. */
+    reset(): void;
+}
 /**
  * Moves through a set of items with the arrow keys, and chooses as it goes.
  *
@@ -107,6 +164,11 @@ export interface KeyboardNavigationOptions {
  * Disabled items are skipped rather than stopped at, so a set with a gap in it
  * still moves in one press.
  *
+ * **Typeahead is opt-in.** Pass `typeahead` with a function that returns an
+ * item's words, and a printable key moves to the next item whose words start
+ * with the letters typed, choosing it where arriving chooses. A key that a text
+ * field inside the set is typing into is left to the field.
+ *
  * A set that starts from focus rather than from the selection, or that moves
  * without choosing, says so through `origin` and `selects`. Neither is a reason
  * to keep a hand-written copy, and neither exempts a set from both axes.
@@ -118,7 +180,23 @@ export declare class KeyboardNavigationController implements ReactiveController
     private readonly selects;
     private readonly reserved;
     private readonly wrap;
-    constructor(host: ReactiveControllerHost & HTMLElement, { items, origin, reserved, selects, wrap, }: KeyboardNavigationOptions);
+    private readonly words;
+    private readonly typeahead;
+    constructor(host: ReactiveControllerHost & HTMLElement, { items, origin, reserved, selects, typeahead, wrap, }: KeyboardNavigationOptions);
+    /** Moves to an item, and chooses it where arriving is choosing. */
+    private arrive;
+    /**
+     * Where the reader is: the item the press came from, or the selection.
+     *
+     * **Focus first, where nothing is chosen.** A reader who tabs into an
+     * unanswered set lands on its first item, and the selection then says `-1`.
+     * Starting from `-1`, a forward step lands on that same first item, so the
+     * first press appeared to do nothing and the second one moved. A native radio
+     * group moves to the second radio on that press, and so does this.
+     */
+    private current;
+    /** Moves to the item whose words start with what was typed, if any. */
+    private handleTypeahead;
     private readonly handleKeydown;
     hostConnected(): void;
     hostDisconnected(): void;

package/dist/controllers/keyboard-navigation-controller/keyboard-navigation-controller.js

@@ -1,10 +1,47 @@
 import { inlineStep } from '../../utils/inline-step/inline-step.js';
 import { keyClaimed } from '../../utils/key-claimed/key-claimed.js';
 const KEYS = new Set(['ArrowDown', 'ArrowLeft', 'ArrowRight', 'ArrowUp', 'End', 'Home']);
+export const typesCharacter = (event) => event.key.length === 1 && !event.ctrlKey && !event.metaKey && !event.altKey;
+export class Typeahead {
+    constructor({ timeout = 500 } = {}) {
+        this.letters = '';
+        this.last = 0;
+        this.timeout = timeout;
+    }
+    typing(now = Date.now()) {
+        return this.letters !== '' && now - this.last <= this.timeout;
+    }
+    match(key, texts, from, now = Date.now()) {
+        if (!this.typing(now)) {
+            this.letters = '';
+        }
+        this.last = now;
+        this.letters += key.toLowerCase();
+        const words = texts.map((text) => text.trim().toLowerCase());
+        const repeated = [...this.letters].every((letter) => letter === this.letters[0]);
+        const needle = repeated ? (this.letters[0] ?? '') : this.letters;
+        const start = repeated ? from + 1 : Math.max(from, 0);
+        for (let step = 0; step < words.length; step += 1) {
+            const at = (start + step) % words.length;
+            if (words[at]?.startsWith(needle)) {
+                return at;
+            }
+        }
+        return -1;
+    }
+    reset() {
+        this.letters = '';
+    }
+}
 export class KeyboardNavigationController {
-    constructor(host, { items, origin = 'selection', reserved = () => [], selects = () => true, wrap = true, }) {
+    constructor(host, { items, origin = 'selection', reserved = () => [], selects = () => true, typeahead, wrap = true, }) {
+        this.typeahead = new Typeahead();
         this.handleKeydown = (event) => {
-            if (!KEYS.has(event.key) || this.reserved().includes(event.key)) {
+            if (!KEYS.has(event.key)) {
+                this.handleTypeahead(event);
+                return;
+            }
+            if (this.reserved().includes(event.key)) {
                 return;
             }
             if (keyClaimed(event)) {
@@ -14,9 +51,7 @@ export class KeyboardNavigationController {
             if (items.length === 0) {
                 return;
             }
-            const current = this.origin === 'focus'
-                ? items.findIndex((item) => item.contains(event.target))
-                : items.findIndex((item) => item.selected);
+            const current = this.current(items, event);
             if (this.origin === 'focus' && current === -1) {
                 return;
             }
@@ -41,20 +76,55 @@ export class KeyboardNavigationController {
                 next = last;
             }
             event.preventDefault();
-            const target = items[next];
-            target?.focusItem();
-            if (this.selects()) {
-                target?.select();
-            }
+            this.typeahead.reset();
+            this.arrive(items[next]);
         };
         this.host = host;
         this.items = items;
         this.origin = origin;
         this.reserved = reserved;
         this.selects = selects;
+        this.words = typeahead;
         this.wrap = wrap;
         host.addController(this);
     }
+    arrive(target) {
+        target?.focusItem();
+        if (this.selects()) {
+            target?.select();
+        }
+    }
+    current(items, event) {
+        const path = event.composedPath().filter((node) => node instanceof Node);
+        const focused = items.findIndex((item) => path.some((node) => item.contains(node)));
+        if (this.origin === 'focus') {
+            return focused;
+        }
+        const selected = items.findIndex((item) => item.selected);
+        return selected < 0 ? focused : selected;
+    }
+    handleTypeahead(event) {
+        const words = this.words;
+        if (!words || !typesCharacter(event) || keyClaimed(event)) {
+            return;
+        }
+        if (event.key === ' ' && !this.typeahead.typing()) {
+            return;
+        }
+        const items = this.items().filter((item) => !item.disabled);
+        if (items.length === 0) {
+            return;
+        }
+        const from = this.current(items, event);
+        if (this.origin === 'focus' && from === -1) {
+            return;
+        }
+        const at = this.typeahead.match(event.key, items.map(words), from);
+        event.preventDefault();
+        if (at >= 0 && at !== from) {
+            this.arrive(items[at]);
+        }
+    }
     hostConnected() {
         this.host.addEventListener('keydown', this.handleKeydown);
     }

package/dist/controllers/popover-controller/popover-controller.d.ts

@@ -122,6 +122,7 @@ export declare class PopoverController implements ReactiveController {
     private readonly dismisser;
     /** Whether the surface is currently shown, so the calls can be idempotent. */
     private shown;
+    private readonly host;
     constructor(host: ReactiveControllerHost & HTMLElement, options: PopoverOptions);
     /** Whether the surface is showing. */
     get open(): boolean;
@@ -152,4 +153,14 @@ export declare class PopoverController implements ReactiveController {
      */
     reposition(): void;
     hostDisconnected(): void;
+    /**
+     * Asks a reconnected host that is still open to update, so the panel is shown
+     * again.
+     *
+     * The flag above lets it show, and nothing asked it to: a host moved in the
+     * DOM while open kept `open` and `aria-expanded="true"` with the panel
+     * hidden until something else updated it, and Escape did not close it,
+     * because the dismissal is started by showing.
+     */
+    hostConnected(): void;
 }

package/dist/controllers/popover-controller/popover-controller.js

@@ -4,6 +4,7 @@ export class PopoverController {
     constructor(host, options) {
         this.shown = false;
         this.options = options;
+        this.host = host;
         this.floating = new FloatingController(host, {
             anchor: options.anchor,
             ...(options.arrow === undefined ? {} : { arrow: options.arrow }),
@@ -85,4 +86,9 @@ export class PopoverController {
     hostDisconnected() {
         this.shown = false;
     }
+    hostConnected() {
+        if (this.options.open?.()) {
+            this.host.requestUpdate();
+        }
+    }
 }