@fusion.dev/helix-core 0.144.0 → 0.145.0

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

@@ -17,6 +17,7 @@ const RELATIONSHIPS = [
     ['aria-labelledby', 'ariaLabelledByElements'],
 ];
 const STATES = [
+    'aria-current',
     'aria-expanded',
     'aria-haspopup',
     'aria-controls',

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

@@ -0,0 +1,55 @@
+import type { ReactiveController, ReactiveControllerHost } from 'lit';
+/** What a `CountdownController` does when its time runs out, and when it stops and starts. */
+export interface CountdownOptions {
+    /** Runs once the time is spent. */
+    done: () => void;
+    /** Runs with `true` when the clock stops partway and `false` when it runs again. */
+    paused?: (paused: boolean) => void;
+}
+/**
+ * A lifetime that pauses: a message that dismisses itself after a time, and
+ * holds that time while a reader is on it.
+ *
+ * Toast's items and Announcement each dismiss themselves after `duration`,
+ * and each stops the clock while the pointer or focus is on the message, so a
+ * reader partway through is not cut off. Resuming continues from what was
+ * left rather than starting over.
+ *
+ * **Holds are counted, not flagged.** Hover and focus stop the same clock and
+ * are independent: a pointer can leave while focus stays. Uncounted, a reader
+ * who tabs into a message and then moves the pointer off it has the clock
+ * restarted underneath them. Only the last one out starts it again.
+ *
+ * **Leaving the page pauses it**, keeping the time already spent, and drops
+ * the holds, since a pointer or focus on a detached element never leaves it.
+ * Coming back does not resume on its own: the host says whether it should,
+ * such as only while it is still showing. `DelayController` is the other wait
+ * in core, for a wait that starts over and forgets itself on leaving.
+ */
+export declare class CountdownController implements ReactiveController {
+    private readonly options;
+    /** When the current run began, or nothing while the clock is stopped. */
+    private startedAt;
+    /** What is left of the time, so resuming continues rather than restarts. */
+    private remaining;
+    private timer;
+    /** How many reasons there are to hold the clock. */
+    private holds;
+    constructor(host: ReactiveControllerHost, options: CountdownOptions);
+    /** Whether the clock is running now. */
+    get running(): boolean;
+    hostConnected(): void;
+    hostDisconnected(): void;
+    /** Starts the clock at `ms`. Nothing, zero or less starts nothing. */
+    start(ms: number | undefined): void;
+    /** Stops the clock and keeps the time that is left. */
+    pause(): void;
+    /** Runs the clock again from where it stopped. */
+    resume(): void;
+    /** Stops the clock where it is, as a dismissal does. */
+    cancel(): void;
+    /** One more reason to hold the clock, such as a pointer arriving. */
+    hold(): void;
+    /** One reason fewer, and the clock runs again once none is left. */
+    release(): void;
+}

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

@@ -0,0 +1,57 @@
+export class CountdownController {
+    constructor(host, options) {
+        this.options = options;
+        this.holds = 0;
+        host.addController(this);
+    }
+    get running() {
+        return this.timer !== undefined;
+    }
+    hostConnected() { }
+    hostDisconnected() {
+        this.pause();
+        this.holds = 0;
+    }
+    start(ms) {
+        if (ms === undefined || !(ms > 0)) {
+            return;
+        }
+        this.remaining = ms;
+        this.resume();
+    }
+    pause() {
+        if (this.timer === undefined || this.startedAt === undefined) {
+            return;
+        }
+        clearTimeout(this.timer);
+        this.timer = undefined;
+        this.remaining = Math.max((this.remaining ?? 0) - (Date.now() - this.startedAt), 0);
+        this.startedAt = undefined;
+        this.options.paused?.(true);
+    }
+    resume() {
+        if (this.timer !== undefined || this.remaining === undefined || this.remaining <= 0) {
+            return;
+        }
+        this.startedAt = Date.now();
+        this.options.paused?.(false);
+        this.timer = setTimeout(() => {
+            this.timer = undefined;
+            this.options.done();
+        }, this.remaining);
+    }
+    cancel() {
+        clearTimeout(this.timer);
+        this.timer = undefined;
+    }
+    hold() {
+        this.holds += 1;
+        this.pause();
+    }
+    release() {
+        this.holds = Math.max(this.holds - 1, 0);
+        if (this.holds === 0) {
+            this.resume();
+        }
+    }
+}

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

@@ -63,6 +63,16 @@ export interface Window {
     /** Index one past the last item rendered. */
     last: number;
 }
+/** Where `reveal` puts an item, and how it gets there. */
+export interface RevealOptions {
+    /**
+     * Where the item lands: the least distance that shows it whole (`nearest`,
+     * the default), or at the box's `start`, `center` or `end`.
+     */
+    align?: 'center' | 'end' | 'nearest' | 'start';
+    /** The platform's scroll behavior. Instant when left out. */
+    behavior?: ScrollBehavior;
+}
 /**
  * Works out which slice of a long set is worth rendering.
  *
@@ -86,35 +96,14 @@ export interface Window {
  * track, so the room the absent rows would have taken is left as padding before
  * and after. A reader dragging that thumb is dragging against the real length.
  *
- * **What it does not do, and the reason is narrower than it first looks.** True
- * virtualization means never creating the rows that are not on screen, and that
- * needs the set as *data*. Two channels are shut: a consumer's items arrive as
- * light-DOM children, which exist by the time this could decide not to create
- * them, and an `items` property cannot survive React hydration, which skips
- * every property it would have to apply imperatively (see `bindReactHandler`,
- * and the note in the rules that objects and functions have that bug and are
- * not fixed).
- *
- * **A third channel is open.** Data as *text*
- * in the markup, a `<script type="application/json">` child or an attribute, is
- * neither a property nor a node per row: React's hydration bug cannot touch text
- * it renders as a child, a server emits it, and the node count is one. The
- * charts already read data out of the document this way, `for="<id>"` at a real
- * `<table>`, so the pattern is in the library rather than being invented for
- * this.
- *
- * So the thing actually blocked is the *row template*. Turning an item into
- * markup wants either a render function, which is a function property and dies
- * on the same bug, or a `<template>` with named holes, which survives because it
- * is markup and which no component here asks anyone to write. That is a decision
- * about what this library is willing to look like, not a platform limit, and it
- * is open at #71.
- *
- * So what this buys is the expensive half rather than all of it: the rows
- * outside the window are not laid out and not painted, which is where the time
- * goes in a long list, and the node count stays. That is worth having and it is
- * not worth calling something it is not. An element that windows children it
- * was handed is not a virtual list, whatever it is named.
+ * **The set arrives as data**, which is what lets a host create only the rows
+ * in the window. A host takes it through a property (an `items` array, which
+ * `applyReactProperties` carries across React hydration with every other object
+ * property) or as text in the markup (a `<script type="application/json">`
+ * named by `for`, which a server emits and which is one node whatever the
+ * row count). A host that is handed its rows as light-DOM children still gets
+ * the expensive half from this: the rows outside the window are not laid out
+ * and not painted, and the node count stays.
  *
  * **One estimate, not per-row measurement.** Measuring every row to place it is
  * how a virtual list ends up reading the layout it is trying to avoid, and it
@@ -166,6 +155,39 @@ export declare class VirtualizeController implements ReactiveController {
      * on screen plus the overscan, whatever the set's length.
      */
     private placed;
+    /**
+     * The items on screen, with no overscan: `first` is the item at the top of
+     * the box and `last` is one past the item at its bottom, so
+     * `items.slice(first, last)` is what a reader sees.
+     *
+     * For a host that reports what is visible, where `window` is what is drawn.
+     * An empty span (`first === last`) while the box has no height or the set
+     * no items.
+     */
+    visible(): {
+        first: number;
+        last: number;
+    };
+    /**
+     * How much of the set lies below the bottom of the box, in pixels.
+     *
+     * For a host that asks for more items as a reader nears the end. Read from
+     * the arithmetic and not from `scrollHeight`, which also counts whatever the
+     * host draws around the rows.
+     */
+    remaining(): number;
+    /**
+     * The two spacers' heights for the window, with item `kept` drawn too.
+     *
+     * For a host that keeps an item outside the window drawn, the row holding
+     * focus say. The item takes its own room out of the spacer on its side, so
+     * the scrollbar still measures the set. Every host that keeps a focused row
+     * asks this, so the arithmetic is written once.
+     */
+    spacers(kept?: number): {
+        after: number;
+        before: number;
+    };
     /**
      * Measures what was just drawn, and holds the reader still if it moved.
      *
@@ -206,14 +228,25 @@ export declare class VirtualizeController implements ReactiveController {
      */
     sizeOf(index: number): number;
     /**
-     * Scrolls the box the least distance that shows item `index` whole.
+     * Scrolls the box to show item `index`.
+     *
+     * By default the least distance that shows it 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.
      *
-     * 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.
+     * `align` puts the item at the box's `start`, `center` or `end` instead, and
+     * `behavior` is the platform's, for a host whose consumer asked to be taken
+     * to an item. A smooth scroll moves the window through the box's own
+     * `scroll` events, the same as a reader scrolling.
+     */
+    reveal(index: number, inset?: number, { align, behavior }?: RevealOptions): void;
+    /**
+     * Where item `index` starts along the scroll axis, in pixels from the top of
+     * the set: what was measured above it, or the estimate.
      */
-    reveal(index: number, inset?: number): void;
+    offsetOf(index: number): number;
     /**
      * Drops every measurement, for a host that swapped its data.
      *

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

@@ -39,6 +39,7 @@ export class VirtualizeController {
         }
         this.observer.observe(box);
         box.addEventListener('scroll', this.handleScroll, { passive: true });
+        box.setAttribute('data-virtual', '');
         this.watching = true;
     }
     measure() {
@@ -97,6 +98,48 @@ export class VirtualizeController {
             last,
         };
     }
+    visible() {
+        const box = this.options.container();
+        const total = Math.max(0, this.options.count());
+        if (!box || total === 0) {
+            return { first: 0, last: 0 };
+        }
+        const top = Math.max(0, box.scrollTop);
+        const bottom = top + box.clientHeight;
+        if (!this.measuring()) {
+            const size = Math.max(1, this.options.estimate());
+            const first = Math.min(Math.floor(top / size), total);
+            return { first, last: Math.max(first, Math.min(total, Math.ceil(bottom / size))) };
+        }
+        const first = this.heights.indexAt(top, total);
+        let last = first;
+        while (last < total && this.heights.before(last, total) < bottom) {
+            last += 1;
+        }
+        return { first, last };
+    }
+    remaining() {
+        const box = this.options.container();
+        const total = Math.max(0, this.options.count());
+        if (!box) {
+            return 0;
+        }
+        const length = this.measuring()
+            ? this.heights.total(total)
+            : total * Math.max(1, this.options.estimate());
+        return Math.max(0, length - Math.max(0, box.scrollTop) - box.clientHeight);
+    }
+    spacers(kept) {
+        const { after, before, first, last } = this.window;
+        if (kept === undefined || (kept >= first && kept < last)) {
+            return { after, before };
+        }
+        const room = this.sizeOf(kept);
+        return {
+            after: kept >= last ? Math.max(0, after - room) : after,
+            before: kept < first ? Math.max(0, before - room) : before,
+        };
+    }
     hostUpdated() {
         if (this.owed !== 0) {
             const box = this.options.container();
@@ -149,22 +192,46 @@ export class VirtualizeController {
     sizeOf(index) {
         return this.measuring() ? this.heights.at(index) : Math.max(1, this.options.estimate());
     }
-    reveal(index, inset = 0) {
+    reveal(index, inset = 0, { align = 'nearest', behavior } = {}) {
         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;
+        const top = this.offsetOf(index);
+        const size = this.sizeOf(index);
+        const room = box.clientHeight - inset;
+        let to;
+        if (align === 'start') {
+            to = top;
+        }
+        else if (align === 'center') {
+            to = top - inset - (room - size) / 2;
+        }
+        else if (align === 'end') {
+            to = top + size + inset - box.clientHeight;
+        }
+        else if (top < box.scrollTop) {
+            to = top;
         }
-        else if (bottom > box.scrollTop + box.clientHeight) {
-            box.scrollTop = bottom - box.clientHeight;
+        else if (top + size + inset > box.scrollTop + box.clientHeight) {
+            to = top + size + inset - box.clientHeight;
         }
+        else {
+            return;
+        }
+        const next = Math.max(0, to);
+        if (behavior && typeof box.scrollTo === 'function') {
+            box.scrollTo({ behavior, top: next });
+        }
+        else {
+            box.scrollTop = next;
+        }
+    }
+    offsetOf(index) {
+        const total = Math.max(0, this.options.count());
+        return this.measuring()
+            ? this.heights.before(index, total)
+            : Math.max(0, Math.min(index, total)) * Math.max(1, this.options.estimate());
     }
     forget() {
         this.heights.forget();