@fusion.dev/helix-core 0.144.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,22 +1,12 @@
-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'],
 ];
 const STATES = [
+    'aria-current',
     'aria-expanded',
     'aria-haspopup',
     'aria-controls',
@@ -48,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/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

@@ -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 {
     /**
@@ -19,6 +20,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 +38,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.
      *
@@ -63,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.
      *
@@ -91,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.
  *
@@ -164,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
@@ -176,13 +138,14 @@ 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

@@ -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,18 +44,21 @@ export class KeyboardNavigationController {
                 next = last;
             }
             event.preventDefault();
-            this.typeahead.reset();
+            this.typeahead?.search.reset();
             this.arrive(items[next]);
         };
         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.typeahead = typeahead;
         this.wrap = wrap;
         host.addController(this);
     }
+    get origin() {
+        return this.originOf();
+    }
     arrive(target) {
         target?.focusItem();
         if (this.selects()) {
@@ -104,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);
@@ -119,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;
+}