@fusion.dev/helix-headless 0.144.0 → 0.146.0

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

@@ -13,12 +13,36 @@ declare const HelixHeadlessFilterInput_base: (new (...args: any[]) => import("@f
  * its tokens show a selection it owns, drawn from the options it was given.
  *
  * `value` is the typed text. Every keystroke fires `input` with the text on the
- * element, so a table can narrow as the user types. A form receives the text
- * under `name`, and then one more entry under `name` for each token: its
- * `value` attribute, or for a `FilterChip`, its field and values written
- * `field:values` as the field reads them typed. Backspace in an empty field fires
- * `helix-dismiss` on the last token, the same event its remove control fires,
- * so one handler covers the pointer and the keyboard.
+ * element, so a table can narrow as the user types. Backspace in an empty field
+ * fires `helix-dismiss` on the last token, the same event its remove control
+ * fires, so one handler covers the pointer and the keyboard.
+ *
+ * **What a form receives.** The text under `name`, and then one more entry
+ * under `name` for each token, in the order the tokens stand:
+ *
+ * | Token | Entry |
+ * |---|---|
+ * | Any element with a `value` attribute | The value as written: `saved:mine` |
+ * | `FilterChip` with `name` and values | `status:open,pending` |
+ * | The same, with `operator="none"` (what a typed `-status:` makes) | `-status:open,pending` |
+ * | The same, with any other `operator` except `any` | `created[after]:2024` |
+ * | A token with neither | Nothing |
+ *
+ * The values are the chip's text outside its `field` and `operator` slots,
+ * with the spaces around each comma removed. A server splits an entry at its
+ * first colon, reads a leading `-` as the negation, and reads a word in
+ * brackets before the colon as the comparison.
+ *
+ * **Keyboard.** Focus stays in the text. The text names the highlighted
+ * suggestion as its `aria-activedescendant`.
+ *
+ * | Key | What it does |
+ * |---|---|
+ * | Enter | Presses the highlighted suggestion. With none highlighted, reads the typed filters into chips, or submits the form when there are none. |
+ * | Down, Up | Moves the highlight through the suggestions, wrapping, and opens the panel. |
+ * | Home, End | Highlights the first or the last suggestion while the panel is open. |
+ * | Escape | Closes the panel and stops there, so a dialog around the field stays open. |
+ * | Backspace | In an empty field, asks the last token to go. |
  *
  * **Typed filters.** The field parses only the fields you declare. Write
  * `FilterField` elements, usually inside the `FilterMenu` slotted into `start`,

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

@@ -364,7 +364,7 @@ let HelixHeadlessFilterInput = class HelixHeadlessFilterInput extends MixinContr
         super.updated(changed);
         this.releaseCaret?.();
         this.releaseCaret = undefined;
-        this.internals.setFormValue(this.formValue());
+        this.internals.setFormValue(this.formValue(), this.value);
         this.sayCount();
         const control = this.control;
         if (control) {

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

@@ -9,9 +9,34 @@
 export declare const currentTerm: (text: string, caret?: number) => string;
 /** Whether a suggestion's words hold the term, ignoring case and accents. */
 export declare const suggests: (words: string, term: string) => boolean;
+/** What a token says about the filter it shows, as `tokenEntry` reads it. */
+export interface TokenWords {
+    /** The field it filters, from its `name` attribute. */
+    readonly field: string | null;
+    /** The comparison, from its `operator` attribute. */
+    readonly operator: string | null;
+    /** The values it shows, from its text. */
+    readonly text: string;
+    /** What it sends as written, from its `value` attribute. */
+    readonly value: string | null;
+}
 /**
- * What a token sends a form: its `value` attribute, or for a token naming a
- * field, the field and the values it shows, written `field:values` the way the
- * field reads them typed. Nothing for a token that says neither.
+ * The form entry for a token's words: its `value` where it has one, or else
+ * `field:values`, the way the field reads a filter typed.
+ *
+ * - The values are the token's text, with the spaces around each comma taken
+ *   out: `status:open,pending`.
+ * - The comparison named `none`, which a typed `-field:` asks for, leads with a
+ *   `-`: `-team:ops`.
+ * - Any comparison other than `any` and `none` is written in brackets after
+ *   the field, so a chip that says `is after` keeps it: `created[after]:2024`.
+ *   `any`, or no `operator`, writes none.
+ * - A token naming no field, or showing no values, sends nothing.
+ */
+export declare const entryFor: ({ field, operator, text, value }: TokenWords) => string | null;
+/**
+ * The form entry for a slotted token. See `entryFor`. The values are the text
+ * of the token's unslotted content, so a name or a comparison slotted into a
+ * chip's `field` or `operator` is not read as a value.
  */
 export declare const tokenEntry: (token: Element) => string | null;

package/dist/filter-input/suggest.js

@@ -8,16 +8,26 @@ export const suggests = (words, term) => {
     const plain = (text) => text.normalize('NFD').replace(/\p{M}/gu, '').toLowerCase();
     return term === '' || plain(words).includes(plain(term));
 };
-export const tokenEntry = (token) => {
-    const written = token.getAttribute('value');
-    if (written !== null) {
-        return written;
+export const entryFor = ({ field, operator, text, value }) => {
+    if (value !== null) {
+        return value;
     }
-    const field = token.getAttribute('name');
-    const values = (token.textContent ?? '').replace(/\s+/gu, ' ').trim();
+    const values = text.replace(/\s+/gu, ' ').trim();
     if (!field || values === '') {
         return null;
     }
-    const negated = token.getAttribute('operator')?.startsWith('not') ? '-' : '';
-    return `${negated}${field}:${values.replace(/\s*,\s*/gu, ',')}`;
+    const shown = values.replace(/\s*,\s*/gu, ',');
+    if (operator === 'none') {
+        return `-${field}:${shown}`;
+    }
+    return operator && operator !== 'any' ? `${field}[${operator}]:${shown}` : `${field}:${shown}`;
 };
+export const tokenEntry = (token) => entryFor({
+    field: token.getAttribute('name'),
+    operator: token.getAttribute('operator'),
+    text: [...token.childNodes]
+        .filter((node) => !(node.nodeType === 1 && node.hasAttribute('slot')))
+        .map((node) => node.textContent ?? '')
+        .join(''),
+    value: token.getAttribute('value'),
+});

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

@@ -154,18 +154,21 @@ export declare class HelixHeadlessFormatDate extends HelixElement {
      */
     year?: 'numeric' | '2-digit';
     /**
-     * The clock this element last drew against.
+     * The clock this element last drew against, moved on when the reading goes
+     * stale.
      *
-     * 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.
+     * A controller's time 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.
+     * The formatter says when its own answer expires, so the clock wakes at
+     * exactly that moment rather than polling: an item minutes old once a minute,
+     * an item hours old once an hour, and an item showing a date never.
      */
-    private clock;
+    private readonly clock;
     /**
      * The date read out of the light DOM, where no attribute carried one.
      */
     private written;
-    private stopTicking;
     private watching;
     /** Whether the timestamp is a day with no time, which is formatted in UTC. */
     private get dateOnly();
@@ -184,16 +187,6 @@ export declare class HelixHeadlessFormatDate extends HelixElement {
     /** 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 {

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, relativeTime, subscribe, } from '@fusion.dev/helix-core';
+import { customElement, elapsedTime, HelixElement, RelativeClockController, relativeTime, } from '@fusion.dev/helix-core';
 import { html, nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
 import { formatOptions } from '../options.js';
@@ -15,9 +15,13 @@ let HelixHeadlessFormatDate = class HelixHeadlessFormatDate extends HelixElement
         this.date = '';
         this.elapsed = false;
         this.locale = '';
-        this.clock = undefined;
+        this.clock = new RelativeClockController(this, {
+            expires: (now) => {
+                const moment = this.moment;
+                return moment && this.reading ? this.readingAt(moment, now).next : undefined;
+            },
+        });
         this.written = '';
-        this.stopTicking = undefined;
         this.watching = undefined;
     }
     get dateOnly() {
@@ -62,15 +66,12 @@ let HelixHeadlessFormatDate = class HelixHeadlessFormatDate extends HelixElement
     }
     connectedCallback() {
         super.connectedCallback();
-        this.tick();
         if (this.hasUpdated) {
             this.watch();
         }
     }
     disconnectedCallback() {
         super.disconnectedCallback();
-        this.stopTicking?.();
-        this.stopTicking = undefined;
         this.watching?.disconnect();
         this.watching = undefined;
     }
@@ -89,7 +90,7 @@ let HelixHeadlessFormatDate = class HelixHeadlessFormatDate extends HelixElement
             changed.has('locale') ||
             changed.has('numeric') ||
             changed.has('relative')) {
-            this.tick();
+            this.clock.tick();
         }
     }
     read() {
@@ -99,7 +100,7 @@ let HelixHeadlessFormatDate = class HelixHeadlessFormatDate extends HelixElement
         const written = this.textContent?.trim() ?? '';
         if (written !== this.written) {
             this.written = written;
-            this.tick();
+            this.clock.tick();
         }
     }
     watch() {
@@ -107,21 +108,6 @@ let HelixHeadlessFormatDate = class HelixHeadlessFormatDate extends HelixElement
         this.watching = new MutationObserver(() => this.read());
         this.watching.observe(this, { characterData: true, childList: true, subtree: true });
     }
-    tick() {
-        this.stopTicking?.();
-        this.stopTicking = undefined;
-        const moment = this.moment;
-        if (!moment || !this.reading) {
-            return;
-        }
-        const now = new Date();
-        this.clock = now.getTime();
-        const { next } = this.readingAt(moment, now);
-        if (!Number.isFinite(next) || !this.isConnected) {
-            return;
-        }
-        this.stopTicking = subscribe(next, () => this.tick());
-    }
     render() {
         const moment = this.moment;
         if (!moment) {
@@ -132,7 +118,7 @@ let HelixHeadlessFormatDate = class HelixHeadlessFormatDate extends HelixElement
             const text = new Intl.DateTimeFormat(this.locale || undefined, this.options).format(moment);
             return html `<time part="time" datetime=${datetime}>${text}</time>`;
         }
-        const now = new Date(this.clock ?? Date.now());
+        const now = new Date(this.clock.now);
         const zone = this.timeZone || (this.dateOnly ? 'UTC' : undefined);
         const whole = new Intl.DateTimeFormat(this.locale || undefined, {
             dateStyle: 'long',
@@ -203,9 +189,6 @@ __decorate([
 __decorate([
     property()
 ], HelixHeadlessFormatDate.prototype, "year", void 0);
-__decorate([
-    state()
-], HelixHeadlessFormatDate.prototype, "clock", void 0);
 __decorate([
     state()
 ], HelixHeadlessFormatDate.prototype, "written", void 0);

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

@@ -1,6 +1,7 @@
 import { AriaForwardController, HelixElement } from '@fusion.dev/helix-core';
 import { nothing, type PropertyValues, type TemplateResult } from 'lit';
 import '../../tooltip/index.js';
+import { type Reading } from './buckets.js';
 declare const HelixHeadlessHeatmap_base: typeof HelixElement & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinChartSourceInterface);
 /**
  * @summary A strip of cells, each colored by its reading, for uptime, contributions, or activity.
@@ -30,7 +31,13 @@ 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.
+ * puts the tooltip away. PageUp and PageDown move four columns, 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
+ * 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.
  *
  * @since 0.1.0
  * @status stable
@@ -51,6 +58,7 @@ declare const HelixHeadlessHeatmap_base: typeof HelixElement & (new (...args: an
  * @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 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.
@@ -87,6 +95,10 @@ declare const HelixHeadlessHeatmap_base: typeof HelixElement & (new (...args: an
  * @cssproperty --heatmap-tone-warning - The color of the `warning` tone.
  */
 export declare class HelixHeadlessHeatmap extends HelixHeadlessHeatmap_base {
+    /**
+     * The word the `overview` puts before the busiest reading.
+     */
+    busiestLabel: string;
     /**
      * Shown when the table has no readings in it.
      *
@@ -151,6 +163,10 @@ export declare class HelixHeadlessHeatmap extends HelixHeadlessHeatmap_base {
      * no order in it.
      */
     tones: string;
+    /**
+     * The word the `overview` puts before the total of the readings drawn.
+     */
+    totalLabel: string;
     /**
      * How many cells are actually drawn.
      *
@@ -197,18 +213,6 @@ export declare class HelixHeadlessHeatmap extends HelixHeadlessHeatmap_base {
      * image a reader lands on. The host is a generic around it.
      */
     protected readonly aria: AriaForwardController;
-    /**
-     * Hears an `aria-label` written on the element, which no property mirrors.
-     *
-     * Lit observes the attributes of its own properties only, and `ariaLabel`
-     * belongs to the platform.
-     */
-    static get observedAttributes(): string[];
-    /**
-     * Called by the browser when an observed attribute changes. A new
-     * `aria-label` asks for an update, because it names the strip.
-     */
-    attributeChangedCallback(name: string, old: string | null, value: string | null): void;
     private observer;
     private announced;
     /**
@@ -314,6 +318,13 @@ export declare class HelixHeadlessHeatmap extends HelixHeadlessHeatmap_base {
     private markEmpty;
     protected updated(changed: PropertyValues): void;
     protected render(): TemplateResult;
+    /**
+     * What the strip shows, in a sentence: the busiest reading drawn, as the
+     * table writes it, and the total of them all, in `locale`. The strip is
+     * described by it, so a reader landing on the strip hears what it holds
+     * before walking it.
+     */
+    protected renderOverview(cells: Reading[]): TemplateResult;
     /**
      * The bubble over the cell a pointer is resting on.
      *

package/dist/heatmap/root/heatmap-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, byRow, CHART_PLOT, customElement, drawTooltip, HelixElement, HelixResizeEvent, MixinChartSource, markRegion, searchableById, writtenList, writtenNumbers, } from '@fusion.dev/helix-core';
+import { AriaForwardController, byRow, CHART_PLOT, customElement, drawTooltip, formatNumbers, HelixElement, HelixResizeEvent, MixinChartSource, markRegion, searchableById, writtenList, writtenNumbers, } from '@fusion.dev/helix-core';
 import { html, nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
 import '../../tooltip/index.js';
@@ -12,12 +12,14 @@ import { fits, toneOf } from './buckets.js';
 let HelixHeadlessHeatmap = class HelixHeadlessHeatmap extends MixinChartSource(HelixElement) {
     constructor() {
         super(...arguments);
+        this.busiestLabel = 'Busiest';
         this.emptyText = 'No readings';
         this.gap = 2;
         this.minCell = 8;
         this.rows = 1;
         this.thresholds = '';
         this.tones = '';
+        this.totalLabel = 'Total';
         this.width = undefined;
         this.metrics = undefined;
         this.aria = new AriaForwardController(this, {
@@ -42,15 +44,6 @@ let HelixHeadlessHeatmap = class HelixHeadlessHeatmap extends MixinChartSource(H
     get visible() {
         return Math.min(this.points.length, this.room);
     }
-    static get observedAttributes() {
-        return [...super.observedAttributes, 'aria-label'];
-    }
-    attributeChangedCallback(name, old, value) {
-        super.attributeChangedCallback(name, old, value);
-        if (name === 'aria-label') {
-            this.requestUpdate();
-        }
-    }
     get points() {
         const series = this.series[0];
         if (!series) {
@@ -151,7 +144,8 @@ let HelixHeadlessHeatmap = class HelixHeadlessHeatmap extends MixinChartSource(H
         const cells = this.drawn;
         const readable = cells.length > 0;
         return html `<div
-        aria-label=${this.getAttribute?.('aria-label') || this.named || 'Heatmap'}
+        aria-describedby=${readable ? 'helix-chart-summary' : nothing}
+        aria-label=${this.named || 'Heatmap'}
         part="strip"
         id=${CHART_PLOT}
         role=${readable ? 'application' : 'img'}
@@ -184,7 +178,29 @@ let HelixHeadlessHeatmap = class HelixHeadlessHeatmap extends MixinChartSource(H
         <span part="start"><slot name="start"></slot></span>
         <span part="summary"><slot name="summary"></slot></span>
         <span part="end"><slot name="end"></slot></span>
-      </div>`;
+      </div>${readable ? this.renderOverview(cells) : nothing}`;
+    }
+    renderOverview(cells) {
+        const rows = this.sourceRows;
+        const offset = this.points.length - cells.length;
+        const column = this.plottedColumns[0] ?? -1;
+        let busiest = -1;
+        let total = 0;
+        cells.forEach((cell, index) => {
+            if (cell.value === undefined) {
+                return;
+            }
+            total += cell.value;
+            if (busiest < 0 || cell.value > (cells[busiest]?.value ?? 0)) {
+                busiest = index;
+            }
+        });
+        const row = rows[offset + busiest];
+        const most = row
+            ? `${this.busiestLabel}: ${row.label} ${row.cells[column]?.text ?? ''}`.trim()
+            : '';
+        const sum = `${this.totalLabel} ${formatNumbers(this.locale)(total)}`;
+        return html `<p id="helix-chart-summary" part="overview">${most ? `${most}; ${sum}` : sum}.</p>`;
     }
     renderTooltip() {
         const at = this.pointer.at;
@@ -203,6 +219,9 @@ let HelixHeadlessHeatmap = class HelixHeadlessHeatmap extends MixinChartSource(H
         }, undefined, this.pointer);
     }
 };
+__decorate([
+    property({ attribute: 'busiest-label' })
+], HelixHeadlessHeatmap.prototype, "busiestLabel", void 0);
 __decorate([
     property({ attribute: 'empty-text' })
 ], HelixHeadlessHeatmap.prototype, "emptyText", void 0);
@@ -221,6 +240,9 @@ __decorate([
 __decorate([
     property()
 ], HelixHeadlessHeatmap.prototype, "tones", void 0);
+__decorate([
+    property({ attribute: 'total-label' })
+], HelixHeadlessHeatmap.prototype, "totalLabel", void 0);
 __decorate([
     state()
 ], HelixHeadlessHeatmap.prototype, "width", void 0);

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

@@ -28,7 +28,8 @@ import { nothing, type PropertyValues, type TemplateResult } from 'lit';
  * rendered is drawn then.
  *
  * A name with no match renders nothing, and the element fires `error`, so a
- * typo in a name can be heard.
+ * typo in a name can be heard. It waits until the page has loaded and painted
+ * first, so a library a later module registers is not taken for a typo.
  *
  * An icon is decorative by default and hidden from assistive technology. Set
  * `label` only when the icon is the only carrier of meaning, such as in a
@@ -120,6 +121,16 @@ export declare class HelixHeadlessIcon extends HelixElement {
     private lookup;
     protected willUpdate(changed: PropertyValues): void;
     protected updated(changed: PropertyValues): void;
+    /** The name a report is waiting on the page to settle for, so it is asked once. */
+    private pending;
+    /**
+     * Says a name drew nothing, once the page has had its chance to register
+     * it: a library registered by a module further down the page, or by the
+     * page's own script after this element, is not a missing glyph. Asked again
+     * then, and said only where the name still draws nothing and nothing is
+     * still on its way.
+     */
+    private reportMissing;
     protected render(): TemplateResult | typeof nothing;
 }
 declare global {

package/dist/icon/root/icon-root.js

@@ -9,6 +9,7 @@ import { html, nothing } from 'lit';
 import { property } from 'lit/decorators.js';
 import { unsafeSVG } from 'lit/directives/unsafe-svg.js';
 import { resolveIcon, watchIcons } from '../registry.js';
+import { afterPageSettles } from '../settle.js';
 let HelixHeadlessIcon = class HelixHeadlessIcon extends HelixElement {
     constructor() {
         super(...arguments);
@@ -18,6 +19,7 @@ let HelixHeadlessIcon = class HelixHeadlessIcon extends HelixElement {
         this.missed = '';
         this.waiting = false;
         this.arrived = '';
+        this.pending = '';
     }
     static get observedAttributes() {
         return [...super.observedAttributes, 'aria-label'];
@@ -69,22 +71,31 @@ let HelixHeadlessIcon = class HelixHeadlessIcon extends HelixElement {
         }
         this.arrived = '';
         if (this.drawn === undefined && this.name !== '' && !this.waiting) {
-            if (this.missed !== this.name) {
-                this.missed = this.name;
-                this.dispatchEvent(new Event('error', { bubbles: false, cancelable: false, composed: false }));
-                reportRuntime({
-                    kind: 'unknown-icon',
-                    message: `<${this.localName} name="${this.name}"> names no registered icon, so it draws ` +
-                        'nothing. Check the name, register the glyph with `registerIcons`, or import it ' +
-                        'and pass it as `icon`.',
-                    tag: this.localName,
-                });
+            if (this.missed !== this.name && this.pending !== this.name) {
+                this.pending = this.name;
+                afterPageSettles(() => this.reportMissing());
             }
         }
         else {
             this.missed = '';
         }
     }
+    reportMissing() {
+        const name = this.pending;
+        this.pending = '';
+        if (this.name !== name || this.drawn !== undefined || this.waiting || !this.isConnected) {
+            return;
+        }
+        this.missed = name;
+        this.dispatchEvent(new Event('error', { bubbles: false, cancelable: false, composed: false }));
+        reportRuntime({
+            kind: 'unknown-icon',
+            message: `<${this.localName} name="${name}"> names no registered icon, so it draws ` +
+                'nothing. Check the name, register the glyph with `registerIcons`, or import it ' +
+                'and pass it as `icon`.',
+            tag: this.localName,
+        });
+    }
     render() {
         const icon = this.drawn;
         if (!icon) {

package/dist/icon/settle.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Calls back once the page has loaded and painted a frame after it: every
+ * module a page lists has run by then, and with it every `registerIcons` and
+ * `registerIconLibrary` they hold. A page that has loaded already waits only
+ * the frame.
+ */
+export declare const afterPageSettles: (callback: () => void) => void;

package/dist/icon/settle.js

@@ -0,0 +1,10 @@
+export const afterPageSettles = (callback) => {
+    const frame = () => {
+        requestAnimationFrame(() => callback());
+    };
+    if (document.readyState === 'complete') {
+        frame();
+        return;
+    }
+    window.addEventListener('load', frame, { once: true });
+};

package/dist/icon-button/root/icon-button-root.d.ts

@@ -17,6 +17,8 @@ import { HelixHeadlessButton } from '../../button/root/button-root.js';
  * mean a part of a button, and an icon-only button is a complete button with
  * different content and a different shape.
  *
+ * **Keyboard.** Enter and Space press the button, as `Button`'s do.
+ *
  * @since 0.1.0
  * @status stable
  * @category actions

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

@@ -12,13 +12,17 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * The `placeholder` slot is empty by default, so the headless tier does not
  * depend on `Skeleton`, which it does not ship.
  *
+ * The placeholder is hidden from screen readers, the picture having a name of
+ * its own. The fallback is read once the picture fails, after the picture's
+ * `alt`, so a reader hears that it did not load, as a sighted reader sees.
+ *
  * @since 0.1.0
  * @status stable
  * @category media
  * @aliases Picture, Img, Figure
  * @documentation https://fusion.dev/helix/components/image
  *
- * @slot fallback - Shown in place of the image if it fails to load.
+ * @slot fallback - Shown in place of the image if it fails to load, and read by screen readers then, such as "Photo unavailable".
  * @slot placeholder - Shown until the image loads.
  *
  * @event {Event} error - The image failed to load. Relayed from the inner image, whose own event stays inside the shadow root.

package/dist/image/root/image-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, DelayController, HelixElement } from '@fusion.dev/helix-core';
+import { customElement, DelayController, HelixElement, reportRuntime } from '@fusion.dev/helix-core';
 import { html, nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
 let HelixHeadlessImage = class HelixHeadlessImage extends HelixElement {
@@ -100,6 +100,14 @@ let HelixHeadlessImage = class HelixHeadlessImage extends HelixElement {
     firstUpdated(changed) {
         super.firstUpdated?.(changed);
         this.settle();
+        if (this.alt === undefined && this.getAttribute('aria-hidden') !== 'true') {
+            reportRuntime({
+                kind: 'missing-alt',
+                message: `<${this.localName}> has no \`alt\`, so a screen reader announces its file name. ` +
+                    'Describe the picture in `alt`, or write `alt=""` for one that is decoration.',
+                tag: this.localName,
+            });
+        }
     }
     get image() {
         return this.renderRoot?.querySelector('img') ?? null;
@@ -139,7 +147,7 @@ let HelixHeadlessImage = class HelixHeadlessImage extends HelixElement {
       ></span>
       <span
         part="fallback"
-        aria-hidden="true"
+        aria-hidden=${this.status === 'error' ? nothing : 'true'}
         ?hidden=${this.status !== 'error'}
         ><slot name="fallback"></slot
       ></span>`;