@fusion.dev/helix-headless 0.0.0-dev

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

@@ -0,0 +1,144 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    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, MixinDismissible, slotFilled, } from '@fusion.dev/helix-core';
+import { x } from '@fusion.dev/helix-icons';
+import { html, nothing } from 'lit';
+import { property } from 'lit/decorators.js';
+import { unsafeSVG } from 'lit/directives/unsafe-svg.js';
+/**
+ * @summary A page-level message above the masthead, which can be dismissed.
+ *
+ * @description
+ * Chrome rather than content. An announcement sits above the header and speaks
+ * for the whole page: a trial ending, a service degraded, a change of terms. A
+ * passage that interrupts a document to set itself apart is a `Callout`, which
+ * is read where it sits and cannot be dismissed. Neither is a variant of the
+ * other.
+ *
+ * **Always a polite live region.** `role="alert"` is assertive and interrupts
+ * whatever is being read, which is right for something that appears mid-session
+ * and wrong for something that was in the served HTML: an assertive
+ * announcement would cut across a screen-reader user on every page load, before
+ * they had read anything. Politeness costs a moment and is never wrong; the tone
+ * does not change that, because an error that was always there is still not an
+ * interruption.
+ *
+ * Dismissing is a request. The announcement does not remove itself, because the
+ * consumer owns the markup and taking the node out from under them would put
+ * their state and the document out of step. `preventDefault()` on the
+ * `helix-dismiss` is a refusal.
+ *
+ * @since 0.1.0
+ * @status stable
+ * @category feedback
+ * @aliases Banner, Notification bar, Alert bar
+ * @documentation https://helix.fusion.dev/components/announcement
+ *
+ * @slot - The message.
+ * @slot actions - What to do about it, usually a link or a button.
+ * @slot icon - Replaces the glyph inside the dismiss control.
+ *
+ * @event {HelixDismissEvent} helix-dismiss - Fired when the reader asks to close it. Cancelable: refusing it takes the decision and nothing moves.
+ *
+ * @csspart actions - The trailing action region.
+ * @csspart content - The message region.
+ * @csspart dismiss - The control that asks to close.
+ * @csspart dismiss-mark - The glyph on the dismiss control, where none is slotted.
+ */
+let HelixHeadlessAnnouncement = class HelixHeadlessAnnouncement extends MixinDismissible(HelixElement) {
+    willUpdate(changed) {
+        super.willUpdate(changed);
+        // On the host, and always polite. See the note above on `role="alert"`.
+        hostAria(this.internals, { role: 'status' });
+        this.internals.ariaLive = 'polite';
+    }
+    updated(changed) {
+        super.updated(changed);
+        this.markEmpty();
+    }
+    /**
+     * Says on the `actions` region whether anything is in it.
+     *
+     * An empty region is not free: it is still a flex item, so it still takes the
+     * container's gap. There is no selector that can ask, `slot:empty` being
+     * about a slot's fallback rather than its assigned nodes, so the component
+     * asks and says so, on the region inside this shadow root rather than on the
+     * host: an attribute written onto the host is a change to markup the consumer
+     * rendered, which React reports on hydration and does not patch up.
+     */
+    markEmpty() {
+        const region = this.renderRoot?.querySelector('[part="actions"]');
+        const empty = !slotFilled(this.renderRoot?.querySelector('slot[name="actions"]'));
+        region?.toggleAttribute('data-empty', empty);
+        /* `hidden` beside the mirror, because `data-empty` is a hook the styled
+           sheet reads and this tier has no sheet: an empty region left in the box
+           tree is a gap a consumer cannot close without knowing to look for it. The
+           styled rule stays, because that sheet sets `display` on this part and
+           therefore outranks the UA one. */
+        region?.toggleAttribute('hidden', empty);
+    }
+    /**
+     * The cross inside the dismiss button, behind a seam.
+     *
+     * Slot fallback, so a consumer replaces it by slotting; and a method, so the
+     * tier above replaces it by overriding. Those answer different people: the
+     * slot is for the page and the method is for whoever is building the styled
+     * layer, and a fallback with only the first is one a tier can restyle and
+     * cannot change.
+     *
+     * **Named for what it draws, which it was not.** It was `renderIcon`, with a
+     * description of "the mark for the announcement's tone", and it draws the `x`
+     * glyph inside the dismiss button and has never drawn a tone. The name is
+     * `renderIcon` on `Toast` and `Callout` too, and on both of those it takes a
+     * severity and draws exactly the tone mark this claimed to: the prose came
+     * from a sibling that meant it. An announcement has no tone mark at all.
+     */
+    renderDismissIcon() {
+        return html `<slot name="icon">
+      <svg part="dismiss-mark" viewBox=${x.viewBox} fill="currentColor" aria-hidden="true">
+        ${unsafeSVG(x.content)}
+      </svg>
+    </slot>`;
+    }
+    render() {
+        return html `<div part="content"><slot></slot></div>
+      <div part="actions"><slot name="actions"></slot></div>
+      ${
+        /* A plain `<button>`, the way `Menu` renders its way back and every
+           other in-shadow control in the library.
+
+           It was `helix-headless-icon-button`, which is the headless tier and
+           therefore ships no CSS at all, so the `<button>` inside it kept the
+           browser's own border and gray fill and the dismiss control read as a
+           form button dropped into a message bar. The styled tier could not
+           reach it: `[part="dismiss"]` selects the host and stops at its shadow
+           boundary, and its rules were already written for a plain button,
+           `all: unset` and all, which is the clue that this element was never
+           meant to be here.
+
+           Nesting a component inside a component's shadow root also makes the
+           parent depend on the child being registered, invisibly, and this was
+           the only place in the library doing it. */
+        this.dismissible
+            ? html `<button
+              part="dismiss"
+              type="button"
+              aria-label=${this.dismissLabel}
+              @click=${() => this.dismiss()}
+            >
+              ${this.renderDismissIcon()}
+            </button>`
+            : nothing}`;
+    }
+};
+__decorate([
+    property({ reflect: true })
+], HelixHeadlessAnnouncement.prototype, "tone", void 0);
+HelixHeadlessAnnouncement = __decorate([
+    customElement('helix-headless-announcement')
+], HelixHeadlessAnnouncement);
+export { HelixHeadlessAnnouncement };

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

@@ -0,0 +1 @@
+export * from './root/app-header-root.js';

package/dist/app-header/index.js

@@ -0,0 +1 @@
+export * from './root/app-header-root.js';

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

@@ -0,0 +1,113 @@
+import { HelixElement } from '@fusion.dev/helix-core';
+import { type PropertyValues, type TemplateResult } from 'lit';
+/**
+ * @summary Page-level banner holding brand, navigation, and actions.
+ *
+ * @description
+ * Tracks whether the page has scrolled and carries it as the custom state
+ * `scrolled`, so the styled tier can lift the bar off the page without a scroll
+ * handler of its own. Scroll position is the one piece of state the server
+ * genuinely cannot know, so it is read on connect rather than derived: a fresh
+ * load starts at the top, which is what the server rendered, and a reload
+ * part-way down corrects on hydration.
+ *
+ * **A custom state and not `data-scrolled`, which is what this used to be.**
+ * The attribute was written onto the host by the element itself, so a server
+ * sent the header without it and the element added it on upgrade. A framework
+ * hydrating the page then found an attribute it had not rendered and reported
+ * the tree as mismatched: intermittently, because it only happens when the
+ * reader reloads far enough down the page to pass the threshold. Every
+ * server-rendered consumer paid for that, and could only answer it by
+ * suppressing hydration warnings on an element they did not write.
+ *
+ * `ElementInternals.states` is deliberately not in the DOM, so there is nothing
+ * for a hydration pass to disagree with, and `:state(scrolled)` selects it. The
+ * base class made the same move for `data-settled` and its note explains the
+ * rest.
+ *
+ * The listener is passive and reads `scrollY` only, so it never blocks
+ * scrolling.
+ *
+ * Three regions, each in its own wrapper, because the row is a grid and a grid
+ * needs three items to put the middle one in the middle. A bare slot is
+ * `display: contents`, so its assigned elements become grid items themselves:
+ * two actions would take two tracks and push the navigation off center. These
+ * wrappers earn their boxes, which is the test; they carry no inset or fill of
+ * their own, so an empty one still paints nothing.
+ *
+ * The host is the banner and spans the viewport; the row inside it is what gets
+ * centered. A banner that is itself narrowed leaves its background stopping
+ * short of the window edges, which reads as a floating bar rather than as the
+ * top of the page. That needs one element and one row, not a wrapper as well:
+ * the host carries the material and `content` carries the measure.
+ *
+ * @since 0.1.0
+ * @status stable
+ * @category navigation
+ * @aliases Masthead, Navbar, TopBar
+ * @documentation https://helix.fusion.dev/components/app-header
+ *
+ * @slot - The middle region, usually a `Navigation`.
+ * @slot end - Trailing content.
+ * @slot start - Leading content, usually a wordmark.
+ *
+ * @event {HelixScrolledEvent} helix-scrolled - Fired when the page crosses the
+ * threshold, with the new state. A custom state cannot be observed the way an
+ * attribute could, so the header says when it changes rather than leaving
+ * consumers to run a second scroll listener and disagree about the hysteresis.
+ *
+ * @csspart content - The middle region.
+ * @csspart end - The trailing region.
+ * @csspart row - The centered row inside the banner.
+ * @csspart start - The leading region.
+ */
+export declare class HelixHeadlessAppHeader extends HelixElement {
+    /**
+     * Where the middle region sits in the bar.
+     *
+     * Centered by default, which reads as the site's spine when the navigation is
+     * the primary thing in the header rather than an afterthought beside a logo.
+     * Centered against the banner rather than against whatever space the brand
+     * left over, so the middle of the nav is the middle of the window whatever
+     * the wordmark and the actions happen to measure.
+     *
+     * `start` is the opt-out, for a header whose middle region trails the brand.
+     *
+     * **Named for the region and not for what is usually in it.** It was
+     * `nav-align`, which reads as a property about `Navigation` and is not: the
+     * middle slot takes whatever a consumer puts there, a search field or a
+     * breadcrumb trail as readily as a nav, and a header that centered its search
+     * box would have been setting `nav-align` to do it. The part is called
+     * `content`, so the property is too.
+     */
+    contentAlign?: 'start';
+    private scrolled;
+    /**
+     * A band rather than a line, so the fill cannot flicker at the boundary.
+     *
+     * **`scrollY > 0` is a threshold with no width, and a threshold with no width
+     * is a switch sitting exactly where scroll positions cluster.** Zero is not a
+     * quiet place: rubber-banding overshoots past it and comes back, scroll
+     * anchoring nudges by a pixel when an image or a font lands, and a
+     * `scroll-behavior: smooth` jump settles by oscillating around its target.
+     * Every one of those crossings toggled the attribute, and the fill and the
+     * blur are both transitioned, so each toggle started a fresh animation in the
+     * opposite direction. What a reader sees is a bar that shimmers, and text
+     * legible through it for as long as the fill is part way in.
+     *
+     * Eight pixels to take the fill, two to give it back. Asymmetric on purpose:
+     * the bar should look attached to the top of the page for as long as it
+     * honestly is, so leaving is nearly the whole way back, and arriving needs
+     * enough travel to mean the reader moved rather than the layout did.
+     */
+    private readonly handleScroll;
+    protected willUpdate(changed: PropertyValues): void;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    protected render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-app-header': HelixHeadlessAppHeader;
+    }
+}

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

@@ -0,0 +1,147 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    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 { html } from 'lit';
+import { property } from 'lit/decorators.js';
+/**
+ * @summary Page-level banner holding brand, navigation, and actions.
+ *
+ * @description
+ * Tracks whether the page has scrolled and carries it as the custom state
+ * `scrolled`, so the styled tier can lift the bar off the page without a scroll
+ * handler of its own. Scroll position is the one piece of state the server
+ * genuinely cannot know, so it is read on connect rather than derived: a fresh
+ * load starts at the top, which is what the server rendered, and a reload
+ * part-way down corrects on hydration.
+ *
+ * **A custom state and not `data-scrolled`, which is what this used to be.**
+ * The attribute was written onto the host by the element itself, so a server
+ * sent the header without it and the element added it on upgrade. A framework
+ * hydrating the page then found an attribute it had not rendered and reported
+ * the tree as mismatched: intermittently, because it only happens when the
+ * reader reloads far enough down the page to pass the threshold. Every
+ * server-rendered consumer paid for that, and could only answer it by
+ * suppressing hydration warnings on an element they did not write.
+ *
+ * `ElementInternals.states` is deliberately not in the DOM, so there is nothing
+ * for a hydration pass to disagree with, and `:state(scrolled)` selects it. The
+ * base class made the same move for `data-settled` and its note explains the
+ * rest.
+ *
+ * The listener is passive and reads `scrollY` only, so it never blocks
+ * scrolling.
+ *
+ * Three regions, each in its own wrapper, because the row is a grid and a grid
+ * needs three items to put the middle one in the middle. A bare slot is
+ * `display: contents`, so its assigned elements become grid items themselves:
+ * two actions would take two tracks and push the navigation off center. These
+ * wrappers earn their boxes, which is the test; they carry no inset or fill of
+ * their own, so an empty one still paints nothing.
+ *
+ * The host is the banner and spans the viewport; the row inside it is what gets
+ * centered. A banner that is itself narrowed leaves its background stopping
+ * short of the window edges, which reads as a floating bar rather than as the
+ * top of the page. That needs one element and one row, not a wrapper as well:
+ * the host carries the material and `content` carries the measure.
+ *
+ * @since 0.1.0
+ * @status stable
+ * @category navigation
+ * @aliases Masthead, Navbar, TopBar
+ * @documentation https://helix.fusion.dev/components/app-header
+ *
+ * @slot - The middle region, usually a `Navigation`.
+ * @slot end - Trailing content.
+ * @slot start - Leading content, usually a wordmark.
+ *
+ * @event {HelixScrolledEvent} helix-scrolled - Fired when the page crosses the
+ * threshold, with the new state. A custom state cannot be observed the way an
+ * attribute could, so the header says when it changes rather than leaving
+ * consumers to run a second scroll listener and disagree about the hysteresis.
+ *
+ * @csspart content - The middle region.
+ * @csspart end - The trailing region.
+ * @csspart row - The centered row inside the banner.
+ * @csspart start - The leading region.
+ */
+let HelixHeadlessAppHeader = class HelixHeadlessAppHeader extends HelixElement {
+    constructor() {
+        super(...arguments);
+        /* Whether the bar currently believes the page has moved, kept alongside the
+           attribute so a scroll that changes nothing writes nothing. */
+        this.scrolled = false;
+        /**
+         * A band rather than a line, so the fill cannot flicker at the boundary.
+         *
+         * **`scrollY > 0` is a threshold with no width, and a threshold with no width
+         * is a switch sitting exactly where scroll positions cluster.** Zero is not a
+         * quiet place: rubber-banding overshoots past it and comes back, scroll
+         * anchoring nudges by a pixel when an image or a font lands, and a
+         * `scroll-behavior: smooth` jump settles by oscillating around its target.
+         * Every one of those crossings toggled the attribute, and the fill and the
+         * blur are both transitioned, so each toggle started a fresh animation in the
+         * opposite direction. What a reader sees is a bar that shimmers, and text
+         * legible through it for as long as the fill is part way in.
+         *
+         * Eight pixels to take the fill, two to give it back. Asymmetric on purpose:
+         * the bar should look attached to the top of the page for as long as it
+         * honestly is, so leaving is nearly the whole way back, and arriving needs
+         * enough travel to mean the reader moved rather than the layout did.
+         */
+        this.handleScroll = () => {
+            const y = window.scrollY;
+            const next = this.scrolled ? y > 2 : y > 8;
+            if (next === this.scrolled) {
+                return;
+            }
+            this.scrolled = next;
+            /* The state is what CSS selects; the event is what anything outside this
+               element can hear. Both, because neither covers the other: a state cannot
+               be observed and an event cannot be styled. */
+            if (next) {
+                this.internals.states.add('scrolled');
+            }
+            else {
+                this.internals.states.delete('scrolled');
+            }
+            this.dispatchEvent(new HelixScrolledEvent({ scrolled: next }));
+        };
+    }
+    willUpdate(changed) {
+        super.willUpdate(changed);
+        // On the host, since the host is the banner.
+        hostAria(this.internals, { role: 'banner' });
+    }
+    connectedCallback() {
+        super.connectedCallback();
+        // Never reached on the server, which is correct: there is no scroll
+        // position to read there, and the un-scrolled markup it emits is what a
+        // fresh load actually shows.
+        window.addEventListener('scroll', this.handleScroll, { passive: true });
+        this.handleScroll();
+    }
+    disconnectedCallback() {
+        super.disconnectedCallback();
+        window.removeEventListener('scroll', this.handleScroll);
+    }
+    render() {
+        return html `
+      <div part="row">
+        <div part="start"><slot name="start"></slot></div>
+        <div part="content"><slot></slot></div>
+        <div part="end"><slot name="end"></slot></div>
+      </div>
+    `;
+    }
+};
+__decorate([
+    property({ attribute: 'content-align', reflect: true })
+], HelixHeadlessAppHeader.prototype, "contentAlign", void 0);
+HelixHeadlessAppHeader = __decorate([
+    customElement('helix-headless-app-header')
+], HelixHeadlessAppHeader);
+export { HelixHeadlessAppHeader };

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

@@ -0,0 +1,116 @@
+import { HelixElement } from '@fusion.dev/helix-core';
+import { type PropertyValues, type TemplateResult } from 'lit';
+/**
+ * The largest `max` the styled tier can hide past.
+ *
+ * The fold is `:host([max="N"]) ::slotted(:nth-child(n + N+1))`, one selector
+ * per value, because `An+B` takes a literal and no custom property can be read
+ * into it. So the range is finite and this is where it is written down, in the
+ * tier that has to agree with it: a count that folds and a stylesheet that does
+ * not would put a "+5" beside five avatars that are still on screen.
+ */
+export declare const FOLDS_UP_TO = 12;
+/**
+ * @summary Overlapping avatars, with a count for the ones not shown.
+ *
+ * @description
+ * A part of `Avatar` rather than a family of its own: it arranges avatars and
+ * is about nothing else, and its member is a complete `Avatar` the group did
+ * not have to explain.
+ *
+ * **The overflow count is the group's, not a slot.** Which avatars are hidden
+ * is a fact the group works out from `max` and how many it was given, so a
+ * consumer writing the "+3" themselves would be writing a number that has to
+ * agree with a list they do not control.
+ *
+ * **Hidden, not removed.** Past `max`, the extra avatars stay in the DOM and
+ * stop being shown, so nothing re-renders when `max` changes and the accessible
+ * name can still be built from all of them. The count is what a sighted reader
+ * gets; the group's own name is what everyone else gets, and "Seven people" is
+ * more useful than seven names read in a row.
+ *
+ * **And hidden by the stylesheet, not by this class.** It wrote `data-overflow`
+ * onto each avatar from `updated`, which is one update too late and one element
+ * too far out: Lit renders on a microtask, so an avatar appended past the limit
+ * was laid out and painted before anything ran to hide it, and the group was
+ * writing attributes onto markup a consumer owns to do it. Measured in Chrome
+ * 148, appending two past `max="3"` and reading before yielding: five `flex`,
+ * folding to three on the next update. The styled tier now does it with
+ * `:host([max="N"]) ::slotted(:nth-child(n + N+1))`, which is right at the
+ * first style resolution and writes nothing.
+ *
+ * **The fold is finite, and the count agrees with it.** `An+B` takes a literal,
+ * so there is one selector per value of `max` and the range stops at twelve.
+ * Past that the group shows everyone, counts nothing and says so, because
+ * showing everyone is a defensible answer and showing everyone beside a "+5" is
+ * not. `max` above twelve is a list the consumer should be slicing themselves.
+ *
+ * **It is a list.** A row of faces is a set of separate people, and a group
+ * with no role announces as one run of text. `role="list"` needs its children
+ * to be `listitem`, which they cannot be told to become without writing an
+ * attribute onto a consumer's element, so the group carries `role="group"` and
+ * its name instead: one announcement, correct, and nothing written to anyone
+ * else's markup.
+ *
+ * @since 0.1.0
+ * @status stable
+ * @aliases Avatar stack, Facepile
+ * @documentation https://helix.fusion.dev/components/avatar
+ *
+ * @slot - The avatars, in the order they should be read.
+ *
+ * @csspart overflow - The count of avatars past `max`.
+ */
+export declare class HelixHeadlessAvatarGroup extends HelixElement {
+    /**
+     * Accessible name for the set, such as "Reviewers".
+     */
+    label: string;
+    /**
+     * How many avatars are shown before the rest become a count.
+     *
+     * Unset shows all of them, which is what no limit means and is more useful
+     * than refusing to render.
+     *
+     * **Reflected, because the fold is a stylesheet rule and nothing else.** The
+     * styled tier hides past the limit with `:host([max="N"]) ::slotted(:nth-child(n + N+1))`,
+     * so the attribute *is* the mechanism: a `max` that reaches this property and
+     * never reaches the host matches no rule, and every avatar is drawn beside a
+     * count that says two of them are hidden. That is the failure this repository
+     * already writes down as "reflect only what CSS selects on", and it went
+     * unnoticed because the examples set `max` in markup, where the author had
+     * written the attribute themselves.
+     *
+     * It is the path a script takes that was broken, and React takes it for
+     * everyone: React assigns a matching property rather than an attribute, so
+     * `<helix-avatar-group max={4}>` folded nothing at all. Measured against the
+     * markup twin, the fifth and sixth avatars rendered at full size where the
+     * markup version had them at 0x0.
+     *
+     * **Optional rather than defaulted, per the rule that a reflected property
+     * takes no default**: `max = 0` would stamp `max="0"` onto every host that
+     * never asked for a limit, including on the server.
+     */
+    max?: number;
+    /** The avatars, in light-DOM order. Empty on the server, which has no tree. */
+    get avatars(): HTMLElement[];
+    /**
+     * How many avatars are past the limit, and so not shown.
+     *
+     * Not `hidden`, which is `HTMLElement`'s own boolean: a getter of that name
+     * returning a number is a type error, and had it been assignable it would
+     * have been worse, because a group with three extra members would have set
+     * the attribute that hides the whole group.
+     */
+    get overflow(): number;
+    /** Said once per element, because a re-render is not a second mistake. */
+    private warned;
+    protected willUpdate(changed: PropertyValues): void;
+    protected updated(changed: PropertyValues): void;
+    protected render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-avatar-group': HelixHeadlessAvatarGroup;
+    }
+}

package/dist/avatar/group/avatar-group.js

@@ -0,0 +1,136 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    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 { property } from 'lit/decorators.js';
+/**
+ * The largest `max` the styled tier can hide past.
+ *
+ * The fold is `:host([max="N"]) ::slotted(:nth-child(n + N+1))`, one selector
+ * per value, because `An+B` takes a literal and no custom property can be read
+ * into it. So the range is finite and this is where it is written down, in the
+ * tier that has to agree with it: a count that folds and a stylesheet that does
+ * not would put a "+5" beside five avatars that are still on screen.
+ */
+export const FOLDS_UP_TO = 12;
+/**
+ * @summary Overlapping avatars, with a count for the ones not shown.
+ *
+ * @description
+ * A part of `Avatar` rather than a family of its own: it arranges avatars and
+ * is about nothing else, and its member is a complete `Avatar` the group did
+ * not have to explain.
+ *
+ * **The overflow count is the group's, not a slot.** Which avatars are hidden
+ * is a fact the group works out from `max` and how many it was given, so a
+ * consumer writing the "+3" themselves would be writing a number that has to
+ * agree with a list they do not control.
+ *
+ * **Hidden, not removed.** Past `max`, the extra avatars stay in the DOM and
+ * stop being shown, so nothing re-renders when `max` changes and the accessible
+ * name can still be built from all of them. The count is what a sighted reader
+ * gets; the group's own name is what everyone else gets, and "Seven people" is
+ * more useful than seven names read in a row.
+ *
+ * **And hidden by the stylesheet, not by this class.** It wrote `data-overflow`
+ * onto each avatar from `updated`, which is one update too late and one element
+ * too far out: Lit renders on a microtask, so an avatar appended past the limit
+ * was laid out and painted before anything ran to hide it, and the group was
+ * writing attributes onto markup a consumer owns to do it. Measured in Chrome
+ * 148, appending two past `max="3"` and reading before yielding: five `flex`,
+ * folding to three on the next update. The styled tier now does it with
+ * `:host([max="N"]) ::slotted(:nth-child(n + N+1))`, which is right at the
+ * first style resolution and writes nothing.
+ *
+ * **The fold is finite, and the count agrees with it.** `An+B` takes a literal,
+ * so there is one selector per value of `max` and the range stops at twelve.
+ * Past that the group shows everyone, counts nothing and says so, because
+ * showing everyone is a defensible answer and showing everyone beside a "+5" is
+ * not. `max` above twelve is a list the consumer should be slicing themselves.
+ *
+ * **It is a list.** A row of faces is a set of separate people, and a group
+ * with no role announces as one run of text. `role="list"` needs its children
+ * to be `listitem`, which they cannot be told to become without writing an
+ * attribute onto a consumer's element, so the group carries `role="group"` and
+ * its name instead: one announcement, correct, and nothing written to anyone
+ * else's markup.
+ *
+ * @since 0.1.0
+ * @status stable
+ * @aliases Avatar stack, Facepile
+ * @documentation https://helix.fusion.dev/components/avatar
+ *
+ * @slot - The avatars, in the order they should be read.
+ *
+ * @csspart overflow - The count of avatars past `max`.
+ */
+let HelixHeadlessAvatarGroup = class HelixHeadlessAvatarGroup extends HelixElement {
+    constructor() {
+        super(...arguments);
+        /**
+         * Accessible name for the set, such as "Reviewers".
+         */
+        this.label = '';
+        /** Said once per element, because a re-render is not a second mistake. */
+        this.warned = false;
+    }
+    /** The avatars, in light-DOM order. Empty on the server, which has no tree. */
+    get avatars() {
+        /* `?? []` is the server: Lit's element shim carries attributes and not a
+           tree, so `children` is undefined there and spreading it throws. The same
+           fault the menu item, the table and the carousel each had in turn, which
+           is why it is written before it can happen again. */
+        return [...(this.children ?? [])].filter((child) => child instanceof HTMLElement);
+    }
+    /**
+     * How many avatars are past the limit, and so not shown.
+     *
+     * Not `hidden`, which is `HTMLElement`'s own boolean: a getter of that name
+     * returning a number is a type error, and had it been assignable it would
+     * have been worse, because a group with three extra members would have set
+     * the attribute that hides the whole group.
+     */
+    get overflow() {
+        const limit = this.max ?? 0;
+        const limited = limit > 0 && limit <= FOLDS_UP_TO;
+        return limited ? Math.max(this.avatars.length - limit, 0) : 0;
+    }
+    willUpdate(changed) {
+        super.willUpdate(changed);
+        hostAria(this.internals, { label: this.label, role: 'group' });
+    }
+    updated(changed) {
+        super.updated(changed);
+        /* Nothing hides anything here any more: the stylesheet does it, from `max`
+           on the host, so the arrangement is right at the first style resolution
+           rather than one update later. What is left is saying so when a `max` is
+           set that no rule can match, because showing everyone is a defensible
+           answer and showing everyone beside a "+5" is not. */
+        const limit = this.max ?? 0;
+        if (limit > FOLDS_UP_TO && this.avatars.length > limit && !this.warned) {
+            this.warned = true;
+            console.warn(`<${this.localName}> has max="${this.max}", past the ${FOLDS_UP_TO} the fold is written for, ` +
+                'so every avatar is shown and none are counted. Lower `max`, or hand the group the ' +
+                'avatars you want shown.');
+        }
+    }
+    render() {
+        const past = this.overflow;
+        return html `<slot @slotchange=${() => this.requestUpdate()}></slot>
+      ${past > 0 ? html `<span part="overflow" aria-hidden="true">+${past}</span>` : ''}`;
+    }
+};
+__decorate([
+    property()
+], HelixHeadlessAvatarGroup.prototype, "label", void 0);
+__decorate([
+    property({ reflect: true, type: Number })
+], HelixHeadlessAvatarGroup.prototype, "max", void 0);
+HelixHeadlessAvatarGroup = __decorate([
+    customElement('helix-headless-avatar-group')
+], HelixHeadlessAvatarGroup);
+export { HelixHeadlessAvatarGroup };

package/dist/avatar/index.d.ts

@@ -0,0 +1,2 @@
+export * from './group/avatar-group.js';
+export * from './root/avatar-root.js';

package/dist/avatar/index.js

@@ -0,0 +1,2 @@
+export * from './group/avatar-group.js';
+export * from './root/avatar-root.js';