@fusion.dev/helix-headless 0.2.0 → 0.3.0

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

@@ -10,64 +10,14 @@ import { html, nothing } from 'lit';
 import { property } from 'lit/decorators.js';
 import { unsafeSVG } from 'lit/directives/unsafe-svg.js';
 import { HelixHeadlessAccordion } from '../root/accordion-root.js';
-/** Shadow-DOM id linking the trigger's aria-controls to the content region. */
 const CONTENT_ID = 'content';
-/**
- * Shadow-DOM id of the trigger, used to name the content region.
- *
- * A `role="region"` with no accessible name is not exposed as a landmark by
- * screen readers and is flagged by every automated audit, so the region borrows
- * the trigger's text. Both ids live in the same shadow root, so the reference
- * resolves; an IDREF pointing at the light DOM never would.
- */
 const TRIGGER_ID = 'trigger';
-/**
- * @summary One collapsible section of an accordion.
- *
- * @description
- * Carries its own open state, which is why it is an element rather than a slot.
- * Used alone, outside an accordion, it is a disclosure.
- *
- * Content stays mounted when closed, so it can animate and so the text is
- * present in server-rendered HTML. Closed content carries both `hidden` and
- * `inert`: the first collapses it with no stylesheet in play, the second keeps
- * it out of the tab order and the accessibility tree once the styled tier's
- * `display` has overridden the first.
- *
- * @since 0.1.0
- * @status experimental
- * @aliases Collapsible, Expander, Disclosure
- * @documentation https://helix.fusion.dev/components/accordion
- *
- * @slot - The content revealed when open.
- * @slot summary - The always-visible trigger content.
- *
- * @event {HelixBeforeCloseEvent} helix-before-close - Fired before the section closes, and cancelable.
- * @event {HelixBeforeOpenEvent} helix-before-open - Fired before the section opens. Cancelable: refusing it takes the decision and nothing moves.
- * @event {Event} toggle - Says the state moved, carrying `newState` and `oldState`.
- *
- * @csspart chevron - The open and close indicator.
- * @csspart container - The outer wrapper.
- * @csspart content - The revealed region.
- * @csspart content-inner - The clipping box inside the animated region.
- * @csspart trigger - The clickable summary row.
- */
 let HelixHeadlessAccordionItem = class HelixHeadlessAccordionItem extends MixinControllerOpen(HelixElement) {
     constructor() {
         super(...arguments);
-        /**
-         * Opens or closes this item, and enforces the accordion's mode.
-         *
-         * The item that was clicked is the coordinator. It refuses first, then
-         * announces, then applies, then closes its peers, in that order: closing a
-         * peer before knowing whether this change was even allowed would leave the
-         * set collapsed after a listener refused it.
-         */
         this.handleToggle = () => {
             const next = !this.open;
             const mode = this.accordion?.mode;
-            // `single` keeps one open at all times, so the last one cannot be closed.
-            // `single-collapsible` is the same rule without that floor.
             if (!next && mode === 'single') {
                 return;
             }
@@ -77,15 +27,12 @@ let HelixHeadlessAccordionItem = class HelixHeadlessAccordionItem extends MixinC
             if (next && (mode !== undefined || (this.name !== undefined && this.name !== ''))) {
                 for (const peer of this.peers) {
                     if (peer !== this && peer.open) {
-                        // A peer whose consumer refuses the request stays open, which can
-                        // legitimately leave two open.
                         peer.requestOpen(false);
                     }
                 }
             }
         };
     }
-    /** The chevron, or nothing when suppressed. */
     renderChevron() {
         if (this.chevronPlacement === 'none') {
             return nothing;
@@ -94,30 +41,11 @@ let HelixHeadlessAccordionItem = class HelixHeadlessAccordionItem extends MixinC
       ${unsafeSVG(caretDown.content)}
     </svg>`;
     }
-    /**
-     * The nearest accordion above this item, if there is one.
-     *
-     * Resolved on demand rather than held, so an item moved between accordions
-     * coordinates with the one it is in now. `closest` crosses no shadow
-     * boundary, which is correct: an item inside another item's content is in
-     * that item's light DOM and finds the same accordion, so the check below is
-     * what keeps it independent.
-     */
     get accordion() {
         return closestInstance(this, HelixHeadlessAccordion);
     }
-    /**
-     * The items this one coordinates with: its own siblings, and only those.
-     *
-     * Direct children only. An accordion nested inside an item's content is a
-     * separate set, and opening a section in it must not close anything outside.
-     */
     get peers() {
         if (this.name !== undefined && this.name !== '') {
-            /* By name, across the whole root rather than one accordion, which is what
-               `<details name>` means. `getRootNode()` so an item inside a shadow tree
-               finds its group there rather than reaching into the document, which is
-               the same boundary every IDREF in this library respects. */
             const root = this.getRootNode();
             return [
                 ...root.querySelectorAll(`${this.localName}[name="${CSS.escape(this.name)}"]`),
@@ -129,45 +57,9 @@ let HelixHeadlessAccordionItem = class HelixHeadlessAccordionItem extends MixinC
         }
         return accordion.items;
     }
-    /**
-     * Moves focus to this item's trigger.
-     *
-     * The parent accordion drives arrow-key navigation and cannot reach the
-     * trigger itself, because it is inside this item's shadow root. Exposing the
-     * intent as a method keeps the parent out of the child's internals.
-     */
     focusTrigger() {
         this.renderRoot.querySelector(`#${TRIGGER_ID}`)?.focus();
     }
-    /**
-     * The item, with `hidden` doing the collapsing.
-     *
-     * **A closed section has to be closed with no stylesheet at all**, which is
-     * the whole claim `headless` makes. `inert` alone is not that: it takes the
-     * region out of the accessibility tree and off the tab order and leaves every
-     * pixel of it on the screen, so a consumer taking this tier gets sections of
-     * text permanently open under a trigger saying `aria-expanded="false"`, and a
-     * sighted reader sees content a screen reader is told is not there. Leaving
-     * the collapse to the styled tier's `grid-template-rows: 0fr` puts the state
-     * in a stylesheet, where only one of the two tiers has it.
-     *
-     * **`hidden` costs the styled tier nothing**, which is what makes this the
-     * cheap fix rather than a trade. The UA sheet hides `[hidden]` from the UA
-     * origin, and `accordion-item.css` already sets `display: grid` on this part
-     * unconditionally, so the author rule wins and the 0fr 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`, so the styled tier's `display: grid` would no longer
-     * override it and a collapsed section would animate open to nothing. It also
-     * needs a `beforematch` handler to set `open`, or find-in-page reveals text
-     * while the trigger still reports collapsed.
-     *
-     * `inert` stays. `hidden` answers the reader who can see and `inert` answers
-     * the one tabbing through, and in the styled tier, where `display` is
-     * overridden, `inert` is the only one of the two still in force.
-     */
     render() {
         const open = this.open;
         return html `

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

@@ -8,38 +8,7 @@ import { customElement, HelixElement } from '@fusion.dev/helix-core';
 import { html } from 'lit';
 import { property } from 'lit/decorators.js';
 import { HelixHeadlessAccordionItem } from '../item/accordion-item.js';
-/** Keys that move focus between triggers, per the APG accordion pattern. */
 const NAVIGATION = new Set(['ArrowDown', 'ArrowUp', 'Home', 'End']);
-/**
- * @summary Groups collapsible sections, one open at a time by default.
- *
- * @description
- * Holds the mode and nothing else. The item that was clicked is what
- * coordinates: it walks up to the nearest accordion, reads the mode off it, and
- * closes its peers itself.
- *
- * Coordination is structural, not a subscription. `helix-before-open` does not bubble
- * and is not composed, because overlays nest and an inner one's lifecycle must
- * never read as the outer one's, so an accordion cannot learn that a child
- * opened by listening for it.
- *
- * Membership resolves on demand, so there is no registry to keep in step: an
- * item added a second after render coordinates on its first click.
- *
- * Items are matched with `instanceof HelixHeadlessAccordionItem`, never by tag
- * name. Matching `helix-accordion-item` would tie this tier to the styled one.
- *
- * Every listener is attached on connect, so none of it runs on the server,
- * where there is no tree to walk and no events to hear.
- *
- * @since 0.1.0
- * @status experimental
- * @category layout
- * @aliases Collapse, Expander group
- * @documentation https://helix.fusion.dev/components/accordion
- *
- * @slot - The accordion's items.
- */
 let HelixHeadlessAccordion = class HelixHeadlessAccordion extends HelixElement {
     constructor() {
         super(...arguments);
@@ -66,12 +35,10 @@ let HelixHeadlessAccordion = class HelixHeadlessAccordion extends HelixElement {
             else {
                 next = last;
             }
-            // Only once a move is certain, so an unhandled key still scrolls the page.
             event.preventDefault();
             items[next]?.focusTrigger();
         };
     }
-    /** Direct items, in light-DOM order. Client only: the server has no tree. */
     get items() {
         return [...this.children].filter((child) => child instanceof HelixHeadlessAccordionItem);
     }

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

@@ -9,50 +9,9 @@ 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';
     }
@@ -60,39 +19,12 @@ let HelixHeadlessAnnouncement = class HelixHeadlessAnnouncement extends MixinDis
         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.
-     *
-     * Not `renderIcon`, which is what `Toast` and `Callout` call the method that
-     * draws a tone mark. 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">
@@ -103,14 +35,7 @@ let HelixHeadlessAnnouncement = class HelixHeadlessAnnouncement extends MixinDis
     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. Never a nested component
-           here: `[part="dismiss"]` would select the host and stop at its shadow
-           boundary, so the styled tier could not reach the inner control at
-           all, and the parent would depend invisibly on the child being
-           registered. */
-        this.dismissible
+      ${this.dismissible
             ? html `<button
               part="dismiss"
               type="button"

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

@@ -7,87 +7,10 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 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 never `data-scrolled`.** An attribute the element writes
- * onto its own host is one the server did not send, so a hydrating framework
- * reports the tree as mismatched, intermittently: only when the reader reloads
- * far enough down the page to pass the threshold. A consumer can answer that
- * only 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
-           custom state 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 toggles the state, and the fill and the blur
-         * are both transitioned, so each toggle starts 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;
@@ -95,23 +18,16 @@ let HelixHeadlessAppHeader = class HelixHeadlessAppHeader extends HelixElement {
                 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. */
             this.toggleState('scrolled', next);
             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();
     }

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

@@ -7,89 +7,16 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 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.** Hiding from `updated` is
- * one update too late and one element too far out: Lit renders on a microtask,
- * so an avatar appended past the limit is laid out and painted before anything
- * runs to hide it, and marking each one means writing attributes onto markup a
- * consumer owns. The styled tier's
- * `:host([max="N"]) ::slotted(:nth-child(n + N+1))` 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. */
         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;
@@ -101,10 +28,6 @@ let HelixHeadlessAvatarGroup = class HelixHeadlessAvatarGroup extends HelixEleme
     }
     updated(changed) {
         super.updated(changed);
-        /* Nothing hides anything here: the stylesheet does it, from `max` on the
-           host. 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;

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

@@ -7,72 +7,21 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 import { customElement, HelixElement, hostAria } from '@fusion.dev/helix-core';
 import { html } from 'lit';
 import { property, state } from 'lit/decorators.js';
-/** Initials for a name: first letter of the first and last words. */
 export const initialsOf = (name) => {
     const words = name.trim().split(/\s+/).filter(Boolean);
     if (words.length === 0) {
         return '';
     }
-    /* By code point, not by code unit.
-     *
-     * `word[0]` indexes UTF-16, so a name beginning with anything outside the
-     * basic plane, an emoji or most of the world's less common scripts, yields a
-     * lone surrogate and the avatar paints U+FFFD. Spreading a string iterates
-     * code points, which is what a first letter means. */
     const initial = (word) => [...(word ?? '')][0] ?? '';
     const first = initial(words[0]);
     const last = words.length > 1 ? initial(words[words.length - 1]) : '';
     return (first + last).toUpperCase();
 };
-/**
- * @summary Represents a person or entity with an image or their initials.
- *
- * @description
- * Shows `src` until it fails to load. Without an image, or after a failure,
- * the default slot is shown; its own fallback is the initials.
- *
- * The host carries the accessible name, taken from `name`, so the `<img>` has an
- * empty `alt` and the initials are hidden from assistive technology. Announcing
- * either would repeat the name. An `aria-label` on the host overrides `name`,
- * for an avatar standing for something a person's name does not describe.
- *
- * `load` and `error` are relayed from the host. They are not composed, so they
- * stop at the shadow boundary otherwise.
- *
- * @since 0.1.0
- * @status stable
- * @category media
- * @aliases Profile picture, Gravatar
- * @documentation https://helix.fusion.dev/components/avatar
- *
- * @slot - Shown when there is no usable image, in place of the initials.
- *
- * @event {Event} error - Relayed from the image when it fails.
- * @event {Event} load - Relayed from the image once it has loaded.
- *
- * @csspart image - The image, when one is loading or loaded.
- * @csspart initials - The initials shown when there is no usable image.
- */
 let HelixHeadlessAvatar = class HelixHeadlessAvatar extends HelixElement {
     constructor() {
         super(...arguments);
-        /**
-         * Name of the person or entity.
-         *
-         * Used for the label and the initials.
-         */
         this.name = '';
-        /**
-         * Image to show.
-         *
-         * Falls back to the slot, or to initials, if it fails.
-         */
         this.src = '';
-        /**
-         * Whether the image failed.
-         *
-         * The element's own observation, never set.
-         */
         this.failed = false;
         this.handleError = (event) => {
             this.failed = true;
@@ -84,22 +33,9 @@ let HelixHeadlessAvatar = class HelixHeadlessAvatar extends HelixElement {
     }
     willUpdate(changed) {
         super.willUpdate(changed);
-        /* A new source is a new attempt.
-         *
-         * `failed` is an observation about the image that was loading, so it has to
-         * be cleared with the source. Latched, an avatar that failed once falls back
-         * to initials for the life of the element, and a consumer swapping a broken
-         * URL for a good one, or a list reusing an avatar for the next person, gets
-         * the initials forever with no error to say why. */
         if (changed.has('src')) {
             this.failed = false;
         }
-        /* A role only where there is a name to carry.
-         *
-         * An unconditional `role="img"` makes an avatar with no `name` an unnamed
-         * image: a screen reader announces "image" and stops, which is worse than
-         * announcing nothing, because nothing is what a decorative mark should be.
-         * With a name it is content and needs the role to hold it. */
         hostAria(this.internals, {
             label: this.name,
             role: this.name === '' ? '' : 'img',
@@ -117,14 +53,6 @@ let HelixHeadlessAvatar = class HelixHeadlessAvatar extends HelixElement {
         }
         return this.renderInitials();
     }
-    /**
-     * The mark shown where no image loaded, behind a seam a tier can move.
-     *
-     * A consumer replaces it by slotting something; a tier above replaces it by
-     * overriding this, and those answer different people. Written inline it
-     * answers only the first, and a styled tier wanting initials drawn its own way
-     * has to reimplement the whole template to reach three elements.
-     */
     renderInitials() {
         return html `<slot>
       <span part="initials" aria-hidden="true">${initialsOf(this.name)}</span>