@fusion.dev/helix-core 0.142.1 → 0.144.0

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

@@ -0,0 +1,45 @@
+const vertical = (key) => (key === 'ArrowDown' ? 1 : key === 'ArrowUp' ? -1 : 0);
+const inline = (key, rtl) => key === 'ArrowRight' ? (rtl ? -1 : 1) : key === 'ArrowLeft' ? (rtl ? 1 : -1) : 0;
+export const alongReadings = (key, layout) => {
+    const single = layout.grid > 1 || layout.series < 2;
+    if (layout.axis === 'block') {
+        const down = vertical(key);
+        return down !== 0 || !single ? down : inline(key, layout.rtl);
+    }
+    const across = inline(key, layout.rtl);
+    if (across !== 0) {
+        return across * Math.max(1, layout.grid);
+    }
+    return single ? vertical(key) : 0;
+};
+export const amongSeries = (key, layout) => {
+    if (layout.grid > 1 || layout.series < 2) {
+        return 0;
+    }
+    return layout.axis === 'block' ? inline(key, layout.rtl) : vertical(key);
+};
+export const stepReading = (key, from, layout) => {
+    const last = layout.count - 1;
+    if (last < 0) {
+        return undefined;
+    }
+    if (key === 'Home') {
+        return { at: 0, series: from.series };
+    }
+    if (key === 'End') {
+        return { at: last, series: from.series };
+    }
+    const along = alongReadings(key, layout);
+    if (along !== 0) {
+        const at = from.at < 0 ? (along > 0 ? 0 : last) : Math.min(Math.max(from.at + along, 0), last);
+        return { at, series: from.series };
+    }
+    const among = amongSeries(key, layout);
+    if (among !== 0) {
+        return {
+            at: Math.max(from.at, 0),
+            series: Math.min(Math.max(from.series + among, -1), layout.series - 1),
+        };
+    }
+    return undefined;
+};

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

@@ -24,10 +24,10 @@ export interface CopyOptions {
  * in more places than it looks and a control that does nothing is
  * indistinguishable from a broken one. See `write` above.
  *
- * **Where neither route is allowed, the failure is silence.** The confirmation
- * does not appear, which is the honest report: a message about a clipboard is
- * worse than a chip that did not flash, and there is nothing a reader could do
- * about a permission policy anyway.
+ * **Where neither route is allowed, the copy has failed**, and `failed` holds
+ * for the moment a confirmation would. A component decides whether to say so:
+ * `CopyButton` names itself with its `error-label`, where Color's chip does
+ * not flash at all.
  *
  * **The event is announced after the write, not before it.** It is not
  * cancelable for the same reason: by the time anything could be said, the text
@@ -42,15 +42,20 @@ export declare class CopyController implements ReactiveController {
     private readonly options;
     /** Whether the last write succeeded and is still being confirmed. */
     copied: boolean;
+    /** Whether the last copy put nothing on the clipboard, and is still being said. */
+    failed: boolean;
     private timer;
     constructor(host: ReactiveControllerHost & EventTarget, options?: CopyOptions);
     /**
      * Writes to the clipboard, and confirms it if the platform allowed it.
+     * Resolves to whether the text is on the clipboard.
      *
      * Empty text is not copied. An empty clipboard is not a thing a reader ever
-     * asks for, and confirming one is worse than doing nothing.
+     * asks for, and confirming one is worse than doing nothing. Empty text and a
+     * refused write each hold `failed` for the same moment a copy holds
+     * `copied`, for a component that says so.
      */
-    copy(text: string): Promise<void>;
+    copy(text: string): Promise<boolean>;
     hostDisconnected(): void;
     private reset;
 }

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 {
@@ -29,30 +34,32 @@ export class CopyController {
         this.host = host;
         this.options = options;
         this.copied = false;
+        this.failed = false;
         host.addController(this);
     }
     async copy(text) {
-        if (text === '') {
-            return;
-        }
-        if (!(await write(text))) {
-            return;
-        }
+        const wrote = text !== '' && (await write(text));
         if (this.host instanceof HTMLElement && !this.host.isConnected) {
-            return;
+            return wrote;
         }
-        this.copied = true;
+        this.copied = wrote;
+        this.failed = !wrote;
         this.host.requestUpdate();
-        this.host.dispatchEvent(new HelixCopyEvent({ value: text }));
+        if (wrote) {
+            this.host.dispatchEvent(new HelixCopyEvent({ value: text }));
+        }
         this.reset();
         this.timer = setTimeout(() => {
             this.copied = false;
+            this.failed = false;
             this.host.requestUpdate();
         }, this.options.after ?? 1200);
+        return wrote;
     }
     hostDisconnected() {
         this.reset();
         this.copied = false;
+        this.failed = false;
     }
     reset() {
         if (this.timer !== undefined) {

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

@@ -0,0 +1,50 @@
+import type { ReactiveController, ReactiveControllerHost } from 'lit';
+/** What a `DelayController` is for. */
+export interface DelayOptions {
+    /**
+     * Whether the host renders `elapsed`, and so updates when it moves.
+     * Defaults to `true`; a wait that only runs `done`, a debounce, leaves its
+     * host alone.
+     */
+    renders?: boolean;
+}
+/**
+ * A wait an element starts and restarts: whether it has run out, and what runs
+ * when it does.
+ *
+ * Avatar's `fallback-delay`, Image's `placeholder-delay` and Loader's `delay`
+ * each hold a region back until a wait is over, and Listbox's `filter-delay`
+ * holds a filter back until typing pauses. Each kept a timer, a flag and the
+ * clean-up by hand; this keeps the three together, and clears the timer when
+ * the element leaves the page.
+ *
+ * `elapsed` is what a template reads, and the host updates when it moves,
+ * unless `renders` is false.
+ * Leaving the page stops the wait without forgetting that it ran out, so a
+ * loader moved to another place in the page does not wait again.
+ */
+export declare class DelayController implements ReactiveController {
+    private readonly host;
+    private readonly options;
+    /** Whether the last wait started has run out. */
+    elapsed: boolean;
+    private timer;
+    private done;
+    constructor(host: ReactiveControllerHost, options?: DelayOptions);
+    /** Whether a wait is running. */
+    get pending(): boolean;
+    hostConnected(): void;
+    hostDisconnected(): void;
+    /**
+     * Starts the wait over: `elapsed` goes back to false, and after `ms`
+     * milliseconds it turns true and `done` runs. No `ms` starts no wait, which
+     * leaves `elapsed` false.
+     */
+    start(ms?: number, done?: () => void): void;
+    /** Stops a running wait, leaving `elapsed` as it is. */
+    cancel(): void;
+    /** Ends a running wait now, as though it had run out. Nothing happens where none is running. */
+    flush(): void;
+    private finish;
+    private mark;
+}

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

@@ -0,0 +1,54 @@
+export class DelayController {
+    constructor(host, options = {}) {
+        this.host = host;
+        this.options = options;
+        this.elapsed = false;
+        this.timer = undefined;
+        this.done = undefined;
+        host.addController(this);
+    }
+    get pending() {
+        return this.timer !== undefined;
+    }
+    hostConnected() { }
+    hostDisconnected() {
+        this.cancel();
+    }
+    start(ms, done) {
+        this.cancel();
+        this.mark(false);
+        if (ms === undefined) {
+            return;
+        }
+        this.done = done;
+        this.timer = setTimeout(() => this.finish(), ms);
+    }
+    cancel() {
+        clearTimeout(this.timer);
+        this.timer = undefined;
+        this.done = undefined;
+    }
+    flush() {
+        if (this.timer === undefined) {
+            return;
+        }
+        clearTimeout(this.timer);
+        this.finish();
+    }
+    finish() {
+        const done = this.done;
+        this.timer = undefined;
+        this.done = undefined;
+        this.mark(true);
+        done?.();
+    }
+    mark(elapsed) {
+        if (elapsed === this.elapsed) {
+            return;
+        }
+        this.elapsed = elapsed;
+        if (this.options.renders !== false) {
+            this.host.requestUpdate();
+        }
+    }
+}

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/focus-scope-controller/focus-scope-controller.d.ts

@@ -0,0 +1,56 @@
+import type { ReactiveController, ReactiveControllerHost } from 'lit';
+export interface FocusScopeOptions {
+    /**
+     * The elements whose controls are inside the scope, in order. For a surface
+     * that holds a slot, these are the elements assigned to it: a query on the
+     * surface stops at the slot and never reaches them.
+     */
+    contents: () => readonly Element[];
+    /** Whether `Tab` is kept inside the scope, wrapping at either end. */
+    contain?: () => boolean;
+    /**
+     * Where focus goes on the way in: the first control inside, or the surface
+     * itself. The first control unless said, falling back to the surface where
+     * there is none.
+     */
+    start?: 'first' | 'surface';
+    /** The box focus is kept in, which takes focus itself where nothing inside can. */
+    surface: () => HTMLElement | null | undefined;
+}
+/** The controls among some elements and inside them, in order. */
+export declare const controlsIn: (elements: readonly Element[]) => HTMLElement[];
+/**
+ * Moves focus into a surface and back out of it, and can keep `Tab` inside
+ * while it is open.
+ *
+ * The part of an overlay that is about focus and nothing else: a popover that
+ * moves focus in as it opens, a modal popover that keeps it there, a toast
+ * region a hotkey takes focus to. Each of them decides *when*; this does the
+ * moving, and remembers where focus came from so `leave` can give it back.
+ *
+ * **Back only from inside.** A surface closed by a press somewhere else has not
+ * taken focus with it, and pulling focus back would move a reader who had
+ * already gone where they meant to.
+ */
+export declare class FocusScopeController implements ReactiveController {
+    private readonly host;
+    private readonly options;
+    /** Where focus was when it was moved in. */
+    private origin;
+    constructor(host: ReactiveControllerHost & HTMLElement, options: FocusScopeOptions);
+    hostConnected(): void;
+    hostDisconnected(): void;
+    /** Whether focus is in the surface or anything assigned into it. */
+    get holdsFocus(): boolean;
+    /** The controls inside the scope, in order. */
+    get controls(): HTMLElement[];
+    /** Moves focus into the scope, and remembers where it was. */
+    enter(): void;
+    /**
+     * Gives focus back to where it was before `enter`, if focus is still inside
+     * the scope. Returns whether it did.
+     */
+    leave(): boolean;
+    /** `Tab` at either end wraps to the other, while the scope is containing. */
+    private readonly handleKeydown;
+}

package/dist/controllers/focus-scope-controller/focus-scope-controller.js

@@ -0,0 +1,71 @@
+import { deepActiveElement, deepContains, focusableElements, } from '../../utils/focusable-elements/focusable-elements.js';
+const takesFocus = (element) => element instanceof HTMLElement &&
+    (element.matches('a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [contenteditable]:not([contenteditable="false"]), [tabindex]:not([tabindex="-1"])') ||
+        element.shadowRoot?.delegatesFocus === true);
+export const controlsIn = (elements) => elements.flatMap((one) => [
+    ...(takesFocus(one) ? [one] : []),
+    ...(one instanceof HTMLElement ? focusableElements(one) : []),
+]);
+export class FocusScopeController {
+    constructor(host, options) {
+        this.handleKeydown = (event) => {
+            if (event.key !== 'Tab' || event.defaultPrevented || !this.options.contain?.()) {
+                return;
+            }
+            const controls = this.controls;
+            const active = deepActiveElement();
+            const first = controls[0];
+            const last = controls[controls.length - 1];
+            if (!first || !last) {
+                event.preventDefault();
+                this.options.surface()?.focus({ preventScroll: true });
+                return;
+            }
+            const at = (control) => active !== null && deepContains(control, active);
+            if (event.shiftKey && (at(first) || active === this.options.surface())) {
+                event.preventDefault();
+                last.focus();
+            }
+            else if (!event.shiftKey && at(last)) {
+                event.preventDefault();
+                first.focus();
+            }
+        };
+        this.host = host;
+        this.options = options;
+        host.addController(this);
+    }
+    hostConnected() {
+        this.host.addEventListener('keydown', this.handleKeydown);
+    }
+    hostDisconnected() {
+        this.host.removeEventListener('keydown', this.handleKeydown);
+    }
+    get holdsFocus() {
+        const active = deepActiveElement();
+        const surface = this.options.surface();
+        return (active !== null &&
+            ((surface !== null && surface !== undefined && deepContains(surface, active)) ||
+                this.options.contents().some((one) => deepContains(one, active))));
+    }
+    get controls() {
+        return controlsIn(this.options.contents());
+    }
+    enter() {
+        const active = deepActiveElement();
+        if (active instanceof HTMLElement && !this.holdsFocus) {
+            this.origin = active;
+        }
+        const first = this.options.start === 'surface' ? undefined : this.controls[0];
+        (first ?? this.options.surface())?.focus({ preventScroll: true });
+    }
+    leave() {
+        const origin = this.origin;
+        this.origin = undefined;
+        if (!origin?.isConnected || !this.holdsFocus) {
+            return false;
+        }
+        origin.focus({ preventScroll: true });
+        return true;
+    }
+}

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);
     }