@fusion.dev/helix-headless 0.153.0 → 0.154.0

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

@@ -27,8 +27,16 @@ import { nothing, type PropertyValues, type TemplateResult } from 'lit';
  * a glyph that came later is drawn. A glyph registered after the element
  * 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. It waits until the page has loaded and painted
+ * **Or point `src` at an SVG file**, such as `src="/icons/rocket.svg"`, and
+ * the element fetches it and draws its shapes in `currentColor` where the file
+ * does not color them. A file is fetched once a page, however many icons name
+ * it, and `load` fires when it is drawn. Scripts, event handlers and
+ * `javascript:` links in the file are taken out before it is drawn. A server
+ * fetches nothing, so a served icon with a `src` is drawn once the script
+ * runs.
+ *
+ * A name with no match, or a `src` that is no SVG, renders nothing, and the
+ * element fires `error`, so a 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
@@ -47,8 +55,8 @@ import { nothing, type PropertyValues, type TemplateResult } from 'lit';
  * @aliases Glyph, Symbol
  * @documentation https://fusion.dev/helix/components/icon
  *
- * @event {Event} error - `name` matches no registered icon and no library answers it, so nothing is drawn.
- * @event {Event} load - A glyph a library gave later for `name` is drawn.
+ * @event {Event} error - `name` matches no registered icon and no library answers it, or `src` is no SVG, so nothing is drawn.
+ * @event {Event} load - A glyph a library gave later for `name`, or the file at `src`, is drawn.
  *
  * @csspart svg - The rendered SVG.
  */
@@ -97,6 +105,13 @@ export declare class HelixHeadlessIcon extends HelixElement {
      * prefix.
      */
     name: string;
+    /**
+     * The URL of an SVG file to draw, fetched once a page and drawn in
+     * `currentColor` where the file does not color its shapes.
+     *
+     * Wins over `name`; `icon` wins over both. Absent draws `name`.
+     */
+    src: string;
     /**
      * Hears an `aria-label` written on the element, which no property mirrors.
      *
@@ -120,11 +135,18 @@ export declare class HelixHeadlessIcon extends HelixElement {
     private arrived;
     /** Stops listening to the registry. */
     private unwatch;
+    /** What the glyph is asked for by: `src` where it is set, and `name` otherwise. */
+    private get asked();
     connectedCallback(): void;
     disconnectedCallback(): void;
-    /** What the registry gives for `name` now, starting the wait for a late glyph. */
+    /**
+     * What `src` or the registry gives now, starting the wait for a late glyph.
+     * A file is fetched only where the page can be read: a server fetches
+     * nothing, and a hydrating render draws what the server sent.
+     */
     private lookup;
     protected willUpdate(changed: PropertyValues): void;
+    protected firstUpdated(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;

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

@@ -8,6 +8,7 @@ import { auditName, customElement, HelixElement, hostAria, reportRuntime, } from
 import { html, nothing } from 'lit';
 import { property } from 'lit/decorators.js';
 import { unsafeSVG } from 'lit/directives/unsafe-svg.js';
+import { fetchIcon } from '../fetch.js';
 import { iconMutator, resolveIcon, watchIcons } from '../registry.js';
 import { afterPageSettles } from '../settle.js';
 let HelixHeadlessIcon = class HelixHeadlessIcon extends HelixElement {
@@ -16,6 +17,7 @@ let HelixHeadlessIcon = class HelixHeadlessIcon extends HelixElement {
         this.label = '';
         this.mirror = false;
         this.name = '';
+        this.src = '';
         this.missed = '';
         this.waiting = false;
         this.arrived = '';
@@ -30,10 +32,13 @@ let HelixHeadlessIcon = class HelixHeadlessIcon extends HelixElement {
             this.requestUpdate();
         }
     }
+    get asked() {
+        return this.src || this.name;
+    }
     connectedCallback() {
         super.connectedCallback();
         this.unwatch = watchIcons(() => {
-            if (this.icon === undefined && this.name !== '') {
+            if (this.icon === undefined && this.src === '' && this.name !== '') {
                 this.requestUpdate();
             }
         });
@@ -44,15 +49,21 @@ let HelixHeadlessIcon = class HelixHeadlessIcon extends HelixElement {
         this.unwatch = undefined;
     }
     lookup() {
-        const found = this.name === '' ? undefined : resolveIcon(this.name);
-        this.waiting = found instanceof Promise;
+        const asked = this.asked;
+        const found = this.src !== ''
+            ? this.childrenKnown
+                ? fetchIcon(this.src)
+                : undefined
+            : this.name === ''
+                ? undefined
+                : resolveIcon(this.name);
+        this.waiting = found instanceof Promise || (this.src !== '' && !this.childrenKnown);
         if (!(found instanceof Promise)) {
             return found;
         }
-        const name = this.name;
         void found.then(() => {
-            if (this.name === name && this.isConnected) {
-                this.arrived = name;
+            if (this.asked === asked && this.isConnected) {
+                this.arrived = asked;
                 this.requestUpdate();
             }
         });
@@ -64,19 +75,26 @@ let HelixHeadlessIcon = class HelixHeadlessIcon extends HelixElement {
         hostAria(this.internals, { role: named ? 'img' : '' });
         this.drawn = this.icon ?? this.lookup();
     }
+    firstUpdated(changed) {
+        super.firstUpdated(changed);
+        if (this.src !== '') {
+            this.finishHydration();
+        }
+    }
     updated(changed) {
         super.updated(changed);
         if (this.drawn !== undefined) {
             this.mutate();
             this.auditControl();
         }
-        if (this.arrived === this.name && this.drawn !== undefined) {
+        const asked = this.asked;
+        if (this.arrived === asked && this.drawn !== undefined) {
             this.dispatchEvent(new Event('load', { bubbles: false, cancelable: false, composed: false }));
         }
         this.arrived = '';
-        if (this.drawn === undefined && this.name !== '' && !this.waiting) {
-            if (this.missed !== this.name && this.pending !== this.name) {
-                this.pending = this.name;
+        if (this.drawn === undefined && asked !== '' && !this.waiting) {
+            if (this.missed !== asked && this.pending !== asked) {
+                this.pending = asked;
                 afterPageSettles(() => this.reportMissing());
             }
         }
@@ -86,7 +104,7 @@ let HelixHeadlessIcon = class HelixHeadlessIcon extends HelixElement {
     }
     mutate() {
         const svg = this.renderRoot.querySelector('svg');
-        const mutator = this.icon === undefined ? iconMutator(this.name) : undefined;
+        const mutator = this.icon === undefined && this.src === '' ? iconMutator(this.name) : undefined;
         if (svg && mutator) {
             mutator(svg);
         }
@@ -102,18 +120,21 @@ let HelixHeadlessIcon = class HelixHeadlessIcon extends HelixElement {
         }
     }
     reportMissing() {
-        const name = this.pending;
+        const asked = this.pending;
         this.pending = '';
-        if (this.name !== name || this.drawn !== undefined || this.waiting || !this.isConnected) {
+        if (this.asked !== asked || this.drawn !== undefined || this.waiting || !this.isConnected) {
             return;
         }
-        this.missed = name;
+        this.missed = asked;
         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`.',
+            message: this.src === ''
+                ? `<${this.localName} name="${asked}"> names no registered icon, so it draws ` +
+                    'nothing. Check the name, register the glyph with `registerIcons`, or import it ' +
+                    'and pass it as `icon`.'
+                : `<${this.localName} src="${asked}"> could not be fetched as an SVG file, so it ` +
+                    'draws nothing. Check the URL, and that the file is an `<svg>`.',
             tag: this.localName,
         });
     }
@@ -148,6 +169,9 @@ __decorate([
 __decorate([
     property()
 ], HelixHeadlessIcon.prototype, "name", void 0);
+__decorate([
+    property()
+], HelixHeadlessIcon.prototype, "src", void 0);
 HelixHeadlessIcon = __decorate([
     customElement('helix-headless-icon')
 ], HelixHeadlessIcon);

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

@@ -1,5 +1,5 @@
 import { HelixElement } from '@fusion.dev/helix-core';
-import { type PropertyValues, type TemplateResult } from 'lit';
+import { type CSSResultGroup, type PropertyValues, type TemplateResult } from 'lit';
 /**
  * @summary A short quotation, set inline with the text around it.
  *
@@ -12,6 +12,12 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * element, and its marks follow it: `lang="de"` sets „…“ and `lang="fr"` «…»
  * inside an English page.
  *
+ * **`no-marks` leaves the marks off**, for a quotation set where the page draws
+ * its own, such as a pull quote with a large decorative mark beside it or a
+ * table of sayings. The quotation still counts toward nesting, so a quote
+ * inside it takes the inner marks it would have had. Text with marks typed
+ * into it raises no warning under `no-marks`.
+ *
  * For a passage set off from the surrounding text, use a blockquote.
  *
  * @since 0.1.0
@@ -25,10 +31,20 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * @csspart quote - The quotation.
  */
 export declare class HelixHeadlessQuote extends HelixElement {
+    static styles: CSSResultGroup;
     /**
      * URL identifying where the quotation came from.
      */
     cite: string;
+    /**
+     * Whether to leave the quotation marks off, for a quotation set where the
+     * page draws its own.
+     *
+     * Negative, because the marks are on by default and a boolean attribute is
+     * true whenever it is present. Reflected, because a stylesheet takes the
+     * marks off on it.
+     */
+    noMarks: boolean;
     /** Whether this quote has said its text carries typed marks, so it says so once. */
     private warned;
     /**

package/dist/quote/root/quote-root.js

@@ -5,20 +5,21 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
 import { customElement, HelixElement, reportRuntime } from '@fusion.dev/helix-core';
-import { html, nothing } from 'lit';
+import { css, html, nothing, } from 'lit';
 import { property } from 'lit/decorators.js';
 import { typedMarks } from '../marks.js';
 let HelixHeadlessQuote = class HelixHeadlessQuote extends HelixElement {
     constructor() {
         super(...arguments);
         this.cite = '';
+        this.noMarks = false;
         this.warned = false;
         this.readText = () => {
             const text = [...this.childNodes]
                 .filter((node) => !(node instanceof Element) || !node.slot)
                 .map((node) => node.textContent ?? '')
                 .join('');
-            if (this.warned || !typedMarks(text)) {
+            if (this.warned || this.noMarks || !typedMarks(text)) {
                 return;
             }
             this.warned = true;
@@ -29,6 +30,15 @@ let HelixHeadlessQuote = class HelixHeadlessQuote extends HelixElement {
             });
         };
     }
+    static { this.styles = css `
+    :host([no-marks]) [part='quote']::before {
+      content: no-open-quote;
+    }
+
+    :host([no-marks]) [part='quote']::after {
+      content: no-close-quote;
+    }
+  `; }
     firstUpdated(changed) {
         super.firstUpdated(changed);
         this.readText();
@@ -41,6 +51,9 @@ let HelixHeadlessQuote = class HelixHeadlessQuote extends HelixElement {
 __decorate([
     property()
 ], HelixHeadlessQuote.prototype, "cite", void 0);
+__decorate([
+    property({ attribute: 'no-marks', reflect: true, type: Boolean })
+], HelixHeadlessQuote.prototype, "noMarks", void 0);
 HelixHeadlessQuote = __decorate([
     customElement('helix-headless-quote')
 ], HelixHeadlessQuote);

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

@@ -61,6 +61,13 @@ export declare class HelixHeadlessSkeleton extends HelixElement {
     protected willUpdate(changed: PropertyValues): void;
     protected firstUpdated(changed: PropertyValues): void;
     protected render(): TemplateResult;
+    /**
+     * The placeholder shape and the sheen inside it.
+     *
+     * A method, so a tier above can draw the placeholder as several shapes, as
+     * the styled tier draws a paragraph of lines.
+     */
+    protected renderShape(): TemplateResult;
 }
 declare global {
     interface HTMLElementTagNameMap {

package/dist/skeleton/root/skeleton-root.js

@@ -38,7 +38,10 @@ let HelixHeadlessSkeleton = class HelixHeadlessSkeleton extends HelixElement {
     render() {
         return html `<span part="content" ?inert=${this.loading}
         ><slot @slotchange=${() => this.requestUpdate()}></slot></span
-      ><span part="skeleton"><span part="sheen"></span></span>`;
+      >${this.renderShape()}`;
+    }
+    renderShape() {
+        return html `<span part="skeleton"><span part="sheen"></span></span>`;
     }
 };
 __decorate([

package/dist/stat/group/stat-group.d.ts

@@ -4,9 +4,12 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * @summary A row of related measurements.
  *
  * @description
- * Screen readers announce the stats as a group. The figures are read together
- * and their order has no meaning, so the group does not announce positions such
- * as "1 of 4".
+ * **A named group is a group**, so a screen reader announces the stats
+ * together under its name, such as "Usage, group". Name it with `label`,
+ * `aria-label` or `aria-labelledby`. An unnamed one has no role, since a group
+ * with no name only adds "group" to what a reader says, as an unnamed Card
+ * has none. The figures are read together and their order has no meaning, so
+ * the group does not announce positions such as "1 of 4".
  *
  * @since 0.1.0
  * @status stable
@@ -17,9 +20,25 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  */
 export declare class HelixHeadlessStatGroup extends HelixElement {
     /**
-     * Accessible name for the group.
+     * Accessible name for the group, which makes it a group.
+     *
+     * Absent leaves the stats with no group around them, unless `aria-label` or
+     * `aria-labelledby` names it.
      */
     label: string;
+    /**
+     * Hears a name written on the element, which no property mirrors.
+     *
+     * Lit observes the attributes of its own properties only, and `ariaLabel`
+     * and `ariaLabelledByElements` belong to the platform.
+     */
+    static get observedAttributes(): string[];
+    /**
+     * Called by the browser when an observed attribute changes. A name written
+     * or taken off asks for an update, because it decides whether the stats are
+     * a group.
+     */
+    attributeChangedCallback(name: string, old: string | null, value: string | null): void;
     protected willUpdate(changed: PropertyValues): void;
     protected render(): TemplateResult;
 }

package/dist/stat/group/stat-group.js

@@ -12,9 +12,21 @@ let HelixHeadlessStatGroup = class HelixHeadlessStatGroup extends HelixElement {
         super(...arguments);
         this.label = '';
     }
+    static get observedAttributes() {
+        return [...super.observedAttributes, 'aria-label', 'aria-labelledby'];
+    }
+    attributeChangedCallback(name, old, value) {
+        super.attributeChangedCallback(name, old, value);
+        if (name === 'aria-label' || name === 'aria-labelledby') {
+            this.requestUpdate();
+        }
+    }
     willUpdate(changed) {
         super.willUpdate(changed);
-        hostAria(this.internals, { label: this.label, role: 'group' });
+        const named = this.label.trim() !== '' ||
+            Boolean(this.getAttribute?.('aria-label')?.trim()) ||
+            Boolean(this.getAttribute?.('aria-labelledby')?.trim());
+        hostAria(this.internals, { label: this.label, role: named ? 'group' : '' });
     }
     render() {
         return html `<slot></slot>`;

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

@@ -19,6 +19,19 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * attribute; a stat with no label has no role. Put a `Trend` in the `trend`
  * slot to have it read inside the group, after the figure it qualifies.
  *
+ * **Or give the figure as a number.** `value` is written with
+ * `Intl.NumberFormat`, in `locale` and with `format-options`, so
+ * `value="1234567" format-options='{"notation":"compact"}'` shows `1.2M`, and
+ * a server writes it as the browser does. A number in `value` takes the place
+ * of a slotted figure.
+ *
+ * **Each slot is a part of the same name**, and `value` for the figure, so a
+ * page reaches the label, the unit and the trend from outside. A slot draws no
+ * box, so a part passes inherited properties to what is slotted. **The stat
+ * says which pieces it holds**, as `:state(has-label)`, `:state(has-unit)` and
+ * `:state(has-trend)`, read in the browser, so a served stat carries none
+ * until the script runs.
+ *
  * @since 0.1.0
  * @status stable
  * @category data
@@ -30,7 +43,14 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * @slot trend - How the value moved, usually a `Trend`, read after the value inside the stat's group.
  * @slot unit - The unit, shown beside the value.
  *
- * @csspart value - The slot the value is written in. A slot draws no box, so it takes the inherited properties, such as color and font, and passes them to the value.
+ * @csspart label - The slot the label arrives through, drawing no box, as `value` does.
+ * @csspart trend - The slot the trend arrives through, drawing no box, as `value` does.
+ * @csspart unit - The slot the unit arrives through, drawing no box, as `value` does.
+ * @csspart value - The slot the value is written in, or the figure `value` writes. A slot draws no box, so it takes the inherited properties, such as color and font, and passes them to the value.
+ *
+ * @cssstate has-label - Something is slotted into `label`.
+ * @cssstate has-trend - Something is slotted into `trend`.
+ * @cssstate has-unit - Something is slotted into `unit`.
  */
 export declare class HelixHeadlessStat extends HelixElement {
     /**
@@ -61,9 +81,34 @@ export declare class HelixHeadlessStat extends HelixElement {
      * carries nothing nobody wrote.
      */
     direction?: 'column-reverse' | 'row' | 'row-reverse';
+    /**
+     * `Intl.NumberFormat` options `value` is written with, such as
+     * `{"notation":"compact"}` for `1.2M` or `{"style":"percent"}` for `98%`,
+     * written as JSON in the attribute.
+     *
+     * Absent writes the number as the locale writes any number.
+     */
+    formatOptions?: Intl.NumberFormatOptions;
+    /**
+     * The locale `value` is written in, such as `de` for `1.234.567`.
+     *
+     * Absent reads the nearest `lang`, then the runtime's own. Set it on a page
+     * rendered on a server, so the server and the browser write the figure
+     * alike.
+     */
+    locale: string;
+    /**
+     * The figure as a number, written with `format-options` in `locale` in
+     * place of a slotted value.
+     *
+     * Absent leaves the figure to the slot.
+     */
+    value?: number;
     protected willUpdate(changed: PropertyValues): void;
     protected firstUpdated(changed: PropertyValues): void;
     protected updated(changed: PropertyValues): void;
+    /** Says which pieces the stat holds, one call apiece so each pairs with its `@cssstate`. */
+    private readonly readPieces;
     protected render(): TemplateResult;
 }
 declare global {

package/dist/stat/root/stat-root.js

@@ -4,10 +4,20 @@ 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, HelixElement, hostAria, reportRuntime, slottedWords, } from '@fusion.dev/helix-core';
+import { customElement, formatNumber, HelixElement, hostAria, reportRuntime, slotFilled, slottedWords, wordsLocale, } from '@fusion.dev/helix-core';
 import { html } from 'lit';
 import { property } from 'lit/decorators.js';
 let HelixHeadlessStat = class HelixHeadlessStat extends HelixElement {
+    constructor() {
+        super(...arguments);
+        this.locale = '';
+        this.readPieces = () => {
+            const filled = (name) => slotFilled(this.renderRoot?.querySelector(`slot[name="${name}"]`));
+            this.toggleState('has-label', filled('label'));
+            this.toggleState('has-unit', filled('unit'));
+            this.toggleState('has-trend', filled('trend'));
+        };
+    }
     willUpdate(changed) {
         super.willUpdate(changed);
         const labels = this.knownChildren.filter((child) => child.slot === 'label');
@@ -25,6 +35,7 @@ let HelixHeadlessStat = class HelixHeadlessStat extends HelixElement {
     }
     updated(changed) {
         super.updated(changed);
+        this.readPieces();
         const given = this.direction;
         if (changed.has('direction') && (given === 'up' || given === 'down' || given === 'neutral')) {
             reportRuntime({
@@ -37,15 +48,28 @@ let HelixHeadlessStat = class HelixHeadlessStat extends HelixElement {
         }
     }
     render() {
-        return html `<slot name="label" @slotchange=${() => this.requestUpdate()}></slot>
-      <slot part="value"></slot>
-      <slot name="unit"></slot>
-      <slot name="trend"></slot>`;
+        const value = this.value;
+        const figure = value === undefined || !Number.isFinite(value)
+            ? ''
+            : formatNumber(value, wordsLocale(this), this.formatOptions);
+        return html `<slot name="label" part="label" @slotchange=${() => this.requestUpdate()}></slot>
+      ${figure === '' ? html `<slot part="value"></slot>` : html `<span part="value">${figure}</span>`}
+      <slot name="unit" part="unit" @slotchange=${this.readPieces}></slot>
+      <slot name="trend" part="trend" @slotchange=${this.readPieces}></slot>`;
     }
 };
 __decorate([
     property({ reflect: true })
 ], HelixHeadlessStat.prototype, "direction", void 0);
+__decorate([
+    property({ attribute: 'format-options', type: Object })
+], HelixHeadlessStat.prototype, "formatOptions", void 0);
+__decorate([
+    property()
+], HelixHeadlessStat.prototype, "locale", void 0);
+__decorate([
+    property({ type: Number })
+], HelixHeadlessStat.prototype, "value", void 0);
 HelixHeadlessStat = __decorate([
     customElement('helix-headless-stat')
 ], HelixHeadlessStat);