@fusion.dev/helix-headless 0.142.1 → 0.143.0

package/dist/accordion/item/accordion-item.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';
 declare const HelixHeadlessAccordionItem_base: (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerOpenInterface) & typeof HelixElement;
 /**
  * @summary One collapsible section of an accordion.
@@ -8,6 +8,10 @@ declare const HelixHeadlessAccordionItem_base: (new (...args: any[]) => import("
  * Holds its own open state. Used alone, outside an accordion, it works as a
  * disclosure.
  *
+ * The trigger sits inside a heading, so a screen reader lists the section with
+ * the page's headings. The level is the item's `heading-level`, then the
+ * 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
@@ -24,12 +28,13 @@ declare const HelixHeadlessAccordionItem_base: (new (...args: any[]) => import("
  *
  * @event {HelixBeforeCloseEvent} helix-before-close - The section is about to close. Cancelable: cancel it to keep it open.
  * @event {HelixBeforeOpenEvent} helix-before-open - The section is about to open. Cancelable: cancel it to keep it closed.
- * @event {Event} toggle - The section opened or closed. The event carries `newState` and `oldState`.
+ * @event {ToggleEvent} toggle - The section opened or closed. The event carries `newState` and `oldState`.
  *
  * @csspart chevron - The open and close indicator.
  * @csspart container - The outer wrapper.
  * @csspart content - The region that holds the content.
  * @csspart content-inner - The clipping box inside the animated region.
+ * @csspart heading - The heading that holds the trigger.
  * @csspart trigger - The button that opens and closes the section, holding the summary.
  *
  * @cssstate open - While the item is open.
@@ -48,6 +53,24 @@ export declare class HelixHeadlessAccordionItem extends HelixHeadlessAccordionIt
     chevronPlacement?: 'auto' | 'start' | 'end' | 'none';
     /** The chevron, or nothing when suppressed. */
     private renderChevron;
+    /**
+     * 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.
+     */
+    disabled: boolean;
+    /**
+     * @internal The accordion's `heading-level`, written by the accordion. A
+     * property, because an attribute written onto your element after it upgrades
+     * causes a hydration mismatch.
+     */
+    groupHeadingLevel: number | undefined;
+    /**
+     * The level of the heading around the trigger, from 1 to 6.
+     *
+     * Unset takes the accordion's `heading-level`, and 3 where that is unset
+     * too.
+     */
+    headingLevel?: number;
     /**
      * A group name. Opening an item closes the other items with the same name,
      * as `<details name>` does.
@@ -69,6 +92,8 @@ export declare class HelixHeadlessAccordionItem extends HelixHeadlessAccordionIt
      * absence. Caught by `hydration.dom.spec.ts`.
      */
     name?: string;
+    /** Whether the item was open at the last update, and `undefined` before one. */
+    private wasOpen;
     /**
      * The nearest accordion above this item, if there is one.
      *
@@ -95,6 +120,17 @@ export declare class HelixHeadlessAccordionItem extends HelixHeadlessAccordionIt
      * set collapsed after a listener refused it.
      */
     protected handleToggle: () => void;
+    /** Closes the other open items in this item's set, where it has one. */
+    private closePeers;
+    /**
+     * Closes the peers of an item opened any other way than its trigger: `open`
+     * set from a script, `requestOpen` or `toggleOpen`. The trigger already
+     * closed them, so for a press this finds nothing open.
+     *
+     * Not on the first update. What the markup opens is the accordion's to
+     * settle, once every item is there to compare.
+     */
+    protected updated(changed: PropertyValues): void;
     /**
      * Moves focus to this item's trigger.
      *

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

@@ -15,7 +15,13 @@ const TRIGGER_ID = 'trigger';
 let HelixHeadlessAccordionItem = class HelixHeadlessAccordionItem extends MixinControllerOpen(HelixElement) {
     constructor() {
         super(...arguments);
+        this.disabled = false;
+        this.groupHeadingLevel = undefined;
+        this.wasOpen = undefined;
         this.handleToggle = () => {
+            if (this.disabled) {
+                return;
+            }
             const next = !this.open;
             const mode = this.accordion?.mode;
             if (!next && mode === 'single') {
@@ -24,12 +30,8 @@ let HelixHeadlessAccordionItem = class HelixHeadlessAccordionItem extends MixinC
             if (!this.requestOpen(next)) {
                 return;
             }
-            if (next && (mode !== undefined || (this.name !== undefined && this.name !== ''))) {
-                for (const peer of this.peers) {
-                    if (peer !== this && peer.open) {
-                        peer.requestOpen(false);
-                    }
-                }
+            if (next) {
+                this.closePeers();
             }
         };
     }
@@ -57,25 +59,46 @@ let HelixHeadlessAccordionItem = class HelixHeadlessAccordionItem extends MixinC
         }
         return accordion.items;
     }
+    closePeers() {
+        if (this.accordion?.mode === undefined && (this.name === undefined || this.name === '')) {
+            return;
+        }
+        for (const peer of this.peers) {
+            if (peer !== this && peer.open) {
+                peer.requestOpen(false);
+            }
+        }
+    }
+    updated(changed) {
+        super.updated(changed);
+        if (this.wasOpen === false && this.open) {
+            this.closePeers();
+        }
+        this.wasOpen = this.open;
+    }
     focusTrigger() {
         this.renderRoot.querySelector(`#${TRIGGER_ID}`)?.focus();
     }
     render() {
         const open = this.open;
+        const level = Math.min(6, Math.max(1, this.headingLevel ?? this.groupHeadingLevel ?? 3));
         return html `
       <div part="container">
+        <div part="heading" role="heading" aria-level=${level}>
         <button
           id=${TRIGGER_ID}
           aria-controls=${CONTENT_ID}
           aria-expanded=${open ? 'true' : 'false'}
           part="trigger"
           type="button"
+          ?disabled=${this.disabled}
           @click=${this.handleToggle}
         >
           ${this.chevronPlacement === 'start' ? this.renderChevron() : nothing}
           <slot name="summary"></slot>
           ${this.chevronPlacement === 'start' ? nothing : this.renderChevron()}
         </button>
+        </div>
         <div
           id=${CONTENT_ID}
           aria-labelledby=${TRIGGER_ID}
@@ -95,6 +118,15 @@ let HelixHeadlessAccordionItem = class HelixHeadlessAccordionItem extends MixinC
 __decorate([
     property({ attribute: 'chevron-placement', reflect: true })
 ], HelixHeadlessAccordionItem.prototype, "chevronPlacement", void 0);
+__decorate([
+    property({ reflect: true, type: Boolean })
+], HelixHeadlessAccordionItem.prototype, "disabled", void 0);
+__decorate([
+    property({ attribute: false })
+], HelixHeadlessAccordionItem.prototype, "groupHeadingLevel", void 0);
+__decorate([
+    property({ attribute: 'heading-level', type: Number })
+], HelixHeadlessAccordionItem.prototype, "headingLevel", void 0);
 __decorate([
     property({ reflect: true })
 ], HelixHeadlessAccordionItem.prototype, "name", void 0);

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

@@ -1,5 +1,5 @@
 import { HelixElement, KeyboardNavigationController } from '@fusion.dev/helix-core';
-import { type TemplateResult } from 'lit';
+import { type PropertyValues, type TemplateResult } from 'lit';
 import { HelixHeadlessAccordionItem } from '../item/accordion-item.js';
 /**
  * @summary A group of collapsible sections.
@@ -20,6 +20,10 @@ import { HelixHeadlessAccordionItem } from '../item/accordion-item.js';
  * The keyboard listener belongs to the controller and is attached on connect,
  * so it does not run on the server.
  *
+ * Each trigger sits inside a heading, level 3 unless `heading-level` says
+ * otherwise, so the sections are in a screen reader's list of headings. Set the
+ * level that fits the page's outline.
+ *
  * @since 0.1.0
  * @status stable
  * @category layout
@@ -29,6 +33,12 @@ import { HelixHeadlessAccordionItem } from '../item/accordion-item.js';
  * @slot - The accordion's items.
  */
 export declare class HelixHeadlessAccordion extends HelixElement {
+    /**
+     * The level of the heading around each trigger, from 1 to 6.
+     *
+     * Unset is 3. An item's own `heading-level` wins over this.
+     */
+    headingLevel?: number;
     /**
      * How many sections may be open at once.
      *
@@ -36,6 +46,11 @@ export declare class HelixHeadlessAccordion extends HelixElement {
      * no attribute on the host. `single` keeps exactly one open and refuses to
      * close the last; `single-collapsible` keeps at most one and lets it close.
      *
+     * Held however a section opens: a press, `open` set from a script,
+     * `toggleOpen()`, or `default-open` in the markup. Opening one closes the
+     * others, and on first render only the first section written open stays
+     * open. Under `single` the first section opens when none is written open.
+     *
      * A union rather than a mode plus a `collapsible` boolean, which would make
      * `collapsible` alongside `multiple` expressible and meaningless.
      */
@@ -43,6 +58,13 @@ export declare class HelixHeadlessAccordion extends HelixElement {
     /** The accordion's own items, in the order they are written. Browser only. */
     get items(): HelixHeadlessAccordionItem[];
     protected readonly keys: KeyboardNavigationController;
+    /**
+     * Holds the mode over the sections as written, and passes the heading level
+     * down. A section opened later closes its peers itself.
+     */
+    private settle;
+    protected firstUpdated(changed: PropertyValues): void;
+    protected updated(changed: PropertyValues): void;
     protected render(): TemplateResult;
 }
 declare global {

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

@@ -4,13 +4,13 @@ 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, } from '@fusion.dev/helix-core';
+import { customElement, HelixElement, KeyboardNavigationController, whenHydrated, } from '@fusion.dev/helix-core';
 import { html } from 'lit';
 import { property } from 'lit/decorators.js';
 import { HelixHeadlessAccordionItem } from '../item/accordion-item.js';
 const navigable = (item) => ({
     contains: (node) => node === item,
-    disabled: false,
+    disabled: item.disabled,
     focusItem: () => item.focusTrigger(),
     select: () => { },
     selected: false,
@@ -27,10 +27,46 @@ let HelixHeadlessAccordion = class HelixHeadlessAccordion extends HelixElement {
     get items() {
         return [...this.children].filter((child) => child instanceof HelixHeadlessAccordionItem);
     }
+    settle() {
+        const items = this.items;
+        for (const item of items) {
+            whenHydrated(item, () => {
+                item.groupHeadingLevel = this.headingLevel;
+            });
+        }
+        if (this.mode === undefined) {
+            return;
+        }
+        const open = items.filter((item) => item.open);
+        for (const extra of open.slice(1)) {
+            whenHydrated(extra, () => {
+                extra.open = false;
+            });
+        }
+        const first = items[0];
+        if (this.mode === 'single' && open.length === 0 && first) {
+            whenHydrated(first, () => {
+                first.open = true;
+            });
+        }
+    }
+    firstUpdated(changed) {
+        super.firstUpdated(changed);
+        this.settle();
+    }
+    updated(changed) {
+        super.updated(changed);
+        if (this.hasUpdated && (changed.has('mode') || changed.has('headingLevel'))) {
+            this.settle();
+        }
+    }
     render() {
-        return html `<slot></slot>`;
+        return html `<slot @slotchange=${() => this.settle()}></slot>`;
     }
 };
+__decorate([
+    property({ attribute: 'heading-level', type: Number })
+], HelixHeadlessAccordion.prototype, "headingLevel", void 0);
 __decorate([
     property({ reflect: true })
 ], HelixHeadlessAccordion.prototype, "mode", void 0);

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

@@ -16,12 +16,17 @@ declare const HelixHeadlessAnnouncement_base: (new (...args: any[]) => import("@
  *
  * The live region is its own part. When the announcement appears after the page
  * has loaded, the message is written into the region one frame later, so screen
- * readers read it reliably. When the announcement is in the served HTML, the
- * region is filled at once and nothing is read out.
+ * readers read it reliably, and the region is emptied seven seconds later, so
+ * the message is not in the page twice. When the announcement is in the served
+ * HTML, the region stays empty and nothing is read out.
  *
  * The dismiss button fires `helix-dismiss`, and the announcement stays in the
  * document, so remove it in your listener. The event is cancelable, and
- * `dismiss()` returns `false` when a listener calls `preventDefault()`.
+ * `dismiss()` returns `false` when a listener calls `preventDefault()`. When
+ * your listener removes an announcement whose dismiss button has focus, focus
+ * moves to the dismiss button of the announcement beside it. With no other
+ * announcement beside it, move focus yourself, for example to the page's main
+ * heading.
  *
  * @since 0.1.0
  * @status stable
@@ -39,7 +44,7 @@ declare const HelixHeadlessAnnouncement_base: (new (...args: any[]) => import("@
  * @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 live - A copy of the message in a live region, read by screen readers when the announcement appears after the page has loaded. Visually hidden in the styled tier.
+ * @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 {
     /**
@@ -55,9 +60,8 @@ export declare class HelixHeadlessAnnouncement extends HelixHeadlessAnnouncement
      * components saying what a thing means, in three vocabularies, one of which
      * described itself as a fourth.
      *
-     * `accent` is the second emphasis, a rotation off the brand seed rather than a
-     * color of its own, so it stays in relation when somebody rethemes. `primary`
-     * is the seed itself.
+     * `accent` is the second emphasis, the second color a theme names, and the
+     * brand itself until one is named. `primary` is the brand.
      *
      * **`surface` was never a color and has moved to `separation`**, which is the
      * axis that owns where a box sits relative to the page. It said the band rode

package/dist/announcement/root/announcement-root.js

@@ -34,7 +34,7 @@ let HelixHeadlessAnnouncement = class HelixHeadlessAnnouncement extends MixinDis
     render() {
         return html `<div part="content"><slot @slotchange=${() => this.arrival.say()}></slot></div>
       <span part="live" role="status">${this.arrival.said}</span>
-      <div part="actions"><slot name="actions"></slot></div>
+      <div part="actions"><slot name="actions" @slotchange=${() => this.markEmpty()}></slot></div>
       ${this.dismissible
             ? html `<button
               part="dismiss"

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

@@ -16,6 +16,9 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * `ElementInternals.states` is not in the DOM, so hydration has nothing to
  * compare. Select the state with `:state(scrolled)`.
  *
+ * The page is the window unless `scroller` names the element that scrolls, for
+ * an app shell whose content scrolls inside a container.
+ *
  * @since 0.1.0
  * @status stable
  * @category navigation
@@ -56,7 +59,24 @@ export declare class HelixHeadlessAppHeader extends HelixElement {
      * the property carries the part's name, `content`.
      */
     contentAlign?: 'start';
+    /**
+     * The id of the element whose scrolling lifts the bar, for an app shell that
+     * scrolls a container instead of the window. Unset is the window.
+     */
+    scroller?: string;
     private scrolled;
+    /** What scroll is listened to now, so a change of `scroller` moves it. */
+    private source;
+    /** The element `scroller` names, or the window. */
+    private findSource;
+    /**
+     * Listens to the scroll source that `scroller` names now.
+     *
+     * A named element that is not in the document yet, such as a `<main>` the
+     * parser has not reached when the header connects, is looked for once more
+     * when the document has loaded.
+     */
+    private listen;
     /**
      * A band rather than a line, so the fill cannot flicker at the boundary.
      *
@@ -79,6 +99,7 @@ export declare class HelixHeadlessAppHeader extends HelixElement {
     protected willUpdate(changed: PropertyValues): void;
     connectedCallback(): void;
     disconnectedCallback(): void;
+    protected updated(changed: PropertyValues): void;
     protected render(): TemplateResult;
 }
 declare global {

package/dist/app-header/root/app-header-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, HelixScrolledEvent, hostAria } from '@fusion.dev/helix-core';
+import { customElement, elementById, HelixElement, HelixScrolledEvent, hostAria, } from '@fusion.dev/helix-core';
 import { html } from 'lit';
 import { property } from 'lit/decorators.js';
 let HelixHeadlessAppHeader = class HelixHeadlessAppHeader extends HelixElement {
@@ -12,7 +12,8 @@ let HelixHeadlessAppHeader = class HelixHeadlessAppHeader extends HelixElement {
         super(...arguments);
         this.scrolled = false;
         this.handleScroll = () => {
-            const y = window.scrollY;
+            const source = this.source ?? window;
+            const y = source instanceof Element ? source.scrollTop : window.scrollY;
             const next = this.scrolled ? y > 2 : y > 8;
             if (next === this.scrolled) {
                 return;
@@ -22,18 +23,40 @@ let HelixHeadlessAppHeader = class HelixHeadlessAppHeader extends HelixElement {
             this.dispatchEvent(new HelixScrolledEvent({ scrolled: next }));
         };
     }
+    findSource() {
+        return (this.scroller ? elementById(this, this.scroller) : null) ?? window;
+    }
+    listen() {
+        const next = this.findSource();
+        if (next === window && this.scroller && document.readyState === 'loading') {
+            document.addEventListener('DOMContentLoaded', () => this.listen(), { once: true });
+        }
+        if (next === this.source) {
+            return;
+        }
+        this.source?.removeEventListener('scroll', this.handleScroll);
+        this.source = next;
+        next.addEventListener('scroll', this.handleScroll, { passive: true });
+        this.handleScroll();
+    }
     willUpdate(changed) {
         super.willUpdate(changed);
         hostAria(this.internals, { role: 'banner' });
     }
     connectedCallback() {
         super.connectedCallback();
-        window.addEventListener('scroll', this.handleScroll, { passive: true });
-        this.handleScroll();
+        this.listen();
     }
     disconnectedCallback() {
         super.disconnectedCallback();
-        window.removeEventListener('scroll', this.handleScroll);
+        this.source?.removeEventListener('scroll', this.handleScroll);
+        this.source = undefined;
+    }
+    updated(changed) {
+        super.updated(changed);
+        if (changed.has('scroller') && this.isConnected) {
+            this.listen();
+        }
     }
     render() {
         return html `
@@ -48,6 +71,9 @@ let HelixHeadlessAppHeader = class HelixHeadlessAppHeader extends HelixElement {
 __decorate([
     property({ attribute: 'content-align', reflect: true })
 ], HelixHeadlessAppHeader.prototype, "contentAlign", void 0);
+__decorate([
+    property()
+], HelixHeadlessAppHeader.prototype, "scroller", void 0);
 HelixHeadlessAppHeader = __decorate([
     customElement('helix-headless-app-header')
 ], HelixHeadlessAppHeader);

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

@@ -8,7 +8,18 @@ import { CHART_PLOT, customElement, drawTooltip, formatNumbers, HelixElement, li
 import { html, nothing, svg } from 'lit';
 import { property } from 'lit/decorators.js';
 import '../../tooltip/index.js';
-const percent = new Intl.NumberFormat(undefined, { maximumFractionDigits: 0, style: 'percent' });
+const PERCENTS = new Map();
+const percentIn = (locale) => {
+    let found = PERCENTS.get(locale);
+    if (!found) {
+        found = new Intl.NumberFormat(locale || undefined, {
+            maximumFractionDigits: 0,
+            style: 'percent',
+        });
+        PERCENTS.set(locale, found);
+    }
+    return found;
+};
 let HelixHeadlessAreaChart = class HelixHeadlessAreaChart extends MixinChartSource(HelixElement) {
     constructor() {
         super(...arguments);
@@ -150,15 +161,15 @@ let HelixHeadlessAreaChart = class HelixHeadlessAreaChart extends MixinChartSour
     renderSummary(stack, rows) {
         const last = rows.length - 1;
         const total = stack.totals[last] ?? 0;
-        const format = formatNumbers('');
-        const shares = stack.names.map((name, depth) => `${name} ${percent.format(total > 0 ? (stack.values[depth]?.[last] ?? 0) / total : 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 named = this.named ? `${this.named}, ` : '';
         return html `<p part="summary">
       ${named}${rows[last]?.label ?? ''}: ${this.totalLabel} ${format(total)}; ${shares.join(', ')}.
     </p>`;
     }
     tallied(rows, stack) {
-        const format = formatNumbers('');
+        const format = formatNumbers(this.locale);
         return rows.map((row, index) => {
             const total = stack.totals[index] ?? 0;
             return {
@@ -167,7 +178,7 @@ let HelixHeadlessAreaChart = class HelixHeadlessAreaChart extends MixinChartSour
                     ...row.cells.map((cell, column) => this.share && cell.value !== undefined && stack.columns.includes(column) && total > 0
                         ? {
                             ...cell,
-                            text: `${cell.text} (${percent.format(Math.max(0, cell.value) / total)})`,
+                            text: `${cell.text} (${percentIn(this.locale).format(Math.max(0, cell.value) / total)})`,
                         }
                         : cell),
                     { name: this.totalLabel, text: format(total) },

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

@@ -20,8 +20,10 @@ export declare const FOLDS_UP_TO = 12;
  * There is no slot for it, because the number has to match which avatars are
  * hidden.
  *
- * Avatars past `max` stay in the DOM and are hidden. Changing `max` re-renders
- * nothing, and the accessible name is still built from all of them.
+ * 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.
  *
  * @since 0.1.0
  * @status stable
@@ -30,7 +32,7 @@ export declare const FOLDS_UP_TO = 12;
  *
  * @slot - The avatars, in the order they should be read.
  *
- * @csspart overflow - The count of avatars past `max`.
+ * @csspart overflow - The count of avatars past `max`, an image named by `overflow-label`.
  */
 export declare class HelixHeadlessAvatarGroup extends HelixElement {
     /**
@@ -56,6 +58,15 @@ export declare class HelixHeadlessAvatarGroup extends HelixElement {
      * never asked for a limit, including on the server.
      */
     max?: number;
+    /**
+     * What a screen reader is told the count is, with `{count}` for the number.
+     *
+     * The count shows "+3", which reads as "plus three" and says nothing about
+     * what was counted.
+     */
+    overflowLabel: string;
+    /** The avatars this group hid, so it unhides only those. */
+    private readonly folded;
     /** The avatars, in light-DOM order. Empty on the server, which has no tree. */
     get avatars(): HTMLElement[];
     /**
@@ -72,6 +83,16 @@ export declare class HelixHeadlessAvatarGroup extends HelixElement {
     protected willUpdate(changed: PropertyValues): void;
     protected firstUpdated(changed: PropertyValues): void;
     protected updated(changed: PropertyValues): void;
+    /**
+     * Hides the avatars past `max`, with the platform's own `hidden`.
+     *
+     * **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.
+     */
+    private fold;
     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 } from '@fusion.dev/helix-core';
+import { customElement, HelixElement, hostAria, reportRuntime, whenHydrated, } from '@fusion.dev/helix-core';
 import { html } from 'lit';
 import { property } from 'lit/decorators.js';
 export const FOLDS_UP_TO = 12;
@@ -12,6 +12,8 @@ let HelixHeadlessAvatarGroup = class HelixHeadlessAvatarGroup extends HelixEleme
     constructor() {
         super(...arguments);
         this.label = '';
+        this.overflowLabel = '{count} more';
+        this.folded = new WeakSet();
         this.warned = false;
     }
     get avatars() {
@@ -32,6 +34,7 @@ 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;
@@ -44,10 +47,36 @@ let HelixHeadlessAvatarGroup = class HelixHeadlessAvatarGroup extends HelixEleme
             });
         }
     }
+    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;
+            if (past && !avatar.hidden) {
+                this.folded.add(avatar);
+                whenHydrated(avatar, () => {
+                    avatar.hidden = true;
+                });
+            }
+            else if (!past && this.folded.has(avatar)) {
+                this.folded.delete(avatar);
+                whenHydrated(avatar, () => {
+                    avatar.hidden = false;
+                });
+            }
+        }
+    }
     render() {
         const past = this.overflow;
         return html `<slot @slotchange=${() => this.requestUpdate()}></slot>
-      ${past > 0 ? html `<span part="overflow" aria-hidden="true">+${past}</span>` : ''}`;
+      ${past > 0
+            ? html `<span
+              part="overflow"
+              role="img"
+              aria-label=${this.overflowLabel.replace('{count}', String(past))}
+              >+${past}</span
+            >`
+            : ''}`;
     }
 };
 __decorate([
@@ -56,6 +85,9 @@ __decorate([
 __decorate([
     property({ reflect: true, type: Number })
 ], HelixHeadlessAvatarGroup.prototype, "max", void 0);
+__decorate([
+    property({ attribute: 'overflow-label' })
+], HelixHeadlessAvatarGroup.prototype, "overflowLabel", void 0);
 HelixHeadlessAvatarGroup = __decorate([
     customElement('helix-headless-avatar-group')
 ], HelixHeadlessAvatarGroup);

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

@@ -46,7 +46,9 @@ export declare class HelixHeadlessAvatar extends HelixElement {
     src: string;
     /**
      * The image's state: `loading` while it is on its way, `loaded` once it
-     * arrives, or `error` when it fails and the initials replace it.
+     * arrives, or `error` when it fails and the initials replace it. An avatar
+     * with no `src` has no image to wait for, and reports `error` as well, since
+     * the initials are what it shows.
      *
      * Read-only to a consumer: it is a report rather than a setting, and the same
      * report `Image` gives, for the same reason. `load` and `error` fire once, so