@fusion.dev/helix-headless 0.145.0 → 0.147.0

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

@@ -1,13 +1,13 @@
 import { HelixElement } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
 /**
- * The largest `max` a stylesheet can hide past.
+ * The largest `max` a stylesheet folds a server's markup at.
  *
- * The fold is `:host([max="N"]) ::slotted(:nth-child(n + N+1))`, one selector
+ * The rule is `:host([max="N"]) ::slotted(:nth-child(n + N+1))`, one selector
  * per value, because `An+B` takes a literal and no custom property can be read
- * into it. So the range is finite, and it is written down beside the count that
- * has to agree with it: a count that folds and a stylesheet that does not would
- * put a "+5" beside five avatars that are still on screen.
+ * into it. So the range a stylesheet covers is finite. The group folds any
+ * `max` itself once it runs, with the platform's `hidden`; past this one, a
+ * server's markup shows every avatar until the page hydrates.
  */
 export declare const FOLDS_UP_TO = 12;
 /**
@@ -21,9 +21,10 @@ export declare const FOLDS_UP_TO = 12;
  * hidden.
  *
  * Avatars past `max` stay in the DOM and are hidden. The group writes `hidden`
- * on each of them, so they are hidden on the headless tier as well, and the
- * count is read out as `overflow-label`, such as "3 more", so a screen reader
- * hears that there are more people than the ones it can reach.
+ * on each of them, so they are hidden on the headless tier as well, and at any
+ * `max`. The count is read out as `overflow-label`, such as "3 more: Grace
+ * Hopper, Alan Turing, Barbara Liskov", so a screen reader hears who is there
+ * past the ones it can reach.
  *
  * @since 0.1.0
  * @status stable
@@ -59,10 +60,11 @@ export declare class HelixHeadlessAvatarGroup extends HelixElement {
      */
     max?: number;
     /**
-     * What a screen reader is told the count is, with `{count}` for the number.
+     * What a screen reader is told the count is, with `{count}` for the number
+     * and `{names}` for the people it stands for, by each avatar's `name`.
      *
      * The count shows "+3", which reads as "plus three" and says nothing about
-     * what was counted.
+     * what was counted, nor who.
      */
     overflowLabel: string;
     /** The avatars this group hid, so it unhides only those. */
@@ -78,8 +80,6 @@ export declare class HelixHeadlessAvatarGroup extends HelixElement {
      * the attribute that hides the whole group.
      */
     get overflow(): number;
-    /** Said once per element, because a re-render is not a second mistake. */
-    private warned;
     protected willUpdate(changed: PropertyValues): void;
     protected firstUpdated(changed: PropertyValues): void;
     protected updated(changed: PropertyValues): void;
@@ -89,10 +89,16 @@ export declare class HelixHeadlessAvatarGroup extends HelixElement {
      * **State in markup, so the headless tier folds too.** The fold was a styled
      * rule alone, and on the headless tier every avatar was drawn beside a "+3".
      * The styled rule stays, because it is what folds a server's markup before
-     * this runs. Written through `whenHydrated`, so an avatar's hydrating render
-     * is the server's, and undone only on the avatars this group hid.
+     * this runs, up to `FOLDS_UP_TO`, and this folds at any `max`. Written
+     * through `whenHydrated`, so an avatar's hydrating render is the server's,
+     * and undone only on the avatars this group hid.
      */
     private fold;
+    /**
+     * The names of the people past `max`, by each avatar's `name`, then its
+     * `aria-label`, in the order they are read.
+     */
+    private foldedNames;
     protected render(): TemplateResult;
 }
 declare global {

package/dist/avatar/group/avatar-group.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, HelixElement, hostAria, reportRuntime, whenHydrated, } from '@fusion.dev/helix-core';
+import { customElement, fillTemplate, HelixElement, hostAria, whenHydrated, } from '@fusion.dev/helix-core';
 import { html } from 'lit';
 import { property } from 'lit/decorators.js';
 export const FOLDS_UP_TO = 12;
@@ -12,17 +12,15 @@ let HelixHeadlessAvatarGroup = class HelixHeadlessAvatarGroup extends HelixEleme
     constructor() {
         super(...arguments);
         this.label = '';
-        this.overflowLabel = '{count} more';
+        this.overflowLabel = '{count} more: {names}';
         this.folded = new WeakSet();
-        this.warned = false;
     }
     get avatars() {
         return this.knownChildren.filter((child) => child instanceof HTMLElement);
     }
     get overflow() {
         const limit = this.max ?? 0;
-        const limited = limit > 0 && limit <= FOLDS_UP_TO;
-        return limited ? Math.max(this.avatars.length - limit, 0) : 0;
+        return limit > 0 ? Math.max(this.avatars.length - limit, 0) : 0;
     }
     willUpdate(changed) {
         super.willUpdate(changed);
@@ -35,23 +33,11 @@ let HelixHeadlessAvatarGroup = class HelixHeadlessAvatarGroup extends HelixEleme
     updated(changed) {
         super.updated(changed);
         this.fold();
-        const limit = this.max ?? 0;
-        if (limit > FOLDS_UP_TO && this.avatars.length > limit && !this.warned) {
-            this.warned = true;
-            reportRuntime({
-                kind: 'max-past-fold',
-                message: `<${this.localName}> has max="${this.max}", past the ${FOLDS_UP_TO} the fold is written for, ` +
-                    'so every avatar is shown and none are counted. Lower `max`, or hand the group the ' +
-                    'avatars you want shown.',
-                tag: this.localName,
-            });
-        }
     }
     fold() {
         const limit = this.max ?? 0;
-        const limited = limit > 0 && limit <= FOLDS_UP_TO;
         for (const [index, avatar] of this.avatars.entries()) {
-            const past = limited && index >= limit;
+            const past = limit > 0 && index >= limit;
             if (past && !avatar.hidden) {
                 this.folded.add(avatar);
                 whenHydrated(avatar, () => {
@@ -66,6 +52,15 @@ let HelixHeadlessAvatarGroup = class HelixHeadlessAvatarGroup extends HelixEleme
             }
         }
     }
+    foldedNames() {
+        const limit = this.max ?? 0;
+        return this.avatars
+            .slice(limit)
+            .map((avatar) => avatar.name ||
+            avatar.getAttribute('aria-label') ||
+            '')
+            .filter(Boolean);
+    }
     render() {
         const past = this.overflow;
         return html `<slot @slotchange=${() => this.requestUpdate()}></slot>
@@ -73,7 +68,10 @@ let HelixHeadlessAvatarGroup = class HelixHeadlessAvatarGroup extends HelixEleme
             ? html `<span
               part="overflow"
               role="img"
-              aria-label=${this.overflowLabel.replace('{count}', String(past))}
+              aria-label=${fillTemplate(this.overflowLabel, {
+                count: String(past),
+                names: this.foldedNames().join(', '),
+            }).replace(/[\s:,]+$/, '')}
               >+${past}</span
             >`
             : ''}`;

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

@@ -15,7 +15,16 @@ export declare const initialsOf: (name: string) => string;
  * a person's name does not describe what the avatar stands for.
  *
  * `load` and `error` are re-dispatched from the host, because they are not
- * composed and would otherwise stop at the shadow boundary.
+ * composed and would otherwise stop at the shadow boundary. `status` says
+ * which of the two happened, for a listener that arrives after it, and the
+ * `loading`, `loaded` and `error` custom states say the same to a stylesheet.
+ *
+ * **On a server the avatar sends the picture's place**, an `<img>` that the
+ * browser fetches while it reads the page. The initials stand in only on the
+ * client: at once where the picture failed before the page hydrated, and after
+ * `fallback-delay` where it is still on its way. `load` or `error` for a
+ * picture that settled before hydration is sent a task after the avatar
+ * hydrates, so a page's own scripts are listening by then.
  *
  * @since 0.1.0
  * @status stable
@@ -30,6 +39,10 @@ export declare const initialsOf: (name: string) => string;
  *
  * @csspart image - The image, when one is loading or loaded.
  * @csspart initials - The initials shown when there is no usable image.
+ *
+ * @cssstate error - The picture failed, or there is none, and the initials show.
+ * @cssstate loaded - The picture arrived.
+ * @cssstate loading - The picture is on its way.
  */
 export declare class HelixHeadlessAvatar extends HelixElement {
     /**
@@ -43,6 +56,23 @@ export declare class HelixHeadlessAvatar extends HelixElement {
      * same idea.
      */
     fallbackDelay?: number;
+    /**
+     * The letters shown where no picture loaded, such as `GH`, in place of the
+     * ones taken from `name`.
+     *
+     * For a name whose initials are not its first and last letters, or an
+     * entity with a short mark of its own. Absent, the first letters of the
+     * first and last words of `name` are shown.
+     */
+    initials?: string;
+    /**
+     * When the browser fetches the picture: `lazy` waits until it is near the
+     * screen, as an `<img loading="lazy">` does, and `eager` fetches it at once.
+     *
+     * Absent is the browser's own default, which is `eager`. `lazy` suits a long
+     * list of people, most of them off screen.
+     */
+    loading?: 'eager' | 'lazy';
     /**
      * Name of the person or entity.
      *

package/dist/avatar/root/avatar-root.js

@@ -45,6 +45,9 @@ let HelixHeadlessAvatar = class HelixHeadlessAvatar extends HelixElement {
             label: this.name,
             role: this.name === '' ? '' : 'img',
         });
+        this.toggleState('error', this.status === 'error');
+        this.toggleState('loaded', this.status === 'loaded');
+        this.toggleState('loading', this.status === 'loading');
     }
     firstUpdated(changed) {
         super.firstUpdated(changed);
@@ -91,6 +94,7 @@ let HelixHeadlessAvatar = class HelixHeadlessAvatar extends HelixElement {
           part="image"
           src=${this.src}
           alt=""
+          loading=${this.loading ?? nothing}
           ?hidden=${standIn}
           @error=${this.handleError}
           @load=${this.handleLoad}
@@ -100,13 +104,19 @@ let HelixHeadlessAvatar = class HelixHeadlessAvatar extends HelixElement {
     }
     renderInitials() {
         return html `<slot>
-      <span part="initials" aria-hidden="true">${initialsOf(this.name)}</span>
+      <span part="initials" aria-hidden="true">${this.initials ?? initialsOf(this.name)}</span>
     </slot>`;
     }
 };
 __decorate([
     property({ attribute: 'fallback-delay', type: Number })
 ], HelixHeadlessAvatar.prototype, "fallbackDelay", void 0);
+__decorate([
+    property()
+], HelixHeadlessAvatar.prototype, "initials", void 0);
+__decorate([
+    property()
+], HelixHeadlessAvatar.prototype, "loading", void 0);
 __decorate([
     property()
 ], HelixHeadlessAvatar.prototype, "name", void 0);

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

@@ -1,5 +1,5 @@
 import { HelixElement } from '@fusion.dev/helix-core';
-import { type TemplateResult } from 'lit';
+import { type PropertyValues, type TemplateResult } from 'lit';
 /**
  * @summary A count or a dot pinned to the corner of another element.
  *
@@ -14,15 +14,20 @@ import { type TemplateResult } from 'lit';
  * - Any other value shows the value. Above `max`, the indicator shows `{max}+`,
  *   so its width stays the same as the count grows.
  *
+ * `format-options` writes a count with `Intl.NumberFormat`, in `locale`:
+ * `format-options='{"notation":"compact"}'` shows 1,200 as `1.2K`. Absent, the
+ * count is shown as it was given.
+ *
  * A count is announced from its own text, and `label` replaces that with a
  * fuller name, such as `4 unread`. A dot needs a `label`. Without one, the dot
  * is a colored circle that screen readers do not announce.
  *
- * **A badge wrapped around a control is not part of the control's name.** It
- * is a status of its own, read when it changes and when a reader moves to it,
- * so focusing a button inside a badge announces the button's name alone. A
- * reference from the control to the count would point into the badge's shadow
- * root, which the platform does not allow.
+ * **A badge wrapped around a control describes it.** The control is the first
+ * element in the badge that takes focus, and its description is the badge's
+ * words, so focusing `<helix-badge value="8" label="{count} unread"><button>Inbox
+ * </button></helix-badge>` announces "Inbox, button, 8 unread", current as the
+ * count changes. A control that already has a description keeps its own. The
+ * count is also a status of its own, read when it changes.
  *
  * **Put the badge inside the control to have its count read with the
  * control's name**, as Web Awesome and Shoelace do: `<button>Inbox
@@ -39,14 +44,34 @@ import { type TemplateResult } from 'lit';
  * @slot - The element being decorated.
  *
  * @csspart indicator - The count, or the dot when there is no value.
+ *
+ * @cssstate blank - The value is zero, so there is no mark.
+ * @cssstate capped - The count is past `max`, so the mark shows `{max}+`.
+ * @cssstate dot - There is no value, so the mark is a dot.
  */
 export declare class HelixHeadlessBadge extends HelixElement {
+    /**
+     * `Intl.NumberFormat` options a count is written with, such as
+     * `{"notation":"compact"}` for `1.2K`, written as JSON in the attribute.
+     *
+     * Absent, a count is shown as it was given. Text that is not a number is
+     * shown as it is either way.
+     */
+    formatOptions?: Intl.NumberFormatOptions;
     /**
      * The badge's name, read by screen readers.
      *
-     * Required for a dot, which has no text to read.
+     * Required for a dot, which has no text to read. `{count}` is replaced with
+     * what the badge shows, so `label="{count} unread"` reads "8 unread" and
+     * stays current as `value` changes, with no label of yours to keep in step.
      */
     label: string;
+    /**
+     * The locale a count is written in under `format-options`, such as `de`.
+     *
+     * Absent uses the runtime's own.
+     */
+    locale: string;
     /**
      * The largest number the badge shows.
      *
@@ -73,8 +98,36 @@ export declare class HelixHeadlessBadge extends HelixElement {
     private get given();
     /** Whether the value counts nothing, in which case there is no mark. */
     private get blank();
+    /** Whether the count is past `max`, which the mark shows as `{max}+`. */
+    private get capped();
     /** What the indicator reads, once the cap has been applied. */
     private get text();
+    /** What a reader hears for the mark, or nothing for a blank or unnamed one. */
+    private get words();
+    /** The control the badge describes, while it describes one. */
+    private described;
+    /**
+     * The first element the badge wraps that takes focus: one with a tab stop,
+     * or a component that hands its focus on.
+     */
+    private wrapped;
+    protected firstUpdated(changed: PropertyValues): void;
+    /**
+     * Points the wrapped control's description at the badge, which carries its
+     * words as its own label, or takes the pointer back.
+     *
+     * **The badge itself and not the count**, because a reference from the
+     * control into the badge's shadow root is one the platform drops, and the
+     * badge is in the control's own tree. A control the page described is left
+     * alone.
+     */
+    private describe;
+    private undescribe;
+    private readonly handleSlotchange;
+    disconnectedCallback(): void;
+    connectedCallback(): void;
+    protected willUpdate(changed: PropertyValues): void;
+    protected updated(changed: PropertyValues): void;
     protected render(): TemplateResult;
 }
 declare global {

package/dist/badge/root/badge-root.js

@@ -4,14 +4,18 @@ 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 } from '@fusion.dev/helix-core';
+import { customElement, fillTemplate, formatNumber, HelixElement } from '@fusion.dev/helix-core';
 import { html, nothing } from 'lit';
 import { property } from 'lit/decorators.js';
 let HelixHeadlessBadge = class HelixHeadlessBadge extends HelixElement {
     constructor() {
         super(...arguments);
         this.label = '';
+        this.locale = '';
         this.value = '';
+        this.handleSlotchange = () => {
+            this.describe();
+        };
     }
     get given() {
         return String(this.value ?? '');
@@ -19,31 +23,110 @@ let HelixHeadlessBadge = class HelixHeadlessBadge extends HelixElement {
     get blank() {
         return this.given.trim() !== '' && Number(this.given) === 0;
     }
+    get capped() {
+        const count = Number(this.given);
+        return this.max !== undefined && Number.isFinite(count) && count > this.max;
+    }
     get text() {
+        const write = (count) => this.formatOptions ? formatNumber(count, this.locale, this.formatOptions) : String(count);
+        if (this.capped) {
+            return `${write(this.max)}+`;
+        }
         const count = Number(this.given);
-        if (this.max !== undefined && Number.isFinite(count) && count > this.max) {
-            return `${this.max}+`;
+        return this.formatOptions && this.given.trim() !== '' && Number.isFinite(count)
+            ? write(count)
+            : this.given;
+    }
+    get words() {
+        const text = this.text;
+        if (this.blank || (text === '' && this.label === '')) {
+            return '';
+        }
+        return fillTemplate(this.label, { count: text }) || text;
+    }
+    wrapped() {
+        const found = this.renderRoot
+            .querySelector('slot:not([name])')
+            ?.assignedElements({ flatten: true })
+            .find((element) => element instanceof HTMLElement &&
+            (element.tabIndex >= 0 || element.shadowRoot?.delegatesFocus === true));
+        const inner = found?.shadowRoot?.delegatesFocus
+            ? found.shadowRoot.querySelector('a[href], button, input, select, textarea')
+            : null;
+        return inner ?? found;
+    }
+    firstUpdated(changed) {
+        super.firstUpdated(changed);
+        requestAnimationFrame(() => this.describe());
+    }
+    describe() {
+        const words = this.words;
+        const control = words === '' ? undefined : this.wrapped();
+        if (this.described && this.described !== control) {
+            this.undescribe();
+        }
+        if (!control || !('ariaDescribedByElements' in control)) {
+            return;
+        }
+        const own = control.getAttribute('aria-describedby') || control.ariaDescribedByElements?.length;
+        if (control !== this.described && own) {
+            return;
         }
-        return this.given;
+        this.internals.ariaLabel = words;
+        control.ariaDescribedByElements = [this];
+        this.described = control;
+    }
+    undescribe() {
+        if (this.described?.ariaDescribedByElements?.includes(this)) {
+            this.described.ariaDescribedByElements = null;
+        }
+        this.described = undefined;
+        this.internals.ariaLabel = null;
+    }
+    disconnectedCallback() {
+        super.disconnectedCallback();
+        this.undescribe();
+    }
+    connectedCallback() {
+        super.connectedCallback();
+        if (this.hasUpdated) {
+            this.describe();
+        }
+    }
+    willUpdate(changed) {
+        super.willUpdate(changed);
+        this.toggleState('capped', this.capped);
+        this.toggleState('dot', this.given.trim() === '');
+        this.toggleState('blank', this.blank);
+    }
+    updated(changed) {
+        super.updated(changed);
+        this.describe();
     }
     render() {
         const blank = this.blank;
         const text = this.text;
         const announced = !blank && (text !== '' || this.label !== '');
-        return html `<slot></slot>
+        return html `<slot @slotchange=${this.handleSlotchange}></slot>
       <span
         part="indicator"
         data-blank=${blank ? '' : nothing}
         data-single=${text.length <= 1 ? '' : nothing}
         role="status"
-        aria-label=${announced ? this.label || text : nothing}
+        aria-label=${announced ? fillTemplate(this.label, { count: text }) || text : nothing}
         >${blank ? html `<span aria-hidden="true">${text}</span>` : text}</span
       >`;
     }
 };
+__decorate([
+    property({ attribute: 'format-options', type: Object })
+], HelixHeadlessBadge.prototype, "formatOptions", void 0);
 __decorate([
     property()
 ], HelixHeadlessBadge.prototype, "label", void 0);
+__decorate([
+    property()
+], HelixHeadlessBadge.prototype, "locale", void 0);
 __decorate([
     property({ type: Number })
 ], HelixHeadlessBadge.prototype, "max", void 0);

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

@@ -176,6 +176,17 @@ export declare class HelixHeadlessBarChart extends HelixHeadlessBarChart_base {
      * of any scale question the picture raises.
      */
     secondary?: string;
+    /**
+     * Stacks a category's columns into one, each series standing on the ones
+     * before it, so the column's height is the category's total.
+     *
+     * Absent stands them side by side, as it always did. A negative reading
+     * hangs below zero on the negatives before it, so neither direction hides
+     * the other. The scale fits the stacks. A series
+     * in `lines` is still a line, measured on its own reading; columns on the
+     * second scale stack among themselves.
+     */
+    stacked: boolean;
     /** The series names on the second scale, lowercased and trimmed. */
     private get scaled();
     /** The series names drawn as a line, lowercased and trimmed for matching. */
@@ -204,7 +215,8 @@ export declare class HelixHeadlessBarChart extends HelixHeadlessBarChart_base {
      *
      * The highest, because which category leads is the question a bar chart is
      * read for, and the table beside it has every other number. The reading is
-     * written the way the table writes it, such as `$128k` for `128000`.
+     * written the way the table writes it, such as `$128k` for `128000`. A
+     * series a legend hid is not drawn and is not said.
      */
     protected renderSummary(series: Series[]): TemplateResult;
     /**
@@ -214,6 +226,11 @@ export declare class HelixHeadlessBarChart extends HelixHeadlessBarChart_base {
      * and a screen reader hearing both hears the same numbers twice.
      */
     protected renderPlot(series: Series[], categories: string[], y: (value: number) => number, domain: [number, number], floor: number, z?: (value: number) => number): TemplateResult;
+    /**
+     * One category's columns stacked into one, each on the ones before it on
+     * its own scale, through the pure `stackSpans`.
+     */
+    private renderStack;
     /**
      * The numbers along one scale, drawn only where there are two of them.
      *