@fusion.dev/helix-headless 0.156.0 → 0.158.0

package/dist/menu/root/menu-root.js

@@ -4,11 +4,28 @@ 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 { AriaForwardController, anchorElement, customElement, DrilldownController, deepActiveElement, deepContains, HelixElement, inlineStep, KeyboardNavigationController, MixinCollection, MixinControllerOpen, PopoverController, scrollItemIntoView, slottedWords, tellDisclosure, typeaheadBy, words, } from '@fusion.dev/helix-core';
+import { AriaForwardController, anchorElement, customElement, DrilldownController, deepActiveElement, deepContains, focusTarget, HelixElement, inlineStep, KeyboardNavigationController, linkDescription, MixinCollection, MixinControllerOpen, PopoverController, scrollItemIntoView, sideOf, slottedWords, tellDisclosure, typeaheadBy, unlinkDescription, words, } from '@fusion.dev/helix-core';
 import { caretLeft } from '@fusion.dev/helix-icons';
 import { html, nothing } from 'lit';
 import { property } from 'lit/decorators.js';
 import { unsafeSVG } from 'lit/directives/unsafe-svg.js';
+import { LongPress } from '../../speed-dial/long-press.js';
+const isItem = (element) => element !== null &&
+    typeof element === 'object' &&
+    'isMenuItem' in element &&
+    element.isMenuItem === true;
+const HOVER_DELAY = 100;
+const GRACE = 300;
+const inTriangle = (x, y, [a, b, c]) => {
+    if (!a || !b || !c) {
+        return false;
+    }
+    const side = (p, q) => (q[0] - p[0]) * (y - p[1]) - (q[1] - p[1]) * (x - p[0]);
+    const one = side(a, b);
+    const two = side(b, c);
+    const three = side(c, a);
+    return (one >= 0 && two >= 0 && three >= 0) || (one <= 0 && two <= 0 && three <= 0);
+};
 const isSection = (element) => 'isMenuSection' in element && element.isMenuSection === true;
 let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinControllerOpen(HelixElement)) {
     constructor() {
@@ -16,8 +33,25 @@ let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinCon
         this.backLabel = 'Back';
         this.context = false;
         this.label = '';
+        this.longPressLabel = 'Long press or press Alt+Down to show the menu';
         this.offset = 4;
+        this.longPress = new LongPress(this, {
+            onLongPress: () => {
+                if (this.context) {
+                    const at = this.heldAt;
+                    if (at) {
+                        this.openContextAt(at);
+                    }
+                    return;
+                }
+                if (!this.open) {
+                    this.show();
+                }
+            },
+        });
+        this.openOn = 'click';
         this.placement = 'bottom-start';
+        this.submenus = 'drill';
         this.drilldown = new DrilldownController(this, {
             isRow: (element) => 'isMenuItem' in element && element.isMenuItem === true,
             root: () => [...this.children]
@@ -42,10 +76,18 @@ let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinCon
             boundary: () => this,
             offset: () => this.offset,
             onDismiss: () => this.hide(),
+            onPlace: (placement) => {
+                const side = sideOf(placement);
+                this.toggleState('placed-bottom', side === 'bottom');
+                this.toggleState('placed-left', side === 'left');
+                this.toggleState('placed-right', side === 'right');
+                this.toggleState('placed-top', side === 'top');
+            },
             open: () => this.open,
             placement: () => this.placement,
             surface: () => this.partNamed('surface'),
         });
+        this.settledOnce = false;
         this.handleContextMenu = (event) => {
             if (!this.context) {
                 return;
@@ -56,21 +98,19 @@ let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinCon
                 return;
             }
             event.preventDefault();
-            const box = this.trigger.getBoundingClientRect();
-            const keyed = event.clientX === 0 && event.clientY === 0;
-            this.point = keyed ? { x: box.left, y: box.top } : { x: event.clientX, y: event.clientY };
-            if (this.open) {
-                this.requestUpdate();
-                this.updateComplete.then(() => this.panel.reposition());
+            if (this.open && this.longPress.takeClick()) {
                 return;
             }
-            const active = deepActiveElement();
-            this.returnTo = active instanceof HTMLElement ? active : undefined;
-            this.show();
+            const box = this.trigger.getBoundingClientRect();
+            const keyed = event.clientX === 0 && event.clientY === 0;
+            this.openContextAt(keyed ? { x: box.left, y: box.top } : { x: event.clientX, y: event.clientY });
         };
         this.handleSelect = (event) => {
             const item = event.target;
-            if (!this.items.includes(item)) {
+            const reachable = this.flies
+                ? isItem(item) && item.onPage
+                : this.items.includes(item);
+            if (!reachable) {
                 return;
             }
             const chosen = item;
@@ -90,7 +130,10 @@ let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinCon
             if (!item) {
                 return;
             }
-            const surface = this.partNamed('surface');
+            const holder = this.flies ? this.holderOf(item) : null;
+            const surface = holder
+                ? holder.shadowRoot?.querySelector('[part="surface"]')
+                : this.partNamed('surface');
             scrollItemIntoView(item, { padding: 4, ...(surface ? { scroller: surface } : {}) });
         };
         this.handleKeydown = (event) => {
@@ -109,6 +152,9 @@ let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinCon
                 this.enter(items[at]);
             }
             else if (along === -1) {
+                if (this.flies ? this.keyPage === null : this.drilldown.atRoot) {
+                    return;
+                }
                 this.leave();
             }
             else if (event.key === 'Tab') {
@@ -127,21 +173,166 @@ let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinCon
             if (this.open) {
                 this.hide();
             }
-            else {
+            else if (!this.pressHeld) {
                 this.show();
             }
         };
+        this.handlePointerDown = (event) => {
+            if (this.open || !this.fromTrigger(event)) {
+                return;
+            }
+            if (this.pressHeld || (this.context && event.pointerType !== 'mouse')) {
+                this.heldAt = { x: event.clientX, y: event.clientY };
+                this.longPress.down(event);
+            }
+        };
+        this.handlePointerMove = (event) => {
+            this.longPress.move(event);
+        };
+        this.handlePointerUp = () => {
+            this.longPress.up();
+        };
+        this.handlePointerCancel = () => {
+            this.longPress.cancel();
+        };
+        this.handleHeldClick = (event) => {
+            if (this.pressHeld && this.longPress.takeClick()) {
+                event.stopImmediatePropagation();
+                event.preventDefault();
+            }
+        };
+        this.handleTriggerFocusIn = (event) => {
+            if (this.pressHeld && this.fromTrigger(event)) {
+                this.describeTrigger(true);
+            }
+        };
+        this.handleHover = (event) => {
+            if (!this.flies || !this.open || event.pointerType !== 'mouse') {
+                return;
+            }
+            const row = event
+                .composedPath()
+                .find((node) => isItem(node));
+            if (!row?.onPage || row === this.hovered || this.inGrace(event)) {
+                return;
+            }
+            this.hovered = row;
+            this.grace = undefined;
+            if (!row.disabled) {
+                row.focus();
+            }
+            clearTimeout(this.hoverTimer);
+            this.hoverTimer = setTimeout(() => {
+                if (!this.open || this.hovered !== row) {
+                    return;
+                }
+                if (row.hasSubmenu && !row.disabled) {
+                    if (this.drilldown.page !== row) {
+                        this.drilldown.enter(row);
+                    }
+                    return;
+                }
+                const holder = this.holderOf(row);
+                if (this.drilldown.page !== holder) {
+                    this.openPage(holder);
+                }
+            }, HOVER_DELAY);
+        };
+        this.handleRowOut = (event) => {
+            if (!this.flies || event.pointerType !== 'mouse') {
+                return;
+            }
+            const row = event
+                .composedPath()
+                .find((node) => isItem(node));
+            const panel = row?.expanded
+                ? row.shadowRoot?.querySelector('[part="surface"]')
+                : undefined;
+            if (!panel) {
+                return;
+            }
+            const box = panel.getBoundingClientRect();
+            const edge = box.left >= event.clientX ? box.left : box.right;
+            this.grace = {
+                points: [
+                    [event.clientX, event.clientY],
+                    [edge, box.top],
+                    [edge, box.bottom],
+                ],
+                until: Date.now() + GRACE,
+            };
+        };
     }
     static { this.words = 'helix-menu'; }
+    get flies() {
+        return this.submenus === 'flyout';
+    }
+    get topRows() {
+        return [...this.children]
+            .filter((child) => child.slot !== 'trigger')
+            .flatMap((child) => (isSection(child) ? [...child.children] : [child]))
+            .filter(isItem);
+    }
+    rowsOf(holder) {
+        return holder
+            ? [...holder.children].filter((child) => child.slot === 'submenu' && isItem(child))
+            : this.topRows;
+    }
+    holderOf(row) {
+        const parent = row.parentElement;
+        return row.slot === 'submenu' && parent && isItem(parent) ? parent : null;
+    }
+    get openPages() {
+        const pages = [];
+        for (let page = this.drilldown.page; page; page = this.holderOf(page)) {
+            pages.unshift(page);
+        }
+        return [null, ...pages];
+    }
+    get keyPage() {
+        for (const page of this.openPages) {
+            const active = this.rowsOf(page).find((row) => row.active);
+            if (active) {
+                return page;
+            }
+        }
+        return this.drilldown.page;
+    }
+    openPage(holder) {
+        if (holder) {
+            this.drilldown.enter(holder);
+        }
+        else {
+            this.drilldown.reset();
+        }
+    }
+    get pressHeld() {
+        return !this.context && this.openOn === 'long-press';
+    }
     tellTrigger() {
         const slot = this.renderRoot?.querySelector('slot[name="trigger"]');
-        tellDisclosure(slot?.assignedElements({ flatten: true })[0], this.open, 'menu');
+        const trigger = slot?.assignedElements({ flatten: true })[0];
+        if (!trigger || trigger.localName.includes('-')) {
+            tellDisclosure(trigger, this.open, 'menu');
+            return;
+        }
+        if (trigger !== this.told) {
+            if (!this.settledOnce || trigger.hasAttribute('aria-expanded')) {
+                return;
+            }
+            this.told = trigger;
+            if (!trigger.hasAttribute('aria-haspopup')) {
+                trigger.setAttribute('aria-haspopup', 'menu');
+            }
+        }
+        trigger.setAttribute('aria-expanded', String(this.open));
     }
     get trigger() {
         return anchorElement(this.renderRoot?.querySelector('slot[name="trigger"]'), this);
     }
     get items() {
-        return this.drilldown.rows.filter((row) => !row.disabled);
+        const rows = this.flies ? this.rowsOf(this.keyPage) : this.drilldown.rows;
+        return rows.filter((row) => !row.disabled);
     }
     show() {
         this.openAt('first');
@@ -161,6 +352,7 @@ let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinCon
         }
         this.panel.hide();
         this.drilldown.reset();
+        this.stopHover();
         if (deepContains(this, deepActiveElement())) {
             ;
             (this.context ? (this.returnTo ?? this.trigger) : this.trigger).focus();
@@ -168,13 +360,43 @@ let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinCon
         this.point = undefined;
         this.returnTo = undefined;
     }
+    openContextAt(point) {
+        this.point = point;
+        if (this.open) {
+            this.requestUpdate();
+            this.updateComplete.then(() => this.panel.reposition());
+            return;
+        }
+        const active = deepActiveElement();
+        this.returnTo = active instanceof HTMLElement ? active : undefined;
+        this.show();
+    }
     enter(item) {
         if (!this.drilldown.enter(item)) {
             return;
         }
-        this.updateComplete.then(() => this.items[0]?.focusItem());
+        void this.updateComplete.then(async () => {
+            if (!this.flies) {
+                this.items[0]?.focusItem();
+                return;
+            }
+            await item.updateComplete;
+            const first = this.rowsOf(item).find((row) => !row.disabled);
+            await first?.updateComplete;
+            first?.focusItem();
+        });
     }
     leave() {
+        if (this.flies) {
+            const holder = this.keyPage;
+            if (!holder) {
+                this.hide();
+                return;
+            }
+            this.openPage(this.holderOf(holder));
+            this.updateComplete.then(() => holder.focus());
+            return;
+        }
         if (this.drilldown.atRoot) {
             this.hide();
             return;
@@ -184,42 +406,107 @@ let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinCon
         this.updateComplete.then(() => leaving?.focus());
     }
     handleClosedKeydown(event) {
+        if (this.context && event.shiftKey && event.key === 'F10' && this.fromTrigger(event)) {
+            event.preventDefault();
+            const box = this.trigger.getBoundingClientRect();
+            this.openContextAt({ x: box.left, y: box.top });
+            return;
+        }
         if (this.context || (event.key !== 'ArrowDown' && event.key !== 'ArrowUp')) {
             return;
         }
-        const slot = this.renderRoot?.querySelector('slot[name="trigger"]');
-        const triggers = slot?.assignedElements({ flatten: true }) ?? [];
-        if (!event.composedPath().some((node) => triggers.includes(node))) {
+        if (this.pressHeld !== event.altKey || !this.fromTrigger(event)) {
             return;
         }
         event.preventDefault();
         this.openAt(event.key === 'ArrowDown' ? 'first' : 'last');
     }
+    fromTrigger(event) {
+        const slot = this.renderRoot?.querySelector('slot[name="trigger"]');
+        const triggers = slot?.assignedElements({ flatten: true }) ?? [];
+        return event.composedPath().some((node) => triggers.includes(node));
+    }
+    describeTrigger(light = false) {
+        const slot = this.renderRoot?.querySelector('slot[name="trigger"]');
+        const trigger = slot?.assignedElements({ flatten: true })[0];
+        const control = this.pressHeld && trigger instanceof HTMLElement ? focusTarget(trigger) : undefined;
+        if (this.described && this.described !== control) {
+            unlinkDescription(this.described, this);
+            this.described = undefined;
+        }
+        if (control && control !== this.described && linkDescription(control, this, light)) {
+            this.described = control;
+        }
+        this.internals.ariaLabel = this.described ? this.longPressLabel : null;
+    }
+    stopHover() {
+        clearTimeout(this.hoverTimer);
+        this.hoverTimer = undefined;
+        this.hovered = undefined;
+        this.grace = undefined;
+    }
+    inGrace(event) {
+        const grace = this.grace;
+        return (grace !== undefined &&
+            Date.now() < grace.until &&
+            inTriangle(event.clientX, event.clientY, grace.points));
+    }
     connectedCallback() {
         super.connectedCallback();
+        this.addEventListener('pointermove', this.handleHover);
+        this.addEventListener('pointerout', this.handleRowOut);
         this.addEventListener('helix-select', this.handleSelect, true);
         this.addEventListener('keydown', this.handleKeydown);
         this.addEventListener('focusin', this.handleFocusIn);
         this.addEventListener('contextmenu', this.handleContextMenu);
+        this.addEventListener('pointerdown', this.handlePointerDown);
+        this.addEventListener('pointermove', this.handlePointerMove);
+        this.addEventListener('pointerup', this.handlePointerUp);
+        this.addEventListener('pointercancel', this.handlePointerCancel);
+        this.addEventListener('click', this.handleHeldClick, true);
+        this.addEventListener('focusin', this.handleTriggerFocusIn);
+        void this.whenSettled.then(() => {
+            this.settledOnce = true;
+            if (!this.context) {
+                this.tellTrigger();
+            }
+        });
     }
     disconnectedCallback() {
         super.disconnectedCallback();
+        this.removeEventListener('pointermove', this.handleHover);
+        this.removeEventListener('pointerout', this.handleRowOut);
+        this.stopHover();
         this.removeEventListener('helix-select', this.handleSelect, true);
         this.removeEventListener('keydown', this.handleKeydown);
         this.removeEventListener('focusin', this.handleFocusIn);
         this.removeEventListener('contextmenu', this.handleContextMenu);
+        this.removeEventListener('pointerdown', this.handlePointerDown);
+        this.removeEventListener('pointermove', this.handlePointerMove);
+        this.removeEventListener('pointerup', this.handlePointerUp);
+        this.removeEventListener('pointercancel', this.handlePointerCancel);
+        this.removeEventListener('click', this.handleHeldClick, true);
+        this.removeEventListener('focusin', this.handleTriggerFocusIn);
+        if (this.described) {
+            unlinkDescription(this.described, this);
+            this.described = undefined;
+        }
     }
     updated(changed) {
         super.updated(changed);
         if (!this.context) {
             this.tellTrigger();
         }
+        if (changed.has('openOn') || changed.has('context') || this.described) {
+            this.describeTrigger();
+        }
+        const top = this.flies || this.drilldown.atRoot;
         for (const child of this.children) {
             if (isSection(child)) {
-                child.onPage = this.drilldown.atRoot;
+                child.onPage = top;
                 for (const row of child.children) {
                     if (row.isMenuItem === true) {
-                        this.mark(row, this.drilldown.atRoot);
+                        this.mark(row, top);
                     }
                 }
                 continue;
@@ -228,9 +515,9 @@ let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinCon
             if (item.isMenuItem !== true) {
                 continue;
             }
-            this.mark(item, this.drilldown.atRoot);
+            this.mark(item, top);
         }
-        this.toggleState('drilled', !this.drilldown.atRoot);
+        this.toggleState('drilled', !this.flies && !this.drilldown.atRoot);
         this.markColumns();
         this.nameSurface();
     }
@@ -249,13 +536,26 @@ let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinCon
         surface.ariaLabelledByElements = trigger && !named ? [trigger] : null;
     }
     markColumns() {
-        const rows = this.drilldown.rows;
+        const rows = this.flies ? this.topRows : this.drilldown.rows;
         this.toggleState('start', rows.some((row) => row.querySelector(':scope > [slot="start"]') !== null));
         this.toggleState('mark', rows.some((row) => row.checkable || row.checked || this.drilldown.hasPage(row)));
     }
     mark(item, onPage) {
         const page = this.drilldown.page;
         item.onPage = onPage;
+        const holds = page !== null && item.contains(page);
+        item.flyout = this.flies;
+        item.expanded = this.flies && holds;
+        if (this.flies) {
+            item.showingSubmenu = false;
+            for (const child of item.children) {
+                const nested = child;
+                if (nested.isMenuItem === true && child.slot === 'submenu') {
+                    this.mark(nested, onPage && holds);
+                }
+            }
+            return;
+        }
         item.showingSubmenu = page !== null && item.contains(page);
         for (const child of item.children) {
             const nested = child;
@@ -279,10 +579,10 @@ let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinCon
         role="menu"
         aria-busy=${this.loading ? 'true' : nothing}
         aria-label=${this.label || nothing}
-        data-drilled=${this.drilldown.atRoot ? nothing : ''}
+        data-drilled=${this.flies || this.drilldown.atRoot ? nothing : ''}
         ?hidden=${!this.open}
       >
-        ${this.drilldown.atRoot
+        ${this.flies || this.drilldown.atRoot
             ? nothing
             : html `<div part="header">
                 <button
@@ -314,12 +614,22 @@ __decorate([
 __decorate([
     property()
 ], HelixHeadlessMenu.prototype, "label", void 0);
+__decorate([
+    words,
+    property({ attribute: 'long-press-label' })
+], HelixHeadlessMenu.prototype, "longPressLabel", void 0);
 __decorate([
     property({ type: Number })
 ], HelixHeadlessMenu.prototype, "offset", void 0);
+__decorate([
+    property({ attribute: 'open-on' })
+], HelixHeadlessMenu.prototype, "openOn", void 0);
 __decorate([
     property()
 ], HelixHeadlessMenu.prototype, "placement", void 0);
+__decorate([
+    property()
+], HelixHeadlessMenu.prototype, "submenus", void 0);
 HelixHeadlessMenu = __decorate([
     customElement('helix-headless-menu')
 ], HelixHeadlessMenu);

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

@@ -40,6 +40,11 @@ declare const HelixHeadlessNotifications_base: (new (...args: any[]) => import("
  * | Control+Home | From anywhere in the feed, moves to the nearest control before it on the page. |
  * | Tab | Moves through the controls in a row, and on out of the feed. |
  *
+ * **A notification that arrives says so.** Unread rows added above the rows
+ * there were are counted in the live region,
+ * "1 new notification", in `arrived-label`. Rows that arrive while `loading`
+ * is set say nothing, so set it while a page is on its way.
+ *
  * **`load-more` adds a button after the list** that sends `helix-load-more`,
  * for a feed that holds one page of a longer list. Append the next page, set
  * `loading` while it is on its way, and take `load-more` off once there is
@@ -100,6 +105,11 @@ export declare class HelixHeadlessNotifications extends HelixHeadlessNotificatio
      * A notification's own words are under `helix-notification`.
      */
     static words: string;
+    /**
+     * What the feed says when unread notifications arrive, with `{count}` the
+     * number of them. Empty it to say nothing.
+     */
+    arrivedLabel: string;
     /** The region's name where `label` is empty. */
     fallbackLabel: string;
     /**
@@ -272,6 +282,16 @@ export declare class HelixHeadlessNotifications extends HelixHeadlessNotificatio
     private rove;
     connectedCallback(): void;
     disconnectedCallback(): void;
+    /** The rows the feed has met, so a row that arrives later is told apart. */
+    private seen;
+    /** Empties the arrival a moment after it is said, so the next one is news. */
+    private readonly hush;
+    /**
+     * Counts the unread rows that arrived above the rows there were, and says
+     * how many. Rows that fill an empty feed are a page, which says nothing. The rows there are at the first update are
+     * the feed's to begin with, and say nothing.
+     */
+    private noteArrivals;
     protected willUpdate(changed: PropertyValues): void;
     /**
      * The error, the empty or the loading line, each around a slot of the same

package/dist/notifications/root/notifications-root.js

@@ -4,13 +4,14 @@ 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 { assignSlots, ChildrenController, customElement, deepContains, focusableElements, HelixElement, HelixLoadMoreEvent, HelixReadEvent, hostAria, MixinCollection, markRegion, rovingStop, whenHydrated, words, } from '@fusion.dev/helix-core';
+import { assignSlots, ChildrenController, customElement, DelayController, deepContains, focusableElements, formatWords, HelixElement, HelixLoadMoreEvent, HelixReadEvent, hostAria, MixinCollection, markRegion, rovingStop, whenHydrated, words, } from '@fusion.dev/helix-core';
 import { html, nothing } from 'lit';
 import { property } from 'lit/decorators.js';
 import { feedStep } from '../feed-keys.js';
 let HelixHeadlessNotifications = class HelixHeadlessNotifications extends MixinCollection(HelixElement) {
     constructor() {
         super(...arguments);
+        this.arrivedLabel = '{count, plural, one {# new notification} other {# new notifications}}';
         this.fallbackLabel = 'Notifications';
         this.label = '';
         this.loadError = '';
@@ -60,6 +61,7 @@ let HelixHeadlessNotifications = class HelixHeadlessNotifications extends MixinC
                 rowBox(next)?.focus();
             }
         };
+        this.hush = new DelayController(this, { renders: false });
         this.askForMore = () => {
             if (!this.loading) {
                 this.dispatchEvent(new HelixLoadMoreEvent());
@@ -196,8 +198,33 @@ let HelixHeadlessNotifications = class HelixHeadlessNotifications extends MixinC
         this.removeEventListener('focusin', this.handleFocusIn);
         this.removeEventListener('keydown', this.handleKeydown);
     }
+    noteArrivals() {
+        if (!this.childrenKnown) {
+            return;
+        }
+        const items = this.items;
+        const seen = this.seen;
+        if (!seen) {
+            this.seen = new WeakSet(items);
+            return;
+        }
+        const firstKnown = items.findIndex((item) => seen.has(item));
+        const fresh = items.filter((item, at) => !seen.has(item) && at < firstKnown && !item.read);
+        for (const item of items) {
+            seen.add(item);
+        }
+        if (fresh.length === 0 || this.loading || this.arrivedLabel === '') {
+            return;
+        }
+        this.announced = formatWords(this, 'arrivedLabel', { count: fresh.length });
+        this.hush.start(1000, () => {
+            this.announced = '';
+            this.requestUpdate();
+        });
+    }
     willUpdate(changed) {
         super.willUpdate(changed);
+        this.noteArrivals();
         hostAria(this.internals, { label: this.label || this.fallbackLabel, role: 'region' });
         const failed = this.failed;
         this.toggleState('error', failed);
@@ -284,6 +311,10 @@ let HelixHeadlessNotifications = class HelixHeadlessNotifications extends MixinC
       <div part="footer"><slot name="footer"></slot></div>`;
     }
 };
+__decorate([
+    words,
+    property({ attribute: 'arrived-label' })
+], HelixHeadlessNotifications.prototype, "arrivedLabel", void 0);
 __decorate([
     words,
     property({ attribute: 'fallback-label' })

package/dist/number-input/root/number-input-root.d.ts

@@ -25,9 +25,9 @@ declare const HelixHeadlessNumberInput_base: (new (...args: any[]) => import("@f
  * The locale's group separators are read in every field, so `1,234` is a
  * number in `en-US`.
  *
- * The field and its two buttons sit in a `role="group"`, and the field carries
- * `role-label`, "number field" in English, as its `aria-roledescription`, as
- * React Aria's NumberField does. On iOS and iPadOS the field is a plain text
+ * The field and its two buttons sit in a `role="group"` named by the label,
+ * and the field carries `role-label`, "number field" in English, as its
+ * `aria-roledescription`, as React Aria's NumberField does. On iOS and iPadOS the field is a plain text
  * field, with no `role="spinbutton"`, which VoiceOver reads as a slider you
  * cannot type in, and no role description, so VoiceOver says the field is
  * required. React Aria's NumberField does the same.
@@ -492,8 +492,11 @@ export declare class HelixHeadlessNumberInput extends HelixHeadlessNumberInput_b
     protected renderIncrementIcon(): TemplateResult;
     protected render(): TemplateResult;
     /**
-     * The value as a number, or `NaN` while the control is empty.
+     * The value as a number, or `NaN` while the control is empty or does not
+     * hold a number.
      *
+     * Read in the locale and the format, as the form reads it, so `1,5` typed
+     * in a locale with a decimal comma is 1.5 here while the form holds 1.5.
      * `NaN` and not zero, which is the trap the platform already avoids: `Number('')`
      * is zero, so an empty control would report a number it does not hold and a
      * form would submit it.