@fusion.dev/helix-headless 0.146.0 → 0.147.0

package/dist/filter-input/root/filter-input-root.d.ts

@@ -97,6 +97,7 @@ declare const HelixHeadlessFilterInput_base: (new (...args: any[]) => import("@f
  * @aliases SearchField, FacetInput, TokenInput
  * @documentation https://fusion.dev/helix/components/filter-input
  *
+ * @slot clear-icon - Replaces the cross on the clear button, under `clearable`.
  * @slot end - Content after the text, such as a count or a control.
  * @slot feedback - The message that says what is wrong, for content richer than a string. It shows while there is a message.
  * @slot hint - Help under the control, for content richer than the `hint` text.
@@ -256,6 +257,11 @@ export declare class HelixHeadlessFilterInput extends HelixHeadlessFilterInput_b
      * and one that pretends it was never there.
      */
     private get suggestions();
+    /**
+     * Every option slotted into `suggestions`, and every option one level inside
+     * a group slotted there, hidden or not.
+     */
+    private get options();
     /**
      * The direction of the selection, named as on `<input>`.
      *
@@ -437,6 +443,8 @@ export declare class HelixHeadlessFilterInput extends HelixHeadlessFilterInput_b
     private markActive;
     /** Puts the caret in the text field. */
     focus(options?: FocusOptions): void;
+    /** The cross on the clear button, behind a seam a tier can move. */
+    protected renderClearIcon(): TemplateResult;
     protected render(): TemplateResult;
 }
 declare global {

package/dist/filter-input/root/filter-input-root.js

@@ -162,22 +162,18 @@ let HelixHeadlessFilterInput = class HelixHeadlessFilterInput extends MixinContr
         };
     }
     narrow() {
-        const slot = this.renderRoot?.querySelector('slot[name="suggestions"]');
         const term = this.filterSuggestions
             ? currentTerm(this.value, this.control?.selectionStart ?? this.value.length)
             : '';
-        for (const node of slot?.assignedElements({ flatten: true }) ?? []) {
-            const options = isOption(node) ? [node] : [...node.children].filter(isOption);
-            for (const option of options) {
-                const hide = !suggests(option.textContent ?? '', term);
-                if (hide && !option.hidden) {
-                    option.hidden = true;
-                    this.narrowed.add(option);
-                }
-                else if (!hide && this.narrowed.has(option)) {
-                    option.hidden = false;
-                    this.narrowed.delete(option);
-                }
+        for (const option of this.options) {
+            const hide = !suggests(option.textContent ?? '', term);
+            if (hide && !option.hidden) {
+                option.hidden = true;
+                this.narrowed.add(option);
+            }
+            else if (!hide && this.narrowed.has(option)) {
+                option.hidden = false;
+                this.narrowed.delete(option);
             }
         }
     }
@@ -220,20 +216,11 @@ let HelixHeadlessFilterInput = class HelixHeadlessFilterInput extends MixinContr
         return this.clearable && this.value !== '' && !this.isDisabled;
     }
     get suggestions() {
+        return this.options.filter((option) => !option.disabled && !option.hidden);
+    }
+    get options() {
         const slot = this.renderRoot?.querySelector('slot[name="suggestions"]');
-        const found = [];
-        for (const node of slot?.assignedElements({ flatten: true }) ?? []) {
-            if (isOption(node)) {
-                found.push(node);
-                continue;
-            }
-            for (const child of node.children) {
-                if (isOption(child)) {
-                    found.push(child);
-                }
-            }
-        }
-        return found.filter((option) => !option.disabled && !option.hidden);
+        return (slot?.assignedElements({ flatten: true }) ?? []).flatMap((node) => isOption(node) ? [node] : [...node.children].filter(isOption));
     }
     get selectionDirection() {
         return this.control?.selectionDirection ?? 'none';
@@ -392,6 +379,9 @@ let HelixHeadlessFilterInput = class HelixHeadlessFilterInput extends MixinContr
     focus(options) {
         this.control?.focus(options);
     }
+    renderClearIcon() {
+        return html `<slot name="clear-icon">${drawIcon(x)}</slot>`;
+    }
     render() {
         return html `${this.renderLabel()}
     <div part="field" @focusin=${this.handleFocusIn} @focusout=${this.handleFocusOut}>
@@ -426,7 +416,7 @@ let HelixHeadlessFilterInput = class HelixHeadlessFilterInput extends MixinContr
               aria-label=${this.clearLabel}
               @click=${this.handleClear}
             >
-              ${drawIcon(x)}
+              ${this.renderClearIcon()}
             </button>`
             : nothing}
     </div>

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

@@ -1,9 +1,8 @@
 /**
  * What a Format Date was asked for, in its own spelling: the `Intl` options a
- * consumer set, and whether the timestamp is a day with no time of day.
+ * consumer set. The element itself is one, so it passes itself.
  */
 export interface Asked {
-    dateOnly: boolean;
     dateStyle?: 'full' | 'long' | 'medium' | 'short' | undefined;
     day?: 'numeric' | '2-digit' | undefined;
     era?: 'long' | 'narrow' | 'short' | undefined;
@@ -26,8 +25,8 @@ export interface Asked {
  * given beside `month` or `hour`, so the fields are left out wherever a style
  * is set. `hourCycle` and `timeZone` go with either.
  *
- * **A day with no time is read in UTC** unless a zone is given. Parsed, it is
+ * **A day with no time, `dateOnly`, is read in UTC** unless a zone is given. Parsed, it is
  * midnight UTC, and read in a zone west of it that is the day before: measured
  * before this, `2026-08-04` read "August 3, 2026" in Los Angeles.
  */
-export declare const formatOptions: (asked: Asked) => Intl.DateTimeFormatOptions;
+export declare const formatOptions: (asked: Asked, dateOnly?: boolean) => Intl.DateTimeFormatOptions;

package/dist/format-date/options.js

@@ -9,7 +9,7 @@ const FIELDS = [
     'weekday',
     'year',
 ];
-export const formatOptions = (asked) => {
+export const formatOptions = (asked, dateOnly = false) => {
     const options = {};
     const styled = asked.dateStyle !== undefined || asked.timeStyle !== undefined;
     if (styled) {
@@ -35,7 +35,7 @@ export const formatOptions = (asked) => {
     if (asked.timeZone) {
         options.timeZone = asked.timeZone;
     }
-    else if (asked.dateOnly) {
+    else if (dateOnly) {
         options.timeZone = 'UTC';
     }
     return options;

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

@@ -25,6 +25,7 @@ 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.
  *
  * **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
@@ -85,6 +86,19 @@ export declare class HelixHeadlessFormatDate extends HelixElement {
      * How the era is written, such as AD, where a date is shown.
      */
     era?: 'long' | 'narrow' | 'short';
+    /**
+     * 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 +114,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.
      */

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

@@ -4,7 +4,7 @@ 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 { formatOptions } from '../options.js';
@@ -14,16 +14,23 @@ 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 ? Number.POSITIVE_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());
     }
@@ -36,30 +43,15 @@ let HelixHeadlessFormatDate = class HelixHeadlessFormatDate extends HelixElement
         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,
-        });
+        return formatOptions(this, this.dateOnly);
     }
     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);
@@ -87,6 +79,7 @@ let HelixHeadlessFormatDate = class HelixHeadlessFormatDate extends HelixElement
         }
         if (changed.has('date') ||
             changed.has('elapsed') ||
+            changed.has('frozen') ||
             changed.has('locale') ||
             changed.has('numeric') ||
             changed.has('relative')) {
@@ -115,18 +108,18 @@ let HelixHeadlessFormatDate = class HelixHeadlessFormatDate extends HelixElement
         }
         const datetime = this.dateOnly ? (this.date || this.written).trim() : moment.toISOString();
         if (!this.reading) {
-            const text = new Intl.DateTimeFormat(this.locale || undefined, this.options).format(moment);
+            const text = new Intl.DateTimeFormat(this.language || undefined, this.options).format(moment);
             return html `<time part="time" datetime=${datetime}>${text}</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, {
             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;
+        const spoken = relativeTime(this.language, { numeric: this.numeric ?? 'auto' })(moment, now).text;
         return html `<time
       part="time"
       datetime=${datetime}
@@ -150,6 +143,9 @@ __decorate([
 __decorate([
     property()
 ], HelixHeadlessFormatDate.prototype, "era", void 0);
+__decorate([
+    property({ type: Boolean })
+], HelixHeadlessFormatDate.prototype, "frozen", void 0);
 __decorate([
     property()
 ], HelixHeadlessFormatDate.prototype, "hour", void 0);

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,17 @@ export declare class HelixHeadlessHeatmap extends HelixHeadlessHeatmap_base {
      * days.
      */
     rows: number;
+    /**
+     * 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 +192,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 +248,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 +359,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;
     /**