@fusion.dev/helix-core 0.142.1 → 0.144.0

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

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

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

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

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

@@ -26,10 +26,24 @@ export interface SourceHost extends ReactiveControllerHost, HTMLElement {
  * The element is watched for `childList` and `characterData` alike, because
  * renaming a series edits a text node in place rather than replacing a cell,
  * and nothing in a page has reason to know a chart is reading it.
+ *
+ * **The tree around it is watched as well, for the table that is not there
+ * yet.** A framework page renders a chart first and its table once the data
+ * loads, or re-keys the table and so replaces it under the same id. Watching
+ * only the element resolved on connect found nothing in the first case and
+ * kept a detached table in the second, and the chart drew neither until some
+ * unrelated property changed. So the root the id resolves in is watched for
+ * nodes arriving and leaving and for `id` and `role` changing, and each batch
+ * asks the id again. That is one lookup by id per batch, and a chart redraws
+ * only when the answer is a different element.
  */
 export declare class SourceController implements ReactiveController {
     private host;
     private observer;
+    /** Watches the tree `for` resolves in, for the table arriving, leaving or being replaced. */
+    private tree;
+    /** The element the watcher is on, or null where `for` named nothing. */
+    private watched;
     /** Whether a hydrating render was told there was nothing, and needs the render after. */
     private deferred;
     /**
@@ -86,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;
@@ -96,4 +126,12 @@ export declare class SourceController implements ReactiveController {
      * there is no `MutationObserver`, which is the server.
      */
     watch(): void;
+    /**
+     * Watches the root `for` resolves in, so a table that arrives, leaves or is
+     * replaced under the same id is followed.
+     *
+     * Only while `for` names something and the host sits in a tree that can
+     * resolve an id, which a detached host and a server render do not.
+     */
+    private watchTree;
 }

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

@@ -1,7 +1,11 @@
 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;
         this.deferred = false;
         this.version = 0;
         this.host = host;
@@ -46,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();
     }
@@ -56,14 +97,25 @@ export class SourceController {
         }
     }
     hostDisconnected() {
+        this.enlist(null);
+        this.watched = null;
         this.observer?.disconnect();
         this.observer = undefined;
+        this.tree?.disconnect();
+        this.tree = undefined;
     }
     watch() {
         this.observer?.disconnect();
+        this.tree?.disconnect();
         this.version += 1;
         const element = this.resolve();
-        if (!element || typeof MutationObserver === 'undefined') {
+        this.enlist(element);
+        this.watched = element;
+        if (typeof MutationObserver === 'undefined') {
+            return;
+        }
+        this.watchTree();
+        if (!element) {
             return;
         }
         this.observer ??= new MutationObserver(() => {
@@ -76,4 +128,21 @@ export class SourceController {
             subtree: true,
         });
     }
+    watchTree() {
+        const root = this.host.getRootNode();
+        if (this.host.for === '' || typeof root.getElementById !== 'function') {
+            return;
+        }
+        this.tree ??= new MutationObserver(() => {
+            if (this.resolve() !== this.watched) {
+                this.watch();
+                this.host.requestUpdate();
+            }
+        });
+        this.tree.observe(root, {
+            attributeFilter: ['id', 'role'],
+            childList: true,
+            subtree: true,
+        });
+    }
 }

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

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

@@ -198,6 +198,22 @@ export declare class VirtualizeController implements ReactiveController {
      * Call it from `willUpdate`, before the render that draws the grown set.
      */
     shift(by: number): void;
+    /**
+     * How tall item `index` is: what was measured, or the estimate.
+     *
+     * For a host that draws an item outside the window, the row holding focus
+     * say, and has to take that item's room out of a spacer.
+     */
+    sizeOf(index: number): number;
+    /**
+     * Scrolls the box the least distance that shows item `index` whole.
+     *
+     * For a host moving focus to an item outside the window, whose own element
+     * cannot be scrolled to because it is not drawn where it belongs. `inset` is
+     * how far into the box the items start, for a heading that sticks at its
+     * top and covers that much of every item scrolled under it.
+     */
+    reveal(index: number, inset?: number): void;
     /**
      * Drops every measurement, for a host that swapped its data.
      *

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

@@ -74,7 +74,7 @@ export class VirtualizeController {
         this.host.requestUpdate();
     }
     uniform(box, total, size, overscan) {
-        const first = Math.max(0, Math.floor(box.scrollTop / size) - overscan);
+        const first = Math.max(0, Math.min(Math.floor(box.scrollTop / size), total) - overscan);
         const fits = Math.ceil(box.clientHeight / size) + overscan * 2;
         const last = Math.min(total, first + fits);
         return { after: Math.max(0, (total - last) * size), before: first * size, first, last };
@@ -146,6 +146,26 @@ export class VirtualizeController {
         };
         this.owed += room;
     }
+    sizeOf(index) {
+        return this.measuring() ? this.heights.at(index) : Math.max(1, this.options.estimate());
+    }
+    reveal(index, inset = 0) {
+        const box = this.options.container();
+        if (!box) {
+            return;
+        }
+        const total = Math.max(0, this.options.count());
+        const top = this.measuring()
+            ? this.heights.before(index, total)
+            : index * Math.max(1, this.options.estimate());
+        const bottom = top + this.sizeOf(index) + inset;
+        if (top < box.scrollTop) {
+            box.scrollTop = top;
+        }
+        else if (bottom > box.scrollTop + box.clientHeight) {
+            box.scrollTop = bottom - box.clientHeight;
+        }
+    }
     forget() {
         this.heights.forget();
     }
@@ -161,7 +181,9 @@ export class VirtualizeController {
                 'the last one. That happens when the scrolling box has no height of its own: its ' +
                 '`clientHeight` is then a function of the rows just drawn, so measuring moves what is ' +
                 'being measured and the two never agree. Give the container a block size and an ' +
-                'overflow, which is what the styled tier does and what a headless consumer has to.',
+                'overflow, which is what the styled tier does and what a headless consumer has to. ' +
+                'It also happens when the rows report no height, such as a row drawn with ' +
+                '`display: contents`, which is a fault in the component that draws them.',
             tag: typeof host.localName === 'string' ? host.localName : undefined,
         });
     }