@fusion.dev/helix-headless 0.146.0 → 0.148.0

package/dist/format-date/root/format-date-root.d.ts

@@ -25,6 +25,13 @@ import { nothing, type PropertyValues, type TemplateResult } from 'lit';
  * **The text refreshes on one timer shared by the page.** Each element
  * schedules an update for when its current reading expires, and an element
  * showing a date schedules none, so a long feed left open costs almost nothing.
+ * `frozen` draws the reading once and leaves it.
+ *
+ * **`fields` draws each field of a date as a part of its own**, such as
+ * `day`, `month` and `year`, so a stylesheet can set the year in a lighter ink
+ * or the weekday in capitals with `::part()`. The text between the fields is
+ * the locale's own and has no part. An `elapsed` or `relative` reading is one
+ * phrase, with no parts inside it.
  *
  * **The output is always `<time datetime>`**, so copy and paste and scripts
  * parsing the page get the exact instant, whatever the visible text says. A
@@ -42,7 +49,20 @@ import { nothing, type PropertyValues, type TemplateResult } from 'lit';
  * @aliases RelativeTime, Timestamp, TimeAgo
  * @documentation https://fusion.dev/helix/components/format-date
  *
+ * @csspart day - The day of the month, with `fields`.
+ * @csspart day-period - AM or PM, or the locale's word for the part of the day, with `fields`.
+ * @csspart era - The era, such as AD, with `fields` and `era`.
+ * @csspart hour - The hour, with `fields`.
+ * @csspart minute - The minute, with `fields`.
+ * @csspart month - The month, with `fields`.
+ * @csspart second - The second, with `fields`.
  * @csspart time - The `<time>` element that holds the formatted text.
+ * @csspart time-zone-name - The time zone's name, with `fields`, where `time-zone-name` or a `long` or `full` `time-style` shows it.
+ * @csspart weekday - The day of the week, with `fields`.
+ * @csspart year - The year, with `fields`.
+ *
+ * @cssstate future - An `elapsed` or `relative` reading of a moment still to come, such as "in 3 hours".
+ * @cssstate past - An `elapsed` or `relative` reading of a moment gone, such as "3 hours ago".
  */
 export declare class HelixHeadlessFormatDate extends HelixElement {
     /**
@@ -85,6 +105,29 @@ export declare class HelixHeadlessFormatDate extends HelixElement {
      * How the era is written, such as AD, where a date is shown.
      */
     era?: 'long' | 'narrow' | 'short';
+    /**
+     * Draws each field of a date in a part of its own: `weekday`, `day`,
+     * `month`, `year`, `era`, `hour`, `minute`, `second`, `day-period` and
+     * `time-zone-name`, so `::part(year)` can set the year apart.
+     *
+     * Off by default, which draws the date as one run of text, as Shoelace and
+     * Web Awesome do. An `elapsed` or `relative` reading is one phrase either
+     * way.
+     */
+    fields?: boolean;
+    /**
+     * Draws an `elapsed` or `relative` reading once and leaves it, where it
+     * would otherwise move on as it goes stale.
+     *
+     * For a reading that describes a moment the page itself is about, such as
+     * "3 hours ago" in a report generated then, or a list a reader compares
+     * line by line while it should not change under them. The reading is taken
+     * when the element draws, and again whenever `date` or another option
+     * changes. Turned off, the reading catches up and moves on again.
+     * `sl-relative-time` and `wa-relative-time` keep still unless `sync` is
+     * set; this keeps moving unless `frozen` is.
+     */
+    frozen: boolean;
     /**
      * How the hour is written, where a time of day is shown.
      */
@@ -100,9 +143,12 @@ export declare class HelixHeadlessFormatDate extends HelixElement {
     /**
      * The locale to format the timestamp in.
      *
-     * Empty is the runtime's own.
+     * Absent is the page's: the `lang` of the nearest element with one, as
+     * Shoelace and Web Awesome read it, then the runtime's own.
      */
     locale: string;
+    /** The locale the words are written in: `locale`, or the page's `lang`. */
+    private get language();
     /**
      * How the minute is written, where a time of day is shown.
      */
@@ -167,15 +213,18 @@ export declare class HelixHeadlessFormatDate extends HelixElement {
     private readonly clock;
     /**
      * The date read out of the light DOM, where no attribute carried one.
+     *
+     * Not a reactive state: `read` asks for the update itself, which keeps the
+     * `state` decorator out of this element's bundle.
      */
     private written;
-    private watching;
+    private watching?;
     /** Whether the timestamp is a day with no time, which is formatted in UTC. */
     private get dateOnly();
     /** The timestamp, or nothing where there is not one to read. */
     private get moment();
-    /** Every `Intl.DateTimeFormat` option a consumer set, and none they did not. */
-    private get options();
+    /** The timestamp as written, in the attribute or in the light DOM. */
+    private get source();
     /** Whether the reading is how long ago rather than the date. */
     private get reading();
     /** What the reading says now, and when it stops being true. */

package/dist/format-date/root/format-date-root.js

@@ -4,9 +4,10 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
-import { customElement, elapsedTime, HelixElement, RelativeClockController, relativeTime, } from '@fusion.dev/helix-core';
+import { customElement, elapsedTime, HelixElement, localeOf, RelativeClockController, relativeTime, } from '@fusion.dev/helix-core';
 import { html, nothing } from 'lit';
-import { property, state } from 'lit/decorators.js';
+import { property } from 'lit/decorators.js';
+import { drawFields } from '../fields.js';
 import { formatOptions } from '../options.js';
 const DATE_ONLY = /^\d{4}-\d{2}-\d{2}$/;
 let HelixHeadlessFormatDate = class HelixHeadlessFormatDate extends HelixElement {
@@ -14,52 +15,43 @@ let HelixHeadlessFormatDate = class HelixHeadlessFormatDate extends HelixElement
         super(...arguments);
         this.date = '';
         this.elapsed = false;
+        this.frozen = false;
         this.locale = '';
         this.clock = new RelativeClockController(this, {
             expires: (now) => {
                 const moment = this.moment;
-                return moment && this.reading ? this.readingAt(moment, now).next : undefined;
+                if (!moment || !this.reading) {
+                    return undefined;
+                }
+                return this.frozen ? Infinity : this.readingAt(moment, now).next;
             },
         });
         this.written = '';
-        this.watching = undefined;
+    }
+    get language() {
+        return localeOf(this, this.locale);
     }
     get dateOnly() {
-        return DATE_ONLY.test((this.date || this.written).trim());
+        return DATE_ONLY.test(this.source);
     }
     get moment() {
-        const source = this.date || this.written;
+        const source = this.source;
         if (source === '') {
             return undefined;
         }
         const parsed = new Date(source);
         return Number.isNaN(parsed.getTime()) ? undefined : parsed;
     }
-    get options() {
-        return formatOptions({
-            dateOnly: this.dateOnly,
-            dateStyle: this.dateStyle,
-            day: this.day,
-            era: this.era,
-            hour: this.hour,
-            hourCycle: this.hourCycle,
-            minute: this.minute,
-            month: this.month,
-            second: this.second,
-            timeStyle: this.timeStyle,
-            timeZone: this.timeZone,
-            timeZoneName: this.timeZoneName,
-            weekday: this.weekday,
-            year: this.year,
-        });
+    get source() {
+        return (this.date || this.written).trim();
     }
     get reading() {
         return this.elapsed || this.relative !== undefined;
     }
     readingAt(moment, now) {
         return this.elapsed
-            ? elapsedTime(this.locale)(moment, now)
-            : relativeTime(this.locale, {
+            ? elapsedTime(this.language)(moment, now)
+            : relativeTime(this.language, {
                 numeric: this.numeric ?? 'auto',
                 style: this.relative ?? 'long',
             })(moment, now);
@@ -73,7 +65,6 @@ let HelixHeadlessFormatDate = class HelixHeadlessFormatDate extends HelixElement
     disconnectedCallback() {
         super.disconnectedCallback();
         this.watching?.disconnect();
-        this.watching = undefined;
     }
     firstUpdated(changed) {
         super.firstUpdated(changed);
@@ -85,13 +76,12 @@ let HelixHeadlessFormatDate = class HelixHeadlessFormatDate extends HelixElement
         if (this.childrenKnown) {
             this.read();
         }
-        if (changed.has('date') ||
-            changed.has('elapsed') ||
-            changed.has('locale') ||
-            changed.has('numeric') ||
-            changed.has('relative')) {
+        if (['date', 'elapsed', 'frozen', 'locale', 'numeric', 'relative'].some((key) => changed.has(key))) {
             this.clock.tick();
         }
+        const ahead = this.reading ? (this.moment?.getTime() ?? NaN) - this.clock.now : NaN;
+        this.toggleState('past', ahead <= 0);
+        this.toggleState('future', ahead > 0);
     }
     read() {
         if (this.date !== '') {
@@ -100,6 +90,7 @@ let HelixHeadlessFormatDate = class HelixHeadlessFormatDate extends HelixElement
         const written = this.textContent?.trim() ?? '';
         if (written !== this.written) {
             this.written = written;
+            this.requestUpdate();
             this.clock.tick();
         }
     }
@@ -113,26 +104,20 @@ let HelixHeadlessFormatDate = class HelixHeadlessFormatDate extends HelixElement
         if (!moment) {
             return nothing;
         }
-        const datetime = this.dateOnly ? (this.date || this.written).trim() : moment.toISOString();
+        const datetime = this.dateOnly ? this.source : moment.toISOString();
         if (!this.reading) {
-            const text = new Intl.DateTimeFormat(this.locale || undefined, this.options).format(moment);
-            return html `<time part="time" datetime=${datetime}>${text}</time>`;
+            const format = new Intl.DateTimeFormat(this.language || undefined, formatOptions(this, this.dateOnly));
+            return html `<time part="time" datetime=${datetime}>${this.fields ? drawFields(format.formatToParts(moment)) : format.format(moment)}</time>`;
         }
         const now = new Date(this.clock.now);
-        const zone = this.timeZone || (this.dateOnly ? 'UTC' : undefined);
-        const whole = new Intl.DateTimeFormat(this.locale || undefined, {
+        const whole = new Intl.DateTimeFormat(this.language || undefined, formatOptions({
             dateStyle: 'long',
-            ...(this.dateOnly ? {} : { timeStyle: 'short' }),
-            ...(this.hourCycle ? { hourCycle: this.hourCycle } : {}),
-            ...(zone ? { timeZone: zone } : {}),
-        }).format(moment);
-        const spoken = relativeTime(this.locale, { numeric: this.numeric ?? 'auto' })(moment, now).text;
-        return html `<time
-      part="time"
-      datetime=${datetime}
-      aria-label=${spoken}
-      title=${whole}
-    >${this.readingAt(moment, now).text}</time>`;
+            hourCycle: this.hourCycle,
+            timeStyle: this.dateOnly ? undefined : 'short',
+            timeZone: this.timeZone,
+        }, this.dateOnly)).format(moment);
+        const spoken = relativeTime(this.language, { numeric: this.numeric ?? 'auto' })(moment, now).text;
+        return html `<time part="time" datetime=${datetime} aria-label=${spoken} title=${whole}>${this.readingAt(moment, now).text}</time>`;
     }
 };
 __decorate([
@@ -150,6 +135,12 @@ __decorate([
 __decorate([
     property()
 ], HelixHeadlessFormatDate.prototype, "era", void 0);
+__decorate([
+    property({ type: Boolean })
+], HelixHeadlessFormatDate.prototype, "fields", void 0);
+__decorate([
+    property({ type: Boolean })
+], HelixHeadlessFormatDate.prototype, "frozen", void 0);
 __decorate([
     property()
 ], HelixHeadlessFormatDate.prototype, "hour", void 0);
@@ -189,9 +180,6 @@ __decorate([
 __decorate([
     property()
 ], HelixHeadlessFormatDate.prototype, "year", void 0);
-__decorate([
-    state()
-], HelixHeadlessFormatDate.prototype, "written", void 0);
 HelixHeadlessFormatDate = __decorate([
     customElement('helix-headless-format-date')
 ], HelixHeadlessFormatDate);

package/dist/graph/root/graph-root.d.ts

@@ -41,7 +41,14 @@ declare const HelixHeadlessGraph_base: (new (...args: any[]) => import("@fusion.
  * @slot - The renderer's box, which the drawing is made in.
  * @slot filter-icon - The icon in the search field. Defaults to a magnifying glass.
  * @slot footer - Content below the graph.
+ * @slot fullscreen-icon - Replaces the glyph inside the fullscreen button.
  * @slot header - Content above the graph.
+ * @slot pan-down-icon - Replaces the glyph inside the pan down button.
+ * @slot pan-end-icon - Replaces the glyph inside the button that pans toward the end of a line of text.
+ * @slot pan-start-icon - Replaces the glyph inside the button that pans toward the start of a line of text.
+ * @slot pan-up-icon - Replaces the glyph inside the pan up button.
+ * @slot zoom-in-icon - Replaces the glyph inside the zoom-in button.
+ * @slot zoom-out-icon - Replaces the glyph inside the zoom-out button.
  *
  * @event {HelixActivateEvent} helix-activate - A note was selected, in the list or in the drawing. The detail's `value` is its `id`.
  * @event {HelixBeforeActivateEvent} helix-before-activate - A note is about to be selected. Cancelable: cancel it to keep the selection in your own state.
@@ -91,9 +98,14 @@ declare const HelixHeadlessGraph_base: (new (...args: any[]) => import("@fusion.
  * @csspart zoom-in - The zoom in button.
  * @csspart zoom-out - The zoom out button.
  *
+ * @cssstate empty - The list holds no notes: the graph has none, or a search or the groups hid them all.
  * @cssstate fullscreen - The graph fills the screen.
  * @cssstate idle - The user has been still long enough for the header and footer to fade.
+ * @cssstate local - The drawing shows the selected note's local graph, with `depth`.
+ * @cssstate panel-open - A graph with `no-panel` has the search and the list open over the drawing.
  * @cssstate ready - The graph has been drawn whole, after `helix-graph-ready`.
+ * @cssstate searching - The search field holds words, and the list holds only the notes they find.
+ * @cssstate selected - A note is selected, in the list or in the drawing.
  * @cssstate sharing - The page keeps the plain wheel and one finger, with `gestures="cooperative"` or while a graph with `gestures="activate"` waits to be pressed.
  * @cssstate using - A graph with `gestures="activate"` has been pressed and has the gestures.
  */
@@ -255,14 +267,20 @@ export declare class HelixHeadlessGraph extends HelixHeadlessGraph_base {
      * drawing: a reader moving through the list was moving the graph under it.
      */
     private readonly handleListKeydown;
-    /** What has been typed toward a note's name, and when the last letter came. */
-    private typed;
+    /** What has been typed toward a note's name. */
+    private readonly typed;
     /**
-     * Moves to the next note whose name starts with what was typed, as a
-     * listbox does. Letters within half a second of each other run together,
-     * and a repeated letter steps through the names that start with it.
+     * Moves to the next note whose name starts with what was typed, through
+     * core's `Typeahead`, as a listbox does: letters within half a second run
+     * together, and a repeated letter steps through the names that start with it.
      */
     private typeahead;
+    /**
+     * How many rows Page Down and Page Up move: the rows that fit in the list's
+     * box, or in the window where the list does not scroll, less one, so the
+     * row at one edge lands at the other.
+     */
+    private pageRows;
     /**
      * The search field's keys, which belong to the field and never pan the
      * graph. Escape empties a search that has words in it, and passes through

package/dist/graph/root/graph-root.js

@@ -4,14 +4,13 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
-import { customElement, fillTemplate, formatNumbers, HelixElement, HelixGraphFilterEvent, HelixGraphLayoutEvent, HelixGraphPanEvent, HelixGraphPartChangeEvent, HelixGraphReadyEvent, HelixGraphSignalEvent, HelixGraphZoomEvent, MixinControllerActive, MixinViewport, scrollItemIntoView, VirtualizeController, } from '@fusion.dev/helix-core';
+import { customElement, fillTemplate, formatNumbers, HelixElement, HelixGraphFilterEvent, HelixGraphLayoutEvent, HelixGraphPanEvent, HelixGraphPartChangeEvent, HelixGraphReadyEvent, HelixGraphSignalEvent, HelixGraphZoomEvent, MixinControllerActive, MixinViewport, scrollItemIntoView, scrollRoom, Typeahead, VirtualizeController, } from '@fusion.dev/helix-core';
 import { list, magnifyingGlass } from '@fusion.dev/helix-icons';
 import { html, nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
 import { repeat } from 'lit/directives/repeat.js';
 import { unsafeSVG } from 'lit/directives/unsafe-svg.js';
 import { adjacencyOf, entriesOf, groupsOf, nameOf, sortedOf, within, withoutGroups, } from './graph-model.js';
-const PAGE = 10;
 let HelixHeadlessGraph = class HelixHeadlessGraph extends MixinViewport(MixinControllerActive(HelixElement)) {
     constructor() {
         super(...arguments);
@@ -53,8 +52,8 @@ let HelixHeadlessGraph = class HelixHeadlessGraph extends MixinViewport(MixinCon
                 ArrowUp: this.cursor - 1,
                 End: this.entries.length - 1,
                 Home: 0,
-                PageDown: this.cursor + PAGE,
-                PageUp: this.cursor - PAGE,
+                PageDown: this.cursor + this.pageRows(),
+                PageUp: this.cursor - this.pageRows(),
             };
             if (event.key in moves) {
                 event.preventDefault();
@@ -74,7 +73,7 @@ let HelixHeadlessGraph = class HelixHeadlessGraph extends MixinViewport(MixinCon
                 this.typeahead(event.key);
             }
         };
-        this.typed = { at: 0, text: '' };
+        this.typed = new Typeahead();
         this.handleSearchKeydown = (event) => {
             if (event.key === 'ArrowDown') {
                 event.preventDefault();
@@ -126,6 +125,9 @@ let HelixHeadlessGraph = class HelixHeadlessGraph extends MixinViewport(MixinCon
         super.willUpdate(changed);
         this.toggleState('fullscreen', this.filled);
         this.toggleState('idle', this.resting);
+        this.toggleState('panel-open', this.noPanel && this.panelOpen);
+        this.toggleState('searching', this.query.trim() !== '');
+        this.toggleState('selected', this.active !== '');
         if (changed.has('links')) {
             this.adjacency = adjacencyOf(this.links);
         }
@@ -141,9 +143,11 @@ let HelixHeadlessGraph = class HelixHeadlessGraph extends MixinViewport(MixinCon
                 ? within(this.adjacency, this.active, Math.max(0, this.depth))
                 : undefined;
             this.kept = withoutGroups(this.nodes, local, this.hiddenGroups);
+            this.toggleState('local', local !== undefined);
         }
         if (['nodes', 'links', 'active', 'depth', 'hiddenGroups', 'query'].some((name) => changed.has(name))) {
             this.entries = entriesOf(this.sorted, this.adjacency, this.active, this.query, this.kept);
+            this.toggleState('empty', this.entries.length === 0);
             this.cursor = 0;
             const list = this.partNamed('list');
             if (list) {
@@ -272,23 +276,16 @@ let HelixHeadlessGraph = class HelixHeadlessGraph extends MixinViewport(MixinCon
         return this.entries.length > 0 && (cursor < first || cursor >= last) ? cursor : undefined;
     }
     typeahead(letter) {
-        const now = Date.now();
-        const text = now - this.typed.at < 500 ? this.typed.text + letter : letter;
-        this.typed = { at: now, text };
-        const wanted = text.toLocaleLowerCase();
-        const repeated = [...wanted].every((one) => one === wanted[0]);
-        const prefix = repeated ? (wanted[0] ?? '') : wanted;
-        const entries = this.entries;
-        const start = repeated ? this.cursor + 1 : this.cursor;
-        for (let step = 0; step < entries.length; step += 1) {
-            const at = (start + step) % entries.length;
-            const entry = entries[at];
-            if (entry && nameOf(entry.node).toLocaleLowerCase().startsWith(prefix)) {
-                this.moveTo(at);
-                return;
-            }
+        const at = this.typed.match(letter, this.entries.map((entry) => nameOf(entry.node)), this.cursor);
+        if (at >= 0) {
+            this.moveTo(at);
         }
     }
+    pageRows() {
+        const room = scrollRoom(this.partNamed('list'));
+        const tall = this.virtualize.sizeOf(this.cursor) || 32;
+        return Math.max(1, Math.floor(room / tall) - 1);
+    }
     togglePanel(open = !this.panelOpen) {
         const inside = this.panelOpen && this.partNamed('panel')?.contains(this.shadowRoot?.activeElement ?? null);
         this.panelOpen = open;

package/dist/heatmap/root/buckets.d.ts

@@ -57,3 +57,24 @@ export declare const toneOf: (reading: Reading, thresholds: readonly number[], t
  * the tail slice aligned.
  */
 export declare const fits: (total: number, width: number, minimum: number, gap: number, rows?: number) => number;
+/** What the drawn readings come to: where the busiest stands, and their total. */
+export interface Overview {
+    /** The place of the busiest reading, the first where several tie, or -1 with none. */
+    busiest: number;
+    /** The sum of every reading, blanks counting nothing. */
+    total: number;
+}
+/**
+ * The busiest reading among `cells` and the total of them all, for the
+ * strip's `overview`. A blank cell is passed over.
+ */
+export declare const overviewOf: (cells: readonly Reading[]) => Overview;
+/**
+ * Where a page of a calendar goes from the reading at `at`: the same day a
+ * month on, or a month back, by the dates the readings carry, written
+ * `YYYY-MM-DD` as a `<time datetime>` gives them. A day the month lacks,
+ * such as the 31st, is the month's last. Where that day has no reading, the
+ * nearest one past it in the direction of travel, and the last or the first
+ * reading past the end. Undefined where the reading at `at` carries no date.
+ */
+export declare const monthPage: (whens: readonly (string | undefined)[], at: number, forward: boolean) => number | undefined;

package/dist/heatmap/root/buckets.js

@@ -1,3 +1,4 @@
+import { extremesOf } from '@fusion.dev/helix-core';
 export const toneOf = (reading, thresholds, tones) => {
     if (reading.tone) {
         return reading.tone;
@@ -24,3 +25,36 @@ export const fits = (total, width, minimum, gap, rows = 1) => {
     const columns = Math.max(1, Math.floor((width + gap) / (minimum + gap)));
     return Math.min(total, columns * Math.max(1, rows));
 };
+export const overviewOf = (cells) => {
+    const values = cells.map((cell) => cell.value);
+    return {
+        busiest: extremesOf(values).high ?? -1,
+        total: values.reduce((sum, value) => sum + (value ?? 0), 0),
+    };
+};
+const dayOf = (when) => {
+    const found = /^(\d{4})-(\d{2})-(\d{2})/.exec(when ?? '');
+    return found
+        ? Date.UTC(Number(found[1]), Number(found[2]) - 1, Number(found[3])) / 86_400_000
+        : undefined;
+};
+export const monthPage = (whens, at, forward) => {
+    const from = dayOf(whens[at]);
+    if (from === undefined) {
+        return undefined;
+    }
+    const date = new Date(from * 86_400_000);
+    const month = date.getUTCMonth() + (forward ? 1 : -1);
+    const last = new Date(Date.UTC(date.getUTCFullYear(), month + 1, 0)).getUTCDate();
+    const target = Date.UTC(date.getUTCFullYear(), month, Math.min(date.getUTCDate(), last)) / 86_400_000;
+    const days = whens.map(dayOf);
+    const order = days.map((_, index) => index);
+    const past = (forward ? order : order.reverse()).find((index) => {
+        const day = days[index];
+        return day !== undefined && (forward ? day >= target : day <= target);
+    });
+    if (past !== undefined) {
+        return past;
+    }
+    return forward ? whens.length - 1 : 0;
+};

package/dist/heatmap/root/heatmap-root.d.ts

@@ -31,14 +31,24 @@ declare const HelixHeadlessHeatmap_base: typeof HelixElement & (new (...args: an
  * down arrows move a cell, the left and right arrows move a column, which is a
  * week with `rows="7"`, and Home and End go to the first and the last. The
  * tooltip follows, the `live` part says the cell's row in words, and Escape
- * puts the tooltip away. PageUp and PageDown move four columns, which is four
- * weeks with `rows="7"`.
+ * puts the tooltip away. PageUp and PageDown move a month, to the same day,
+ * where each row's header carries its date as a `<time datetime>`, and four
+ * columns otherwise, which is four weeks with `rows="7"`.
  *
  * **The strip describes itself.** The `overview` part says the busiest
- * reading and the total of the readings drawn, "Busiest: 11 Jun 12; Total
+ * reading and the total of the readings drawn, "Busiest: 11 Jun, 12; Total
  * 84", and the strip is described by it, as every chart is by its summary.
  * Hide it visually. The `summary` slot is still yours, for words of your own.
  *
+ * **`selection-mode` lets a reader select cells**: `single` one at a time and
+ * `multiple` any number. Space, Enter or a press selects the cell the keys or
+ * the pointer rest on, or lets it go, and under `multiple` Shift with an arrow,
+ * Home, End, PageUp or PageDown takes in every cell from the last one pressed
+ * to where the key went. `value` holds the selected days, by the names their
+ * rows have in the table, separated by commas. A change asks with
+ * `helix-before-change` and tells with `change`, and the `selection` part says
+ * how many are selected, in `selection-label`.
+ *
  * @since 0.1.0
  * @status stable
  * @category charts
@@ -49,16 +59,20 @@ declare const HelixHeadlessHeatmap_base: typeof HelixElement & (new (...args: an
  * @slot start - Below the strip, at the leading edge: usually the oldest date.
  * @slot summary - Below the strip, in the middle: a summary of the range shown.
  *
+ * @event {Event} change - Fired once a press or a key has changed which cells are selected.
+ * @event {HelixBeforeChangeEvent} helix-before-change - Fired before a press or a key changes which cells are selected, with the `value` it would leave. Cancelable.
  * @event {HelixResizeEvent} helix-resize - Fired when the number of cells drawn changes, with the new number.
  *
  * @csspart cell - One reading.
  * @csspart cell-active - The cell the pointer or the keys rest on. Set alongside `cell`.
+ * @csspart cell-selected - A cell that is selected, under `selection-mode`. Set alongside `cell`.
  * @csspart empty - Shown when the table has no readings. It stays hidden until the table can be read: on the server and during hydration, there is no document to resolve `for` in.
  * @csspart end - The trailing slot's box.
  * @csspart footer - The three-slot row under the strip.
  * @csspart live - The readout: a polite live region that says the cell the keys moved to. Hide it visually.
  * @csspart mark - The invisible point the tooltip is anchored to.
  * @csspart overview - The busiest reading and the total of the readings drawn, written as a sentence for screen readers, which describes the strip. Rendered once there are cells. Hide it visually.
+ * @csspart selection - A polite region that says how many cells are selected after a change, rendered from the first change. Hide it visually.
  * @csspart start - The leading slot's box.
  * @csspart strip - The grid of cells, which takes focus to be read by key. It is named by the host's `aria-labelledby` or `aria-label`, then by `label`, then by the caption of the table.
  * @csspart summary - The middle slot's box.
@@ -141,6 +155,23 @@ export declare class HelixHeadlessHeatmap extends HelixHeadlessHeatmap_base {
      * days.
      */
     rows: number;
+    /**
+     * What the readout adds for a selected cell, under `selection-mode`, after
+     * where the cell stands: "Day 1: 0 (1 of 14, selected)". Empty adds
+     * nothing.
+     */
+    selectedLabel: string;
+    /**
+     * What the `selection` part says after the selection changes, with `{count}` for
+     * how many cells are selected.
+     */
+    selectionLabel: string;
+    /**
+     * How many cells a reader can select: `single` or `multiple`.
+     *
+     * Absent selects nothing, and a press or Space does what it did.
+     */
+    selectionMode?: 'multiple' | 'single';
     /**
      * Lower bounds for the tone buckets, in the order the tones are given.
      *
@@ -167,6 +198,14 @@ export declare class HelixHeadlessHeatmap extends HelixHeadlessHeatmap_base {
      * The word the `overview` puts before the total of the readings drawn.
      */
     totalLabel: string;
+    /**
+     * The selected cells, by the names their rows have in the table, such as
+     * `2026-06-11`, separated by commas.
+     *
+     * Set it to start with cells selected. Written by a press or a key under
+     * `selection-mode`.
+     */
+    value: string;
     /**
      * How many cells are actually drawn.
      *
@@ -215,6 +254,28 @@ export declare class HelixHeadlessHeatmap extends HelixHeadlessHeatmap_base {
     protected readonly aria: AriaForwardController;
     private observer;
     private announced;
+    /** Where a range taken in with Shift starts: the cell last pressed, or none. */
+    private anchor;
+    /** The region a change of selection is said in, rendered from the first change. */
+    private readonly status;
+    /** The name each drawn cell stands for in `value`: its row's name in the table. */
+    private keysOf;
+    /**
+     * Moves `value` to `next`, asking first: `helix-before-change` carries it,
+     * a listener that refuses keeps the selection, and `change` follows, with
+     * the count said in the `selection` part.
+     */
+    private choose;
+    /** Selects the drawn cell at `index`, or lets it go, as `selection-mode` says. */
+    private press;
+    /**
+     * Space and Enter select the cell the keys rest on, and Shift with a key
+     * that moved them takes in the range from the anchor. After the pointer
+     * controller, which has already moved `at` for an arrow.
+     */
+    private readonly onKeydown;
+    /** A press on a cell selects it, under `selection-mode`. */
+    private readonly onClick;
     /**
      * Every row in the table, oldest first, as the table is written, with its
      * reading where the row has one.
@@ -304,6 +365,12 @@ export declare class HelixHeadlessHeatmap extends HelixHeadlessHeatmap_base {
      * the reason `BarChart` gives: SSR calls this one.
      */
     protected willUpdate(changed: PropertyValues<this>): void;
+    /**
+     * Where PageUp or PageDown goes from the drawn cell at `at`: the same day a
+     * month on or back, by the dates the rows' headers carry. Undefined where
+     * they carry none, and the keys move four columns.
+     */
+    pageFrom(at: number, forward: boolean): number | undefined;
     connectedCallback(): void;
     disconnectedCallback(): void;
     /**
@@ -348,6 +415,12 @@ export declare class HelixHeadlessHeatmap extends HelixHeadlessHeatmap_base {
      * pitch is `cell + gap` and both are measured.
      */
     protected renderTooltip(): TemplateResult | typeof nothing;
+    /**
+     * The readout's cursor: the pointer, with the selected word after where a
+     * selected cell stands, so a reader moving through the strip hears which
+     * cells are in the selection and not only how many.
+     */
+    private reading;
     /**
      * Which drawn cell the pointer is over, or -1.
      *