@fusion.dev/helix-headless 0.143.0 → 0.145.0

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

@@ -1,5 +1,5 @@
 import { HelixElement } from '@fusion.dev/helix-core';
-import { type PropertyValues, type TemplateResult } from 'lit';
+import { nothing, type PropertyValues, type TemplateResult } from 'lit';
 declare const HelixHeadlessAccordionItem_base: (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerOpenInterface) & typeof HelixElement;
 /**
  * @summary One collapsible section of an accordion.
@@ -18,12 +18,18 @@ declare const HelixHeadlessAccordionItem_base: (new (...args: any[]) => import("
  * out of the tab order and the accessibility tree after the styled tier's
  * `display` overrides `hidden`.
  *
+ * 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
  * @documentation https://fusion.dev/helix/components/accordion
  *
  * @slot - The content shown when the section is open.
+ * @slot chevron - Replaces the open and close indicator, such as with your own icon.
  * @slot summary - The text of the button that opens and closes the section. Always shown.
  *
  * @event {HelixBeforeCloseEvent} helix-before-close - The section is about to close. Cancelable: cancel it to keep it open.
@@ -51,8 +57,13 @@ export declare class HelixHeadlessAccordionItem extends HelixHeadlessAccordionIt
      * have two.
      */
     chevronPlacement?: 'auto' | 'start' | 'end' | 'none';
-    /** The chevron, or nothing when suppressed. */
-    private renderChevron;
+    /**
+     * The chevron, or nothing when suppressed.
+     *
+     * The drawn chevron is the `chevron` slot's fallback, so an icon of your own
+     * replaces it by being slotted, and a tier drawing its own overrides this.
+     */
+    protected renderChevron(): TemplateResult | typeof nothing;
     /**
      * Whether the section is disabled, so its trigger cannot be pressed or
      * reached with the arrow keys. A script can still open and close it.
@@ -64,6 +75,11 @@ export declare class HelixHeadlessAccordionItem extends HelixHeadlessAccordionIt
      * causes a hydration mismatch.
      */
     groupHeadingLevel: number | undefined;
+    /**
+     * @internal The accordion's `hidden-until-found`, written by the accordion,
+     * for the reason `groupHeadingLevel` is a property.
+     */
+    groupHiddenUntilFound: boolean;
     /**
      * The level of the heading around the trigger, from 1 to 6.
      *
@@ -71,6 +87,16 @@ export declare class HelixHeadlessAccordionItem extends HelixHeadlessAccordionIt
      * too.
      */
     headingLevel?: number;
+    /**
+     * 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.
+     */
+    hiddenUntilFound: boolean;
     /**
      * A group name. Opening an item closes the other items with the same name,
      * as `<details name>` does.
@@ -92,6 +118,15 @@ export declare class HelixHeadlessAccordionItem extends HelixHeadlessAccordionIt
      * absence. Caught by `hydration.dom.spec.ts`.
      */
     name?: string;
+    /** Whether find in page searches this section while it is closed. */
+    private get findable();
+    /**
+     * Opens the section find in page has matched in, before the match is shown.
+     *
+     * The browser removes `hidden` itself. A refusal puts it back, so the trigger
+     * and the region still agree.
+     */
+    private readonly handleBeforeMatch;
     /** Whether the item was open at the last update, and `undefined` before one. */
     private wasOpen;
     /**
@@ -157,16 +192,17 @@ export declare class HelixHeadlessAccordionItem extends HelixHeadlessAccordionIt
      * part outranks it and the transition runs exactly as before. Measured on
      * both tiers.
      *
-     * **Not `hidden="until-found"`**, which would be the better accordion and is
-     * a different piece of work. It hides through `content-visibility` rather
-     * than `display`, which an author `display` does not override, so a collapsed
-     * section a sheet animates would open to nothing. It also needs a
-     * `beforematch` handler to set `open`, or find-in-page reveals text while the
-     * trigger still reports collapsed.
+     * **`hidden="until-found"` only where it was asked for.** 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.
      *
-     * `inert` stays. `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.
+     * `inert` stays, except under `until-found`. `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
+     * the accessibility tree by itself, and an inert region is never searched.
      */
     protected render(): TemplateResult;
 }

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

@@ -17,6 +17,15 @@ let HelixHeadlessAccordionItem = class HelixHeadlessAccordionItem extends MixinC
         super(...arguments);
         this.disabled = false;
         this.groupHeadingLevel = undefined;
+        this.groupHiddenUntilFound = false;
+        this.hiddenUntilFound = false;
+        this.handleBeforeMatch = (event) => {
+            if (this.open || this.requestOpen(true)) {
+                return;
+            }
+            ;
+            event.currentTarget.setAttribute('hidden', 'until-found');
+        };
         this.wasOpen = undefined;
         this.handleToggle = () => {
             if (this.disabled) {
@@ -39,9 +48,14 @@ let HelixHeadlessAccordionItem = class HelixHeadlessAccordionItem extends MixinC
         if (this.chevronPlacement === 'none') {
             return nothing;
         }
-        return html `<svg part="chevron" fill="currentColor" viewBox=${caretDown.viewBox} aria-hidden="true">
-      ${unsafeSVG(caretDown.content)}
-    </svg>`;
+        return html `<slot name="chevron"
+      ><svg part="chevron" fill="currentColor" viewBox=${caretDown.viewBox} aria-hidden="true">
+        ${unsafeSVG(caretDown.content)}
+      </svg></slot
+    >`;
+    }
+    get findable() {
+        return this.hiddenUntilFound || this.groupHiddenUntilFound;
     }
     get accordion() {
         return closestInstance(this, HelixHeadlessAccordion);
@@ -103,9 +117,10 @@ let HelixHeadlessAccordionItem = class HelixHeadlessAccordionItem extends MixinC
           id=${CONTENT_ID}
           aria-labelledby=${TRIGGER_ID}
           part="content"
-          ?hidden=${!open}
-          ?inert=${!open}
+          hidden=${open ? nothing : this.findable ? 'until-found' : ''}
+          ?inert=${!open && !this.findable}
           role="region"
+          @beforematch=${this.handleBeforeMatch}
         >
           <div part="content-inner">
             <slot></slot>
@@ -124,9 +139,15 @@ __decorate([
 __decorate([
     property({ attribute: false })
 ], HelixHeadlessAccordionItem.prototype, "groupHeadingLevel", void 0);
+__decorate([
+    property({ attribute: false })
+], HelixHeadlessAccordionItem.prototype, "groupHiddenUntilFound", void 0);
 __decorate([
     property({ attribute: 'heading-level', type: Number })
 ], HelixHeadlessAccordionItem.prototype, "headingLevel", void 0);
+__decorate([
+    property({ attribute: 'hidden-until-found', type: Boolean })
+], HelixHeadlessAccordionItem.prototype, "hiddenUntilFound", void 0);
 __decorate([
     property({ reflect: true })
 ], HelixHeadlessAccordionItem.prototype, "name", void 0);

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

@@ -39,6 +39,12 @@ export declare class HelixHeadlessAccordion extends HelixElement {
      * Unset is 3. An item's own `heading-level` wins over this.
      */
     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.
+     */
+    hiddenUntilFound: boolean;
     /**
      * How many sections may be open at once.
      *

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

@@ -18,6 +18,7 @@ const navigable = (item) => ({
 let HelixHeadlessAccordion = class HelixHeadlessAccordion extends HelixElement {
     constructor() {
         super(...arguments);
+        this.hiddenUntilFound = false;
         this.keys = new KeyboardNavigationController(this, {
             items: () => this.items.map(navigable),
             origin: 'focus',
@@ -32,6 +33,7 @@ let HelixHeadlessAccordion = class HelixHeadlessAccordion extends HelixElement {
         for (const item of items) {
             whenHydrated(item, () => {
                 item.groupHeadingLevel = this.headingLevel;
+                item.groupHiddenUntilFound = this.hiddenUntilFound;
             });
         }
         if (this.mode === undefined) {
@@ -56,7 +58,8 @@ let HelixHeadlessAccordion = class HelixHeadlessAccordion extends HelixElement {
     }
     updated(changed) {
         super.updated(changed);
-        if (this.hasUpdated && (changed.has('mode') || changed.has('headingLevel'))) {
+        if (this.hasUpdated &&
+            (changed.has('mode') || changed.has('headingLevel') || changed.has('hiddenUntilFound'))) {
             this.settle();
         }
     }
@@ -67,6 +70,9 @@ let HelixHeadlessAccordion = class HelixHeadlessAccordion extends HelixElement {
 __decorate([
     property({ attribute: 'heading-level', type: Number })
 ], HelixHeadlessAccordion.prototype, "headingLevel", void 0);
+__decorate([
+    property({ attribute: 'hidden-until-found', type: Boolean })
+], HelixHeadlessAccordion.prototype, "hiddenUntilFound", void 0);
 __decorate([
     property({ reflect: true })
 ], HelixHeadlessAccordion.prototype, "mode", void 0);

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

@@ -28,6 +28,11 @@ declare const HelixHeadlessAnnouncement_base: (new (...args: any[]) => import("@
  * announcement beside it, move focus yourself, for example to the page's main
  * heading.
  *
+ * 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.
+ *
  * @since 0.1.0
  * @status stable
  * @category feedback
@@ -38,7 +43,7 @@ declare const HelixHeadlessAnnouncement_base: (new (...args: any[]) => import("@
  * @slot actions - Actions for the message, usually a link or a button.
  * @slot icon - Replaces the icon inside the dismiss button.
  *
- * @event {HelixDismissEvent} helix-dismiss - The dismiss button was pressed. The announcement does not remove itself, so remove it in response. Cancelable.
+ * @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.
@@ -47,6 +52,14 @@ declare const HelixHeadlessAnnouncement_base: (new (...args: any[]) => import("@
  * @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.
  */
 export declare class HelixHeadlessAnnouncement extends HelixHeadlessAnnouncement_base {
+    /**
+     * How long the announcement stays, in milliseconds, before it sends
+     * `helix-dismiss`. When it is not set, it stays until it is dismissed.
+     *
+     * Read once when the announcement is first rendered, as `Toast` reads its
+     * own. The clock stops while the pointer or focus is on the announcement.
+     */
+    duration?: number;
     /**
      * The band's color.
      *
@@ -71,6 +84,13 @@ export declare class HelixHeadlessAnnouncement extends HelixHeadlessAnnouncement
      */
     tone?: 'accent' | 'danger' | 'info' | 'neutral' | 'primary' | 'success' | 'warning';
     protected readonly arrival: ArrivalController;
+    /** The time `duration` gives it, held while a reader is on it. */
+    private readonly countdown;
+    private readonly handleHold;
+    private readonly handleRelease;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    protected firstUpdated(changed: PropertyValues): void;
     protected updated(changed: PropertyValues): void;
     /**
      * Says on the `actions` region whether anything is in it.

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, customElement, HelixElement, MixinDismissible, markRegion, slottedWords, } from '@fusion.dev/helix-core';
+import { ArrivalController, CountdownController, customElement, HelixElement, MixinDismissible, markRegion, slottedWords, } from '@fusion.dev/helix-core';
 import { x } from '@fusion.dev/helix-icons';
 import { html, nothing } from 'lit';
 import { property } from 'lit/decorators.js';
@@ -16,6 +16,38 @@ let HelixHeadlessAnnouncement = class HelixHeadlessAnnouncement extends MixinDis
             arriving: () => !this.serverRendered && document.readyState === 'complete',
             text: () => slottedWords(this, ['']),
         });
+        this.countdown = new CountdownController(this, {
+            done: () => {
+                this.dismiss();
+            },
+        });
+        this.handleHold = () => {
+            this.countdown.hold();
+        };
+        this.handleRelease = () => {
+            this.countdown.release();
+        };
+    }
+    connectedCallback() {
+        super.connectedCallback();
+        this.addEventListener('mouseenter', this.handleHold);
+        this.addEventListener('mouseleave', this.handleRelease);
+        this.addEventListener('focusin', this.handleHold);
+        this.addEventListener('focusout', this.handleRelease);
+        if (this.hasUpdated) {
+            this.countdown.resume();
+        }
+    }
+    disconnectedCallback() {
+        super.disconnectedCallback();
+        this.removeEventListener('mouseenter', this.handleHold);
+        this.removeEventListener('mouseleave', this.handleRelease);
+        this.removeEventListener('focusin', this.handleHold);
+        this.removeEventListener('focusout', this.handleRelease);
+    }
+    firstUpdated(changed) {
+        super.firstUpdated(changed);
+        this.countdown.start(this.duration);
     }
     updated(changed) {
         super.updated(changed);
@@ -47,6 +79,9 @@ let HelixHeadlessAnnouncement = class HelixHeadlessAnnouncement extends MixinDis
             : nothing}`;
     }
 };
+__decorate([
+    property({ type: Number })
+], HelixHeadlessAnnouncement.prototype, "duration", void 0);
 __decorate([
     property({ reflect: true })
 ], HelixHeadlessAnnouncement.prototype, "tone", void 0);

package/dist/app-header/root/app-header-root.d.ts

@@ -19,6 +19,12 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * The page is the window unless `scroller` names the element that scrolls, for
  * an app shell whose content scrolls inside a container.
  *
+ * The host is the page's `banner` landmark. Placed inside `main`, `article`,
+ * `aside`, `nav` or `section`, it is a plain box instead, as a native
+ * `<header>` is there, so a header inside a card or a pane does not add a
+ * second banner. A server cannot see the ancestors, so it serves the banner and
+ * the browser corrects it when the element connects.
+ *
  * @since 0.1.0
  * @status stable
  * @category navigation
@@ -64,6 +70,7 @@ export declare class HelixHeadlessAppHeader extends HelixElement {
      * scrolls a container instead of the window. Unset is the window.
      */
     scroller?: string;
+    private landmark;
     private scrolled;
     /** What scroll is listened to now, so a change of `scroller` moves it. */
     private source;

package/dist/app-header/root/app-header-root.js

@@ -7,9 +7,11 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 import { customElement, elementById, HelixElement, HelixScrolledEvent, hostAria, } from '@fusion.dev/helix-core';
 import { html } from 'lit';
 import { property } from 'lit/decorators.js';
+import { inSectioningContent } from '../sectioning.js';
 let HelixHeadlessAppHeader = class HelixHeadlessAppHeader extends HelixElement {
     constructor() {
         super(...arguments);
+        this.landmark = 'banner';
         this.scrolled = false;
         this.handleScroll = () => {
             const source = this.source ?? window;
@@ -41,10 +43,12 @@ let HelixHeadlessAppHeader = class HelixHeadlessAppHeader extends HelixElement {
     }
     willUpdate(changed) {
         super.willUpdate(changed);
-        hostAria(this.internals, { role: 'banner' });
+        hostAria(this.internals, { role: this.landmark });
     }
     connectedCallback() {
         super.connectedCallback();
+        this.landmark = inSectioningContent(this) ? '' : 'banner';
+        hostAria(this.internals, { role: this.landmark });
         this.listen();
     }
     disconnectedCallback() {

package/dist/app-header/sectioning.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Whether an element sits inside sectioning content, read across shadow
+ * boundaries as the accessibility tree reads it.
+ *
+ * Client only: a server has no ancestors to read.
+ */
+export declare const inSectioningContent: (element: Element) => boolean;

package/dist/app-header/sectioning.js

@@ -0,0 +1,26 @@
+const SECTIONING = [
+    'article',
+    'aside',
+    'main',
+    'nav',
+    'section',
+    '[role="article"]',
+    '[role="complementary"]',
+    '[role="main"]',
+    '[role="navigation"]',
+    '[role="region"]',
+].join(', ');
+export const inSectioningContent = (element) => {
+    let node = element.parentElement ?? hostOf(element);
+    while (node) {
+        if (node.matches(SECTIONING)) {
+            return true;
+        }
+        node = node.parentElement ?? hostOf(node);
+    }
+    return false;
+};
+const hostOf = (element) => {
+    const root = element.getRootNode();
+    return root instanceof ShadowRoot ? root.host : null;
+};

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

@@ -44,9 +44,15 @@ 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.
  *
- * The drawing is `aria-hidden`. 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.
+ * 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.
+ *
+ * **The plot is read by key.** It takes focus, named by `label` or the caption.
+ * The left and right arrows move from reading to reading, Home and End go to
+ * the first and the last, and the up and down arrows move among the series of
+ * a reading. The tooltip follows, the `live` part says the reading in words,
+ * and Escape puts the tooltip away.
  *
  * Every numeric column is a part, so leave a total column out of the table the
  * chart reads, or it is counted twice. A negative reading is drawn as zero.
@@ -64,8 +70,9 @@ declare const HelixHeadlessAreaChart_base: typeof HelixElement & (new (...args:
  * @csspart label - One reading's name.
  * @csspart labels - The row of reading names.
  * @csspart line - The top edge of one part's band.
+ * @csspart live - The readout: a polite live region that says the reading the keys moved to. Hide it visually.
  * @csspart mark - The invisible point the tooltip is anchored to.
- * @csspart plot - The drawing.
+ * @csspart plot - The drawing, which takes focus to be read by key.
  * @csspart summary - The total and each part's share at the latest reading, written as a sentence for screen readers.
  * @csspart svg - The drawing surface the bands sit on.
  * @csspart tooltip - The bubble, forwarded from `Tooltip`.
@@ -77,6 +84,7 @@ declare const HelixHeadlessAreaChart_base: typeof HelixElement & (new (...args:
  * @csspart tooltip-arrow-top - The point while the bubble is above the reading, so on its bottom edge, beside `tooltip-arrow`.
  * @csspart tooltip-bottom - The bubble while it is below the reading, beside `tooltip`.
  * @csspart tooltip-cell - One column's name and value inside the tooltip.
+ * @csspart tooltip-cell-current - The cell the up and down arrows rest on, while they rest there. Set alongside `tooltip-cell`.
  * @csspart tooltip-label - The reading's own name inside the tooltip.
  * @csspart tooltip-left - The bubble while it is left of the reading, beside `tooltip`.
  * @csspart tooltip-name - A column's name inside the tooltip.

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

@@ -36,7 +36,11 @@ let HelixHeadlessAreaChart = class HelixHeadlessAreaChart extends MixinChartSour
     get stack() {
         const rows = this.sourceRows;
         const columns = this.plottedColumns;
-        const values = columns.map((column) => rows.map((row) => {
+        const names = columns.map((column) => rows.find((row) => row.cells[column])?.cells[column]?.name ?? '');
+        const values = columns.map((column, depth) => rows.map((row) => {
+            if (!this.showsSeries(names[depth] ?? '')) {
+                return 0;
+            }
             const value = row.cells[column]?.value ?? 0;
             if (value < 0) {
                 this.warnNegative();
@@ -59,7 +63,7 @@ let HelixHeadlessAreaChart = class HelixHeadlessAreaChart extends MixinChartSour
         return {
             columns,
             layers,
-            names: columns.map((column) => rows.find((row) => row.cells[column])?.cells[column]?.name ?? ''),
+            names,
             totals,
             values,
         };
@@ -94,8 +98,17 @@ let HelixHeadlessAreaChart = class HelixHeadlessAreaChart extends MixinChartSour
     }
     renderPlot(stack, count, x, y, domain) {
         const order = stack.layers.map((_, depth) => depth).reverse();
-        return html `<div aria-hidden="true" id=${CHART_PLOT} part="plot">
+        return html `<div
+      aria-describedby=${this.named ? 'helix-chart-summary' : nothing}
+      aria-label=${this.named || nothing}
+      aria-labelledby=${this.named ? nothing : 'helix-chart-summary'}
+      id=${CHART_PLOT}
+      part="plot"
+      role="application"
+      tabindex="0"
+    >
       <svg part="svg"
+        aria-hidden="true"
         data-mirror
         preserveAspectRatio="none"
         viewBox="0 0 ${PLOT_WIDTH} ${PLOT_HEIGHT}"
@@ -162,9 +175,13 @@ let HelixHeadlessAreaChart = class HelixHeadlessAreaChart extends MixinChartSour
         const last = rows.length - 1;
         const total = stack.totals[last] ?? 0;
         const format = formatNumbers(this.locale);
-        const shares = stack.names.map((name, depth) => `${name} ${percentIn(this.locale).format(total > 0 ? (stack.values[depth]?.[last] ?? 0) / total : 0)}`);
+        const shares = stack.names.flatMap((name, depth) => this.showsSeries(name)
+            ? [
+                `${name} ${percentIn(this.locale).format(total > 0 ? (stack.values[depth]?.[last] ?? 0) / total : 0)}`,
+            ]
+            : []);
         const named = this.named ? `${this.named}, ` : '';
-        return html `<p part="summary">
+        return html `<p id="helix-chart-summary" part="summary">
       ${named}${rows[last]?.label ?? ''}: ${this.totalLabel} ${format(total)}; ${shares.join(', ')}.
     </p>`;
     }
@@ -190,14 +207,14 @@ let HelixHeadlessAreaChart = class HelixHeadlessAreaChart extends MixinChartSour
         const at = this.pointer.at;
         const rows = this.tallied(this.sourceRows, stack);
         if (at < 0) {
-            return drawTooltip(rows, at, this.tag('tooltip'));
+            return drawTooltip(rows, at, this.tag('tooltip'), undefined, undefined, this.pointer);
         }
         const slot = 100 / rows.length;
         return drawTooltip(rows, at, this.tag('tooltip'), {
             placement: 'top',
             x: `${at * slot + slot / 2}%`,
             y: `${y(stack.layers.at(-1)?.[at] ?? 0)}%`,
-        }, (cell) => this.seriesOf(cell));
+        }, (cell) => this.seriesOf(cell), this.pointer);
     }
 };
 __decorate([

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

@@ -32,6 +32,17 @@ export declare const initialsOf: (name: string) => string;
  * @csspart initials - The initials shown when there is no usable image.
  */
 export declare class HelixHeadlessAvatar extends HelixElement {
+    /**
+     * How long, in milliseconds, a picture may take before the initials stand
+     * in for it while it loads.
+     *
+     * Absent keeps the picture's place empty until it arrives or fails. Set,
+     * the initials show once the wait is over and the picture
+     * replaces them when it arrives, so a slow connection shows who it is
+     * without a cached picture flashing initials first. Radix's `delayMs` is the
+     * same idea.
+     */
+    fallbackDelay?: number;
     /**
      * Name of the person or entity.
      *
@@ -65,10 +76,13 @@ export declare class HelixHeadlessAvatar extends HelixElement {
      * report waits for the event it reports, below.
      */
     private broken;
+    /** The wait `fallback-delay` asks for, which has run out for the picture loading now or not. */
+    private readonly wait;
     private readonly handleError;
     private readonly handleLoad;
     protected willUpdate(changed: PropertyValues): void;
     protected firstUpdated(changed: PropertyValues): void;
+    private startWait;
     protected updated(changed: PropertyValues): void;
     protected render(): TemplateResult;
     /**

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

@@ -4,8 +4,8 @@ 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 } from '@fusion.dev/helix-core';
-import { html } from 'lit';
+import { customElement, DelayController, HelixElement, hostAria } from '@fusion.dev/helix-core';
+import { html, nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
 export const initialsOf = (name) => {
     const words = name.trim().split(/\s+/).filter(Boolean);
@@ -24,6 +24,7 @@ let HelixHeadlessAvatar = class HelixHeadlessAvatar extends HelixElement {
         this.src = '';
         this.status = 'loading';
         this.broken = false;
+        this.wait = new DelayController(this);
         this.handleError = (event) => {
             this.broken = true;
             this.status = 'error';
@@ -64,8 +65,16 @@ let HelixHeadlessAvatar = class HelixHeadlessAvatar extends HelixElement {
             });
         }
     }
+    startWait() {
+        this.wait.start(this.fallbackDelay !== undefined && this.src !== ''
+            ? Math.max(this.fallbackDelay, 0)
+            : undefined);
+    }
     updated(changed) {
         super.updated(changed);
+        if (changed.has('src') || changed.has('fallbackDelay')) {
+            this.startWait();
+        }
         if (changed.has('status')) {
             if (this.status === 'loading') {
                 this.removeAttribute('data-status');
@@ -77,13 +86,15 @@ let HelixHeadlessAvatar = class HelixHeadlessAvatar extends HelixElement {
     }
     render() {
         if (this.src !== '' && !this.broken) {
-            return html `<img
-        part="image"
-        src=${this.src}
-        alt=""
-        @error=${this.handleError}
-        @load=${this.handleLoad}
-      />`;
+            const standIn = this.wait.elapsed && this.status === 'loading';
+            return html `${standIn ? this.renderInitials() : nothing}<img
+          part="image"
+          src=${this.src}
+          alt=""
+          ?hidden=${standIn}
+          @error=${this.handleError}
+          @load=${this.handleLoad}
+        />`;
         }
         return this.renderInitials();
     }
@@ -93,6 +104,9 @@ let HelixHeadlessAvatar = class HelixHeadlessAvatar extends HelixElement {
     </slot>`;
     }
 };
+__decorate([
+    property({ attribute: 'fallback-delay', type: Number })
+], HelixHeadlessAvatar.prototype, "fallbackDelay", void 0);
 __decorate([
     property()
 ], HelixHeadlessAvatar.prototype, "name", void 0);

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

@@ -18,13 +18,17 @@ import { type TemplateResult } from 'lit';
  * 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.
  *
- * **The count is not part of the wrapped 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. Where the count
- * belongs in that name, write it into the control's own label, such as
- * `aria-label="Inbox, 8 unread"` on a button that reads "Inbox". The badge
- * cannot add it: 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 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.
+ *
+ * **Put the badge inside the control to have its count read with the
+ * control's name**, as Web Awesome and Shoelace do: `<button>Inbox
+ * <helix-badge value="8" label="8 unread"></helix-badge></button>` is the
+ * button "Inbox 8 unread", and stays current as the count changes. The styled
+ * tier's `placement="inline"` draws the mark in the line for that case.
  *
  * @since 0.1.0
  * @status stable