@fusion.dev/helix-headless 0.146.0 → 0.147.0

package/dist/accordion/item/accordion-item.d.ts

@@ -13,20 +13,22 @@ declare const HelixHeadlessAccordionItem_base: (new (...args: any[]) => import("
  * accordion's, then 3.
  *
  * Content stays mounted when the item is closed, so it can animate and its text
- * is present in server-rendered HTML. Closed content has both `hidden` and
- * `inert`. `hidden` collapses it when no stylesheet is loaded. `inert` keeps it
- * out of the tab order and the accessibility tree after the styled tier's
- * `display` overrides `hidden`.
+ * is present in server-rendered HTML.
+ *
+ * The browser's find in page searches a closed section, and a match opens it,
+ * with `helix-before-open` first, as React Aria's disclosure does. Closed
+ * content is `hidden="until-found"`, which hides it with no stylesheet loaded
+ * and keeps it out of the tab order and the accessibility tree. A section
+ * that closes keeps its content drawn until the content part's animations and
+ * transitions end, so a sheet that animates the section closed shows the
+ * content shrinking rather than an empty box. Set `hidden-until-found="false"`
+ * and a closed section is `hidden` and `inert` instead, and find in page skips
+ * it.
  *
  * While it is open, the content part carries the content's height as
  * `--accordion-content-height`, as Radix's accordion does, for a stylesheet
  * that animates the section open with keyframes of its own.
  *
- * Set `hidden-until-found` and the browser's find in page searches a closed
- * section too: a match opens it, with `helix-before-open` first, as React
- * Aria's disclosure does. The content is then `hidden="until-found"` while
- * closed, and not `inert`, since an inert region is never searched.
- *
  * @since 0.1.0
  * @status stable
  * @aliases Collapsible, Expander, Disclosure
@@ -97,12 +99,11 @@ export declare class HelixHeadlessAccordionItem extends HelixHeadlessAccordionIt
      * Whether find in page searches the section while it is closed, and opens it
      * on a match.
      *
-     * Off by default. A closed section is then `hidden="until-found"`, which
-     * hides through `content-visibility`, so a stylesheet that animates the
-     * section closed shows an empty box for the length of that animation. The
-     * accordion's own `hidden-until-found` turns it on for every section.
+     * Unset takes the accordion's `hidden-until-found`, which is on. Write
+     * `hidden-until-found="false"` to keep find in page out of this section: a
+     * closed section is then `hidden` and `inert`.
      */
-    hiddenUntilFound: boolean;
+    hiddenUntilFound?: boolean;
     /**
      * A group name. Opening an item closes the other items with the same name,
      * as `<details name>` does.
@@ -126,6 +127,24 @@ export declare class HelixHeadlessAccordionItem extends HelixHeadlessAccordionIt
     name?: string;
     /** Whether find in page searches this section while it is closed. */
     private get findable();
+    /**
+     * Whether the section has closed and its content is still drawn, until the
+     * content part's animations end.
+     *
+     * `hidden="until-found"` hides through `content-visibility`, which an
+     * author's `display` does not override, so writing it the moment the section
+     * closes empties the box a sheet is still shrinking. `inert` holds the
+     * content meanwhile.
+     */
+    private closing;
+    protected willUpdate(changed: PropertyValues): void;
+    /**
+     * Hides the content of a section that closed, once whatever animates the
+     * content part has finished. Nothing running, as under reduced motion or
+     * with no stylesheet, hides it at once. `getAnimations` brings the styles up
+     * to date first, so a transition the close starts is among them.
+     */
+    private finishClosing;
     /**
      * Opens the section find in page has matched in, before the match is shown.
      *
@@ -204,13 +223,13 @@ export declare class HelixHeadlessAccordionItem extends HelixHeadlessAccordionIt
      * part outranks it and the transition runs exactly as before. Measured on
      * both tiers.
      *
-     * **`hidden="until-found"` only where it was asked for.** It hides through
+     * **`hidden="until-found"` unless it is turned off.** It hides through
      * `content-visibility` rather than `display`, which an author `display` does
-     * not override, so a section a sheet animates closed shows an empty box while
-     * it shrinks. `beforematch` sets `open`, so find in page never reveals text
-     * under a trigger that still reports collapsed.
+     * not override, so it is written only once the section's closing motion has
+     * ended (`closing`). `beforematch` sets `open`, so find in page never reveals
+     * text under a trigger that still reports collapsed.
      *
-     * `inert` stays, except under `until-found`. `hidden` answers the reader who
+     * `inert` only where `until-found` is not. `hidden` answers the reader who
      * can see and `inert` answers the one tabbing through, and wherever a sheet
      * overrides `display`, `inert` is the only one of the two still in force.
      * `content-visibility: hidden` keeps skipped content out of the tab order and

package/dist/accordion/item/accordion-item.js

@@ -4,10 +4,10 @@ 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 { closestInstance, customElement, HelixElement, headingLevel, MixinControllerOpen, } from '@fusion.dev/helix-core';
+import { closestInstance, customElement, HelixElement, headingLevel, MixinControllerOpen, onUnlessFalse, } from '@fusion.dev/helix-core';
 import { caretDown } from '@fusion.dev/helix-icons';
 import { html, nothing } from 'lit';
-import { property } from 'lit/decorators.js';
+import { property, state } from 'lit/decorators.js';
 import { unsafeSVG } from 'lit/directives/unsafe-svg.js';
 import { HelixHeadlessAccordion } from '../root/accordion-root.js';
 const CONTENT_ID = 'content';
@@ -17,8 +17,8 @@ let HelixHeadlessAccordionItem = class HelixHeadlessAccordionItem extends MixinC
         super(...arguments);
         this.disabled = false;
         this.groupHeadingLevel = undefined;
-        this.groupHiddenUntilFound = false;
-        this.hiddenUntilFound = false;
+        this.groupHiddenUntilFound = true;
+        this.closing = false;
         this.handleBeforeMatch = (event) => {
             if (this.open || this.requestOpen(true)) {
                 return;
@@ -63,7 +63,22 @@ let HelixHeadlessAccordionItem = class HelixHeadlessAccordionItem extends MixinC
     >`;
     }
     get findable() {
-        return this.hiddenUntilFound || this.groupHiddenUntilFound;
+        return this.hiddenUntilFound ?? this.groupHiddenUntilFound;
+    }
+    willUpdate(changed) {
+        super.willUpdate(changed);
+        if (changed.has('open')) {
+            this.closing = !this.open && changed.get('open') === true && this.findable;
+        }
+    }
+    finishClosing() {
+        const running = this.partNamed('content')?.getAnimations?.({ subtree: true }) ?? [];
+        const done = () => {
+            if (!this.open) {
+                this.closing = false;
+            }
+        };
+        Promise.all(running.map((animation) => animation.finished)).then(done, done);
     }
     get accordion() {
         return closestInstance(this, HelixHeadlessAccordion);
@@ -96,6 +111,9 @@ let HelixHeadlessAccordionItem = class HelixHeadlessAccordionItem extends MixinC
         if (this.wasOpen === false && this.open) {
             this.closePeers();
         }
+        if (changed.has('closing') && this.closing) {
+            this.finishClosing();
+        }
         this.wasOpen = this.open;
         this.measure();
     }
@@ -104,7 +122,8 @@ let HelixHeadlessAccordionItem = class HelixHeadlessAccordionItem extends MixinC
     }
     render() {
         const open = this.open;
-        const landmark = open || !this.findable;
+        const shown = open || this.closing;
+        const landmark = shown || !this.findable;
         const level = headingLevel(this.headingLevel ?? this.groupHeadingLevel);
         return html `
       <div part="container">
@@ -127,8 +146,8 @@ let HelixHeadlessAccordionItem = class HelixHeadlessAccordionItem extends MixinC
           id=${CONTENT_ID}
           aria-labelledby=${landmark ? TRIGGER_ID : nothing}
           part="content"
-          hidden=${open ? nothing : this.findable ? 'until-found' : ''}
-          ?inert=${!open && !this.findable}
+          hidden=${shown ? nothing : this.findable ? 'until-found' : ''}
+          ?inert=${!open && (this.closing || !this.findable)}
           role=${landmark ? 'region' : nothing}
           @beforematch=${this.handleBeforeMatch}
         >
@@ -156,11 +175,14 @@ __decorate([
     property({ attribute: 'heading-level', type: Number })
 ], HelixHeadlessAccordionItem.prototype, "headingLevel", void 0);
 __decorate([
-    property({ attribute: 'hidden-until-found', type: Boolean })
+    property({ attribute: 'hidden-until-found', converter: onUnlessFalse })
 ], HelixHeadlessAccordionItem.prototype, "hiddenUntilFound", void 0);
 __decorate([
     property({ reflect: true })
 ], HelixHeadlessAccordionItem.prototype, "name", void 0);
+__decorate([
+    state()
+], HelixHeadlessAccordionItem.prototype, "closing", void 0);
 HelixHeadlessAccordionItem = __decorate([
     customElement('helix-headless-accordion-item')
 ], HelixHeadlessAccordionItem);

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

@@ -27,6 +27,9 @@ import { HelixHeadlessAccordionItem } from '../item/accordion-item.js';
  * in a screen reader's list of headings. An open section is a region named by
  * its trigger. Set the level that fits the page's outline.
  *
+ * Find in page searches the closed sections too, and opens the one it matches
+ * in. `hidden-until-found="false"` turns that off.
+ *
  * @since 0.1.0
  * @status stable
  * @category layout
@@ -44,8 +47,11 @@ export declare class HelixHeadlessAccordion extends HelixElement {
     headingLevel?: number;
     /**
      * Whether find in page searches every closed section, and opens the one it
-     * matches in. Each item's own `hidden-until-found` turns it on for that item
-     * alone.
+     * matches in.
+     *
+     * On by default, as in React Aria's disclosure. Write
+     * `hidden-until-found="false"` to turn it off for every section; an item's
+     * own `hidden-until-found` wins for that item.
      */
     hiddenUntilFound: boolean;
     /**

package/dist/accordion/root/accordion-root.js

@@ -4,7 +4,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
-import { customElement, HelixElement, KeyboardNavigationController, whenHydrated, } from '@fusion.dev/helix-core';
+import { customElement, HelixElement, KeyboardNavigationController, onUnlessFalse, whenHydrated, } from '@fusion.dev/helix-core';
 import { html } from 'lit';
 import { property } from 'lit/decorators.js';
 import { HelixHeadlessAccordionItem } from '../item/accordion-item.js';
@@ -18,7 +18,7 @@ const navigable = (item) => ({
 let HelixHeadlessAccordion = class HelixHeadlessAccordion extends HelixElement {
     constructor() {
         super(...arguments);
-        this.hiddenUntilFound = false;
+        this.hiddenUntilFound = true;
         this.keys = new KeyboardNavigationController(this, {
             items: () => this.items.map(navigable),
             origin: 'focus',
@@ -71,7 +71,7 @@ __decorate([
     property({ attribute: 'heading-level', type: Number })
 ], HelixHeadlessAccordion.prototype, "headingLevel", void 0);
 __decorate([
-    property({ attribute: 'hidden-until-found', type: Boolean })
+    property({ attribute: 'hidden-until-found', converter: onUnlessFalse })
 ], HelixHeadlessAccordion.prototype, "hiddenUntilFound", void 0);
 __decorate([
     property({ reflect: true })

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

@@ -31,8 +31,11 @@ declare const HelixHeadlessAnnouncement_base: (new (...args: any[]) => import("@
  *
  * Set `duration` to dismiss it after a time. The clock stops while the pointer
  * or focus is on the announcement, and continues from what was left, so a
- * reader partway through is not cut off. When the time runs out it sends
- * `helix-dismiss`, as the button does.
+ * reader partway through is not cut off. It stops while the page is hidden too,
+ * in another tab or a minimized window, so the message is not spent where
+ * nobody can see it. While the clock is stopped the announcement carries
+ * `:state(paused)`. When the time runs out it sends `helix-dismiss`, as the
+ * button does.
  *
  * @since 0.1.0
  * @status stable
@@ -42,15 +45,18 @@ declare const HelixHeadlessAnnouncement_base: (new (...args: any[]) => import("@
  *
  * @slot - The message.
  * @slot actions - Actions for the message, usually a link or a button.
- * @slot icon - Replaces the icon inside the dismiss button.
+ * @slot dismiss-icon - Replaces the cross inside the dismiss button, as `Callout`'s slot of the same name does.
+ * @slot icon - Replaces the cross inside the dismiss button. Deprecated: use `dismiss-icon`, which is read first.
  *
  * @event {HelixDismissEvent} helix-dismiss - The dismiss button was pressed, or `duration` ran out. The announcement does not remove itself, so remove it in response. Cancelable.
  *
  * @csspart actions - The region after the message that holds the actions.
  * @csspart content - The region that holds the message.
  * @csspart dismiss - The button that dismisses the announcement.
- * @csspart dismiss-mark - The icon on the dismiss button, shown when the `icon` slot is empty.
+ * @csspart dismiss-mark - The cross on the dismiss button, shown when the `dismiss-icon` and `icon` slots are empty.
  * @csspart live - A copy of the message in a live region, read by screen readers when the announcement appears after the page has loaded, and emptied seven seconds later. Visually hidden in the styled tier.
+ *
+ * @cssstate paused - The clock `duration` started is stopped, while the pointer or focus is on the announcement or the page is hidden.
  */
 export declare class HelixHeadlessAnnouncement extends HelixHeadlessAnnouncement_base {
     /**
@@ -87,6 +93,9 @@ export declare class HelixHeadlessAnnouncement extends HelixHeadlessAnnouncement
     protected readonly arrival: ArrivalController;
     /** The time `duration` gives it, held while a reader is on it. */
     private readonly countdown;
+    /** Whether the page being hidden is one of the reasons the clock is held. */
+    private heldHidden;
+    private readonly handleVisibility;
     private readonly handleHold;
     private readonly handleRelease;
     connectedCallback(): void;

package/dist/announcement/root/announcement-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 { ArrivalController, CountdownController, customElement, HelixElement, MixinDismissible, markRegion, slottedWords, } from '@fusion.dev/helix-core';
+import { ArrivalController, CountdownController, customElement, HelixElement, MixinDismissible, markRegion, reportRuntime, slottedWords, } from '@fusion.dev/helix-core';
 import { x } from '@fusion.dev/helix-icons';
 import { html, nothing } from 'lit';
 import { property } from 'lit/decorators.js';
@@ -20,7 +20,21 @@ let HelixHeadlessAnnouncement = class HelixHeadlessAnnouncement extends MixinDis
             done: () => {
                 this.dismiss();
             },
+            paused: (paused) => {
+                this.toggleState('paused', paused);
+            },
         });
+        this.heldHidden = false;
+        this.handleVisibility = () => {
+            if (document.hidden && !this.heldHidden) {
+                this.heldHidden = true;
+                this.countdown.hold();
+            }
+            else if (!document.hidden && this.heldHidden) {
+                this.heldHidden = false;
+                this.countdown.release();
+            }
+        };
         this.handleHold = () => {
             this.countdown.hold();
         };
@@ -34,8 +48,10 @@ let HelixHeadlessAnnouncement = class HelixHeadlessAnnouncement extends MixinDis
         this.addEventListener('mouseleave', this.handleRelease);
         this.addEventListener('focusin', this.handleHold);
         this.addEventListener('focusout', this.handleRelease);
+        document.addEventListener('visibilitychange', this.handleVisibility);
         if (this.hasUpdated) {
             this.countdown.resume();
+            this.handleVisibility();
         }
     }
     disconnectedCallback() {
@@ -44,10 +60,20 @@ let HelixHeadlessAnnouncement = class HelixHeadlessAnnouncement extends MixinDis
         this.removeEventListener('mouseleave', this.handleRelease);
         this.removeEventListener('focusin', this.handleHold);
         this.removeEventListener('focusout', this.handleRelease);
+        document.removeEventListener('visibilitychange', this.handleVisibility);
+        this.heldHidden = false;
     }
     firstUpdated(changed) {
         super.firstUpdated(changed);
         this.countdown.start(this.duration);
+        this.handleVisibility();
+        if (this.querySelector(':scope > [slot="icon"]')) {
+            reportRuntime({
+                kind: 'deprecated',
+                message: `<${this.localName}>'s \`icon\` slot is deprecated: slot the glyph as \`dismiss-icon\`, the name Callout uses.`,
+                tag: this.localName,
+            });
+        }
     }
     updated(changed) {
         super.updated(changed);
@@ -57,11 +83,13 @@ let HelixHeadlessAnnouncement = class HelixHeadlessAnnouncement extends MixinDis
         markRegion(this.renderRoot, 'actions', ['actions']);
     }
     renderDismissIcon() {
-        return html `<slot name="icon">
-      <svg part="dismiss-mark" viewBox=${x.viewBox} fill="currentColor" aria-hidden="true">
-        ${unsafeSVG(x.content)}
-      </svg>
-    </slot>`;
+        return html `<slot name="dismiss-icon"
+      ><slot name="icon">
+        <svg part="dismiss-mark" viewBox=${x.viewBox} fill="currentColor" aria-hidden="true">
+          ${unsafeSVG(x.content)}
+        </svg>
+      </slot></slot
+    >`;
     }
     render() {
         return html `<div aria-hidden=${this.arrival.said === '' ? nothing : 'true'} part="content"

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

@@ -5,7 +5,10 @@ import '../../tooltip/index.js';
 export interface AreaStack {
     /** The table's columns that hold numbers, by their place among its cells. */
     columns: number[];
-    /** Each column's running sum at each reading, the top edge of its band. */
+    /**
+     * Each column's top edge at each reading: its running sum, or its own
+     * reading under `overlap`.
+     */
     layers: number[][];
     /** Each column's heading. */
     names: string[];
@@ -44,6 +47,11 @@ declare const HelixHeadlessAreaChart_base: typeof HelixElement & (new (...args:
  * bands show each part's share. Use it to see which part grew. The default
  * shows whether the total grew.
  *
+ * `overlap` draws every band from zero, one in front of another, so each
+ * part's own amount is its height: the first column is in front. Use it to
+ * compare the parts with each other; the scale then fits the largest part
+ * rather than the total.
+ *
  * The drawing is hidden from screen readers. The text summary gives the latest
  * reading's total and each part's share of it, and the table beside the chart
  * has every number.
@@ -121,6 +129,15 @@ export declare class HelixHeadlessAreaChart extends HelixHeadlessAreaChart_base
      * a rule nobody sees.
      */
     gridlines?: 'both' | 'category' | 'value';
+    /**
+     * Draws every band from zero, in front of the next, so a band's height is
+     * its own part's amount and not its place in a stack.
+     *
+     * Absent stacks the parts, so the top edge is the total. Set, the first
+     * column is in front and the scale fits the largest part. Reflected, because
+     * the styled tier lets the bands behind show through the ones in front.
+     */
+    overlap: boolean;
     /**
      * Draws each reading as a hundred percent, so each band shows its share of
      * the total.

package/dist/area-chart/root/area-chart-root.js

@@ -23,6 +23,7 @@ const percentIn = (locale) => {
 let HelixHeadlessAreaChart = class HelixHeadlessAreaChart extends MixinChartSource(HelixElement) {
     constructor() {
         super(...arguments);
+        this.overlap = false;
         this.share = false;
         this.totalLabel = 'Total';
         this.warnedAboutNegatives = false;
@@ -57,7 +58,7 @@ let HelixHeadlessAreaChart = class HelixHeadlessAreaChart extends MixinChartSour
         const layers = [];
         let running = rows.map(() => 0);
         for (const column of drawn) {
-            running = running.map((sum, index) => sum + (column[index] ?? 0));
+            running = this.overlap ? column : running.map((sum, index) => sum + (column[index] ?? 0));
             layers.push(running);
         }
         return {
@@ -88,7 +89,11 @@ let HelixHeadlessAreaChart = class HelixHeadlessAreaChart extends MixinChartSour
         if (rows.length === 0 || stack.columns.length === 0) {
             return html `<div id=${CHART_PLOT} part="plot"></div>`;
         }
-        const top = this.share ? 1 : Math.max(0, ...stack.totals);
+        const top = this.overlap
+            ? Math.max(0, ...stack.layers.flat())
+            : this.share
+                ? 1
+                : Math.max(0, ...stack.totals);
         const domain = [0, top > 0 ? top : 1];
         const y = linear(domain, [PLOT_HEIGHT, 0]);
         const slot = PLOT_WIDTH / rows.length;
@@ -213,7 +218,7 @@ let HelixHeadlessAreaChart = class HelixHeadlessAreaChart extends MixinChartSour
         return drawTooltip(rows, at, this.tag('tooltip'), {
             placement: 'top',
             x: `${at * slot + slot / 2}%`,
-            y: `${y(stack.layers.at(-1)?.[at] ?? 0)}%`,
+            y: `${y(Math.max(0, ...stack.layers.map((layer) => layer[at] ?? 0)))}%`,
         }, (cell) => this.seriesOf(cell), this.pointer);
     }
 };
@@ -223,6 +228,9 @@ __decorate([
 __decorate([
     property()
 ], HelixHeadlessAreaChart.prototype, "gridlines", void 0);
+__decorate([
+    property({ reflect: true, type: Boolean })
+], HelixHeadlessAreaChart.prototype, "overlap", void 0);
 __decorate([
     property({ reflect: true, type: Boolean })
 ], HelixHeadlessAreaChart.prototype, "share", void 0);

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,8 +44,20 @@ 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.
      *
@@ -49,6 +66,12 @@ export declare class HelixHeadlessBadge extends HelixElement {
      * 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.
      *
@@ -75,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 {