@fusion.dev/helix-core 0.148.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/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/reorder-controller/reorder-controller.d.ts

@@ -0,0 +1,285 @@
+import type { nothing, ReactiveController, ReactiveControllerHost, TemplateResult } from 'lit';
+import type { ReorderDetail } from '../../events/details.js';
+import { type ReorderAxis, type ReorderHold } from '../../utils/reorder/reorder.js';
+/**
+ * What a screen reader hears as an item moves. `{name}` is the item's name,
+ * and `{position}` and `{count}` say where it would go.
+ */
+export interface ReorderWords {
+    /** Said when a key or a click puts the item back where it was. */
+    canceled: string;
+    /** Said when the item is let go. */
+    dropped: string;
+    /** Said each time a key moves the held item. */
+    moved: string;
+    /** Said when a key or a click takes hold of the item. */
+    pickedUp: string;
+}
+/** A move a drop asks for, counted from 0 in the order the items are drawn. */
+export interface ReorderMove {
+    from: number;
+    key: string;
+    to: number;
+}
+export interface ReorderOptions {
+    /**
+     * Every key the item with that key moves among, the ones a filter hides
+     * included, for a drop the controller asks for itself. `keys` where this is
+     * not given.
+     */
+    all?: (key: string) => readonly string[];
+    /** Which way the items run: rows down the block axis, or columns along the inline one. */
+    axis: ReorderAxis;
+    /** The box an item is drawn in, or nothing for one a window did not draw. */
+    box: (key: string) => DOMRect | undefined;
+    /**
+     * Called when an item is let go at a new place. Returns whether the move
+     * stood: `false` where a listener refused it.
+     *
+     * Where this is not given, the controller asks the page itself, from the
+     * host: `helix-before-reorder`, then `helix-reorder`, with `kind` and
+     * every key of `all` in the new order, joined by commas in `value`. A key a
+     * filter hides keeps its place, as `placeKey` says.
+     */
+    drop?: (move: ReorderMove) => boolean;
+    /**
+     * The key of the item a key pressed in the host stands for: the one with
+     * focus, or the one `aria-activedescendant` names. Alt with Up or Down then
+     * moves that item a place at once, and Alt with Home or End to either end,
+     * as the rearrangeable listbox of the APG does, with no grip and nothing
+     * held. Alt with an arrow moves nothing where this is not given.
+     */
+    current?: (event: KeyboardEvent) => string | undefined;
+    /**
+     * Whether an item may be moved now. Where this is not given, the host's own
+     * `reorderable` says, and every item may on a host without one.
+     */
+    enabled?: () => boolean;
+    /**
+     * The grip an event passed through, and the key of the item it moves, or
+     * nothing for an event that passed through none.
+     */
+    grip: (event: Event) => {
+        element: HTMLElement;
+        key: string;
+    } | undefined;
+    /**
+     * Whether a key or a click holds the item for the arrow keys. `true` where
+     * this is not given. Data Table's columns move a place for each arrow on the
+     * grip and say `false`, so they are only dragged. A listbox's options say
+     * `false` too: the whole option is what a pointer drags, and a click on it
+     * still chooses it.
+     */
+    holds?: boolean;
+    /**
+     * The key of the item an event passed through, anywhere in it. A click there
+     * drops a held item at that place, which is the move a single pointer makes
+     * without a drag.
+     */
+    item?: (event: Event) => string | undefined;
+    /** What a drop the controller asks for itself moves: `item`, the default, or `row`. */
+    kind?: ReorderDetail['kind'];
+    /**
+     * The keys of the items the item with that key moves among, in the order
+     * they are drawn: every item of a list, or the item's siblings in a tree.
+     */
+    keys: (key: string) => readonly string[];
+    /** An item's name, for the words. */
+    name?: (key: string) => string;
+    /**
+     * The element a pointer drag copies for the drag preview: a copy of what it
+     * draws follows the pointer, raised over the page, until the item is let go
+     * or Escape puts it back. A move made with the keys draws none. No preview
+     * is drawn where this is not given.
+     *
+     * The copy is drawn in the host's `drag-preview` part, which the host's
+     * template draws with `drawDragPreview`: a manual popover in its shadow
+     * root, hidden from assistive technology, shown in the top layer so no
+     * scrolling box clips it. The host's stylesheet gives it its look. No
+     * preview is drawn where the host draws no such part.
+     */
+    preview?: (key: string) => Element | null | undefined;
+    /**
+     * Gives focus back to the item with that key, called after a move made from
+     * the keyboard stood, once the page has moved the item and focus went to the
+     * body with it. Focus the page put anywhere else is left there. Focus is left
+     * alone where this is not given.
+     */
+    refocus?: (key: string) => void;
+    /**
+     * Speaks words in the host's live region. Where this is not given, the
+     * words go to the host's `announced`, the region a collection draws, where
+     * it has one, and nowhere otherwise.
+     */
+    say?: (words: string) => void;
+    /**
+     * The box to scroll while a dragged item nears one of its edges, or `null`
+     * for the window. Where this is not given, rows down the block axis scroll
+     * the nearest box around the host's first child that scrolls that way and
+     * has more to show, or the window, and items along the inline axis scroll
+     * nothing.
+     */
+    scroller?: () => HTMLElement | null;
+    /**
+     * The words a screen reader hears. Where this is not given, they are the
+     * host's own `canceledLabel`, `droppedLabel`, `movedLabel`, and
+     * `pickedUpLabel`, which is what a family declares them as.
+     */
+    words?: () => ReorderWords;
+}
+/**
+ * Asks to move a row or an item and reports whether the move stood:
+ * `helix-before-reorder`, which can refuse it, and then `helix-reorder`, which
+ * is when you move your data.
+ */
+export declare const requestReorder: (host: HTMLElement, detail: ReorderDetail) => boolean;
+/**
+ * Moves one item of a collection to a new place, by pointer, by keyboard, and
+ * by a screen reader, and says each step in words.
+ *
+ * - **A pointer** drags an item by its grip. The page under it scrolls near an
+ *   edge, and `mark` says where a drop indicator goes.
+ * - **A key or a click** on a grip holds the item. The arrows move it, Home
+ *   and End move it to either end, Enter, Space, or a second click drops it,
+ *   and Escape puts it back. A click on another item drops it there, so one
+ *   pointer can move an item without dragging, as WCAG 2.5.7 asks.
+ * - **Alt with an arrow** moves the item focus is on a place at once, where
+ *   the host says which item that is with `current`. A collection whose own
+ *   keys are the arrows, Enter, and Space, such as a listbox or a tree, moves
+ *   its items this way.
+ *
+ * **It moves nothing.** A drop calls `drop`, and the host asks its page,
+ * which owns the items, to move them. The host reads `held` and `mark` when
+ * it renders, and this asks it for an update at each change of state.
+ *
+ * Each change of state is worked out by `reorderStep`, a pure function, and
+ * what it calls for runs here: the words, the scrolling, and the drop.
+ */
+export declare class ReorderController implements ReactiveController {
+    private readonly host;
+    private readonly options;
+    /** The state of the move. */
+    private state;
+    /** The grip a key or a click took hold of, which has to keep focus. */
+    private holder;
+    /** Where the pointer was last, for the scrolling to place the item by. */
+    private pointer;
+    /** The frame the next scroll waits for. */
+    private frame;
+    /** The copy of the dragged item that follows the pointer, while one is drawn. */
+    private shown;
+    /** Where the pointer went down on the item the preview copies. */
+    private anchor;
+    constructor(host: ReactiveControllerHost & HTMLElement, options: ReorderOptions);
+    /** The item held and where it would go, or nothing while none is. */
+    get held(): {
+        by: ReorderHold;
+        from: number;
+        key: string;
+        to: number;
+    } | undefined;
+    /**
+     * Where the drop indicator goes: before or after the item with that key, or
+     * nothing while no item is held away from its place.
+     */
+    get mark(): {
+        edge: 'after' | 'before';
+        key: string;
+    } | undefined;
+    /**
+     * Where the item with that key stands in a move, for the host to mark it:
+     * the item held, the item the drop indicator is before or after, or nothing.
+     */
+    moveOf(key: string): 'dragging' | 'drop-after' | 'drop-before' | undefined;
+    /**
+     * The `drag-preview` part, for the host's template: an empty manual popover
+     * while items may be moved, which a pointer drag fills and shows.
+     */
+    drawDragPreview(): TemplateResult | typeof nothing;
+    hostConnected(): void;
+    hostDisconnected(): void;
+    /** Puts a held item back where it was, as Escape does. */
+    cancel(): void;
+    /** Moves the state on, and runs what the change calls for. */
+    private send;
+    /** What a change of state calls for. */
+    private enter;
+    /** Asks for a move: through `drop`, or of the page where the host gives none. */
+    private drop;
+    /** Says one of the words, with the item's name and place filled in. */
+    private speak;
+    /** The place among the others that the pointer is over, for the item with that key. */
+    private placeAt;
+    private enabled;
+    /** The page's own watch for the move it was asked for, while one is awaited. */
+    private awaiting;
+    /**
+     * Gives focus back to a moved item once the page has moved it, where moving
+     * it sent focus to the body. A page that moves the item as it hears
+     * `helix-reorder` has done so already; one that renders later changes the
+     * host's children first.
+     */
+    private follow;
+    private readonly handleDown;
+    private readonly handleMove;
+    /**
+     * Draws the drag preview: a copy of the item, where it is, in the host's
+     * `drag-preview` part, shown in the top layer. Measured before the host
+     * draws the item as dragged, so the copy is the item as it was.
+     */
+    private lift;
+    /** Moves the drag preview with the pointer. */
+    private glide;
+    /** Takes the drag preview away: hides the part and empties it. */
+    private lower;
+    /** Places the dragged item under the pointer's last reading. */
+    private drag;
+    private readonly handleUp;
+    private readonly handleCancel;
+    /**
+     * Escape while a pointer drags puts the item back. Heard on the window,
+     * since focus may be anywhere while a pointer drags, and kept from the page,
+     * so a dialog the list is in stays open.
+     */
+    private readonly handleEscape;
+    /** Starts or stops hearing the pointer on the window, and the scrolling with it. */
+    private listen;
+    /** Scrolls the box while the dragged item is near one of its edges, a frame at a time. */
+    private scroll;
+    /**
+     * A click on a grip takes hold of its item, and a second one drops it. While
+     * one is held, a click on another item drops it there. Heard in the capture
+     * phase, so the click that drops an item does not also select a row.
+     */
+    private readonly handleClick;
+    /** Takes hold of an item from its grip, which keeps focus while it is held. */
+    private take;
+    /**
+     * The keys while an item is held: the arrows, Home and End move it, Enter and
+     * Space drop it, and Escape puts it back. Heard in the capture phase and kept
+     * from everything else, so an arrow moves the item and not focus.
+     *
+     * A grip that is a native button answers Enter and Space with a click, which
+     * `handleClick` hears. Any other grip, such as a cell of a grid, is answered
+     * here.
+     */
+    private readonly handleKey;
+    /**
+     * Alt with an arrow, Home, or End: moves the item the key stands for at
+     * once, with nothing held, and says where it went. A move the page refuses
+     * is said as canceled. At an end the key is kept and nothing moves.
+     */
+    private nudge;
+    /**
+     * A pointer went down while a key or a click holds an item. Its click may
+     * drop the item on another one, so the focus it moves does not put the item
+     * back until that click has been heard.
+     */
+    private press;
+    /** Whether a pointer is down while an item is held, for `press`. */
+    private pressing;
+    /** Focus leaving the grip that holds an item puts the item back. */
+    private readonly handleFocusOut;
+    /** Puts a held item back where focus has left its grip. */
+    private keepOrCancel;
+}