@fusion.dev/helix-headless 0.152.0 → 0.154.0

package/dist/scatter-chart/root/scatter-chart-root.d.ts

@@ -24,7 +24,7 @@ export interface ScatterField {
     y: [number, number];
     yNames: string[];
 }
-declare const HelixHeadlessScatterChart_base: typeof HelixElement & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinChartSourceInterface);
+declare const HelixHeadlessScatterChart_base: typeof HelixElement & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinChartSourceInterface) & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinChartStatusInterface);
 /**
  * @summary A chart that shows whether two measures move together, with one point per row.
  *
@@ -71,17 +71,32 @@ declare const HelixHeadlessScatterChart_base: typeof HelixElement & (new (...arg
  * tap or key, and `helix-reading-press` says a reading was clicked, tapped, or
  * pressed with Enter or Space, for a page that opens what a reading stands for.
  *
+ * **`data` takes the readings as data** where the page has no table to point
+ * `for` at, in a table's shape: the column headings, then one row per reading
+ * with its label first. A table is still the better source where the page can
+ * show one, since it reads before any script runs.
+ *
+ * **A chart with nothing to draw says so.** A table with no readings shows
+ * `empty-text`, "No readings", in the plot, and `loading` shows `loading-text`
+ * there until readings arrive. The `empty` and `loading` slots take markup in
+ * their place, such as a link to add the first reading.
+ *
  * @since 0.1.0
  * @status stable
  * @category charts
  * @aliases Scatter Plot, XY Chart, Correlation Chart, Dot Plot
  * @documentation https://fusion.dev/helix/components/scatter-chart
  *
+ * @slot empty - Content shown in place of the drawing when the table has no readings, such as a link to add the first. Falls back to `empty-text`.
+ * @slot loading - Content shown in place of the drawing while `loading` is set and there are no readings yet. Falls back to `loading-text`.
+ *
  * @event {HelixReadingChangeEvent} helix-reading-change - The reading shown moved, or was put away: `index` is the row, or `-1` for none, with its `label`, the `series` the keys rest on, and the `pointerType` that moved it.
  * @event {HelixReadingPressEvent} helix-reading-press - A reading was clicked, tapped, or pressed with Enter or Space, with the same detail as `helix-reading-change`.
  *
+ * @csspart empty - The words in place of the drawing when the table has no readings: the `empty` slot, falling back to `empty-text`. Not drawn while the table cannot be read yet, on the server and during hydration.
  * @csspart gridline - One line across the plot, drawn when `gridlines` is set.
  * @csspart live - The readout: a polite live region that says the row the keys moved to. Hide it visually.
+ * @csspart loading - The words in place of the drawing while `loading` is set and there are no readings: the `loading` slot, falling back to `loading-text`.
  * @csspart mark - The invisible point the tooltip is anchored to.
  * @csspart plane - The grid that holds the plot, both axes, and their names. It runs left to right on every page.
  * @csspart plot - The drawing, which takes focus to be read by key.

package/dist/scatter-chart/root/scatter-chart-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 { CHART_PLOT, customElement, drawTooltip, extent, formatNumbers, formatWords, HelixElement, HelixReadingChangeEvent, HelixReadingPressEvent, isRtl, linear, MixinChartSource, PLOT_HEIGHT, PLOT_WIDTH, seriesIndex, ticks, words, wordsLocale, } from '@fusion.dev/helix-core';
+import { CHART_PLOT, customElement, drawTooltip, extent, formatNumbers, formatWords, HelixElement, HelixReadingChangeEvent, HelixReadingPressEvent, isRtl, linear, MixinChartSource, MixinChartStatus, PLOT_HEIGHT, PLOT_WIDTH, seriesIndex, ticks, words, wordsLocale, } from '@fusion.dev/helix-core';
 import { html, nothing, svg } from 'lit';
 import { property } from 'lit/decorators.js';
 import '../../tooltip/index.js';
@@ -33,7 +33,7 @@ const nice = ([low, high]) => {
     const round = (value) => Number(value.toPrecision(12));
     return [round(Math.floor(low / step) * step), round(Math.ceil(high / step) * step)];
 };
-let HelixHeadlessScatterChart = class HelixHeadlessScatterChart extends MixinChartSource(HelixElement) {
+let HelixHeadlessScatterChart = class HelixHeadlessScatterChart extends MixinChartStatus(MixinChartSource(HelixElement)) {
     constructor() {
         super(...arguments);
         this.correlationLabel = 'correlation';
@@ -140,7 +140,7 @@ let HelixHeadlessScatterChart = class HelixHeadlessScatterChart extends MixinCha
         this.drawn = field.points;
         if (field.points.length === 0) {
             return html `<div dir="ltr" part="plane">
-        <div id=${CHART_PLOT} part="plot"></div>
+        <div id=${CHART_PLOT} part="plot">${this.renderStatus()}</div>
       </div>`;
         }
         const format = formatNumbers(wordsLocale(this));

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);