@fusion.dev/helix-headless 0.145.0 → 0.147.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

@@ -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,23 @@ 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 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
+ * 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
@@ -42,15 +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.
@@ -87,6 +109,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.
      *
@@ -129,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.
      *
@@ -151,6 +188,18 @@ 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;
+    /**
+     * 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.
      *
@@ -197,20 +246,30 @@ export declare class HelixHeadlessHeatmap extends HelixHeadlessHeatmap_base {
      * image a reader lands on. The host is a generic around it.
      */
     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;
     /**
-     * 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.
+     * 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.
      */
-    static get observedAttributes(): string[];
+    private choose;
+    /** Selects the drawn cell at `index`, or lets it go, as `selection-mode` says. */
+    private press;
     /**
-     * Called by the browser when an observed attribute changes. A new
-     * `aria-label` asks for an update, because it names the strip.
+     * 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.
      */
-    attributeChangedCallback(name: string, old: string | null, value: string | null): void;
-    private observer;
-    private announced;
+    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.
@@ -300,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;
     /**
@@ -314,6 +379,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,20 +4,24 @@ 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, commaList, customElement, drawTooltip, fillTemplate, formatNumbers, HelixBeforeChangeEvent, HelixElement, HelixResizeEvent, MixinChartSource, markRegion, pressedValue, rangeAdd, requestChange, StatusController, searchableById, writtenList, writtenNumbers, } from '@fusion.dev/helix-core';
 import { html, nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
 import '../../tooltip/index.js';
-import { fits, toneOf } from './buckets.js';
+import { fits, monthPage, overviewOf, 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.selectionLabel = '{count} selected';
         this.thresholds = '';
         this.tones = '';
+        this.totalLabel = 'Total';
+        this.value = '';
         this.width = undefined;
         this.metrics = undefined;
         this.aria = new AriaForwardController(this, {
@@ -25,6 +29,35 @@ let HelixHeadlessHeatmap = class HelixHeadlessHeatmap extends MixinChartSource(H
         });
         this.observer = undefined;
         this.announced = undefined;
+        this.anchor = -1;
+        this.status = new StatusController(this);
+        this.onKeydown = (event) => {
+            const at = this.pointer.at;
+            if (!this.selectionMode || at < 0 || event.altKey || event.ctrlKey || event.metaKey) {
+                return;
+            }
+            if (event.key === ' ' || event.key === 'Enter') {
+                event.preventDefault();
+                this.press(at);
+                return;
+            }
+            const moves = /^(Arrow|Page|Home$|End$)/.test(event.key);
+            if (!event.shiftKey || !moves || this.selectionMode !== 'multiple') {
+                return;
+            }
+            const keys = this.keysOf(this.drawn);
+            const added = rangeAdd(commaList(this.value), keys, this.anchor < 0 ? at : this.anchor, at);
+            if (added) {
+                this.choose(added.join(', '));
+            }
+        };
+        this.onClick = (event) => {
+            const cell = event.target?.closest?.('[part~="cell"]');
+            const index = Number(cell?.getAttribute('data-index') ?? -1);
+            if (cell && Number.isInteger(index) && index >= 0) {
+                this.press(index);
+            }
+        };
         this.onPointerOver = (event) => {
             if (!this.pointer.accepts(event)) {
                 return;
@@ -42,14 +75,34 @@ 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'];
+    keysOf(cells) {
+        const offset = this.points.length - cells.length;
+        const rows = this.sourceRows;
+        return cells.map((_, index) => rows[offset + index]?.label ?? '');
+    }
+    choose(next) {
+        if (next === this.value) {
+            return;
+        }
+        requestChange({
+            apply: (value) => {
+                this.value = value;
+                this.dispatchEvent(new Event('change', { bubbles: true, composed: true }));
+                this.status.say(fillTemplate(this.selectionLabel, { count: commaList(value).length }));
+            },
+            event: (value) => new HelixBeforeChangeEvent({ value }),
+            host: this,
+            next,
+        });
     }
-    attributeChangedCallback(name, old, value) {
-        super.attributeChangedCallback(name, old, value);
-        if (name === 'aria-label') {
-            this.requestUpdate();
+    press(index) {
+        const mode = this.selectionMode;
+        const key = this.keysOf(this.drawn)[index];
+        if (!mode || key === undefined || key === '') {
+            return;
         }
+        this.anchor = index;
+        this.choose(pressedValue(mode, this.value, key));
     }
     get points() {
         const series = this.series[0];
@@ -106,8 +159,13 @@ let HelixHeadlessHeatmap = class HelixHeadlessHeatmap extends MixinChartSource(H
         super.willUpdate(changed);
         this.pointer.grid = this.rowCount;
     }
+    pageFrom(at, forward) {
+        const offset = this.points.length - this.drawn.length;
+        return monthPage(this.sourceRows.slice(offset).map((row) => row.when), at, forward);
+    }
     connectedCallback() {
         super.connectedCallback();
+        this.addEventListener('keydown', this.onKeydown);
         if (typeof ResizeObserver !== 'undefined') {
             this.observer = new ResizeObserver((entries) => {
                 const measured = entries[0]?.contentRect.width;
@@ -120,6 +178,7 @@ let HelixHeadlessHeatmap = class HelixHeadlessHeatmap extends MixinChartSource(H
     }
     disconnectedCallback() {
         super.disconnectedCallback();
+        this.removeEventListener('keydown', this.onKeydown);
         this.observer?.disconnect();
         this.observer = undefined;
     }
@@ -150,13 +209,17 @@ let HelixHeadlessHeatmap = class HelixHeadlessHeatmap extends MixinChartSource(H
         const palette = writtenList(this.tones);
         const cells = this.drawn;
         const readable = cells.length > 0;
+        const keys = this.selectionMode ? this.keysOf(cells) : [];
+        const chosen = new Set(this.selectionMode ? commaList(this.value) : []);
         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'}
         style="--heatmap-rows: ${this.rowCount}"
         tabindex=${readable ? '0' : nothing}
+        @click=${this.onClick}
         @pointerover=${this.onPointerOver}
         @pointerleave=${this.onPointerLeave}
       >
@@ -165,13 +228,14 @@ let HelixHeadlessHeatmap = class HelixHeadlessHeatmap extends MixinChartSource(H
             : cells.map((reading, index) => {
                 const tone = toneOf(reading, bounds, palette);
                 const active = this.pointer.at === index;
+                const picked = chosen.has(keys[index] ?? '');
                 return tone === undefined
                     ? html `<span
-                      part="cell${active ? ' cell-active' : ''}"
+                      part="cell${active ? ' cell-active' : ''}${picked ? ' cell-selected' : ''}"
                       data-index=${index}
                     ></span>`
                     : html `<span
-                part="cell${active ? ' cell-active' : ''}"
+                part="cell${active ? ' cell-active' : ''}${picked ? ' cell-selected' : ''}"
                 data-index=${index}
                 data-tone=${tone}
                 style="--heatmap-tone: var(--heatmap-tone-${tone})"
@@ -184,7 +248,20 @@ 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}${this.status.spoken
+            ? html `<span part="selection" role="status">${this.status.said}</span>`
+            : nothing}`;
+    }
+    renderOverview(cells) {
+        const rows = this.sourceRows;
+        const offset = this.points.length - cells.length;
+        const column = this.plottedColumns[0] ?? -1;
+        const { busiest, total } = overviewOf(cells);
+        const row = rows[offset + busiest];
+        const text = row?.cells[column]?.text ?? '';
+        const most = row ? `${this.busiestLabel}: ${row.label}${text === '' ? '' : `, ${text}`}` : '';
+        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 +280,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);
@@ -215,12 +295,24 @@ __decorate([
 __decorate([
     property({ type: Number })
 ], HelixHeadlessHeatmap.prototype, "rows", void 0);
+__decorate([
+    property({ attribute: 'selection-label' })
+], HelixHeadlessHeatmap.prototype, "selectionLabel", void 0);
+__decorate([
+    property({ attribute: 'selection-mode' })
+], HelixHeadlessHeatmap.prototype, "selectionMode", void 0);
 __decorate([
     property()
 ], HelixHeadlessHeatmap.prototype, "thresholds", void 0);
 __decorate([
     property()
 ], HelixHeadlessHeatmap.prototype, "tones", void 0);
+__decorate([
+    property({ attribute: 'total-label' })
+], HelixHeadlessHeatmap.prototype, "totalLabel", void 0);
+__decorate([
+    property()
+], HelixHeadlessHeatmap.prototype, "value", void 0);
 __decorate([
     state()
 ], HelixHeadlessHeatmap.prototype, "width", void 0);

package/dist/icon/index.d.ts

@@ -1,3 +1,3 @@
 import './set.js';
-export { type IconResolver, registerIconLibrary, registerIcons, resolveIcon } from './registry.js';
+export { type IconLibraryOptions, type IconResolver, registerIconLibrary, registerIcons, resolveIcon, } from './registry.js';
 export * from './root/icon-root.js';

package/dist/icon/index.js

@@ -1,3 +1,3 @@
 import './set.js';
-export { registerIconLibrary, registerIcons, resolveIcon } from './registry.js';
+export { registerIconLibrary, registerIcons, resolveIcon, } from './registry.js';
 export * from './root/icon-root.js';

package/dist/icon/registry.d.ts

@@ -1,6 +1,15 @@
 import type { HelixIcon } from '@fusion.dev/helix-icons';
 /** What a library gives for a name: a glyph, a glyph later, or nothing. */
 export type IconResolver = (name: string) => HelixIcon | Promise<HelixIcon | undefined> | undefined;
+/** How a library's glyphs are drawn, beside the names it resolves. */
+export interface IconLibraryOptions {
+    /**
+     * Changes each drawn `<svg>` of the library's glyphs, as Web Awesome's
+     * `mutator` does: a stroke width, a fill, an attribute the set leaves out.
+     * Called after every render that draws one of them.
+     */
+    mutator?: (svg: SVGSVGElement) => void;
+}
 /**
  * Makes glyphs resolvable by name: a record of names to glyphs, such as the
  * whole set, or a list of glyphs, each under its own `name`.
@@ -15,14 +24,30 @@ export declare const registerIcons: (glyphs: Record<string, HelixIcon> | readonl
  * The resolver may answer at once or with a promise; an element waiting on a
  * promise draws the glyph when it arrives and fires `load`. Each written name
  * is asked once, and a prefix registered again is asked afresh.
+ *
+ * A sprite sheet is a library whose glyphs point into it, so the sheet is
+ * fetched once and cached:
+ *
+ * ```js
+ * registerIconLibrary('sprite', (name) => ({
+ *   content: `<use href="/icons.svg#${name}"></use>`,
+ *   name,
+ *   viewBox: '0 0 24 24',
+ * }))
+ * ```
+ *
+ * `mutator` changes each drawn `<svg>` of the library, such as
+ * `(svg) => svg.setAttribute('stroke-width', '1.5')`.
  */
-export declare const registerIconLibrary: (prefix: string, resolve: IconResolver) => void;
+export declare const registerIconLibrary: (prefix: string, resolve: IconResolver, options?: IconLibraryOptions) => void;
 /**
  * Calls `watcher` whenever a glyph or a library is registered, so an element
  * drawn before its glyph was registered can look again. Returns the function
  * that stops it.
  */
 export declare const watchIcons: (watcher: () => void) => (() => void);
+/** The mutator of the library a written name asks, or `undefined`. */
+export declare const iconMutator: (name: string) => ((svg: SVGSVGElement) => void) | undefined;
 /** The registered glyph of this name, or `undefined`. */
 export declare const registeredIcon: (name: string) => HelixIcon | undefined;
 /**

package/dist/icon/registry.js

@@ -24,9 +24,16 @@ export const registerIcons = (glyphs) => {
     }
     changed(held);
 };
-export const registerIconLibrary = (prefix, resolve) => {
+export const registerIconLibrary = (prefix, resolve, options = {}) => {
     const held = registry();
     held.libraries.set(prefix, resolve);
+    held.mutators ??= new Map();
+    if (options.mutator) {
+        held.mutators.set(prefix, options.mutator);
+    }
+    else {
+        held.mutators.delete(prefix);
+    }
     for (const name of held.answers.keys()) {
         if (name.startsWith(`${prefix}:`)) {
             held.answers.delete(name);
@@ -41,6 +48,10 @@ export const watchIcons = (watcher) => {
         held.watchers.delete(watcher);
     };
 };
+export const iconMutator = (name) => {
+    const split = name.indexOf(':');
+    return split > 0 ? registry().mutators?.get(name.slice(0, split)) : undefined;
+};
 export const registeredIcon = (name) => registry().glyphs.get(name);
 export const resolveIcon = (name) => {
     const registered = registeredIcon(name);

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

@@ -28,13 +28,19 @@ 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
  * button with no text. An `aria-label` on the element works too: the element
  * is then an image with that name.
  *
+ * **A decorative icon that is all a control holds is reported.** In a
+ * development build, a button or a link whose only content is an icon with no
+ * `label`, and which has no name of its own, warns `missing-name` once,
+ * through the runtime channel every Helix warning uses.
+ *
  * @since 0.1.0
  * @status stable
  * @category media
@@ -120,6 +126,24 @@ export declare class HelixHeadlessIcon extends HelixElement {
     private lookup;
     protected willUpdate(changed: PropertyValues): void;
     protected updated(changed: PropertyValues): void;
+    /** Hands the drawn `<svg>` to the mutator of the library `name` asks, where it has one. */
+    private mutate;
+    /**
+     * Asks the button or link a decorative icon sits in whether it has a name.
+     * Its content is this icon alone where it has none, and the audit says so
+     * once, in a development build only. A Helix button reports its own name.
+     */
+    private auditControl;
+    /** 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 {