@fusion.dev/helix-core 0.145.0 → 0.146.0

package/dist/controllers/aria-forward-controller/aria-forward-controller.d.ts

@@ -84,7 +84,8 @@ export interface AriaForwardOptions {
  * and the host is a generic the reader never lands on, so a `<label for>` or a
  * wrapping `<label>` left the textbox unnamed. The labels travel the same way a
  * forwarded `aria-labelledby` does, as element references, and are read again
- * when focus arrives, since a label can be added without the host hearing.
+ * on every update, which a form control asks for whenever a label in its tree
+ * changes (`watchLabels`), and as focus arrives.
  */
 export declare class AriaForwardController implements ReactiveController {
     private readonly host;
@@ -128,7 +129,7 @@ export declare class AriaForwardController implements ReactiveController {
     forward(): void;
     hostConnected(): void;
     hostDisconnected(): void;
-    /** Forwards again as focus arrives, for a label added since the last update. */
+    /** Forwards again as focus arrives. */
     private readonly refresh;
     hostUpdated(): void;
 }

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

@@ -1,17 +1,6 @@
-import { auditName } from '../../utils/audit-name/audit-name.js';
+import { auditName } from '#audit-name';
 import { elementById } from '../../utils/element-by-id/element-by-id.js';
-const shownText = (node) => {
-    if (node instanceof HTMLSlotElement) {
-        return node.assignedNodes({ flatten: true }).map(shownText).join('');
-    }
-    if (node.nodeType === Node.TEXT_NODE) {
-        return node.textContent ?? '';
-    }
-    if (node instanceof HTMLElement && node.hidden) {
-        return '';
-    }
-    return [...node.childNodes].map(shownText).join('');
-};
+import { nameText } from '../../utils/name-text/name-text.js';
 const RELATIONSHIPS = [
     ['aria-describedby', 'ariaDescribedByElements'],
     ['aria-labelledby', 'ariaLabelledByElements'],
@@ -49,7 +38,7 @@ export class AriaForwardController {
             return true;
         }
         const own = target.labels;
-        return [...(own ?? [])].some((label) => shownText(label).trim() !== '');
+        return [...(own ?? [])].some((label) => nameText(label).trim() !== '');
     }
     hostLabels(target) {
         const labels = this.host.labels;

package/dist/controllers/chart-pointer-controller/chart-pointer-controller.d.ts

@@ -34,6 +34,31 @@ export interface ChartPointerHost extends ReactiveControllerHost, HTMLElement {
      * drawn from, such as a scatter's measure across.
      */
     seriesOf?(cell: number): number | undefined;
+    /**
+     * Whether the series drawn from the cell at this place in a row is shown,
+     * which it is unless a legend hid it. Absent, every series is shown.
+     *
+     * The series keys pass over a hidden one, and the readout leaves it out.
+     */
+    showsColumn?(cell: number): boolean;
+    /**
+     * Whether the reading at this place is shown, for a chart whose readings
+     * a legend can hide: a ring's slices are its rows. Absent, every reading is
+     * shown.
+     *
+     * The keys pass over a hidden reading, as they pass over a hidden series.
+     */
+    showsReading?(at: number): boolean;
+    /**
+     * The words for where a reading stands among them, with `{position}` and
+     * `{count}` to fill. Absent or empty, no position is said.
+     */
+    readonly positionLabel?: string;
+    /**
+     * The locale the position's numbers are written in. Absent or empty is the
+     * runtime's own.
+     */
+    readonly locale?: string;
 }
 /**
  * Which reading a pointer is nearest, for a chart that draws no markers.
@@ -62,8 +87,9 @@ export interface ChartPointerHost extends ReactiveControllerHost, HTMLElement {
  * **The keyboard moves the same reading, which is what makes it the reading
  * and not the pointer's.** A chart's plot takes focus (`tabindex="0"` on the
  * element carrying `CHART_PLOT`), and while it has it the arrow keys walk the
- * readings, Home and End go to the first and the last, and the other pair of
- * arrows walks the series within a reading. Escape puts the bubble away, as it
+ * readings, Home and End go to the first and the last, PageUp and PageDown
+ * move a page of readings, and the other pair of arrows walks the series
+ * within a reading. Escape puts the bubble away, as it
  * does a tooltip. The tooltip follows because it already follows `at`, and the
  * chart's readout, a polite live region `drawTooltip` renders, says the
  * reading in words. It speaks only for a key: a pointer crossing a chart is a
@@ -125,8 +151,41 @@ export declare class ChartPointerController implements ReactiveController {
      * from, and the bubble lists every one of them.
      */
     get column(): number | undefined;
-    /** The cells a series key can rest on: every column a series was drawn from. */
+    /**
+     * Whether the series drawn from the cell at this place in a row is shown.
+     *
+     * The readout asks, so a reading said whole leaves out what a legend hid,
+     * as the drawing does.
+     */
+    shows(cell: number): boolean;
+    /**
+     * How far PageUp and PageDown move: four columns of a grid, which is four
+     * weeks of a calendar heatmap, a month near enough; and a tenth of the
+     * readings otherwise, at least one.
+     */
+    private page;
+    /**
+     * Where the reading stands among the shown readings, in the host's
+     * `positionLabel`, such as "2 of 12". Empty with no reading, and where the
+     * host gives no words.
+     *
+     * Counted among the shown readings, so a slice a legend hid is not one of
+     * the count.
+     */
+    get position(): string;
+    /**
+     * The cells a series key can rest on: every column a series was drawn
+     * from, and is still drawn from.
+     */
     private columns;
+    /**
+     * The readings the keys walk, by place: every one, less those a legend hid.
+     *
+     * The keys step through this list, so a hidden
+     * slice is passed over as if it were not in the table, which is how the
+     * ring draws it.
+     */
+    private shown;
     /**
      * Tells the tooltip its anchor moved, which nothing else would.
      *
@@ -145,6 +204,9 @@ export declare class ChartPointerController implements ReactiveController {
     /**
      * The box the readings are laid out in, which is the plot and not the host.
      *
+     * Found by its part, or by the id every chart gives its plot, which is how
+     * a sparkline's drawing, whose part is `svg`, is found.
+     *
      * The host also holds the row of labels, so measuring against it would map
      * the pointer over a box taller than the drawing. That mattered the moment a
      * chart started measuring down the box rather than across it, which is what

package/dist/controllers/chart-pointer-controller/chart-pointer-controller.js

@@ -1,3 +1,5 @@
+import { fillTemplate } from '../../utils/fill-template/fill-template.js';
+import { formatNumbers } from '../../utils/format-numbers/format-numbers.js';
 import { isRtl } from '../../utils/is-rtl/is-rtl.js';
 import { stepReading } from './reading-step.js';
 export const CHART_PLOT = 'helix-chart-plot';
@@ -13,7 +15,8 @@ export class ChartPointerController {
             if (!this.fromPlot(event) || event.altKey || event.ctrlKey || event.metaKey) {
                 return;
             }
-            const count = this.host.readings;
+            const shown = this.shown();
+            const count = shown.length;
             if (count === 0) {
                 return;
             }
@@ -24,17 +27,19 @@ export class ChartPointerController {
                 }
                 return;
             }
-            const next = stepReading(event.key, { at: this.at, series: this.series }, {
+            const next = stepReading(event.key, { at: shown.indexOf(this.at), series: this.series }, {
                 axis: this.axis,
                 count,
                 grid: this.grid,
+                page: this.page(count),
                 rtl: isRtl(this.host),
                 series: this.columns().length,
             });
             if (next === undefined) {
                 return;
             }
-            const { at, series } = next;
+            const at = shown[next.at] ?? -1;
+            const { series } = next;
             event.preventDefault();
             if (at === this.at && series === this.series && this.keyed) {
                 return;
@@ -56,10 +61,11 @@ export class ChartPointerController {
             }
             catch {
             }
-            if (!visible || this.host.readings === 0) {
+            const first = this.shown()[0];
+            if (!visible || first === undefined) {
                 return;
             }
-            this.at = 0;
+            this.at = first;
             this.keyed = true;
             this.moved = true;
             this.host.requestUpdate();
@@ -123,12 +129,32 @@ export class ChartPointerController {
     get column() {
         return this.series < 0 ? undefined : this.columns()[this.series];
     }
+    shows(cell) {
+        return this.host.showsColumn?.(cell) !== false;
+    }
+    page(count) {
+        return this.grid > 1 ? this.grid * 4 : Math.max(1, Math.round(count / 10));
+    }
+    get position() {
+        const words = this.host.positionLabel ?? '';
+        const shown = this.shown();
+        const place = shown.indexOf(this.at);
+        if (words === '' || place < 0) {
+            return '';
+        }
+        const format = formatNumbers(this.host.locale ?? '');
+        return fillTemplate(words, { count: format(shown.length), position: format(place + 1) });
+    }
     columns() {
         const host = this.host;
-        const all = host.plottedColumns ?? [];
-        return host.seriesOf === undefined
+        return (host.plottedColumns ?? []).filter((one) => (host.seriesOf === undefined || host.seriesOf(one) !== undefined) && this.shows(one));
+    }
+    shown() {
+        const host = this.host;
+        const all = Array.from({ length: host.readings }, (_, at) => at);
+        return host.showsReading === undefined
             ? all
-            : all.filter((one) => host.seriesOf?.(one) !== undefined);
+            : all.filter((at) => host.showsReading?.(at) !== false);
     }
     hostUpdated() {
         if (!this.moved) {
@@ -141,7 +167,9 @@ export class ChartPointerController {
     }
     box() {
         if (!this.plot?.isConnected) {
-            this.plot = this.host.renderRoot.querySelector('[part="plot"]') ?? undefined;
+            this.plot =
+                this.host.renderRoot.querySelector(`[part="plot"], #${CHART_PLOT}`) ??
+                    undefined;
         }
         return this.plot?.getBoundingClientRect();
     }

package/dist/controllers/chart-pointer-controller/reading-step.d.ts

@@ -18,6 +18,11 @@ export interface ReadingLayout {
     count: number;
     /** How many readings stand in one column, for a grid. `1` is a row of them. */
     grid: number;
+    /**
+     * How far PageUp and PageDown move, in readings. Absent, they move nothing
+     * and the page keeps them.
+     */
+    page?: number;
     /** Whether the line of text runs right to left, which turns the inline arrows. */
     rtl: boolean;
     /** How many series a reading holds, which the cross pair of arrows walks. */
@@ -49,7 +54,8 @@ export declare const amongSeries: (key: string, layout: ReadingLayout) => number
  * Where a key moves the reading, or `undefined` for a key that moves nothing,
  * which the page keeps.
  *
- * Home and End go to the first and the last. From no reading, an arrow moving
+ * Home and End go to the first and the last, and PageUp and PageDown move a
+ * `page` of readings where the layout gives one. From no reading, an arrow moving
  * on starts at the first and one moving back at the last, so either arrow
  * starts somewhere a reader expects. A series key on no reading starts on the
  * first. Nothing walks off either end.

package/dist/controllers/chart-pointer-controller/reading-step.js

@@ -29,6 +29,11 @@ export const stepReading = (key, from, layout) => {
     if (key === 'End') {
         return { at: last, series: from.series };
     }
+    if ((key === 'PageDown' || key === 'PageUp') && layout.page !== undefined) {
+        const step = Math.max(1, layout.page) * (key === 'PageDown' ? 1 : -1);
+        const at = from.at < 0 ? (step > 0 ? 0 : last) : Math.min(Math.max(from.at + step, 0), last);
+        return { at, series: from.series };
+    }
     const along = alongReadings(key, layout);
     if (along !== 0) {
         const at = from.at < 0 ? (along > 0 ? 0 : last) : Math.min(Math.max(from.at + along, 0), last);

package/dist/controllers/keyboard-navigation-controller/keyboard-navigation-controller.d.ts

@@ -1,4 +1,5 @@
 import type { ReactiveController, ReactiveControllerHost } from 'lit';
+import { type TypeaheadBy } from '../../utils/typeahead/typeahead.js';
 /** What a controller needs of an item to move to it and choose it. */
 export interface NavigableItem {
     /**
@@ -70,14 +71,15 @@ export interface KeyboardNavigationOptions {
      */
     reserved?: () => string[];
     /**
-     * The words of an item, which turns on typeahead: a printable key moves to
-     * the next item whose words start with what was typed.
+     * The search that turns on typeahead, built with `typeaheadBy` from the
+     * words of an item: a printable key moves to the next item whose words
+     * start with what was typed.
      *
      * Off unless given. A set whose items have no words a reader would type, or
      * that holds a text field of its own, leaves it out. See `Typeahead` for how
      * the letters are matched.
      */
-    typeahead?: (item: NavigableItem) => string;
+    typeahead?: TypeaheadBy<NavigableItem>;
     /**
      * Whether the ends join up, which they do unless a set says otherwise.
      *
@@ -98,54 +100,6 @@ export interface KeyboardNavigationOptions {
      */
     wrap?: boolean;
 }
-/**
- * Whether a press types a character, which is what typeahead reads.
- *
- * One character with no Control, Command or Alt held, so a shortcut such as
- * Control+A is never taken for the letter A. Shift is allowed, because a
- * capital is still a letter.
- */
-export declare const typesCharacter: (event: KeyboardEvent) => boolean;
-/**
- * Finds an item by the letters a reader types at a set, the way a native
- * `<select>` does.
- *
- * Letters typed within `timeout` milliseconds of each other build one search,
- * so typing "ca" moves to "Canada" past "Cambodia". The same letter typed again
- * moves to the next item that starts with it, so pressing "c" three times visits
- * the first three. A pause starts a new search.
- *
- * Matching ignores case and leading spaces, and searches from the reader's
- * position, wrapping at the end. A search that matches nothing moves nothing.
- *
- * Holds only the letters, so one instance serves any set: the caller passes the
- * words of the items and where the reader is on every key.
- */
-export declare class Typeahead {
-    private letters;
-    private last;
-    private readonly timeout;
-    constructor({ timeout }?: {
-        timeout?: number;
-    });
-    /**
-     * Whether a search is under way.
-     *
-     * A set that chooses on Space asks this first, because a Space typed in the
-     * middle of a search is part of the words, as in "New York".
-     */
-    typing(now?: number): boolean;
-    /**
-     * Adds a character to the search, and returns the index of the item it
-     * matches, or `-1` where none does.
-     *
-     * `texts` are the words of the items a reader can reach, in order, and
-     * `from` is the index of the item the reader is on, or `-1`.
-     */
-    match(key: string, texts: readonly string[], from: number, now?: number): number;
-    /** Ends the search, so the next letter starts a new one. */
-    reset(): void;
-}
 /**
  * Moves through a set of items with the arrow keys, and chooses as it goes.
  *
@@ -171,9 +125,10 @@ export declare class Typeahead {
  * Disabled items are skipped rather than stopped at, so a set with a gap in it
  * still moves in one press.
  *
- * **Typeahead is opt-in.** Pass `typeahead` with a function that returns an
- * item's words, and a printable key moves to the next item whose words start
- * with the letters typed, choosing it where arriving chooses. A key that a text
+ * **Typeahead is opt-in.** Pass `typeahead`, built by `typeaheadBy` from a
+ * function that returns an item's words, and a printable key moves to the next
+ * item whose words start with the letters typed, choosing it where arriving
+ * chooses. A key that a text
  * field inside the set is typing into is left to the field.
  *
  * A set that starts from focus rather than from the selection, or that moves
@@ -187,7 +142,6 @@ export declare class KeyboardNavigationController implements ReactiveController
     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. */

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

@@ -1,41 +1,9 @@
 import { inlineStep } from '../../utils/inline-step/inline-step.js';
 import { keyClaimed } from '../../utils/key-claimed/key-claimed.js';
+import { typesCharacter } from '../../utils/typeahead/typeahead.js';
 const KEYS = new Set(['ArrowDown', 'ArrowLeft', 'ArrowRight', 'ArrowUp', 'End', 'Home']);
-export const typesCharacter = (event) => event.key.length === 1 && !event.ctrlKey && !event.metaKey && !event.altKey;
-export class Typeahead {
-    constructor({ timeout = 500 } = {}) {
-        this.letters = '';
-        this.last = 0;
-        this.timeout = timeout;
-    }
-    typing(now = Date.now()) {
-        return this.letters !== '' && now - this.last <= this.timeout;
-    }
-    match(key, texts, from, now = Date.now()) {
-        if (!this.typing(now)) {
-            this.letters = '';
-        }
-        this.last = now;
-        this.letters += key.toLowerCase();
-        const words = texts.map((text) => text.trim().toLowerCase());
-        const repeated = [...this.letters].every((letter) => letter === this.letters[0]);
-        const needle = repeated ? (this.letters[0] ?? '') : this.letters;
-        const start = repeated ? from + 1 : Math.max(from, 0);
-        for (let step = 0; step < words.length; step += 1) {
-            const at = (start + step) % words.length;
-            if (words[at]?.startsWith(needle)) {
-                return at;
-            }
-        }
-        return -1;
-    }
-    reset() {
-        this.letters = '';
-    }
-}
 export class KeyboardNavigationController {
     constructor(host, { items, origin = 'selection', reserved = () => [], selects = () => true, typeahead, wrap = true, }) {
-        this.typeahead = new Typeahead();
         this.handleKeydown = (event) => {
             if (!KEYS.has(event.key)) {
                 this.handleTypeahead(event);
@@ -76,7 +44,7 @@ export class KeyboardNavigationController {
                 next = last;
             }
             event.preventDefault();
-            this.typeahead.reset();
+            this.typeahead?.search.reset();
             this.arrive(items[next]);
         };
         this.host = host;
@@ -84,7 +52,7 @@ export class KeyboardNavigationController {
         this.originOf = typeof origin === 'function' ? origin : () => origin;
         this.reserved = reserved;
         this.selects = selects;
-        this.words = typeahead;
+        this.typeahead = typeahead;
         this.wrap = wrap;
         host.addController(this);
     }
@@ -107,11 +75,11 @@ export class KeyboardNavigationController {
         return selected < 0 ? focused : selected;
     }
     handleTypeahead(event) {
-        const words = this.words;
-        if (!words || !typesCharacter(event) || keyClaimed(event)) {
+        const typeahead = this.typeahead;
+        if (!typeahead || !typesCharacter(event) || keyClaimed(event)) {
             return;
         }
-        if (event.key === ' ' && !this.typeahead.typing()) {
+        if (event.key === ' ' && !typeahead.search.typing()) {
             return;
         }
         const items = this.items().filter((item) => !item.disabled);
@@ -122,7 +90,7 @@ export class KeyboardNavigationController {
         if (this.origin === 'focus' && from === -1) {
             return;
         }
-        const at = this.typeahead.match(event.key, items.map(words), from);
+        const at = typeahead.search.match(event.key, items.map(typeahead.words), from);
         event.preventDefault();
         if (at >= 0 && at !== from) {
             this.arrive(items[at]);

package/dist/controllers/relative-clock-controller/relative-clock-controller.d.ts

@@ -0,0 +1,44 @@
+import type { ReactiveController, ReactiveControllerHost } from 'lit';
+/** What the clock reads from its host. */
+export interface RelativeClockOptions {
+    /**
+     * When the reading drawn at `now` stops being true, as `relativeTime` and
+     * `elapsedTime` say in `next`, in milliseconds from `now`; or `undefined`
+     * where the host shows no reading, which reads nothing and schedules
+     * nothing.
+     */
+    expires: (now: Date) => number | undefined;
+}
+/**
+ * The time a relative reading is drawn against, moved on when the reading
+ * would change: "3 minutes ago" becoming "4 minutes ago".
+ *
+ * **One wakeup when the words go stale, and none in between.** The reading
+ * says how long it holds, so the clock asks core's shared ticker for exactly
+ * that moment: a reading a minute old wakes once a minute, an hour old once an
+ * hour, and a date never. Every reading on the page shares the ticker's one
+ * timer. Chat Message and Format Date draw against it.
+ *
+ * **Only on a page.** A server has nobody to update a reading for, and a
+ * subscription there holds the element after its markup is sent, so off the
+ * page `tick()` reads the time and schedules nothing.
+ */
+export declare class RelativeClockController implements ReactiveController {
+    private readonly host;
+    private readonly options;
+    /** The time the host last drew against, in milliseconds. */
+    now: number;
+    private stop;
+    constructor(host: ReactiveControllerHost & HTMLElement, options: RelativeClockOptions);
+    hostConnected(): void;
+    hostDisconnected(): void;
+    /**
+     * Reads the clock again, asks the host to draw against it, and schedules
+     * the next reading.
+     *
+     * The host calls it when what it reads changes, the instant or the locale,
+     * and the ticker calls it when the words go stale. A host with no reading
+     * is left as it is.
+     */
+    tick(): void;
+}

package/dist/controllers/relative-clock-controller/relative-clock-controller.js

@@ -0,0 +1,31 @@
+import { subscribe } from '../../utils/ticker/ticker.js';
+export class RelativeClockController {
+    constructor(host, options) {
+        this.host = host;
+        this.options = options;
+        this.now = Date.now();
+        this.stop = undefined;
+        host.addController(this);
+    }
+    hostConnected() {
+        this.tick();
+    }
+    hostDisconnected() {
+        this.stop?.();
+        this.stop = undefined;
+    }
+    tick() {
+        this.stop?.();
+        this.stop = undefined;
+        const now = Date.now();
+        const next = this.options.expires(new Date(now));
+        if (next === undefined) {
+            return;
+        }
+        this.now = now;
+        this.host.requestUpdate();
+        if (Number.isFinite(next) && this.host.isConnected) {
+            this.stop = subscribe(next, () => this.tick());
+        }
+    }
+}

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

@@ -107,13 +107,20 @@ export declare class SourceController implements ReactiveController {
     get hidden(): ReadonlySet<string>;
     /**
      * Hides these series on the table and shows every other, for every chart
-     * and legend reading it, which then redraw.
+     * and legend reading it, which then redraw. Answers the table it wrote to,
+     * or null where `for` names none.
+     *
+     * Given `among`, only those names are shown or hidden, and a series hidden
+     * outside them stays hidden. A legend passes its own entries, so a legend
+     * of the rows and a legend of the columns on one table each keep what the
+     * other hid.
      *
      * 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.
+     * table, or the set is already this one, so two writers that agree stop
+     * asking each other to redraw.
      */
-    hide(names: Iterable<string>): void;
+    hide(names: Iterable<string>, among?: Iterable<string>): Element | null;
     /** Counts this controller among the readers of the table it watches, or of none. */
     private enlist;
     hostConnected(): void;

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

@@ -54,15 +54,17 @@ export class SourceController {
         const element = this.element;
         return element ? (HIDDEN.get(element) ?? NONE) : NONE;
     }
-    hide(names) {
+    hide(names, among) {
         const element = this.resolve();
         if (!element) {
-            return;
+            return null;
         }
-        const next = new Set([...names].map(seriesKey).filter(Boolean));
         const now = HIDDEN.get(element) ?? NONE;
+        const mine = among === undefined ? undefined : new Set([...among].map(seriesKey));
+        const kept = mine === undefined ? [] : [...now].filter((one) => !mine.has(one));
+        const next = new Set([...kept, ...[...names].map(seriesKey)].filter(Boolean));
         if (next.size === now.size && [...next].every((one) => now.has(one))) {
-            return;
+            return element;
         }
         if (next.size === 0) {
             HIDDEN.delete(element);
@@ -73,6 +75,7 @@ export class SourceController {
         for (const reader of READERS.get(element) ?? []) {
             reader.host.requestUpdate();
         }
+        return element;
     }
     enlist(element) {
         if (this.watched) {