@fusion.dev/helix-headless 0.0.0-dev

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

@@ -0,0 +1,151 @@
+import { HelixElement } from '@fusion.dev/helix-core';
+import { nothing, type PropertyValues, type TemplateResult } from 'lit';
+/**
+ * @summary A timestamp, written the way the reader's locale writes one.
+ *
+ * @description
+ * A date in a page is almost never wanted as an ISO string, and formatting one
+ * in the consumer's own code means every consumer ships a copy of the same
+ * `Intl` call and a different set of options. This is that call, as an element,
+ * so a date is written where it is shown.
+ *
+ * **`elapsed` is the mode a feed wants, and it stops being relative on
+ * purpose.** "42m", "3h", "1d" is what a row of activity reads as, and past a
+ * week the compact form is a lie: `Intl.NumberFormat` narrow renders both
+ * `minute` and `month` as `m` in en-US, so "3m" is three minutes at the top of a
+ * feed and three months further down it. Past six days this shows a date, which
+ * is shorter to read and impossible to misread. `elapsedTime` in `helix/core`
+ * carries the measurement.
+ *
+ * **The reading refreshes itself, from one timer the page shares.** A relative
+ * timestamp is correct for as long as its unit lasts and wrong afterwards, and a
+ * page left open is exactly where that shows. Each element asks to be woken when
+ * its own reading expires rather than polling, and an element showing a date
+ * asks for nothing at all: fifty rows and fifty intervals is fifty wakeups a
+ * second where one will do, and a feed of last month's notifications should cost
+ * nothing to leave open.
+ *
+ * **`<time datetime>` whatever the text says**, so a screen reader, a copy and
+ * paste, and anything parsing the page all get the real instant rather than
+ * "yesterday".
+ *
+ * @since 0.1.0
+ * @status experimental
+ * @category typography
+ * @aliases RelativeTime, Timestamp, TimeAgo
+ * @documentation https://helix.fusion.dev/components/format-date
+ *
+ * @csspart time - The `<time>` element carrying the reading.
+ */
+export declare class HelixHeadlessFormatDate extends HelixElement {
+    /**
+     * The timestamp, as anything `Date` parses.
+     *
+     * An ISO string is what an API sends and what `<time datetime>` takes, so it
+     * is the shape that needs no translation at either end. Left unset this
+     * renders nothing rather than the epoch, which is what parsing an empty string
+     * would give.
+     *
+     * **The element's own text is read as a fallback, and only in a browser.**
+     * `<helix-format-date elapsed>2026-08-27T01:00:00Z</helix-format-date>` is the
+     * spelling that reads best in markup, and it cannot be the only one: measured
+     * against Lit's server shim, `textContent`, `children`, `firstChild` and
+     * `querySelector` are all `undefined` there, so a server has no way to see it.
+     * An element rendered on a server needs the attribute; one rendered in a
+     * browser may use either.
+     */
+    date: string;
+    /**
+     * How the day of the month is written, where a date is shown.
+     */
+    day?: 'numeric' | '2-digit';
+    /**
+     * Show how long ago it was, compactly, instead of the date.
+     *
+     * Reflected, because it is the one property that decides which of two readings
+     * this is and a stylesheet has a reason to know: a compact reading is a fixed
+     * few characters and a date is not.
+     */
+    elapsed: boolean;
+    /**
+     * How the hour is written, where a time of day is shown.
+     */
+    hour?: 'numeric' | '2-digit';
+    /**
+     * Locale for the reading.
+     *
+     * Empty is the runtime's own.
+     */
+    locale: string;
+    /**
+     * How the minute is written, where a time of day is shown.
+     */
+    minute?: 'numeric' | '2-digit';
+    /**
+     * How the month is written, where a date is shown.
+     */
+    month?: 'numeric' | '2-digit' | 'long' | 'short' | 'narrow';
+    /**
+     * How the second is written, where a time of day is shown.
+     */
+    second?: 'numeric' | '2-digit';
+    /**
+     * The time zone to read the timestamp in.
+     *
+     * Empty is the runtime's own.
+     */
+    timeZone?: string;
+    /**
+     * Whether to name the time zone, and how.
+     */
+    timeZoneName?: 'long' | 'short';
+    /**
+     * How the weekday is written, where one is shown.
+     */
+    weekday?: 'long' | 'short' | 'narrow';
+    /**
+     * How the year is written, where a date is shown.
+     */
+    year?: 'numeric' | '2-digit';
+    /**
+     * The clock this element last drew against.
+     *
+     * A state field and not a read of `Date.now()` inside `render`, which would
+     * make the template a function of something Lit cannot see change: the element
+     * would draw the right text once and never notice it had gone stale.
+     */
+    private clock;
+    /**
+     * The date read out of the light DOM, where no attribute carried one.
+     */
+    private written;
+    private stopTicking;
+    private watching;
+    /** 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();
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    protected firstUpdated(changed: PropertyValues): void;
+    protected willUpdate(changed: PropertyValues): void;
+    /** The light DOM's own text, which is the other way to write the value. */
+    private read;
+    private watch;
+    /**
+     * Schedules the next reading, and only the next one.
+     *
+     * The formatter says when its own answer expires, so this asks for exactly
+     * that moment rather than polling: an item minutes old wakes once a minute, an
+     * item hours old once an hour, and an item showing a date never, which is the
+     * difference between a feed that costs nothing to leave open and one that
+     * does.
+     */
+    private tick;
+    protected render(): TemplateResult | typeof nothing;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-format-date': HelixHeadlessFormatDate;
+    }
+}

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

@@ -0,0 +1,266 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    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, subscribe } from '@fusion.dev/helix-core';
+import { html, nothing } from 'lit';
+import { property, state } from 'lit/decorators.js';
+/**
+ * @summary A timestamp, written the way the reader's locale writes one.
+ *
+ * @description
+ * A date in a page is almost never wanted as an ISO string, and formatting one
+ * in the consumer's own code means every consumer ships a copy of the same
+ * `Intl` call and a different set of options. This is that call, as an element,
+ * so a date is written where it is shown.
+ *
+ * **`elapsed` is the mode a feed wants, and it stops being relative on
+ * purpose.** "42m", "3h", "1d" is what a row of activity reads as, and past a
+ * week the compact form is a lie: `Intl.NumberFormat` narrow renders both
+ * `minute` and `month` as `m` in en-US, so "3m" is three minutes at the top of a
+ * feed and three months further down it. Past six days this shows a date, which
+ * is shorter to read and impossible to misread. `elapsedTime` in `helix/core`
+ * carries the measurement.
+ *
+ * **The reading refreshes itself, from one timer the page shares.** A relative
+ * timestamp is correct for as long as its unit lasts and wrong afterwards, and a
+ * page left open is exactly where that shows. Each element asks to be woken when
+ * its own reading expires rather than polling, and an element showing a date
+ * asks for nothing at all: fifty rows and fifty intervals is fifty wakeups a
+ * second where one will do, and a feed of last month's notifications should cost
+ * nothing to leave open.
+ *
+ * **`<time datetime>` whatever the text says**, so a screen reader, a copy and
+ * paste, and anything parsing the page all get the real instant rather than
+ * "yesterday".
+ *
+ * @since 0.1.0
+ * @status experimental
+ * @category typography
+ * @aliases RelativeTime, Timestamp, TimeAgo
+ * @documentation https://helix.fusion.dev/components/format-date
+ *
+ * @csspart time - The `<time>` element carrying the reading.
+ */
+let HelixHeadlessFormatDate = class HelixHeadlessFormatDate extends HelixElement {
+    constructor() {
+        super(...arguments);
+        /**
+         * The timestamp, as anything `Date` parses.
+         *
+         * An ISO string is what an API sends and what `<time datetime>` takes, so it
+         * is the shape that needs no translation at either end. Left unset this
+         * renders nothing rather than the epoch, which is what parsing an empty string
+         * would give.
+         *
+         * **The element's own text is read as a fallback, and only in a browser.**
+         * `<helix-format-date elapsed>2026-08-27T01:00:00Z</helix-format-date>` is the
+         * spelling that reads best in markup, and it cannot be the only one: measured
+         * against Lit's server shim, `textContent`, `children`, `firstChild` and
+         * `querySelector` are all `undefined` there, so a server has no way to see it.
+         * An element rendered on a server needs the attribute; one rendered in a
+         * browser may use either.
+         */
+        this.date = '';
+        /**
+         * Show how long ago it was, compactly, instead of the date.
+         *
+         * Reflected, because it is the one property that decides which of two readings
+         * this is and a stylesheet has a reason to know: a compact reading is a fixed
+         * few characters and a date is not.
+         */
+        this.elapsed = false;
+        /**
+         * Locale for the reading.
+         *
+         * Empty is the runtime's own.
+         */
+        this.locale = '';
+        /**
+         * The clock this element last drew against.
+         *
+         * A state field and not a read of `Date.now()` inside `render`, which would
+         * make the template a function of something Lit cannot see change: the element
+         * would draw the right text once and never notice it had gone stale.
+         */
+        this.clock = undefined;
+        /**
+         * The date read out of the light DOM, where no attribute carried one.
+         */
+        this.written = '';
+        this.stopTicking = undefined;
+        this.watching = undefined;
+    }
+    /** The timestamp, or nothing where there is not one to read. */
+    get moment() {
+        const source = this.date || this.written;
+        if (source === '') {
+            return undefined;
+        }
+        const parsed = new Date(source);
+        return Number.isNaN(parsed.getTime()) ? undefined : parsed;
+    }
+    /** Every `Intl.DateTimeFormat` option a consumer set, and none they did not. */
+    get options() {
+        const asked = {};
+        if (this.day) {
+            asked.day = this.day;
+        }
+        if (this.hour) {
+            asked.hour = this.hour;
+        }
+        if (this.minute) {
+            asked.minute = this.minute;
+        }
+        if (this.month) {
+            asked.month = this.month;
+        }
+        if (this.second) {
+            asked.second = this.second;
+        }
+        if (this.timeZone) {
+            asked.timeZone = this.timeZone;
+        }
+        if (this.timeZoneName) {
+            asked.timeZoneName = this.timeZoneName;
+        }
+        if (this.weekday) {
+            asked.weekday = this.weekday;
+        }
+        if (this.year) {
+            asked.year = this.year;
+        }
+        return asked;
+    }
+    connectedCallback() {
+        super.connectedCallback();
+        this.tick();
+        /* Rebuilt on every connection rather than built once, because
+           `disconnectedCallback` takes it down and a framework moves nodes for
+           ordinary reasons: built in `firstUpdated` alone this comes back
+           permanently dead the first time a list is reordered. Guarded on
+           `hasUpdated` because the first connection happens before there is anything
+           to watch. See `check:observers`. */
+        if (this.hasUpdated) {
+            this.watch();
+        }
+    }
+    disconnectedCallback() {
+        super.disconnectedCallback();
+        /* Both outlive the element otherwise, and a page that mounts and unmounts a
+           feed leaks one of each every time it opens. */
+        this.stopTicking?.();
+        this.stopTicking = undefined;
+        this.watching?.disconnect();
+        this.watching = undefined;
+    }
+    firstUpdated(changed) {
+        super.firstUpdated(changed);
+        this.read();
+        this.watch();
+    }
+    willUpdate(changed) {
+        super.willUpdate(changed);
+        if (changed.has('date') || changed.has('elapsed') || changed.has('locale')) {
+            this.tick();
+        }
+    }
+    /** The light DOM's own text, which is the other way to write the value. */
+    read() {
+        if (this.date !== '') {
+            return;
+        }
+        const written = this.textContent?.trim() ?? '';
+        if (written !== this.written) {
+            this.written = written;
+            this.tick();
+        }
+    }
+    watch() {
+        this.watching?.disconnect();
+        this.watching = new MutationObserver(() => this.read());
+        this.watching.observe(this, { characterData: true, childList: true, subtree: true });
+    }
+    /**
+     * Schedules the next reading, and only the next one.
+     *
+     * The formatter says when its own answer expires, so this asks for exactly
+     * that moment rather than polling: an item minutes old wakes once a minute, an
+     * item hours old once an hour, and an item showing a date never, which is the
+     * difference between a feed that costs nothing to leave open and one that
+     * does.
+     */
+    tick() {
+        this.stopTicking?.();
+        this.stopTicking = undefined;
+        const moment = this.moment;
+        if (!moment || !this.elapsed) {
+            return;
+        }
+        const now = new Date();
+        this.clock = now.getTime();
+        const { next } = elapsedTime(this.locale)(moment, now);
+        if (!Number.isFinite(next)) {
+            return;
+        }
+        this.stopTicking = subscribe(next, () => this.tick());
+    }
+    render() {
+        const moment = this.moment;
+        if (!moment) {
+            return nothing;
+        }
+        const text = this.elapsed
+            ? elapsedTime(this.locale)(moment, new Date(this.clock ?? Date.now())).text
+            : new Intl.DateTimeFormat(this.locale || undefined, this.options).format(moment);
+        return html `<time part="time" datetime=${moment.toISOString()}>${text}</time>`;
+    }
+};
+__decorate([
+    property()
+], HelixHeadlessFormatDate.prototype, "date", void 0);
+__decorate([
+    property()
+], HelixHeadlessFormatDate.prototype, "day", void 0);
+__decorate([
+    property({ reflect: true, type: Boolean })
+], HelixHeadlessFormatDate.prototype, "elapsed", void 0);
+__decorate([
+    property()
+], HelixHeadlessFormatDate.prototype, "hour", void 0);
+__decorate([
+    property()
+], HelixHeadlessFormatDate.prototype, "locale", void 0);
+__decorate([
+    property()
+], HelixHeadlessFormatDate.prototype, "minute", void 0);
+__decorate([
+    property()
+], HelixHeadlessFormatDate.prototype, "month", void 0);
+__decorate([
+    property()
+], HelixHeadlessFormatDate.prototype, "second", void 0);
+__decorate([
+    property({ attribute: 'time-zone' })
+], HelixHeadlessFormatDate.prototype, "timeZone", void 0);
+__decorate([
+    property({ attribute: 'time-zone-name' })
+], HelixHeadlessFormatDate.prototype, "timeZoneName", void 0);
+__decorate([
+    property()
+], HelixHeadlessFormatDate.prototype, "weekday", void 0);
+__decorate([
+    property()
+], HelixHeadlessFormatDate.prototype, "year", void 0);
+__decorate([
+    state()
+], HelixHeadlessFormatDate.prototype, "clock", void 0);
+__decorate([
+    state()
+], HelixHeadlessFormatDate.prototype, "written", void 0);
+HelixHeadlessFormatDate = __decorate([
+    customElement('helix-headless-format-date')
+], HelixHeadlessFormatDate);
+export { HelixHeadlessFormatDate };

package/dist/heatmap/index.d.ts

@@ -0,0 +1,2 @@
+export { fits, numbers, type Reading, toneOf, words } from './root/buckets.js';
+export { HelixHeadlessHeatmap } from './root/heatmap-root.js';

package/dist/heatmap/index.js

@@ -0,0 +1,2 @@
+export { fits, numbers, toneOf, words } from './root/buckets.js';
+export { HelixHeadlessHeatmap } from './root/heatmap-root.js';

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

@@ -0,0 +1,62 @@
+/**
+ * Which tone a reading gets, and how many readings fit.
+ *
+ * Kept apart from the element because both answers are arithmetic and both are
+ * easy to get subtly wrong in ways a picture hides: a threshold comparison off
+ * by one boundary colours a handful of cells wrong out of ninety, and a fit
+ * calculation off by one drops a day silently. Neither is visible in a
+ * screenshot of a strip.
+ */
+/** A reading, reduced to what the bucketing needs. */
+export interface Reading {
+    tone?: string | undefined;
+    value: number;
+}
+/**
+ * The tone for one reading, from its own `data-tone` or from the thresholds.
+ *
+ * **The cell's own tone wins**, and that ordering is the whole reason both
+ * exist. A status page already knows a day was degraded; making it encode that
+ * as a number so a component can decode it again is work for nothing, and the
+ * encoding would have to agree with the thresholds or the colours would drift
+ * from the truth. A contribution graph has only counts and wants the buckets.
+ *
+ * Thresholds are read as lower bounds, in the order given, and the last one that
+ * a value reaches wins. `thresholds="0,1,3,6"` with `tones="muted,info,accent,success"`
+ * puts 0 in `muted`, 1 and 2 in `info`, 3 to 5 in `accent`, and 6 upward in
+ * `success`. A value below the first bound gets no tone rather than the first
+ * one: an empty cell in a contribution graph is a day with nothing in it, and
+ * painting it as the lowest bucket claims a reading that does not exist.
+ */
+export declare const toneOf: (reading: Reading, thresholds: readonly number[], tones: readonly string[]) => string | undefined;
+/** A comma or space separated list of numbers, in the order written. */
+export declare const numbers: (source: string) => number[];
+/** A comma or space separated list of names, in the order written. */
+export declare const words: (source: string) => string[];
+/**
+ * How many readings fit across a given width, and which ones they are.
+ *
+ * **Ninety cells in 320 pixels is three and a half pixels each**, which is not a
+ * strip, it is a smear. So a narrow container shows fewer cells rather than
+ * thinner ones, and it shows the *most recent* ones, because a status strip that
+ * drops the newest days to keep the oldest is answering a question nobody asked.
+ *
+ * **The count it returns is what the summary has to be recomputed against.** A
+ * strip labeled "99.2% over 90 days" that is drawing 45 of them is telling the
+ * reader something false about the picture in front of them, and nothing about
+ * the picture says so. That is the one fault in this component that a screenshot
+ * cannot show, which is why the element reflects the number and announces it.
+ *
+ * **What crosses the width is a column, and `rows` is how many cells are in
+ * one.** This counted cells until 27 Aug 2026, which is the same number only
+ * while `rows` is 1. At `rows="7"` a ten week graph came out at fifty-nine
+ * readings in a 592px box: eleven days dropped to fit a strip that wanted 156
+ * pixels, and the fifty-nine were not a multiple of seven, so every column after
+ * the cut was offset by a day and the day-of-week rows stopped meaning anything.
+ * A calendar heatmap that silently rotates its own weekdays is worse than one
+ * that drops a week, and both came from dividing by the wrong thing.
+ *
+ * The count is therefore always a whole number of columns, which is what keeps
+ * the tail slice aligned.
+ */
+export declare const fits: (total: number, width: number, minimum: number, gap: number, rows?: number) => number;

package/dist/heatmap/root/buckets.js

@@ -0,0 +1,85 @@
+/**
+ * Which tone a reading gets, and how many readings fit.
+ *
+ * Kept apart from the element because both answers are arithmetic and both are
+ * easy to get subtly wrong in ways a picture hides: a threshold comparison off
+ * by one boundary colours a handful of cells wrong out of ninety, and a fit
+ * calculation off by one drops a day silently. Neither is visible in a
+ * screenshot of a strip.
+ */
+/**
+ * The tone for one reading, from its own `data-tone` or from the thresholds.
+ *
+ * **The cell's own tone wins**, and that ordering is the whole reason both
+ * exist. A status page already knows a day was degraded; making it encode that
+ * as a number so a component can decode it again is work for nothing, and the
+ * encoding would have to agree with the thresholds or the colours would drift
+ * from the truth. A contribution graph has only counts and wants the buckets.
+ *
+ * Thresholds are read as lower bounds, in the order given, and the last one that
+ * a value reaches wins. `thresholds="0,1,3,6"` with `tones="muted,info,accent,success"`
+ * puts 0 in `muted`, 1 and 2 in `info`, 3 to 5 in `accent`, and 6 upward in
+ * `success`. A value below the first bound gets no tone rather than the first
+ * one: an empty cell in a contribution graph is a day with nothing in it, and
+ * painting it as the lowest bucket claims a reading that does not exist.
+ */
+export const toneOf = (reading, thresholds, tones) => {
+    if (reading.tone) {
+        return reading.tone;
+    }
+    if (thresholds.length === 0) {
+        return undefined;
+    }
+    let chosen;
+    for (const [index, bound] of thresholds.entries()) {
+        if (reading.value >= bound) {
+            chosen = tones[index] ?? chosen;
+        }
+    }
+    return chosen;
+};
+/** A comma or space separated list of numbers, in the order written. */
+export const numbers = (source) => source
+    .split(/[\s,]+/)
+    .filter((one) => one !== '')
+    .map(Number)
+    .filter((one) => Number.isFinite(one));
+/** A comma or space separated list of names, in the order written. */
+export const words = (source) => source.split(/[\s,]+/).filter((one) => one !== '');
+/**
+ * How many readings fit across a given width, and which ones they are.
+ *
+ * **Ninety cells in 320 pixels is three and a half pixels each**, which is not a
+ * strip, it is a smear. So a narrow container shows fewer cells rather than
+ * thinner ones, and it shows the *most recent* ones, because a status strip that
+ * drops the newest days to keep the oldest is answering a question nobody asked.
+ *
+ * **The count it returns is what the summary has to be recomputed against.** A
+ * strip labeled "99.2% over 90 days" that is drawing 45 of them is telling the
+ * reader something false about the picture in front of them, and nothing about
+ * the picture says so. That is the one fault in this component that a screenshot
+ * cannot show, which is why the element reflects the number and announces it.
+ *
+ * **What crosses the width is a column, and `rows` is how many cells are in
+ * one.** This counted cells until 27 Aug 2026, which is the same number only
+ * while `rows` is 1. At `rows="7"` a ten week graph came out at fifty-nine
+ * readings in a 592px box: eleven days dropped to fit a strip that wanted 156
+ * pixels, and the fifty-nine were not a multiple of seven, so every column after
+ * the cut was offset by a day and the day-of-week rows stopped meaning anything.
+ * A calendar heatmap that silently rotates its own weekdays is worse than one
+ * that drops a week, and both came from dividing by the wrong thing.
+ *
+ * The count is therefore always a whole number of columns, which is what keeps
+ * the tail slice aligned.
+ */
+export const fits = (total, width, minimum, gap, rows = 1) => {
+    if (!Number.isFinite(width) || width <= 0 || minimum <= 0) {
+        return total;
+    }
+    /* n columns need n widths and n-1 gaps, so solving for n gives the +gap on
+       both sides. Written as `width / (minimum + gap)` it is short by one column
+       at every size, which is the off-by-one that reads as "the strip has a
+       margin". */
+    const columns = Math.max(1, Math.floor((width + gap) / (minimum + gap)));
+    return Math.min(total, columns * Math.max(1, rows));
+};