@fusion.dev/helix-headless 0.146.0 → 0.147.0

package/dist/megamenu/hand-over.d.ts

@@ -0,0 +1,75 @@
+/** Which way a panel moved when another took its place along the bar. */
+export type Motion = 'from-end' | 'from-start' | 'to-end' | 'to-start';
+/** What a hand-over asks of a megamenu. */
+export interface Handed extends Node {
+    /** Asks the panel to open or close, and returns whether it did. */
+    requestOpen(open: boolean): boolean;
+}
+/**
+ * The bar's one open panel, handed from one megamenu to the next.
+ *
+ * A page has one panel open at a time: a nav bar whose Products panel is still
+ * down while Solutions opens is a nav bar with two panels over the page. Module
+ * scope rather than a coordinating parent, because there is nothing to
+ * coordinate through: megamenus sit in whatever container the consumer used,
+ * which is usually `Navigation` and is not required to be. `Video` holds the
+ * media session the same way and for the same reason.
+ *
+ * When one panel opens in place of another, each is told which way the reader
+ * moved, as Radix's `data-motion` does: toward the end of the bar where the
+ * one opening comes after the one closing in the document. The one opening
+ * enters from the side the reader moved toward, and the one closing leaves
+ * toward the side they came from. Only the latest move is ever described.
+ */
+export declare class HandOver<T extends Handed> {
+    private readonly motion;
+    /**
+     * Every megamenu on the page, so a press on another one's trigger counts as
+     * moving along the bar. Closing on that press would close this panel before
+     * the other opens, and the hand-over would have no direction.
+     */
+    readonly connected: Set<T>;
+    /** The panel showing now, so opening one closes the last. */
+    showing: T | undefined;
+    /**
+     * The megamenu a pointer is pressing, from the press until the click that
+     * ends it. A press moves focus before the click opens anything, and the open
+     * panel must not close on that focus move, or the hand-over has no direction.
+     */
+    pressed: T | undefined;
+    /** The panels closing because another opened in their place. */
+    private readonly handed;
+    /** @param motion Writes a megamenu's direction, and clears it for `undefined`. */
+    constructor(motion: (megamenu: T, to: Motion | undefined) => void);
+    /** Counts a megamenu as part of the bar. */
+    add(megamenu: T): void;
+    /** Stops counting a megamenu that left the page. */
+    remove(megamenu: T): void;
+    /**
+     * Forgets the press a task after it ends, so the click it makes still finds
+     * it. One function for every press, so a listener added again is the same
+     * listener and never a second one.
+     */
+    private readonly release;
+    /**
+     * The megamenus that share this one's parent, in document order: the bar it
+     * is one trigger of.
+     */
+    alongside(megamenu: T): T[];
+    /** Notes a press on a megamenu, until the press ends. */
+    press(megamenu: T): void;
+    /**
+     * Opens one panel in place of the one showing, and returns that one, if
+     * there was one. The other closes through `requestOpen`, so a consumer
+     * holding it open is asked rather than overruled, and a refusal clears its
+     * direction again.
+     */
+    open(opening: T): T | undefined;
+    /**
+     * Notes a panel closing. One that closed on its own moved nowhere, and
+     * neither did any other, so every direction clears.
+     */
+    close(closing: T): void;
+    /** Clears the direction of every megamenu but the ones moving. */
+    private settle;
+}

package/dist/megamenu/hand-over.js

@@ -0,0 +1,67 @@
+export class HandOver {
+    constructor(motion) {
+        this.motion = motion;
+        this.connected = new Set();
+        this.handed = new Set();
+        this.release = () => {
+            setTimeout(() => {
+                this.pressed = undefined;
+            });
+        };
+    }
+    add(megamenu) {
+        this.connected.add(megamenu);
+    }
+    remove(megamenu) {
+        this.connected.delete(megamenu);
+        this.handed.delete(megamenu);
+        if (this.showing === megamenu) {
+            this.showing = undefined;
+        }
+        if (this.pressed === megamenu) {
+            this.pressed = undefined;
+        }
+    }
+    alongside(megamenu) {
+        return [...this.connected]
+            .filter((other) => other.parentNode === megamenu.parentNode)
+            .sort((a, b) => (a.compareDocumentPosition(b) & Node.DOCUMENT_POSITION_FOLLOWING ? -1 : 1));
+    }
+    press(megamenu) {
+        this.pressed = megamenu;
+        window.addEventListener('pointerup', this.release, { capture: true, once: true });
+        window.addEventListener('pointercancel', this.release, { capture: true, once: true });
+    }
+    open(opening) {
+        const previous = this.showing !== opening ? this.showing : undefined;
+        const forward = previous !== undefined &&
+            (previous.compareDocumentPosition(opening) & Node.DOCUMENT_POSITION_FOLLOWING) !== 0;
+        this.motion(opening, previous ? (forward ? 'from-end' : 'from-start') : undefined);
+        this.settle(opening, previous);
+        if (previous) {
+            this.motion(previous, forward ? 'to-start' : 'to-end');
+            this.handed.add(previous);
+            if (!previous.requestOpen(false)) {
+                this.handed.delete(previous);
+                this.motion(previous, undefined);
+            }
+        }
+        this.showing = opening;
+        return previous;
+    }
+    close(closing) {
+        if (this.showing === closing) {
+            this.showing = undefined;
+        }
+        if (!this.handed.delete(closing)) {
+            this.settle();
+        }
+    }
+    settle(...moving) {
+        for (const megamenu of this.connected) {
+            if (!moving.includes(megamenu)) {
+                this.motion(megamenu, undefined);
+            }
+        }
+    }
+}

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

@@ -1,5 +1,5 @@
-import { HelixElement, PopoverController } from '@fusion.dev/helix-core';
-import { type PropertyValues, type TemplateResult } from 'lit';
+import { HelixElement, KeyboardNavigationController, PopoverController } from '@fusion.dev/helix-core';
+import { nothing, type PropertyValues, type TemplateResult } from 'lit';
 declare const HelixHeadlessMegamenu_base: (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerOpenInterface) & typeof HelixElement;
 /**
  * @summary A section of a navigation with a trigger that opens a panel of links.
@@ -36,8 +36,17 @@ declare const HelixHeadlessMegamenu_base: (new (...args: any[]) => import("@fusi
  * navigation menu publishes the same pair from its shared viewport, so a
  * stylesheet can grow or shrink one panel into the next.
  *
- * Put megamenus in a `Navigation` with `arrows` and the arrow keys move
- * between their triggers. Down Arrow on the trigger of an open panel moves
+ * The panel's default slot is the `columns` part and draws no box, so a sheet
+ * can give the columns one of their own. While a panel is open, an
+ * `indicator` slot is rendered beside its trigger, as Radix's indicator
+ * marks the open one: slot a mark of your own, such as a bar or an arrow
+ * pointing at the panel, and it shows only while the panel is open. The styled
+ * tier rests it on the trigger's bottom edge.
+ *
+ * Left and Right Arrow move between the triggers of the megamenus beside this
+ * one, and Home and End go to the first and the last, as Radix's navigation
+ * menu does. In a `Navigation`, which holds them in a slot, the arrows are the
+ * navigation's, and move between its destinations under its `arrows`. Down Arrow on the trigger of an open panel moves
  * focus to the panel's first link, Escape closes the panel and returns focus
  * to its trigger, and Tab moves through the panel's links and closes it on the
  * way out. The trigger says `aria-expanded`, and the panel is a group named by
@@ -50,12 +59,15 @@ declare const HelixHeadlessMegamenu_base: (new (...args: any[]) => import("@fusi
  * @documentation https://fusion.dev/helix/components/megamenu
  *
  * @slot - The panel's contents, such as your own lists of links and their headings.
+ * @slot indicator - A mark for the open trigger, shown while the panel is open, such as a bar or an arrow pointing at the panel.
  * @slot trigger - The control that opens the panel. When it is empty, a button named by `label` is shown.
  *
  * @event {HelixBeforeCloseEvent} helix-before-close - The panel is about to close. Cancelable.
  * @event {HelixBeforeOpenEvent} helix-before-open - The panel is about to open. Cancelable.
  * @event {ToggleEvent} toggle - The panel opened or closed. Carries `newState` and `oldState`.
  *
+ * @csspart columns - The panel's default slot. It draws no box until a sheet gives it a `display`.
+ * @csspart indicator - The `indicator` slot, rendered while the panel is open.
  * @csspart surface - The floating panel that opens.
  * @csspart trigger - The default trigger button, shown when the `trigger` slot is empty.
  *
@@ -73,6 +85,8 @@ declare const HelixHeadlessMegamenu_base: (new (...args: any[]) => import("@fusi
  * @cssstate to-start - The panel closed because one later in the bar opened, so it can leave toward the start.
  */
 export declare class HelixHeadlessMegamenu extends HelixHeadlessMegamenu_base {
+    /** The bar's one open panel, shared by every megamenu on the page. */
+    private static readonly bar;
     /**
      * The page width, in pixels, below which a card panel is shown as a band. At
      * zero, it never is.
@@ -155,6 +169,17 @@ export declare class HelixHeadlessMegamenu extends HelixHeadlessMegamenu_base {
      * the consumer slotted, or the button drawn in its place.
      */
     get navigationControl(): HTMLElement;
+    /**
+     * The arrows along a bar of megamenus that no component holds in a slot.
+     *
+     * Each megamenu's trigger is one stop, and a press counts only from a
+     * trigger, so an arrow among an open panel's links stays with the panel.
+     * Down and Up are reserved: Down enters an open panel. A megamenu whose
+     * parent is a component, and so holds it in a slot, passes no stops, so a
+     * `Navigation` around it decides the arrows, on or off, for every
+     * destination at once.
+     */
+    protected readonly keys: KeyboardNavigationController;
     /**
      * Down Arrow on the trigger of an open panel moves focus to the panel's first
      * link or control, as Radix's navigation menu does.
@@ -277,18 +302,10 @@ export declare class HelixHeadlessMegamenu extends HelixHeadlessMegamenu_base {
      *
      * Before the render rather than after it, because the popover controller
      * raises the panel from its own `hostUpdated`, which runs before `updated`:
-     * settled there, the two would be up together for a frame. The other closes
-     * through `requestOpen`, so a consumer holding it open is asked rather than
-     * overruled.
+     * settled there, the two would be up together for a frame. The bookkeeping
+     * is `HandOver`'s.
      */
     protected willUpdate(changed: PropertyValues): void;
-    /**
-     * Clears the direction of every panel but the two in a hand-over, so only
-     * the latest move is ever described.
-     */
-    private static settle;
-    /** Whether the panel is closing because another one opened in its place. */
-    private handedOver;
     /** The panel's size the last time it was open, in pixels. */
     private size;
     /** The size of the panel this one took over from, if it took over. */
@@ -312,6 +329,13 @@ export declare class HelixHeadlessMegamenu extends HelixHeadlessMegamenu_base {
      * has one reaches this without reimplementing the panel below it.
      */
     protected renderTrigger(): TemplateResult;
+    /**
+     * The mark under the trigger, while the panel is open. Rendered only then,
+     * so a mark of your own needs no rule to hide it while the panel is closed,
+     * and hidden from the accessibility tree: the trigger's `aria-expanded`
+     * already says the panel is open.
+     */
+    protected renderIndicator(): TemplateResult | typeof nothing;
     protected render(): TemplateResult;
 }
 declare global {

package/dist/megamenu/root/megamenu-root.js

@@ -5,17 +5,10 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
 var HelixHeadlessMegamenu_1;
-import { anchorElement, customElement, deepContains, focusableElements, HelixElement, MixinControllerOpen, PopoverController, tellDisclosure, } from '@fusion.dev/helix-core';
+import { anchorElement, customElement, deepContains, focusableElements, HelixElement, KeyboardNavigationController, MixinControllerOpen, PopoverController, tellDisclosure, } from '@fusion.dev/helix-core';
 import { html, nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
-let showing;
-const connected = new Set();
-let pressed;
-const release = () => {
-    setTimeout(() => {
-        pressed = undefined;
-    });
-};
+import { HandOver } from '../hand-over.js';
 let HelixHeadlessMegamenu = class HelixHeadlessMegamenu extends MixinControllerOpen(HelixElement) {
     constructor() {
         super(...arguments);
@@ -28,13 +21,31 @@ let HelixHeadlessMegamenu = class HelixHeadlessMegamenu extends MixinControllerO
         };
         this.panel = new PopoverController(this, {
             anchor: () => this.trigger,
-            boundary: () => [...connected],
+            boundary: () => [...HelixHeadlessMegamenu_1.bar.connected],
             onDismiss: () => this.close(),
             open: () => this.open,
             place: () => !this.banded,
             placement: () => 'bottom-start',
             surface: () => this.partNamed('surface'),
         });
+        this.keys = new KeyboardNavigationController(this, {
+            items: () => !this.parentElement?.shadowRoot
+                ? HelixHeadlessMegamenu_1.bar.alongside(this).map((megamenu) => ({
+                    contains: (node) => {
+                        const control = megamenu.trigger;
+                        return node === control || control.contains(node);
+                    },
+                    disabled: false,
+                    focusItem: () => megamenu.trigger.focus(),
+                    select: () => { },
+                    selected: false,
+                }))
+                : [],
+            origin: 'focus',
+            reserved: () => ['ArrowDown', 'ArrowUp'],
+            selects: () => false,
+            wrap: false,
+        });
         this.handleKeyDown = (event) => {
             if (event.key !== 'ArrowDown' || !this.open || event.defaultPrevented) {
                 return;
@@ -61,14 +72,13 @@ let HelixHeadlessMegamenu = class HelixHeadlessMegamenu extends MixinControllerO
         };
         this.handlePointerDown = (event) => {
             this.pointer = event.pointerType;
-            pressed = this;
-            window.addEventListener('pointerup', release, { capture: true, once: true });
-            window.addEventListener('pointercancel', release, { capture: true, once: true });
+            HelixHeadlessMegamenu_1.bar.press(this);
         };
         this.handlePointerEnter = (event) => {
             if (this.openOn !== 'hover' || event.pointerType !== 'mouse') {
                 return;
             }
+            const showing = HelixHeadlessMegamenu_1.bar.showing;
             this.schedule(showing && showing !== this ? 0 : HelixHeadlessMegamenu_1.OPEN_DELAY, () => {
                 this.requestOpen(true);
             });
@@ -86,6 +96,7 @@ let HelixHeadlessMegamenu = class HelixHeadlessMegamenu extends MixinControllerO
             if (!this.open || next === null || deepContains(this, next)) {
                 return;
             }
+            const pressed = HelixHeadlessMegamenu_1.bar.pressed;
             if (pressed !== undefined && pressed !== this && deepContains(pressed, next)) {
                 return;
             }
@@ -119,9 +130,9 @@ let HelixHeadlessMegamenu = class HelixHeadlessMegamenu extends MixinControllerO
             }
             this.requestOpen(false);
         };
-        this.handedOver = false;
     }
     static { HelixHeadlessMegamenu_1 = this; }
+    static { this.bar = new HandOver((megamenu, to) => megamenu.motion(to)); }
     get banded() {
         return this.variant === 'band' || this.narrow;
     }
@@ -191,7 +202,7 @@ let HelixHeadlessMegamenu = class HelixHeadlessMegamenu extends MixinControllerO
     connectedCallback() {
         super.connectedCallback();
         this.watchWidth();
-        connected.add(this);
+        HelixHeadlessMegamenu_1.bar.add(this);
         window.addEventListener('scroll', this.handleScroll, { capture: true, passive: true });
         this.addEventListener('pointerdown', this.handlePointerDown);
         this.addEventListener('click', this.handleContentClick);
@@ -211,11 +222,8 @@ let HelixHeadlessMegamenu = class HelixHeadlessMegamenu extends MixinControllerO
         this.removeEventListener('pointerleave', this.handlePointerLeave);
         this.removeEventListener('focusout', this.handleFocusOut);
         this.removeEventListener('keydown', this.handleKeyDown);
-        connected.delete(this);
+        HelixHeadlessMegamenu_1.bar.remove(this);
         this.stop();
-        if (showing === this) {
-            showing = undefined;
-        }
     }
     willUpdate(changed) {
         super.willUpdate(changed);
@@ -223,37 +231,10 @@ let HelixHeadlessMegamenu = class HelixHeadlessMegamenu extends MixinControllerO
             return;
         }
         if (this.open) {
-            const previous = showing && showing !== this ? showing : undefined;
-            const forward = previous !== undefined &&
-                (previous.compareDocumentPosition(this) & Node.DOCUMENT_POSITION_FOLLOWING) !== 0;
-            this.motion(previous ? (forward ? 'from-end' : 'from-start') : undefined);
-            this.from = previous?.size;
-            HelixHeadlessMegamenu_1.settle(this, previous);
-            if (previous) {
-                previous.motion(forward ? 'to-start' : 'to-end');
-                previous.handedOver = true;
-                if (!previous.requestOpen(false)) {
-                    previous.handedOver = false;
-                    previous.motion(undefined);
-                }
-            }
-            showing = this;
+            this.from = HelixHeadlessMegamenu_1.bar.open(this)?.size;
             return;
         }
-        if (showing === this) {
-            showing = undefined;
-        }
-        if (!this.handedOver) {
-            HelixHeadlessMegamenu_1.settle();
-        }
-        this.handedOver = false;
-    }
-    static settle(...moving) {
-        for (const megamenu of connected) {
-            if (!moving.includes(megamenu)) {
-                megamenu.motion(undefined);
-            }
-        }
+        HelixHeadlessMegamenu_1.bar.close(this);
     }
     measure() {
         const surface = this.partNamed('surface');
@@ -301,8 +282,13 @@ let HelixHeadlessMegamenu = class HelixHeadlessMegamenu extends MixinControllerO
       </button>
     </slot>`;
     }
+    renderIndicator() {
+        return this.open
+            ? html `<slot name="indicator" part="indicator" aria-hidden="true"></slot>`
+            : nothing;
+    }
     render() {
-        return html `${this.renderTrigger()}
+        return html `${this.renderTrigger()}${this.renderIndicator()}
       <div
         part="surface"
         id="panel"
@@ -311,7 +297,7 @@ let HelixHeadlessMegamenu = class HelixHeadlessMegamenu extends MixinControllerO
         role="group"
         ?hidden=${!this.open}
       >
-        <slot></slot>
+        <slot part="columns"></slot>
       </div>`;
     }
 };

package/dist/menu/item/menu-item.js

@@ -4,7 +4,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
-import { ariaChord, customElement, deepActiveElement, HelixBeforeToggleEvent, HelixElement, HelixSelectEvent, onApple, requestChange, } from '@fusion.dev/helix-core';
+import { ariaChord, customElement, deepActiveElement, HelixBeforeToggleEvent, HelixElement, HelixSelectEvent, onApple, requestChange, slotFilled, } from '@fusion.dev/helix-core';
 import { caretRight, check } from '@fusion.dev/helix-icons';
 import { html, nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
@@ -33,15 +33,15 @@ let HelixHeadlessMenuItem = class HelixHeadlessMenuItem extends HelixElement {
         this.description = false;
         this.readStart = () => {
             const slot = this.renderRoot.querySelector('slot[name="start"]');
-            this.start = (slot?.assignedNodes().length ?? 0) > 0;
+            this.start = slotFilled(slot);
         };
         this.readEnd = () => {
             const slot = this.renderRoot.querySelector('slot[name="end"]');
-            this.end = (slot?.assignedNodes().length ?? 0) > 0;
+            this.end = slotFilled(slot);
         };
         this.readDescription = () => {
             const slot = this.renderRoot.querySelector('slot[name="description"]');
-            this.description = (slot?.assignedNodes().length ?? 0) > 0;
+            this.description = slotFilled(slot);
         };
         this.readSubmenu = () => {
             const slot = this.renderRoot.querySelector('slot[name="submenu"]');

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

@@ -71,6 +71,9 @@ declare const HelixHeadlessMenu_base: (new (...args: any[]) => import("@fusion.d
  * @csspart surface - The floating panel the menu is drawn on.
  * @csspart title - The name of the submenu that is showing.
  *
+ * @cssproperty --floating-anchor-inline-size - The trigger's width, written on the panel while it is open, as in `min-inline-size: var(--floating-anchor-inline-size)`. Read it; a value set here is written over.
+ * @cssproperty --floating-available-block-size - The room between the panel and the edge of the screen it opens toward, written on the panel while it is open. Read it; a value set here is written over.
+ *
  * @cssstate drilled - A submenu's page is showing, so content that is not a row can hide with the top page.
  * @cssstate mark - A row on the current page has a checkbox or a link, so every row keeps the trailing column.
  * @cssstate open - While the menu is open.

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

@@ -16,6 +16,15 @@ export type MeterBand = 'fair' | 'good' | 'poor';
  * band. `optimum` sets the preferred band. The band next to it is fair, and the
  * band two away is poor.
  *
+ * The band is a custom state on the meter, `good`, `fair` or `poor`, beside
+ * `over` and `under` for a value past an end, so a page styles the meter
+ * around the fill as well as the fill.
+ *
+ * **`live` says the reading when it moves into another band**, such as "92%,
+ * Poor", in a polite region, for a meter whose value changes while a reader is
+ * on the page: a disk filling or a battery draining. The band's word comes from
+ * `band-labels`.
+ *
  * @since 0.1.0
  * @status stable
  * @category feedback
@@ -24,6 +33,8 @@ export type MeterBand = 'fair' | 'good' | 'poor';
  *
  * @slot label - A visible label. Its words name the meter in place of `label`.
  *
+ * @event {HelixBandEvent} helix-band - Fired when the reading moves into another band, with the band it is in now, or `''` where it is in none. Not sent on the first render, since a meter that arrives in a band has not moved.
+ *
  * @csspart groove - The unfilled circle, in `ring` and `arc`.
  * @csspart indicator - The part of the track the value fills.
  * @csspart indicator-fair - The fill while the reading is in a band next to the good band. Set alongside `indicator`.
@@ -31,6 +42,7 @@ export type MeterBand = 'fair' | 'good' | 'poor';
  * @csspart indicator-over - The fill while the value is above `max`. Set alongside `indicator`.
  * @csspart indicator-poor - The fill while the reading is two bands from the good band. Set alongside `indicator`.
  * @csspart indicator-under - The fill while the value is below `min`. Set alongside `indicator`.
+ * @csspart live - A polite region that says the reading as it moves into another band, under `live`, rendered from the first time it does. Hide it visually.
  * @csspart tick - A mark at `low` or at `high`.
  * @csspart track - The whole range, or the drawing in `ring` and `arc`.
  * @csspart value - The reading as text, shown when `show-value` is set.
@@ -39,6 +51,12 @@ export type MeterBand = 'fair' | 'good' | 'poor';
  * @cssproperty --meter-at - Where a bound sits on a linear track, as a percentage.
  * @cssproperty --meter-fraction - The value as a fraction of the range, 0 to 1.
  * @cssproperty --meter-sweep - How much of the circle the arc covers, as a path length.
+ *
+ * @cssstate fair - The reading is in a band next to the good band.
+ * @cssstate good - The reading is in the good band.
+ * @cssstate over - The value is above `max`.
+ * @cssstate poor - The reading is two bands from the good band.
+ * @cssstate under - The value is below `min`.
  */
 export declare class HelixHeadlessMeter extends HelixElement {
     /**
@@ -71,6 +89,13 @@ export declare class HelixHeadlessMeter extends HelixElement {
      * no reader.
      */
     band?: MeterBand;
+    /**
+     * The words each band is said with under `live`, by its name, written as
+     * JSON in the attribute: `band-labels='{"poor":"Almost full"}'`.
+     *
+     * A band left out keeps its default: "Good", "Fair" or "Poor".
+     */
+    bandLabels: Partial<Record<MeterBand, string>>;
     /**
      * `Intl.NumberFormat` options the reading is written with, as React Aria's
      * Meter and ProgressBar take them: a unit, a currency, or a number of
@@ -99,6 +124,15 @@ export declare class HelixHeadlessMeter extends HelixElement {
      * shows, so the name and the label cannot disagree.
      */
     label: string;
+    /**
+     * Says the reading in a polite `live` region each time it moves into
+     * another band, with the band's word, such as "92%, Poor".
+     *
+     * For a meter whose value changes while it is on screen. Off by default,
+     * because a meter that reads a fixed level has nothing new to say. A meter
+     * with no bands says nothing.
+     */
+    live: boolean;
     /**
      * The locale the percentage is written in, such as `fr` for `72 %`.
      *
@@ -171,6 +205,13 @@ export declare class HelixHeadlessMeter extends HelixElement {
      * fair summary of a task and a poor one of a quantity.
      */
     valueText: string;
+    /** The region `live` speaks in, rendered from the first time it does. */
+    private readonly status;
+    /**
+     * The band at the last update, so a move into another one is heard once:
+     * an empty string for none, and undefined before the first update.
+     */
+    private lastBand;
     /** The range, clamped so `max` is never at or below `min`. */
     private get span();
     /** The reading, pulled into the range. */
@@ -221,6 +262,7 @@ export declare class HelixHeadlessMeter extends HelixElement {
      */
     private get text();
     protected willUpdate(changed: PropertyValues): void;
+    protected updated(changed: PropertyValues): void;
     /**
      * The same reading, drawn round.
      *

package/dist/meter/root/meter-root.js

@@ -4,20 +4,23 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
-import { customElement, formatNumber, HelixElement, hostAria, slottedWords, } from '@fusion.dev/helix-core';
+import { customElement, drawStatus, HelixBandEvent, HelixElement, hostAria, readingText, StatusController, slottedWords, wordsConverter, } from '@fusion.dev/helix-core';
 import { html, nothing, svg } from 'lit';
 import { property } from 'lit/decorators.js';
-const WHOLE_PERCENT = { maximumFractionDigits: 0, style: 'percent' };
+const BAND_WORDS = { fair: 'Fair', good: 'Good', poor: 'Poor' };
 let HelixHeadlessMeter = class HelixHeadlessMeter extends HelixElement {
     constructor() {
         super(...arguments);
+        this.bandLabels = {};
         this.label = 'Meter';
+        this.live = false;
         this.locale = '';
         this.max = 100;
         this.min = 0;
         this.showValue = false;
         this.value = 0;
         this.valueText = '';
+        this.status = new StatusController(this);
         this.renamed = () => {
             this.requestUpdate();
         };
@@ -69,11 +72,8 @@ let HelixHeadlessMeter = class HelixHeadlessMeter extends HelixElement {
         return distance === 0 ? 'good' : distance === 1 ? 'fair' : 'poor';
     }
     get text() {
-        const options = this.formatOptions;
         return (this.valueText ||
-            (options && options.style !== 'percent'
-                ? formatNumber(Number.isFinite(this.value) ? this.value : this.span.min, this.locale, options)
-                : formatNumber(this.ratio, this.locale, options ?? WHOLE_PERCENT)));
+            readingText(Number.isFinite(this.value) ? this.value : this.span.min, this.ratio, this.locale, this.formatOptions));
     }
     willUpdate(changed) {
         super.willUpdate(changed);
@@ -84,6 +84,26 @@ let HelixHeadlessMeter = class HelixHeadlessMeter extends HelixElement {
         this.internals.ariaValueNow = String(this.reading);
         this.internals.ariaValueText =
             this.valueText || this.formatOptions !== undefined || this.beyond ? this.text : null;
+        const band = this.computedBand;
+        const beyond = this.beyond;
+        this.toggleState('fair', band === 'fair');
+        this.toggleState('good', band === 'good');
+        this.toggleState('poor', band === 'poor');
+        this.toggleState('over', beyond === 'over');
+        this.toggleState('under', beyond === 'under');
+    }
+    updated(changed) {
+        super.updated(changed);
+        const band = this.computedBand;
+        const moved = this.lastBand !== undefined && (band ?? '') !== this.lastBand;
+        this.lastBand = band ?? '';
+        if (!moved) {
+            return;
+        }
+        this.dispatchEvent(new HelixBandEvent({ band: band ?? '' }));
+        if (band && this.live) {
+            this.status.say(`${this.text}, ${this.bandLabels[band] ?? BAND_WORDS[band]}`);
+        }
     }
     renderRound() {
         const bounds = this.thresholds;
@@ -131,12 +151,15 @@ let HelixHeadlessMeter = class HelixHeadlessMeter extends HelixElement {
               style="--meter-fraction: ${this.fraction}"
             ></div>
           </div>`}
-      ${this.showValue ? html `<span part="value">${this.text}</span>` : nothing}`;
+      ${this.showValue ? html `<span part="value">${this.text}</span>` : nothing}${drawStatus(this.status)}`;
     }
 };
 __decorate([
     property()
 ], HelixHeadlessMeter.prototype, "band", void 0);
+__decorate([
+    property({ attribute: 'band-labels', converter: wordsConverter })
+], HelixHeadlessMeter.prototype, "bandLabels", void 0);
 __decorate([
     property({ attribute: 'format-options', type: Object })
 ], HelixHeadlessMeter.prototype, "formatOptions", void 0);
@@ -146,6 +169,9 @@ __decorate([
 __decorate([
     property()
 ], HelixHeadlessMeter.prototype, "label", void 0);
+__decorate([
+    property({ type: Boolean })
+], HelixHeadlessMeter.prototype, "live", void 0);
 __decorate([
     property()
 ], HelixHeadlessMeter.prototype, "locale", void 0);