@fusion.dev/helix-headless 0.0.0-dev → 0.0.3

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

@@ -8,10 +8,11 @@ declare const HelixHeadlessAccordionItem_base: (new (...args: any[]) => import("
  * 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 and is hidden by the styled tier's CSS, so
- * it can animate and so the text is present in server-rendered HTML. Closed
- * content is `inert`, keeping it out of the tab order and the accessibility
- * tree without removing it from the box tree.
+ * 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
@@ -22,7 +23,7 @@ declare const HelixHeadlessAccordionItem_base: (new (...args: any[]) => import("
  * @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 item opens or closes. Cancelable: refusing it takes the decision and nothing moves.
+ * @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.
@@ -103,22 +104,19 @@ export declare class HelixHeadlessAccordionItem extends HelixHeadlessAccordionIt
      * 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 was not that: it takes the
+     * 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 got two sections
-     * of text permanently open with a trigger underneath saying
-     * `aria-expanded="false"`. Worse than merely unstyled: a sighted reader saw
-     * content a screen reader was told is not there.
-     *
-     * The collapse was living in the styled tier's `grid-template-rows: 0fr`,
-     * which is an animation and was doing the hiding as a side effect. So the
-     * state was in a stylesheet, and only one of the two tiers had it.
+     * 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 both tiers after the change.
+     * 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

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

@@ -28,10 +28,11 @@ const TRIGGER_ID = 'trigger';
  * 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 and is hidden by the styled tier's CSS, so
- * it can animate and so the text is present in server-rendered HTML. Closed
- * content is `inert`, keeping it out of the tab order and the accessibility
- * tree without removing it from the box tree.
+ * 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
@@ -42,7 +43,7 @@ const TRIGGER_ID = 'trigger';
  * @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 item opens or closes. Cancelable: refusing it takes the decision and nothing moves.
+ * @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.
@@ -76,8 +77,8 @@ 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 in controlled mode will only notify: its consumer owns the
-                        // value and may decline, which can legitimately leave two open.
+                        // A peer whose consumer refuses the request stays open, which can
+                        // legitimately leave two open.
                         peer.requestOpen(false);
                     }
                 }
@@ -142,22 +143,19 @@ let HelixHeadlessAccordionItem = class HelixHeadlessAccordionItem extends MixinC
      * 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 was not that: it takes the
+     * 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 got two sections
-     * of text permanently open with a trigger underneath saying
-     * `aria-expanded="false"`. Worse than merely unstyled: a sighted reader saw
-     * content a screen reader was told is not there.
-     *
-     * The collapse was living in the styled tier's `grid-template-rows: 0fr`,
-     * which is an animation and was doing the hiding as a side effect. So the
-     * state was in a stylesheet, and only one of the two tiers had it.
+     * 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 both tiers after the change.
+     * 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

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

@@ -45,25 +45,11 @@ export declare class HelixHeadlessAnnouncement extends HelixHeadlessAnnouncement
     /**
      * Which color the band wears.
      *
-     * **This was `severity` and it was claiming more than it did.** Severity is a
-     * judgment about the message, and elsewhere in this library it carries one:
-     * `Callout` reads `TONE_MARKS` for an icon and a label, so `tone="danger"`
-     * puts a mark beside the text and names it to a screen reader. Here it did
-     * none of that. It set a color, the live region stayed polite either way, and
-     * nothing about the announcement's semantics moved. A property that only
-     * changes the paint should say so.
-     *
-     * `tone` is the word this library already uses for exactly that, and `Tag`
-     * made the identical rename for the identical reason: the word it left was a
-     * treatment, `tone` is semantic color. The set matches `Tag`'s so the two
-     * agree, with `neutral` as the resting value and `primary` for a band that is
-     * about the product rather than about a state.
-     *
-     * `neutral` is what an unset announcement already looked like, said out loud
-     * so a consumer can put a band back to it from markup, and `surface` is the
-     * one value that is not a color: it lifts the band onto the surface step
-     * instead of the sunken one, for a strip carrying something that is not a
-     * state at all.
+     * Paint only: unlike `Callout`, no value here draws a mark, changes the label,
+     * or moves the live region off polite. The set matches `Tag`'s. `neutral` is
+     * the resting value, said out loud so a consumer can put a band back to it
+     * from markup, and `surface` is the one value that is not a color: it lifts
+     * the band onto the surface step instead of the sunken one.
      */
     tone?: 'danger' | 'info' | 'neutral' | 'primary' | 'success' | 'surface' | 'warning';
     protected willUpdate(changed: PropertyValues): void;
@@ -88,12 +74,8 @@ export declare class HelixHeadlessAnnouncement extends HelixHeadlessAnnouncement
      * 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.
+     * Not `renderIcon`, which is what `Toast` and `Callout` call the method that
+     * draws a tone mark. An announcement has no tone mark at all.
      */
     protected renderDismissIcon(): TemplateResult;
     protected render(): TemplateResult;

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

@@ -90,12 +90,8 @@ let HelixHeadlessAnnouncement = class HelixHeadlessAnnouncement extends MixinDis
      * 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.
+     * 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">
@@ -109,20 +105,11 @@ let HelixHeadlessAnnouncement = class HelixHeadlessAnnouncement extends MixinDis
       <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. */
+           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
             ? html `<button
               part="dismiss"

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

@@ -11,15 +11,11 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * 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.
- *
+ * **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
@@ -73,12 +69,9 @@ export declare class HelixHeadlessAppHeader extends HelixElement {
      *
      * `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.
+     * **Named for the region and not for what is usually in it.** The middle slot
+     * takes a search field or a breadcrumb trail as readily as a `Navigation`, so
+     * the property carries the part's name, `content`.
      */
     contentAlign?: 'start';
     private scrolled;
@@ -90,8 +83,8 @@ export declare class HelixHeadlessAppHeader extends HelixElement {
      * 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
+     * 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.
      *

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

@@ -18,15 +18,11 @@ import { property } from 'lit/decorators.js';
  * 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.
- *
+ * **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
@@ -72,7 +68,7 @@ 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. */
+           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.
@@ -82,8 +78,8 @@ let HelixHeadlessAppHeader = class HelixHeadlessAppHeader extends HelixElement {
          * 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
+         * 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.
          *
@@ -102,12 +98,7 @@ let HelixHeadlessAppHeader = class HelixHeadlessAppHeader extends HelixElement {
             /* 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.toggleState('scrolled', next);
             this.dispatchEvent(new HelixScrolledEvent({ scrolled: next }));
         };
     }

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

@@ -29,15 +29,13 @@ export declare const FOLDS_UP_TO = 12;
  * 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.
+ * **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.
@@ -76,16 +74,9 @@ export declare class HelixHeadlessAvatarGroup extends HelixElement {
      * 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.
+     * count claiming some are hidden. Markup is the safe path and hides the fault;
+     * a script is the broken one, and React takes it for everyone, assigning a
+     * matching property rather than an attribute.
      *
      * **Optional rather than defaulted, per the rule that a reflected property
      * takes no default**: `max = 0` would stamp `max="0"` onto every host that

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

@@ -36,15 +36,13 @@ export const FOLDS_UP_TO = 12;
  * 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.
+ * **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.
@@ -81,9 +79,7 @@ let HelixHeadlessAvatarGroup = class HelixHeadlessAvatarGroup extends HelixEleme
     /** 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. */
+           tree, so `children` is undefined there and spreading it throws. */
         return [...(this.children ?? [])].filter((child) => child instanceof HTMLElement);
     }
     /**
@@ -105,11 +101,10 @@ let HelixHeadlessAvatarGroup = class HelixHeadlessAvatarGroup extends HelixEleme
     }
     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. */
+        /* 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.d.ts

@@ -32,18 +32,18 @@ export declare const initialsOf: (name: string) => string;
  * @csspart initials - The initials shown when there is no usable image.
  */
 export declare class HelixHeadlessAvatar extends HelixElement {
-    /**
-     * Image to show.
-     *
-     * Falls back to the slot, or to initials, if it fails.
-     */
-    src: string;
     /**
      * Name of the person or entity.
      *
      * Used for the label and the initials.
      */
     name: string;
+    /**
+     * Image to show.
+     *
+     * Falls back to the slot, or to initials, if it fails.
+     */
+    src: string;
     /**
      * Whether the image failed.
      *
@@ -59,8 +59,8 @@ export declare class HelixHeadlessAvatar extends HelixElement {
      *
      * A consumer replaces it by slotting something; a tier above replaces it by
      * overriding this, and those answer different people. Written inline it
-     * answered only the first, and a styled tier wanting initials drawn its own
-     * way had to reimplement the whole template to reach three elements.
+     * answers only the first, and a styled tier wanting initials drawn its own way
+     * has to reimplement the whole template to reach three elements.
      */
     protected renderInitials(): TemplateResult;
 }

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

@@ -56,18 +56,18 @@ export const initialsOf = (name) => {
 let HelixHeadlessAvatar = class HelixHeadlessAvatar extends HelixElement {
     constructor() {
         super(...arguments);
-        /**
-         * Image to show.
-         *
-         * Falls back to the slot, or to initials, if it fails.
-         */
-        this.src = '';
         /**
          * 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.
          *
@@ -86,21 +86,20 @@ let HelixHeadlessAvatar = class HelixHeadlessAvatar extends HelixElement {
         super.willUpdate(changed);
         /* A new source is a new attempt.
          *
-         * `failed` is an observation about the image that was loading, and it
-         * outlived the image: it latched on the first error and nothing ever
-         * cleared it, so an avatar that failed once fell back to initials for the
-         * life of the element. A consumer swapping a broken URL for a good one, or
-         * a list reusing an avatar for the next person, got the initials forever
-         * and no error to say why. */
+         * `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.
          *
-         * `role="img"` was asserted unconditionally, so an avatar with no `name`
-         * was 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. */
+         * 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',
@@ -123,8 +122,8 @@ let HelixHeadlessAvatar = class HelixHeadlessAvatar extends HelixElement {
      *
      * A consumer replaces it by slotting something; a tier above replaces it by
      * overriding this, and those answer different people. Written inline it
-     * answered only the first, and a styled tier wanting initials drawn its own
-     * way had to reimplement the whole template to reach three elements.
+     * 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>
@@ -134,10 +133,10 @@ let HelixHeadlessAvatar = class HelixHeadlessAvatar extends HelixElement {
 };
 __decorate([
     property()
-], HelixHeadlessAvatar.prototype, "src", void 0);
+], HelixHeadlessAvatar.prototype, "name", void 0);
 __decorate([
     property()
-], HelixHeadlessAvatar.prototype, "name", void 0);
+], HelixHeadlessAvatar.prototype, "src", void 0);
 __decorate([
     state()
 ], HelixHeadlessAvatar.prototype, "failed", void 0);

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

@@ -31,11 +31,11 @@ import { type TemplateResult } from 'lit';
  */
 export declare class HelixHeadlessBadge extends HelixElement {
     /**
-     * The count or short text to show.
+     * Accessible name.
      *
-     * Absent shows a dot, zero shows nothing.
+     * Required for a dot, which has no text to read.
      */
-    value: string;
+    label: string;
     /**
      * Cap for a numeric value.
      *
@@ -43,11 +43,11 @@ export declare class HelixHeadlessBadge extends HelixElement {
      */
     max?: number;
     /**
-     * Accessible name.
+     * The count or short text to show.
      *
-     * Required for a dot, which has no text to read.
+     * Absent shows a dot, zero shows nothing.
      */
-    label: string;
+    value: string;
     /** Whether the value counts nothing, in which case there is no mark. */
     private get blank();
     /** What the indicator reads, once the cap has been applied. */

package/dist/badge/root/badge-root.js

@@ -39,18 +39,18 @@ import { property } from 'lit/decorators.js';
 let HelixHeadlessBadge = class HelixHeadlessBadge extends HelixElement {
     constructor() {
         super(...arguments);
-        /**
-         * The count or short text to show.
-         *
-         * Absent shows a dot, zero shows nothing.
-         */
-        this.value = '';
         /**
          * Accessible name.
          *
          * Required for a dot, which has no text to read.
          */
         this.label = '';
+        /**
+         * The count or short text to show.
+         *
+         * Absent shows a dot, zero shows nothing.
+         */
+        this.value = '';
     }
     /** Whether the value counts nothing, in which case there is no mark. */
     get blank() {
@@ -70,11 +70,11 @@ let HelixHeadlessBadge = class HelixHeadlessBadge extends HelixElement {
         /* A mark with text is content and is announced; a dot is decoration and is
            not.
          *
-         * This asked for a `label` as well, so a badge showing a count and no label
-         * was `aria-hidden` and the number it exists to show reached nobody using a
-         * screen reader. The number is its own name where none is given, which is
-         * why `aria-label` is now conditional on the label rather than on this: a
-         * `4` announces as "4" from the text, and `label="4 unread"` says the
+         * It must not ask for a `label` as well, or a badge showing a count and no
+         * label is `aria-hidden` and the number it exists to show reaches nobody
+         * using a screen reader. The number is its own name where none is given,
+         * which is why `aria-label` is conditional on the label rather than on this:
+         * a `4` announces as "4" from the text, and `label="4 unread"` says the
          * better thing.
          *
          * A dot with no label still says nothing, which is the deliberate half: a
@@ -108,13 +108,13 @@ let HelixHeadlessBadge = class HelixHeadlessBadge extends HelixElement {
 };
 __decorate([
     property()
-], HelixHeadlessBadge.prototype, "value", void 0);
+], HelixHeadlessBadge.prototype, "label", void 0);
 __decorate([
     property({ type: Number })
 ], HelixHeadlessBadge.prototype, "max", void 0);
 __decorate([
     property()
-], HelixHeadlessBadge.prototype, "label", void 0);
+], HelixHeadlessBadge.prototype, "value", void 0);
 HelixHeadlessBadge = __decorate([
     customElement('helix-headless-badge')
 ], HelixHeadlessBadge);