@fusion.dev/helix-core 0.147.0 → 0.149.0

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

@@ -1,4 +1,4 @@
-import { auditName } from '#audit-name';
+import { auditName } from '@fusion.dev/helix-core/audits/name';
 import { elementById } from '../../utils/element-by-id/element-by-id.js';
 import { nameText } from '../../utils/name-text/name-text.js';
 const RELATIONSHIPS = [

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

@@ -61,8 +61,8 @@ export interface ChartPointerHost extends ReactiveControllerHost, HTMLElement {
      */
     readonly positionLabel?: string;
     /**
-     * The locale the position's numbers are written in. Absent or empty is the
-     * runtime's own.
+     * The locale the position's numbers are written in. Absent or empty reads
+     * the nearest `lang`, then the runtime's own, as `wordsLocale` does.
      */
     readonly locale?: string;
 }

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

@@ -1,6 +1,5 @@
-import { fillTemplate } from '../../utils/fill-template/fill-template.js';
-import { formatNumbers } from '../../utils/format-numbers/format-numbers.js';
 import { isRtl } from '../../utils/is-rtl/is-rtl.js';
+import { formatWords } from '../../words/words.js';
 import { stepReading } from './reading-step.js';
 export const CHART_PLOT = 'helix-chart-plot';
 export class ChartPointerController {
@@ -155,8 +154,10 @@ export class ChartPointerController {
         if (words === '' || place < 0) {
             return '';
         }
-        const format = formatNumbers(this.host.locale ?? '');
-        return fillTemplate(words, { count: format(shown.length), position: format(place + 1) });
+        return formatWords(this.host, 'positionLabel', {
+            count: shown.length,
+            position: place + 1,
+        });
     }
     columns() {
         const host = this.host;

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

@@ -0,0 +1,28 @@
+import type { ReactiveController, ReactiveControllerHost } from 'lit';
+/**
+ * Calls back whenever a child arrives at its host or leaves it.
+ *
+ * **A root that assigns its slots by hand needs this, and nothing else
+ * does.** `slotchange` fires when an assignment changes, and under
+ * `slotAssignment: 'manual'` the only thing that changes one is the host
+ * calling `assign`. A child appended after the first render reaches no slot,
+ * fires no `slotchange` and schedules no render, so it is drawn nowhere and
+ * counted by nothing: a notification added to a feed of three was never shown
+ * until some property changed. A default slot takes whatever is there and
+ * needs no watcher.
+ *
+ * **`childList` and not `subtree`.** A child rewriting its own text, a
+ * streaming chat turn on every frame, is no arrival, and a subtree watch would
+ * render the whole host again for each change.
+ *
+ * Asks the host for an update unless given something else to do. Watches
+ * from connection to disconnection, and again after a move.
+ */
+export declare class ChildrenController implements ReactiveController {
+    private readonly host;
+    private readonly changed;
+    private watcher;
+    constructor(host: ReactiveControllerHost & Node, changed?: () => void);
+    hostConnected(): void;
+    hostDisconnected(): void;
+}

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

@@ -0,0 +1,18 @@
+export class ChildrenController {
+    constructor(host, changed = () => host.requestUpdate()) {
+        this.host = host;
+        this.changed = changed;
+        this.watcher = undefined;
+        host.addController(this);
+    }
+    hostConnected() {
+        if (typeof MutationObserver === 'undefined') {
+            return;
+        }
+        this.watcher ??= new MutationObserver(() => this.changed());
+        this.watcher.observe(this.host, { childList: true });
+    }
+    hostDisconnected() {
+        this.watcher?.disconnect();
+    }
+}

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

@@ -3,6 +3,13 @@ import type { ReactiveController, ReactiveControllerHost } from 'lit';
 export interface CountdownOptions {
     /** Runs once the time is spent. */
     done: () => void;
+    /**
+     * Whether a hidden page holds the clock, as a pointer on the message does,
+     * so a timed message is not spent in a background tab. Counted as one hold
+     * however often the page hides, and a clock started while the page is
+     * hidden waits for it to show. Defaults to `false`.
+     */
+    holdWhileHidden?: boolean;
     /** Runs with `true` when the clock stops partway and `false` when it runs again. */
     paused?: (paused: boolean) => void;
 }
@@ -23,7 +30,10 @@ export interface CountdownOptions {
  * **Leaving the page pauses it**, keeping the time already spent, and drops
  * the holds, since a pointer or focus on a detached element never leaves it.
  * Coming back does not resume on its own: the host says whether it should,
- * such as only while it is still showing. `DelayController` is the other wait
+ * such as only while it is still showing.
+ *
+ * **A hidden page holds it too, where the host asks** with `holdWhileHidden`:
+ * RAC's toast queue stops its timers while the window is in the background. `DelayController` is the other wait
  * in core, for a wait that starts over and forgets itself on leaving.
  */
 export declare class CountdownController implements ReactiveController {
@@ -35,6 +45,10 @@ export declare class CountdownController implements ReactiveController {
     private timer;
     /** How many reasons there are to hold the clock. */
     private holds;
+    /** Whether a hidden page is one of the holds, with `holdWhileHidden`. */
+    private hidden;
+    /** Holds the clock as the page hides, and lets it go as the page shows. */
+    private readonly handleVisibility;
     constructor(host: ReactiveControllerHost, options: CountdownOptions);
     /** Whether the clock is running now. */
     get running(): boolean;

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

@@ -2,15 +2,37 @@ export class CountdownController {
     constructor(host, options) {
         this.options = options;
         this.holds = 0;
+        this.hidden = false;
+        this.handleVisibility = () => {
+            if (document.hidden === this.hidden) {
+                return;
+            }
+            this.hidden = document.hidden;
+            if (this.hidden) {
+                this.hold();
+            }
+            else {
+                this.release();
+            }
+        };
         host.addController(this);
     }
     get running() {
         return this.timer !== undefined;
     }
-    hostConnected() { }
+    hostConnected() {
+        if (this.options.holdWhileHidden && typeof document !== 'undefined') {
+            document.addEventListener('visibilitychange', this.handleVisibility);
+            this.handleVisibility();
+        }
+    }
     hostDisconnected() {
         this.pause();
         this.holds = 0;
+        this.hidden = false;
+        if (typeof document !== 'undefined') {
+            document.removeEventListener('visibilitychange', this.handleVisibility);
+        }
     }
     start(ms) {
         if (ms === undefined || !(ms > 0)) {
@@ -30,7 +52,10 @@ export class CountdownController {
         this.options.paused?.(true);
     }
     resume() {
-        if (this.timer !== undefined || this.remaining === undefined || this.remaining <= 0) {
+        if (this.hidden ||
+            this.timer !== undefined ||
+            this.remaining === undefined ||
+            this.remaining <= 0) {
             return;
         }
         this.startedAt = Date.now();

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

@@ -97,6 +97,17 @@ export interface FloatingOptions {
      */
     within?: () => Element | null | undefined;
 }
+/**
+ * How wide a panel that matches its anchor is drawn: the anchor's width, no
+ * wider than the room the panel has inside the window's margins.
+ *
+ * **A trigger as wide as the window gave a list as wide as the window**, and
+ * `shift` keeps a margin it then cannot keep: a Select spanning a phone with no
+ * gutter opened its list 8 pixels past the end edge, on both sides of the
+ * window at once. The room is Floating UI's `availableWidth` after the shift,
+ * so a panel that fits is the anchor's width exactly, as before.
+ */
+export declare const matchedInlineSize: (anchor: number, room: number) => number;
 /**
  * Places one element against another, and keeps it there.
  *
@@ -123,7 +134,7 @@ export interface FloatingOptions {
  * package and none of them is private. the `hooks` rule pairs a documented
  * hook with a rule that reads one, in both directions.
  *
- * @cssproperty --floating-anchor-inline-size - The anchor's width, for a panel that matches it.
+ * @cssproperty --floating-anchor-inline-size - The anchor's width, for a panel that matches it, and never wider than the room the panel has inside the window's margins.
  * @cssproperty --floating-arrow-x - Where the arrow meets the anchor, from the panel's left edge in both text directions.
  * @cssproperty --floating-arrow-y - Where the arrow meets the anchor, from the panel's top edge.
  * @cssproperty --floating-available-block-size - How much room is left below, for a panel that scrolls.

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

@@ -20,6 +20,7 @@ const corner = (floating) => {
     }
     return largest;
 };
+export const matchedInlineSize = (anchor, room) => Math.round(Math.max(0, Math.min(anchor, room)));
 export class FloatingController {
     constructor(host, options) {
         this.run = 0;
@@ -53,7 +54,7 @@ export class FloatingController {
                     apply: ({ availableHeight, availableWidth, elements, rects }) => {
                         room = availableWidth;
                         elements.floating.style.setProperty('--floating-available-block-size', `${Math.round(availableHeight)}px`);
-                        elements.floating.style.setProperty('--floating-anchor-inline-size', `${Math.round(rects.reference.width)}px`);
+                        elements.floating.style.setProperty('--floating-anchor-inline-size', `${matchedInlineSize(rects.reference.width, availableWidth)}px`);
                     },
                     padding: 8,
                 }));

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

@@ -25,6 +25,31 @@ export interface NavigableItem {
      */
     readonly words?: string;
 }
+/** What `focusItemOf` reads of an element, where its defaults do not fit. */
+export interface FocusItemOptions {
+    /** Whether the item is skipped. Defaults to `false`. */
+    disabled?: boolean;
+    /** Moves focus to the item. Defaults to the element's own `focus()`. */
+    focus?: () => void;
+    /**
+     * Whether a node is the item, for `origin: 'focus'`. Defaults to the element
+     * and anything inside it; an item whose children are content of their own,
+     * an accordion section's panel, answers for itself alone.
+     */
+    owns?: (node: Node | null) => boolean;
+    /** The words a reader types the start of. */
+    words?: string;
+}
+/**
+ * An item that is only ever focused: arrows move between such items and
+ * nothing is chosen on arrival, the shape of a toolbar, a megamenu bar or a
+ * legend.
+ *
+ * Eight families wrote the same object literal by hand, `select` a no-op and
+ * `selected` false, and an item that forgot one of them type-checked
+ * wherever its `contains` came from an element.
+ */
+export declare const focusItemOf: (element: HTMLElement, options?: FocusItemOptions) => NavigableItem;
 /** Where a move starts from: the item that has focus, or the chosen item. */
 export type KeyboardOrigin = 'focus' | 'selection';
 /** How the controller is told what it is moving through. */

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

@@ -1,6 +1,14 @@
 import { inlineStep } from '../../utils/inline-step/inline-step.js';
 import { keyClaimed } from '../../utils/key-claimed/key-claimed.js';
 import { typesCharacter } from '../../utils/typeahead/typeahead.js';
+export const focusItemOf = (element, options = {}) => ({
+    contains: options.owns ?? ((node) => element.contains(node)),
+    disabled: options.disabled ?? false,
+    focusItem: options.focus ?? (() => element.focus()),
+    select: () => { },
+    selected: false,
+    ...(options.words === undefined ? {} : { words: options.words }),
+});
 const KEYS = new Set(['ArrowDown', 'ArrowLeft', 'ArrowRight', 'ArrowUp', 'End', 'Home']);
 export class KeyboardNavigationController {
     constructor(host, { items, origin = 'selection', reserved = () => [], selects = () => true, typeahead, wrap = true, }) {

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

@@ -0,0 +1,69 @@
+import type { ReactiveController, ReactiveControllerHost } from 'lit';
+import { type Machine, type MachineEvent } from './machine.js';
+export * from './machine.js';
+/** An effect a state runs: it may return a function that ends it. */
+export type MachineEffect<E extends MachineEvent, C> = (context: C, by: E | undefined) => undefined | (() => void);
+/** What a `MachineController` starts from and what it runs. */
+export interface MachineOptions<S extends string, E extends MachineEvent, C, F extends string> {
+    /** The context the machine starts with. */
+    context: C;
+    /**
+     * Each effect a state names, by name. It runs after the host renders the
+     * state, with the event that entered it, and never on a server. The function
+     * it returns runs when the state is left and when the host is disconnected.
+     */
+    effects: {
+        [K in F]: MachineEffect<E, C>;
+    };
+    /** The state the machine starts in, before the host's first `willUpdate`. */
+    initial: S;
+    /**
+     * Records a state on the host, or takes it off: the host's own
+     * `toggleState`, passed in because it is protected.
+     */
+    mark?: (state: S, on: boolean) => void;
+}
+/**
+ * Runs a `Machine` on a host: holds the state and the context, moves them by
+ * `step`, and runs each state's effects with their clean-ups.
+ *
+ * The host turns its property writes into events in `willUpdate`, so a write
+ * moves the machine the way a press does, and the state a server prints comes
+ * from properties. Effects run in `hostUpdated`, which a server never calls,
+ * and none runs at the first update except a state's `atStart` effects: an
+ * element served in a state was not moved there by anybody.
+ */
+export declare class MachineController<S extends string, E extends MachineEvent, C, F extends string = string> implements ReactiveController {
+    /** The current state. */
+    state: S;
+    /** The current context. */
+    context: C;
+    private readonly host;
+    private readonly machine;
+    private readonly options;
+    /** The event that entered the current state, which its effects are told. */
+    private by;
+    /** The clean-ups of the effects that are running. */
+    private ends;
+    /** Whether the host has finished its first update. */
+    private live;
+    /** Whether the current state's effects have run. */
+    private ran;
+    constructor(host: ReactiveControllerHost & EventTarget, machine: Machine<S, E, C, F>, options: MachineOptions<S, E, C, F>);
+    /** Whether an event would move the machine, with nothing run or asked. */
+    can(event: E): boolean;
+    /**
+     * Moves the machine by an event, and returns whether it moved.
+     *
+     * A request is announced first and applies only where nobody refused it.
+     * Entering a state ends the effects of the state it leaves at once, and runs
+     * its own after the host's next update.
+     */
+    send(event: E): boolean;
+    hostConnected(): void;
+    hostUpdated(): void;
+    hostDisconnected(): void;
+    /** Ends the running effects, so the next update runs the current state's. */
+    private end;
+    private mark;
+}

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

@@ -0,0 +1,78 @@
+import { requestChange } from '../../utils/request-change/request-change.js';
+import { step } from './machine.js';
+export * from './machine.js';
+export class MachineController {
+    constructor(host, machine, options) {
+        this.by = undefined;
+        this.ends = [];
+        this.live = false;
+        this.ran = false;
+        this.host = host;
+        this.machine = machine;
+        this.options = options;
+        this.state = options.initial;
+        this.context = options.context;
+        this.mark(this.state, true);
+        host.addController(this);
+    }
+    can(event) {
+        return step(this.machine, this.state, this.context, event).changed;
+    }
+    send(event) {
+        const next = step(this.machine, this.state, this.context, event);
+        if (!next.changed) {
+            return false;
+        }
+        const apply = () => {
+            if (next.entered) {
+                this.end();
+                this.by = event;
+            }
+            this.mark(this.state, false);
+            this.state = next.state;
+            this.context = next.context;
+            this.mark(this.state, true);
+            this.host.requestUpdate();
+        };
+        if (next.ask) {
+            return requestChange({ apply, event: next.ask, host: this.host, next: 0 });
+        }
+        apply();
+        return true;
+    }
+    hostConnected() {
+        if (this.live) {
+            this.by = undefined;
+            this.hostUpdated();
+        }
+    }
+    hostUpdated() {
+        const first = !this.live;
+        this.live = true;
+        if (this.ran) {
+            return;
+        }
+        this.ran = true;
+        const state = this.machine.states[this.state];
+        for (const name of (first ? state.atStart : state.effects) ?? []) {
+            const end = this.options.effects[name](this.context, first ? undefined : this.by);
+            if (end) {
+                this.ends.push(end);
+            }
+        }
+    }
+    hostDisconnected() {
+        this.end();
+    }
+    end() {
+        for (const end of this.ends.splice(0)) {
+            end();
+        }
+        this.ran = false;
+    }
+    mark(state, on) {
+        if (this.machine.states[state].mark) {
+            this.options.mark?.(state, on);
+        }
+    }
+}

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

@@ -0,0 +1,93 @@
+/** Something that happens to a machine, named by `type`, with whatever it carries. */
+export interface MachineEvent {
+    /** The event's name, such as `NEXT`. */
+    type: string;
+}
+/** One way an event moves a machine. Every function on it is pure. */
+export interface Transition<S extends string, E extends MachineEvent, C> {
+    /**
+     * The cancelable event announced before the move, which makes the move a
+     * request. It goes through `requestChange`, so a listener calling
+     * `preventDefault()` refuses it, and a refusal changes nothing, as a failed
+     * guard does.
+     */
+    ask?: ((context: C, event: E) => Event) | undefined;
+    /** The context after the move. */
+    assign?: (context: C, event: E) => C;
+    /** Whether this way applies. The first way whose guard passes is taken. */
+    guard?: (context: C, event: E) => boolean;
+    /**
+     * The state the move enters. Given, the state is entered again even where it
+     * is the same state, so its effects end and run again. Left out, the machine
+     * stays where it is and only `assign` applies.
+     */
+    to?: S | ((context: C, event: E) => S) | undefined;
+}
+/**
+ * What a state does with one event: one way, ways tried in order, or
+ * `'ignore'`, which says in the table that the state hears the event and does
+ * nothing with it.
+ */
+export type MachineAnswer<S extends string, E extends MachineEvent, C> = Transition<S, E, C> | readonly Transition<S, E, C>[] | 'ignore';
+/** One state of a machine: its answers to events, and the effects it runs. */
+export interface MachineState<S extends string, E extends MachineEvent, C, F extends string> {
+    /**
+     * The effects that also run when the element starts in this state, at its
+     * first update. They run with no event, because nobody moved the element
+     * there. Every other effect waits for a move.
+     */
+    atStart?: readonly F[];
+    /** The effects that run while the element is in this state, by name. */
+    effects?: readonly F[];
+    /** Records the state on the host as `:state(<name>)` while it is current. */
+    mark?: boolean;
+    /** What each event does in this state. An event left out changes nothing. */
+    on?: {
+        [T in E['type']]?: MachineAnswer<S, E, C>;
+    };
+}
+/**
+ * A table of states. Each state lists the events it answers and the effects
+ * it runs. The effects are named here and written on the element, so the table
+ * stays pure and a spec can walk it.
+ */
+export interface Machine<S extends string, E extends MachineEvent, C, F extends string = string> {
+    /** Every state, by name. */
+    states: {
+        [K in S]: MachineState<S, E, C, F>;
+    };
+}
+/**
+ * The exhaustive form of a machine: every state answers every event, with a
+ * transition or with `'ignore'`. A table typed this way cannot leave a pair
+ * out by accident, so a reviewer reads every pair the machine ignores.
+ */
+export interface ExhaustiveMachine<S extends string, E extends MachineEvent, C, F extends string = string> extends Machine<S, E, C, F> {
+    states: {
+        [K in S]: MachineState<S, E, C, F> & {
+            on: {
+                [T in E['type']]: MachineAnswer<S, E, C>;
+            };
+        };
+    };
+}
+/** What one event does to a state and its context. */
+export interface MachineStep<S extends string, C> {
+    /** Makes the event announced before the move, where the move is a request. */
+    ask?: (() => Event) | undefined;
+    /** Whether anything moves: the state, the context, or both. */
+    changed: boolean;
+    /** The context after the event. */
+    context: C;
+    /** Whether the event enters a state, so its effects end and run again. */
+    entered: boolean;
+    /** The state after the event. */
+    state: S;
+}
+/**
+ * What an event does to a state and its context, with nothing run.
+ *
+ * Takes the first way whose guard passes. An event the state does not answer,
+ * an event it ignores, and an event whose guards all fail change nothing.
+ */
+export declare const step: <S extends string, E extends MachineEvent, C>(machine: Machine<S, E, C, string>, state: S, context: C, event: E) => MachineStep<S, C>;

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

@@ -0,0 +1,20 @@
+export const step = (machine, state, context, event) => {
+    const answer = machine.states[state].on?.[event.type];
+    const ways = answer === undefined || answer === 'ignore' ? [] : [answer].flat();
+    for (const way of ways) {
+        if (way.guard?.(context, event) === false) {
+            continue;
+        }
+        const next = way.assign ? way.assign(context, event) : context;
+        const entered = way.to !== undefined;
+        const ask = way.ask;
+        return {
+            ask: ask && (() => ask(context, event)),
+            changed: entered || next !== context,
+            context: next,
+            entered,
+            state: typeof way.to === 'function' ? way.to(context, event) : (way.to ?? state),
+        };
+    }
+    return { changed: false, context, entered: false, state };
+};

package/dist/controllers/open-phase-controller/open-phase-controller.d.ts

@@ -14,6 +14,16 @@ export interface OpenPhaseOptions {
     /** The element whose animations are the entrance and the exit. */
     surface: () => Element | null | undefined;
 }
+/**
+ * Resolves once every animation running on an element and inside it has
+ * finished, or at once where none is running.
+ *
+ * **Asked now, with no frame waited first**, for an exit that is already
+ * running when the caller asks: a section closing, a message leaving. A
+ * canceled animation counts as finished. `animationsSettled` waits two frames
+ * first, for an entrance that has not started yet.
+ */
+export declare const animationsFinished: (element: Element | null | undefined) => Promise<void>;
 /**
  * Resolves once an element's animations have finished, or two frames on where
  * it has none.

package/dist/controllers/open-phase-controller/open-phase-controller.js

@@ -1,3 +1,9 @@
+export const animationsFinished = async (element) => {
+    if (!element || typeof element.getAnimations !== 'function') {
+        return;
+    }
+    await Promise.allSettled(element.getAnimations({ subtree: true }).map((one) => one.finished));
+};
 export const animationsSettled = async (element) => {
     const frame = () => new Promise((resolve) => {
         if (typeof requestAnimationFrame === 'function') {
@@ -9,10 +15,7 @@ export const animationsSettled = async (element) => {
     });
     await frame();
     await frame();
-    if (!element || typeof element.getAnimations !== 'function') {
-        return;
-    }
-    await Promise.allSettled(element.getAnimations({ subtree: true }).map((one) => one.finished));
+    await animationsFinished(element);
 };
 export class OpenPhaseController {
     constructor(host, options) {