@fusion.dev/helix-core 0.143.0 → 0.144.0

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

package/dist/events/events.d.ts

@@ -261,6 +261,34 @@ export declare class HelixCanvasEditEvent extends CustomEvent<{
         name: string;
     });
 }
+/** Why a file field did not take a file. */
+export type Refusal = 'count' | 'invalid' | 'size' | 'type';
+/** One file a file field did not take, and why. */
+export interface RefusedFile {
+    /** The file. */
+    readonly file: File;
+    /** What the field's `validate` said about it, where it was the one refusing. */
+    readonly message?: string;
+    /** Why it was not taken. */
+    readonly reason: Refusal;
+}
+/** The files a file field refused. */
+export interface RejectDetail {
+    /** Each refused file with its reason, in the order they arrived. */
+    files: RefusedFile[];
+}
+/**
+ * Files arrived at a file field and some were refused: by `accept`, by
+ * `max-file-size`, by `max-files`, or by the field's own `validate`.
+ *
+ * A notification and not a request, because the files are already left out;
+ * the event is how a page tells the reader why. Bubbles and is composed, so a
+ * form around the field hears it.
+ */
+export declare class HelixRejectEvent extends CustomEvent<RejectDetail> {
+    static readonly eventName = "helix-reject";
+    constructor(detail: RejectDetail);
+}
 /** What a reader asked to take off the board. */
 export interface RemoveDetail {
     /** The cards, by name. */
@@ -1037,6 +1065,12 @@ export interface SelectDetail {
      * A flag says it outright.
      */
     alternate?: boolean;
+    /**
+     * The link of a row that is a link, which the browser follows once the event
+     * is done unless it is canceled. A client-side router cancels it and follows
+     * the link itself.
+     */
+    href?: string;
     /** Value of the item the reader chose. */
     value: string;
 }
@@ -1337,6 +1371,7 @@ declare const registry: {
     readonly HelixPreviousEvent: typeof HelixPreviousEvent;
     readonly HelixReadEvent: typeof HelixReadEvent;
     readonly HelixReconnectEvent: typeof HelixReconnectEvent;
+    readonly HelixRejectEvent: typeof HelixRejectEvent;
     readonly HelixRelabelEvent: typeof HelixRelabelEvent;
     readonly HelixRemoveEvent: typeof HelixRemoveEvent;
     readonly HelixReorderEvent: typeof HelixReorderEvent;

package/dist/events/events.js

@@ -152,6 +152,17 @@ export class HelixCanvasEditEvent extends CustomEvent {
         });
     }
 }
+export class HelixRejectEvent extends CustomEvent {
+    static { this.eventName = 'helix-reject'; }
+    constructor(detail) {
+        super(HelixRejectEvent.eventName, {
+            bubbles: true,
+            cancelable: false,
+            composed: true,
+            detail,
+        });
+    }
+}
 export class HelixRemoveEvent extends CustomEvent {
     static { this.eventName = 'helix-remove'; }
     constructor(detail) {
@@ -778,6 +789,7 @@ const registry = {
     HelixPreviousEvent,
     HelixReadEvent,
     HelixReconnectEvent,
+    HelixRejectEvent,
     HelixRelabelEvent,
     HelixRemoveEvent,
     HelixReorderEvent,