@fusion.dev/helix-core 0.143.0 → 0.145.0

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/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

@@ -19,6 +19,8 @@ export interface NavigableItem {
     /** Whether the item is the current one, which is where movement starts. */
     selected: boolean;
 }
+/** 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. */
 export interface KeyboardNavigationOptions {
     /** The items, in the order a reader moves through them. */
@@ -35,8 +37,13 @@ export interface KeyboardNavigationOptions {
      * every time. It is also the only reading that can tell a press on a tab from
      * a press somewhere else in the component, which matters wherever the host
      * holds more than the set (a tab panel is a tab stop of its own).
+     *
+     * A function where the answer changes with the element's state, read on every
+     * press. A read-only radio group is the case: while it is read-only the arrows
+     * move focus between radios without choosing, so the move has to start where
+     * focus is, and once it is editable again the selection is the start.
      */
-    origin?: 'focus' | 'selection';
+    origin?: KeyboardOrigin | (() => KeyboardOrigin);
     /**
      * Whether arriving also chooses.
      *
@@ -176,13 +183,15 @@ export declare class Typeahead {
 export declare class KeyboardNavigationController implements ReactiveController {
     private readonly host;
     private readonly items;
-    private readonly origin;
+    private readonly originOf;
     private readonly selects;
     private readonly reserved;
     private readonly wrap;
     private readonly words;
     private readonly typeahead;
     constructor(host: ReactiveControllerHost & HTMLElement, { items, origin, reserved, selects, typeahead, wrap, }: KeyboardNavigationOptions);
+    /** Where this press starts from, read again on every press. */
+    private get origin();
     /** Moves to an item, and chooses it where arriving is choosing. */
     private arrive;
     /**

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

@@ -81,13 +81,16 @@ export class KeyboardNavigationController {
         };
         this.host = host;
         this.items = items;
-        this.origin = origin;
+        this.originOf = typeof origin === 'function' ? origin : () => origin;
         this.reserved = reserved;
         this.selects = selects;
         this.words = typeahead;
         this.wrap = wrap;
         host.addController(this);
     }
+    get origin() {
+        return this.originOf();
+    }
     arrive(target) {
         target?.focusItem();
         if (this.selects()) {

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

@@ -0,0 +1,49 @@
+import type { ReactiveController, ReactiveControllerHost } from 'lit';
+/** The two journeys an overlay makes. */
+export type OpenPhase = 'entering' | 'exiting';
+/** What an `OpenPhaseController` reads of its host and writes onto it. */
+export interface OpenPhaseOptions {
+    /**
+     * Records each phase on the host, or takes it off: the host's own
+     * `toggleState`, passed in because it is protected, and one callback per
+     * phase so each state's name is written out where it is recorded.
+     */
+    mark: Record<OpenPhase, (on: boolean) => void>;
+    /** Whether the host is open, read after every update. */
+    open: () => boolean;
+    /** The element whose animations are the entrance and the exit. */
+    surface: () => Element | null | undefined;
+}
+/**
+ * Resolves once an element's animations have finished, or two frames on where
+ * it has none.
+ *
+ * Two frames first, so an entrance that starts on the frame after the change,
+ * as a `@starting-style` transition does once the element is shown, is
+ * running by the time the element is asked. `subtree`, so a `::backdrop` and
+ * anything inside the surface count too.
+ */
+export declare const animationsSettled: (element: Element | null | undefined) => Promise<void>;
+/**
+ * Says on the host that an overlay is on its way in or out, until its
+ * animations have finished, as `:state(entering)` and `:state(exiting)`.
+ *
+ * `:state(open)` turns at once, which is right for what the overlay is and too
+ * early for a stylesheet that wants to draw the journey: an exit has to know it
+ * is an exit while the panel is still on screen.
+ *
+ * **Never on the first update.** An overlay served open has made no journey,
+ * and marking one would put a state on a page that nobody moved.
+ *
+ * A turn counter, because a close that arrives during an entrance starts a new
+ * phase, and the entrance settling late must not clear the exit.
+ */
+export declare class OpenPhaseController implements ReactiveController {
+    private readonly options;
+    /** What `open` was after the last update, and `undefined` before the first. */
+    private last;
+    /** Which phase is the latest. */
+    private turn;
+    constructor(host: ReactiveControllerHost, options: OpenPhaseOptions);
+    hostUpdated(): void;
+}

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

@@ -0,0 +1,41 @@
+export const animationsSettled = async (element) => {
+    const frame = () => new Promise((resolve) => {
+        if (typeof requestAnimationFrame === 'function') {
+            requestAnimationFrame(() => resolve());
+        }
+        else {
+            setTimeout(resolve, 16);
+        }
+    });
+    await frame();
+    await frame();
+    if (!element || typeof element.getAnimations !== 'function') {
+        return;
+    }
+    await Promise.allSettled(element.getAnimations({ subtree: true }).map((one) => one.finished));
+};
+export class OpenPhaseController {
+    constructor(host, options) {
+        this.turn = 0;
+        this.options = options;
+        host.addController(this);
+    }
+    hostUpdated() {
+        const open = this.options.open();
+        const last = this.last;
+        this.last = open;
+        if (last === undefined || last === open) {
+            return;
+        }
+        this.turn += 1;
+        const turn = this.turn;
+        this.options.mark.entering(open);
+        this.options.mark.exiting(!open);
+        void animationsSettled(this.options.surface()).then(() => {
+            if (turn === this.turn) {
+                this.options.mark.entering(false);
+                this.options.mark.exiting(false);
+            }
+        });
+    }
+}

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

@@ -100,6 +100,22 @@ export declare class SourceController implements ReactiveController {
     get rows(): Row[];
     /** A held parse where it still describes the table, or a fresh one. */
     private parsed;
+    /**
+     * The series hidden on the table, by lowercased name. Empty where there is
+     * no table, which is every server render.
+     */
+    get hidden(): ReadonlySet<string>;
+    /**
+     * Hides these series on the table and shows every other, for every chart
+     * and legend reading it, which then redraw.
+     *
+     * Names are matched without regard to case or surrounding space, as a
+     * column's heading is everywhere else. Nothing happens where `for` names no
+     * table, or the set is already this one.
+     */
+    hide(names: Iterable<string>): void;
+    /** Counts this controller among the readers of the table it watches, or of none. */
+    private enlist;
     hostConnected(): void;
     hostUpdated(): void;
     hostDisconnected(): void;

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

@@ -1,5 +1,8 @@
 import { elementById } from '../../utils/element-by-id/element-by-id.js';
-import { readRows, readSeries } from '../../utils/read-series/read-series.js';
+import { readRows, readSeries, seriesKey, } from '../../utils/read-series/read-series.js';
+const HIDDEN = new WeakMap();
+const READERS = new WeakMap();
+const NONE = new Set();
 export class SourceController {
     constructor(host) {
         this.watched = null;
@@ -47,6 +50,43 @@ export class SourceController {
         }
         return { element, value: read(element), version: this.version };
     }
+    get hidden() {
+        const element = this.element;
+        return element ? (HIDDEN.get(element) ?? NONE) : NONE;
+    }
+    hide(names) {
+        const element = this.resolve();
+        if (!element) {
+            return;
+        }
+        const next = new Set([...names].map(seriesKey).filter(Boolean));
+        const now = HIDDEN.get(element) ?? NONE;
+        if (next.size === now.size && [...next].every((one) => now.has(one))) {
+            return;
+        }
+        if (next.size === 0) {
+            HIDDEN.delete(element);
+        }
+        else {
+            HIDDEN.set(element, next);
+        }
+        for (const reader of READERS.get(element) ?? []) {
+            reader.host.requestUpdate();
+        }
+    }
+    enlist(element) {
+        if (this.watched) {
+            READERS.get(this.watched)?.delete(this);
+        }
+        if (element) {
+            let readers = READERS.get(element);
+            if (!readers) {
+                readers = new Set();
+                READERS.set(element, readers);
+            }
+            readers.add(this);
+        }
+    }
     hostConnected() {
         this.watch();
     }
@@ -57,6 +97,8 @@ export class SourceController {
         }
     }
     hostDisconnected() {
+        this.enlist(null);
+        this.watched = null;
         this.observer?.disconnect();
         this.observer = undefined;
         this.tree?.disconnect();
@@ -67,6 +109,7 @@ export class SourceController {
         this.tree?.disconnect();
         this.version += 1;
         const element = this.resolve();
+        this.enlist(element);
         this.watched = element;
         if (typeof MutationObserver === 'undefined') {
             return;

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

@@ -0,0 +1,47 @@
+import { nothing, type ReactiveController, type ReactiveControllerHost, type TemplateResult } from 'lit';
+/** How `say` speaks. */
+export interface SayOptions {
+    /**
+     * Whether the region is emptied before the words land, so the same words
+     * said twice are heard twice. Defaults to `true`.
+     */
+    clear?: boolean;
+}
+/**
+ * A live status region an element renders only once it has something to say,
+ * and the words it says.
+ *
+ * **Not rendered until the first time**, so an element that never speaks
+ * carries no live region: a button that never waits, a file field that never
+ * refuses a file. `spoken` says whether it is rendered and `said` what it
+ * holds, and `drawStatus` draws it.
+ *
+ * **The words land a frame after the region**, through `say`, because a region
+ * that arrives with its words is read inconsistently, and emptied first, so
+ * the same words twice are a change both times. `sayNow` puts them in at once,
+ * for a region already rendered that is only changing what it says.
+ *
+ * `ArrivalController` is the other half of the same idea, for an element that
+ * is itself the news.
+ */
+export declare class StatusController implements ReactiveController {
+    private readonly host;
+    /** Whether the region is rendered: from the first time anything is said. */
+    spoken: boolean;
+    /** What the region says now. */
+    said: string;
+    constructor(host: ReactiveControllerHost);
+    hostConnected(): void;
+    /** Says `words` a frame from now, rendering the region at once where it is not yet. */
+    say(words: string, { clear }?: SayOptions): void;
+    /** Says `words` now, in the same update that renders the region. */
+    sayNow(words: string): void;
+    /** Records what the region holds, and asks for an update only where that moved. */
+    private hold;
+}
+/**
+ * The region a `StatusController` speaks in, or nothing before it has spoken:
+ * `<span part="live" role="status">`, which the element documents as its
+ * `live` part.
+ */
+export declare const drawStatus: (status: StatusController) => TemplateResult | typeof nothing;

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

@@ -0,0 +1,34 @@
+import { html, nothing, } from 'lit';
+export class StatusController {
+    constructor(host) {
+        this.host = host;
+        this.spoken = false;
+        this.said = '';
+        host.addController(this);
+    }
+    hostConnected() { }
+    say(words, { clear = true } = {}) {
+        this.hold(true, clear ? '' : this.said);
+        const fill = () => {
+            this.hold(true, words);
+        };
+        if (typeof requestAnimationFrame === 'function') {
+            requestAnimationFrame(fill);
+        }
+        else {
+            fill();
+        }
+    }
+    sayNow(words) {
+        this.hold(true, words);
+    }
+    hold(spoken, said) {
+        if (spoken === this.spoken && said === this.said) {
+            return;
+        }
+        this.spoken = spoken;
+        this.said = said;
+        this.host.requestUpdate();
+    }
+}
+export const drawStatus = (status) => status.spoken ? html `<span part="live" role="status">${status.said}</span>` : nothing;

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

@@ -0,0 +1,61 @@
+import type { ReactiveController, ReactiveControllerHost } from 'lit';
+import type { SwipeAxis } from '../../utils/swipe/swipe.js';
+export interface SwipeOptions {
+    /** The axis a swipe is read along, or `undefined` while swiping is off. */
+    axis: () => SwipeAxis | undefined;
+    /**
+     * Called on the release, with how far the pointer went and how fast it was
+     * going, in pixels per millisecond, on each axis.
+     */
+    end: (dx: number, dy: number, vx: number, vy: number) => void;
+    /** Called as the pointer moves, with how far it has gone from the press. */
+    move: (dx: number, dy: number) => void;
+    /**
+     * Whether a press may start a swipe, given the element it landed on. Every
+     * press may where this is not given. A field, a scroller that has its own use
+     * for the drag, or a mouse where dragging selects text, says no.
+     */
+    start?: (target: Element, event: PointerEvent) => boolean;
+    /** The element a swipe starts on, which carries `data-swiping` while one runs. */
+    surface: () => HTMLElement | null | undefined;
+}
+/**
+ * Follows a pointer dragged across a surface along one axis, for a surface the
+ * reader swipes away or along: a drawer, a toast, a lightbox's pictures.
+ *
+ * It decides only that a swipe is happening and reports where the pointer is.
+ * What a swipe means is the host's, which is why `move` and `end` are told the
+ * distance and nothing else: a drawer settles it against snap points, a toast
+ * against half its width, and a lightbox turns it into next or previous.
+ *
+ * **A press is a swipe only once it has moved `SLOP` pixels, mostly along the
+ * axis.** Before that it is still a press, so a tap on a button inside the
+ * surface is a tap, and a drag across the axis, a reader scrolling, is left to
+ * the page. Once it is a swipe, the click that ends it is swallowed, so a
+ * swipe that started on a button does not also press it.
+ *
+ * The move and the release are heard on the window, so a pointer that leaves
+ * the surface mid-swipe is still followed.
+ */
+export declare class SwipeController implements ReactiveController {
+    private readonly host;
+    private readonly options;
+    /** Where the press began, while one is down. */
+    private origin;
+    /** The last two readings, for the speed. */
+    private samples;
+    /** Whether the press has become a swipe. */
+    private swiping;
+    /** The pointer being followed. */
+    private pointer;
+    constructor(host: ReactiveControllerHost & HTMLElement, options: SwipeOptions);
+    hostConnected(): void;
+    hostDisconnected(): void;
+    private readonly handleDown;
+    private readonly handleMove;
+    private readonly handleUp;
+    /** A swipe the browser took over, for a scroll of its own, goes back to where it began. */
+    private readonly handleCancel;
+    /** Forgets the press and stops listening for it. */
+    private stop;
+}

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

@@ -0,0 +1,106 @@
+const SLOP = 8;
+export class SwipeController {
+    constructor(host, options) {
+        this.samples = [];
+        this.swiping = false;
+        this.handleDown = (event) => {
+            const surface = this.options.surface();
+            const path = event.composedPath();
+            const target = path[0];
+            if (event.button !== 0 ||
+                this.options.axis() === undefined ||
+                !surface ||
+                !(target instanceof Element) ||
+                !path.includes(surface) ||
+                (this.options.start && !this.options.start(target, event))) {
+                return;
+            }
+            this.pointer = event.pointerId;
+            this.origin = { t: event.timeStamp, x: event.clientX, y: event.clientY };
+            this.samples = [this.origin];
+            this.swiping = false;
+            window.addEventListener('pointermove', this.handleMove);
+            window.addEventListener('pointerup', this.handleUp);
+            window.addEventListener('pointercancel', this.handleCancel);
+        };
+        this.handleMove = (event) => {
+            const origin = this.origin;
+            const axis = this.options.axis();
+            if (!origin || event.pointerId !== this.pointer || axis === undefined) {
+                return;
+            }
+            const dx = event.clientX - origin.x;
+            const dy = event.clientY - origin.y;
+            if (!this.swiping) {
+                const along = Math.abs(axis === 'x' ? dx : dy);
+                const across = Math.abs(axis === 'x' ? dy : dx);
+                if (Math.max(along, across) < SLOP) {
+                    return;
+                }
+                if (across >= along) {
+                    this.stop();
+                    return;
+                }
+                this.swiping = true;
+                this.options.surface()?.setAttribute('data-swiping', '');
+            }
+            this.samples = [
+                ...this.samples.slice(-1),
+                { t: event.timeStamp, x: event.clientX, y: event.clientY },
+            ];
+            this.options.move(dx, dy);
+        };
+        this.handleUp = (event) => {
+            const origin = this.origin;
+            if (!origin || event.pointerId !== this.pointer) {
+                return;
+            }
+            const swiped = this.swiping;
+            const [before, last] = [this.samples[0], this.samples[this.samples.length - 1]];
+            const elapsed = before && last ? last.t - before.t : 0;
+            const vx = before && last && elapsed > 0 ? (last.x - before.x) / elapsed : 0;
+            const vy = before && last && elapsed > 0 ? (last.y - before.y) / elapsed : 0;
+            this.stop();
+            if (!swiped) {
+                return;
+            }
+            window.addEventListener('click', swallow, { capture: true, once: true });
+            setTimeout(() => window.removeEventListener('click', swallow, { capture: true }), 0);
+            this.options.end(event.clientX - origin.x, event.clientY - origin.y, vx, vy);
+        };
+        this.handleCancel = (event) => {
+            if (event.pointerId !== this.pointer) {
+                return;
+            }
+            const swiped = this.swiping;
+            this.stop();
+            if (swiped) {
+                this.options.end(0, 0, 0, 0);
+            }
+        };
+        this.host = host;
+        this.options = options;
+        host.addController(this);
+    }
+    hostConnected() {
+        this.host.addEventListener('pointerdown', this.handleDown);
+    }
+    hostDisconnected() {
+        this.host.removeEventListener('pointerdown', this.handleDown);
+        this.stop();
+    }
+    stop() {
+        window.removeEventListener('pointermove', this.handleMove);
+        window.removeEventListener('pointerup', this.handleUp);
+        window.removeEventListener('pointercancel', this.handleCancel);
+        this.options.surface()?.removeAttribute('data-swiping');
+        this.origin = undefined;
+        this.pointer = undefined;
+        this.samples = [];
+        this.swiping = false;
+    }
+}
+const swallow = (event) => {
+    event.preventDefault();
+    event.stopPropagation();
+};