@fusion.dev/helix-headless 0.147.0 → 0.149.0

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

@@ -132,6 +132,11 @@ declare const HelixHeadlessFilterInput_base: (new (...args: any[]) => import("@f
  * @cssstate open - The suggestions are open.
  */
 export declare class HelixHeadlessFilterInput extends HelixHeadlessFilterInput_base {
+    /**
+     * The key this family's words are registered under, its styled tag:
+     * `registerWords('de', { 'helix-filter-input': { clearLabel: 'Leeren' } })`.
+     */
+    static words: string;
     protected readonly aria: AriaForwardController;
     /** Typed, so every keystroke is announced. See `announcesInput`. */
     protected readonly announcesInput = true;
@@ -161,9 +166,21 @@ export declare class HelixHeadlessFilterInput extends HelixHeadlessFilterInput_b
      * Not a label: it goes when typing starts.
      */
     placeholder: string;
-    /** What a reader hears for one suggestion, with `{count}` filled in. */
-    suggestionLabel: string;
-    /** What a reader hears for any other number of suggestions, with `{count}` filled in. */
+    /**
+     * What a reader hears for one suggestion, where `suggestions-label` should
+     * not say it. `{count}` is the count.
+     *
+     * @deprecated Write every form in `suggestions-label`, as `{count, plural,
+     * one {# suggestion} other {# suggestions}}`. Removed in the next major
+     * version.
+     */
+    suggestionLabel?: string;
+    /**
+     * What a reader hears as the panel opens on its suggestions. `{count}` is
+     * how many, written in the locale, and each language writes the forms it
+     * has: `{count, plural, one {# sugestia} few {# sugestie} many {# sugestii}
+     * other {# sugestii}}`.
+     */
     suggestionsLabel: string;
     /** The live region, rendered from the first count said. */
     private readonly status;

package/dist/filter-input/root/filter-input-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 { AriaForwardController, countLabel, customElement, drawIcon, drawStatus, HelixFacetEvent, HelixFormElement, holdCaret, MixinControllerOpen, MixinControllerValue, MixinField, MixinTokens, PopoverController, restoreValue, StatusController, scrollItemIntoView, } from '@fusion.dev/helix-core';
+import { AriaForwardController, countLabel, customElement, drawIcon, drawStatus, formatWords, HelixFacetEvent, HelixFormElement, holdCaret, MixinControllerOpen, MixinControllerValue, MixinField, MixinTokens, PopoverController, restoreValue, StatusController, scrollItemIntoView, words, wordsLocale, } from '@fusion.dev/helix-core';
 import { x } from '@fusion.dev/helix-icons';
 import { html, nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
@@ -25,8 +25,7 @@ let HelixHeadlessFilterInput = class HelixHeadlessFilterInput extends MixinContr
         this.clearLabel = 'Clear';
         this.filterSuggestions = false;
         this.placeholder = '';
-        this.suggestionLabel = '{count} suggestion';
-        this.suggestionsLabel = '{count} suggestions';
+        this.suggestionsLabel = '{count, plural, one {# suggestion} other {# suggestions}}';
         this.status = new StatusController(this);
         this.saidCount = -1;
         this.narrowed = new Set();
@@ -161,6 +160,7 @@ let HelixHeadlessFilterInput = class HelixHeadlessFilterInput extends MixinContr
             this.over = this.hideOverflow(this.tokens);
         };
     }
+    static { this.words = 'helix-filter-input'; }
     narrow() {
         const term = this.filterSuggestions
             ? currentTerm(this.value, this.control?.selectionStart ?? this.value.length)
@@ -186,7 +186,9 @@ let HelixHeadlessFilterInput = class HelixHeadlessFilterInput extends MixinContr
         if (count < 0) {
             return;
         }
-        this.status.sayNow(countLabel(count, this.suggestionLabel, this.suggestionsLabel, this.lang));
+        this.status.sayNow(this.suggestionLabel
+            ? countLabel(count, this.suggestionLabel, this.suggestionsLabel, wordsLocale(this))
+            : formatWords(this, 'suggestionsLabel', { count }));
     }
     formValue() {
         const entries = (this.tokens?.assignedElements({ flatten: true }) ?? [])
@@ -443,6 +445,7 @@ __decorate([
     property({ type: Boolean })
 ], HelixHeadlessFilterInput.prototype, "clearable", void 0);
 __decorate([
+    words,
     property({ attribute: 'clear-label' })
 ], HelixHeadlessFilterInput.prototype, "clearLabel", void 0);
 __decorate([
@@ -455,6 +458,7 @@ __decorate([
     property({ attribute: 'suggestion-label' })
 ], HelixHeadlessFilterInput.prototype, "suggestionLabel", void 0);
 __decorate([
+    words,
     property({ attribute: 'suggestions-label' })
 ], HelixHeadlessFilterInput.prototype, "suggestionsLabel", void 0);
 __decorate([

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

@@ -0,0 +1,20 @@
+import { type TemplateResult } from 'lit';
+/**
+ * Each date field `Intl` names, drawn as a part of its own.
+ *
+ * Keyed by the `type` of `Intl.DateTimeFormat#formatToParts`. Written out one
+ * template to a field rather than bound through one `part` binding, because a
+ * part is read from the source as a literal: a bound name is a part no
+ * stylesheet check can find. A type left out, the punctuation between the
+ * fields among them, is drawn as plain text.
+ */
+export declare const FIELD: Record<string, (value: string) => TemplateResult>;
+/**
+ * A formatted date, each field in a part of its own and the text between them
+ * as it is.
+ *
+ * The words are the ones `format` would give, in the same order, so the reading
+ * a screen reader hears and the text a reader copies do not change: an inline
+ * span with no style of its own changes nothing on the page either.
+ */
+export declare const drawFields: (parts: readonly Intl.DateTimeFormatPart[]) => unknown[];

package/dist/format-date/fields.js

@@ -0,0 +1,14 @@
+import { html } from 'lit';
+export const FIELD = {
+    day: (value) => html `<span part="day">${value}</span>`,
+    dayPeriod: (value) => html `<span part="day-period">${value}</span>`,
+    era: (value) => html `<span part="era">${value}</span>`,
+    hour: (value) => html `<span part="hour">${value}</span>`,
+    minute: (value) => html `<span part="minute">${value}</span>`,
+    month: (value) => html `<span part="month">${value}</span>`,
+    second: (value) => html `<span part="second">${value}</span>`,
+    timeZoneName: (value) => html `<span part="time-zone-name">${value}</span>`,
+    weekday: (value) => html `<span part="weekday">${value}</span>`,
+    year: (value) => html `<span part="year">${value}</span>`,
+};
+export const drawFields = (parts) => parts.map(({ type, value }) => FIELD[type]?.(value) ?? value);

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

@@ -18,7 +18,8 @@ export interface Asked {
     year?: 'numeric' | '2-digit' | undefined;
 }
 /**
- * The `Intl.DateTimeFormat` options for what was asked, and none that was not.
+ * The `Intl.DateTimeFormat` options for what was asked, and none that was not:
+ * an option not asked for is `undefined`, which `Intl` reads as absent.
  *
  * **A style wins over the fields.** `dateStyle` and `timeStyle` are each
  * locale's own whole pattern, and `Intl` throws a `TypeError` when one is

package/dist/format-date/options.js

@@ -1,42 +1,13 @@
-const FIELDS = [
-    'day',
-    'era',
-    'hour',
-    'minute',
-    'month',
-    'second',
-    'timeZoneName',
-    'weekday',
-    'year',
-];
+import { FIELD } from './fields.js';
+const FIELDS = Object.keys(FIELD);
 export const formatOptions = (asked, dateOnly = false) => {
-    const options = {};
-    const styled = asked.dateStyle !== undefined || asked.timeStyle !== undefined;
-    if (styled) {
-        if (asked.dateStyle) {
-            options.dateStyle = asked.dateStyle;
-        }
-        if (asked.timeStyle) {
-            options.timeStyle = asked.timeStyle;
-        }
-    }
-    else {
-        for (const field of FIELDS) {
-            const value = asked[field];
-            if (value) {
-                ;
-                options[field] = value;
-            }
-        }
-    }
-    if (asked.hourCycle) {
-        options.hourCycle = asked.hourCycle;
-    }
-    if (asked.timeZone) {
-        options.timeZone = asked.timeZone;
-    }
-    else if (dateOnly) {
-        options.timeZone = 'UTC';
+    const options = {
+        hourCycle: asked.hourCycle,
+        timeZone: asked.timeZone || (dateOnly ? 'UTC' : undefined),
+    };
+    const styled = asked.dateStyle || asked.timeStyle;
+    for (const field of styled ? ['dateStyle', 'timeStyle'] : FIELDS) {
+        options[field] = asked[field];
     }
     return options;
 };

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

@@ -1,4 +1,4 @@
-import { HelixElement } from '@fusion.dev/helix-core';
+import { type DateCalendar, HelixElement } from '@fusion.dev/helix-core';
 import { nothing, type PropertyValues, type TemplateResult } from 'lit';
 /**
  * @summary A timestamp, formatted for the user's locale.
@@ -27,6 +27,12 @@ import { nothing, type PropertyValues, type TemplateResult } from 'lit';
  * 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
  * screen reader reads the text, so an `elapsed` reading is named in full, such
@@ -37,15 +43,43 @@ import { nothing, type PropertyValues, type TemplateResult } from 'lit';
  * Picker format their dates, so a reader west of UTC sees August 4 and not
  * August 3.
  *
+ * **A date is written in a calendar Date Picker draws**: the locale's own
+ * where its months are the Gregorian months, as `th-TH` writes 2569 for 2026,
+ * and `gregory` where they are not, as for `fa-IR`. `calendar` picks one of
+ * the five.
+ *
  * @since 0.1.0
  * @status stable
  * @category typography
  * @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 {
+    /**
+     * The calendar a date is written in: `gregory`, `buddhist`, `japanese`,
+     * `roc`, or `iso8601`, the calendars Date Picker and Date Input draw.
+     *
+     * Absent is the locale's own where it is one of the five, such as
+     * `buddhist` for `th-TH`, and `gregory` for every other, such as `persian`
+     * for `fa-IR`, so a date written here reads as the same date a Date Picker
+     * beside it shows.
+     */
+    calendar?: DateCalendar;
     /**
      * The timestamp, in any format `Date` can parse.
      *
@@ -86,6 +120,16 @@ 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.
@@ -118,7 +162,10 @@ export declare class HelixHeadlessFormatDate extends HelixElement {
      * 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`. */
+    /**
+     * The locale the words are written in, `locale` or the page's `lang`, with
+     * the calendar.
+     */
     private get language();
     /**
      * How the minute is written, where a time of day is shown.
@@ -184,15 +231,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, localeOf, RelativeClockController, relativeTime, } from '@fusion.dev/helix-core';
+import { calendarLocale, customElement, elapsedTime, HelixElement, RelativeClockController, relativeTime, wordsLocale, } 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 {
@@ -22,28 +23,27 @@ let HelixHeadlessFormatDate = class HelixHeadlessFormatDate extends HelixElement
                 if (!moment || !this.reading) {
                     return undefined;
                 }
-                return this.frozen ? Number.POSITIVE_INFINITY : this.readingAt(moment, now).next;
+                return this.frozen ? Infinity : this.readingAt(moment, now).next;
             },
         });
         this.written = '';
-        this.watching = undefined;
     }
     get language() {
-        return localeOf(this, this.locale);
+        return calendarLocale(wordsLocale(this), this.calendar);
     }
     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(this, this.dateOnly);
+    get source() {
+        return (this.date || this.written).trim();
     }
     get reading() {
         return this.elapsed || this.relative !== undefined;
@@ -65,7 +65,6 @@ let HelixHeadlessFormatDate = class HelixHeadlessFormatDate extends HelixElement
     disconnectedCallback() {
         super.disconnectedCallback();
         this.watching?.disconnect();
-        this.watching = undefined;
     }
     firstUpdated(changed) {
         super.firstUpdated(changed);
@@ -77,14 +76,12 @@ let HelixHeadlessFormatDate = class HelixHeadlessFormatDate extends HelixElement
         if (this.childrenKnown) {
             this.read();
         }
-        if (changed.has('date') ||
-            changed.has('elapsed') ||
-            changed.has('frozen') ||
-            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 !== '') {
@@ -93,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();
         }
     }
@@ -106,28 +104,25 @@ 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.language || 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.language || 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);
+            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>`;
+        return html `<time part="time" datetime=${datetime} aria-label=${spoken} title=${whole}>${this.readingAt(moment, now).text}</time>`;
     }
 };
+__decorate([
+    property()
+], HelixHeadlessFormatDate.prototype, "calendar", void 0);
 __decorate([
     property()
 ], HelixHeadlessFormatDate.prototype, "date", void 0);
@@ -143,6 +138,9 @@ __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);
@@ -185,9 +183,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-model.d.ts

@@ -87,6 +87,17 @@ export declare const within: (adjacency: Adjacency, from: string, depth: number)
  * its order instead.
  */
 export declare const entriesOf: (sorted: readonly GraphNode[], adjacency: Adjacency, active: string, query: string, shown?: ReadonlySet<string>) => Entry[];
+/**
+ * The row the keyboard stays on once the rows are read again from changed
+ * notes or links: the row of the note it was on, `id`, wherever that note now
+ * is, or, where the note was taken away, the row at `at` that took its place,
+ * the last row where the list grew shorter than that.
+ *
+ * **The reader stays where they were.** A graph a page feeds as things happen
+ * changes its notes every few seconds, and a cursor sent to the top on each
+ * change threw a reader moving through the list back to its first row.
+ */
+export declare const cursorAfter: (entries: readonly Entry[], id: string | undefined, at: number) => number;
 /** The notes in the order of their names, as the page's language orders words. */
 export declare const sortedOf: (nodes: readonly GraphNode[], lang?: string) => GraphNode[];
 /** One group the notes are in, as the legend names it. */

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

@@ -69,6 +69,10 @@ export const entriesOf = (sorted, adjacency, active, query, shown) => {
     }
     return [...first, ...neighbors, ...rest];
 };
+export const cursorAfter = (entries, id, at) => {
+    const found = id === undefined ? -1 : entries.findIndex((entry) => entry.node.id === id);
+    return found >= 0 ? found : Math.max(0, Math.min(at, entries.length - 1));
+};
 export const sortedOf = (nodes, lang) => {
     const collator = new Intl.Collator(lang || undefined, { numeric: true, sensitivity: 'base' });
     return [...nodes].sort((one, other) => collator.compare(nameOf(one), nameOf(other)));