@fusion.dev/helix-headless 0.142.1 → 0.143.0

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

@@ -1,4 +1,4 @@
-import { HelixElement, KeyboardNavigationController, type Placement } from '@fusion.dev/helix-core';
+import { AriaForwardController, HelixElement, KeyboardNavigationController, type Placement } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
 declare const HelixHeadlessMenu_base: (new (...args: any[]) => import("@fusion.dev/helix-core").CollectionElement) & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerOpenInterface) & typeof HelixElement;
 /**
@@ -9,6 +9,12 @@ declare const HelixHeadlessMenu_base: (new (...args: any[]) => import("@fusion.d
  * menu renders its surface in the top layer with the popover API, so an
  * ancestor with `overflow: hidden` does not clip it and it needs no `z-index`.
  *
+ * Slot a `helix-button` or `helix-icon-button` as the trigger, and the menu
+ * tells it that it opens a menu and whether the menu is open. A plain
+ * `<button>` can only be told by writing attributes onto your markup, which
+ * the menu does not do, so give it `aria-haspopup="menu"` and set its
+ * `aria-expanded` from the `toggle` event.
+ *
  * Submenus drill down. A submenu replaces the panel's content, and a back row
  * returns to the previous page. One panel avoids the diagonal pointer path that
  * side-by-side panels need, stays inside a narrow window, and works on touch
@@ -30,7 +36,7 @@ declare const HelixHeadlessMenu_base: (new (...args: any[]) => import("@fusion.d
  * @event {HelixBeforeCloseEvent} helix-before-close - The menu is about to close. Cancelable: cancel it to keep it open.
  * @event {HelixBeforeOpenEvent} helix-before-open - The menu is about to open. Cancelable: cancel it to keep it closed.
  * @event {HelixSelectEvent} helix-select - An item was chosen. Cancelable: cancel it to keep the menu open.
- * @event {Event} toggle - The menu opened or closed. The event carries `newState` and `oldState`.
+ * @event {ToggleEvent} toggle - The menu opened or closed. The event carries `newState` and `oldState`.
  *
  * @csspart back - The control that returns from a submenu.
  * @csspart back-mark - The glyph on the back control of a submenu.
@@ -53,6 +59,10 @@ export declare class HelixHeadlessMenu extends HelixHeadlessMenu_base {
     backLabel: string;
     /**
      * Accessible name for the surface.
+     *
+     * Empty by default, which names the surface by its trigger, so a menu opened
+     * from "Actions" is announced as "Actions". An `aria-label` or
+     * `aria-labelledby` on the host names it too, and wins over both.
      */
     label: string;
     /**
@@ -92,6 +102,8 @@ export declare class HelixHeadlessMenu extends HelixHeadlessMenu_base {
      * menu that drills, so those keys are spoken for here rather than unhandled.
      */
     protected readonly keys: KeyboardNavigationController;
+    /** Carries a host `aria-label` and `aria-labelledby` to the surface. */
+    protected readonly aria: AriaForwardController;
     private readonly panel;
     /**
      * Tells a slotted trigger the disclosure state, by property.
@@ -108,6 +120,8 @@ export declare class HelixHeadlessMenu extends HelixHeadlessMenu_base {
     private get items();
     /** Opens the menu. */
     show(): void;
+    /** Opens the menu with focus on its first or its last row. */
+    private openAt;
     /** Closes the menu and returns it to its first page. */
     hide(): void;
     /** Shows an item's submenu in place of the current page. */
@@ -124,10 +138,26 @@ export declare class HelixHeadlessMenu extends HelixHeadlessMenu_base {
      */
     private readonly handleFocusIn;
     private readonly handleKeydown;
+    /**
+     * Down and Up on the trigger open the menu on its first and its last row.
+     *
+     * Everything else passes through. Escape in particular is not this element's
+     * while the menu is closed, so a dialog around the menu still closes on it.
+     */
+    private handleClosedKeydown;
     private readonly handleTriggerClick;
     connectedCallback(): void;
     disconnectedCallback(): void;
     protected updated(changed: PropertyValues): void;
+    /**
+     * Names the surface by its trigger, where nothing else names it.
+     *
+     * By element reference, which is the one direction that crosses: the surface
+     * is in this shadow root and the trigger is in the tree around it. A host
+     * `aria-labelledby` is carried down by `aria`, and a host `aria-label` or
+     * `label` is a name of its own, so each of them clears this reference.
+     */
+    private nameSurface;
     /**
      * Says whether the page showing reserves a column either side of its labels.
      *

package/dist/menu/root/menu-root.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 { anchorElement, customElement, DrilldownController, HelixElement, inlineStep, KeyboardNavigationController, MixinCollection, MixinControllerOpen, PopoverController, scrollItemIntoView, tellDisclosure, } from '@fusion.dev/helix-core';
+import { AriaForwardController, anchorElement, customElement, DrilldownController, deepActiveElement, deepContains, HelixElement, inlineStep, KeyboardNavigationController, MixinCollection, MixinControllerOpen, PopoverController, scrollItemIntoView, slottedWords, tellDisclosure, } from '@fusion.dev/helix-core';
 import { caretLeft } from '@fusion.dev/helix-icons';
 import { html, nothing } from 'lit';
 import { property } from 'lit/decorators.js';
@@ -13,7 +13,7 @@ let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinCon
     constructor() {
         super(...arguments);
         this.backLabel = 'Back';
-        this.label = 'Menu';
+        this.label = '';
         this.offset = 4;
         this.placement = 'bottom-start';
         this.drilldown = new DrilldownController(this, {
@@ -22,9 +22,14 @@ let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinCon
             slot: 'submenu',
         });
         this.keys = new KeyboardNavigationController(this, {
-            items: () => this.items,
+            items: () => (this.open ? this.items : []),
             reserved: () => ['ArrowLeft', 'ArrowRight'],
             selects: () => false,
+            typeahead: (item) => slottedWords(item, ['']),
+        });
+        this.aria = new AriaForwardController(this, {
+            label: true,
+            target: () => this.partNamed('surface'),
         });
         this.panel = new PopoverController(this, {
             anchor: () => this.trigger,
@@ -61,8 +66,12 @@ let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinCon
             scrollItemIntoView(item, { padding: 4, ...(surface ? { scroller: surface } : {}) });
         };
         this.handleKeydown = (event) => {
+            if (!this.open) {
+                this.handleClosedKeydown(event);
+                return;
+            }
             const items = this.items;
-            const at = items.indexOf(document.activeElement);
+            const at = items.findIndex((item) => item.active);
             const along = inlineStep(this, event.key);
             if (event.key === 'Escape') {
                 event.stopPropagation();
@@ -94,7 +103,7 @@ let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinCon
     }
     tellTrigger() {
         const slot = this.renderRoot?.querySelector('slot[name="trigger"]');
-        tellDisclosure(slot?.assignedElements({ flatten: false })[0], this.open, 'menu');
+        tellDisclosure(slot?.assignedElements({ flatten: true })[0], this.open, 'menu');
     }
     get trigger() {
         return anchorElement(this.renderRoot?.querySelector('slot[name="trigger"]'), this);
@@ -103,11 +112,15 @@ let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinCon
         return this.drilldown.rows.filter((row) => !row.disabled);
     }
     show() {
+        this.openAt('first');
+    }
+    openAt(end) {
         if (this.open || !this.requestOpen(true)) {
             return;
         }
         this.updateComplete.then(() => {
-            this.items[0]?.focus();
+            const items = this.items;
+            (end === 'first' ? items[0] : items[items.length - 1])?.focus();
         });
     }
     hide() {
@@ -116,7 +129,7 @@ let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinCon
         }
         this.panel.hide();
         this.drilldown.reset();
-        if (this.contains(document.activeElement)) {
+        if (deepContains(this, deepActiveElement())) {
             this.trigger.focus();
         }
     }
@@ -135,6 +148,18 @@ let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinCon
         this.drilldown.back();
         this.updateComplete.then(() => leaving?.focus());
     }
+    handleClosedKeydown(event) {
+        if (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))) {
+            return;
+        }
+        event.preventDefault();
+        this.openAt(event.key === 'ArrowDown' ? 'first' : 'last');
+    }
     connectedCallback() {
         super.connectedCallback();
         this.addEventListener('helix-select', this.handleSelect, true);
@@ -159,6 +184,21 @@ let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinCon
         }
         this.toggleState('drilled', !this.drilldown.atRoot);
         this.markColumns();
+        this.nameSurface();
+    }
+    nameSurface() {
+        const surface = this.partNamed('surface');
+        if (!surface || !('ariaLabelledByElements' in surface)) {
+            return;
+        }
+        if (this.hasAttribute('aria-labelledby')) {
+            return;
+        }
+        const trigger = this.renderRoot
+            ?.querySelector('slot[name="trigger"]')
+            ?.assignedElements({ flatten: true })[0];
+        const named = this.label !== '' || this.hasAttribute('aria-label');
+        surface.ariaLabelledByElements = trigger && !named ? [trigger] : null;
     }
     markColumns() {
         const rows = this.drilldown.rows;
@@ -183,7 +223,7 @@ let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinCon
         popover="manual"
         role="menu"
         aria-busy=${this.loading ? 'true' : nothing}
-        aria-label=${this.label}
+        aria-label=${this.label || nothing}
         data-drilled=${this.drilldown.atRoot ? nothing : ''}
         ?hidden=${!this.open}
       >

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

@@ -79,6 +79,12 @@ export declare class HelixHeadlessMeter extends HelixElement {
      * Accessible name for the reading.
      */
     label: string;
+    /**
+     * The locale the percentage is written in, such as `fr` for `72 %`.
+     *
+     * Absent uses the runtime's own.
+     */
+    locale: string;
     /**
      * Top of the low band.
      *

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

@@ -7,10 +7,23 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 import { customElement, HelixElement, hostAria } from '@fusion.dev/helix-core';
 import { html, nothing, svg } from 'lit';
 import { property } from 'lit/decorators.js';
+const percents = new Map();
+const percent = (share, locale) => {
+    let format = percents.get(locale);
+    if (!format) {
+        format = new Intl.NumberFormat(locale || undefined, {
+            maximumFractionDigits: 0,
+            style: 'percent',
+        });
+        percents.set(locale, format);
+    }
+    return format.format(share);
+};
 let HelixHeadlessMeter = class HelixHeadlessMeter extends HelixElement {
     constructor() {
         super(...arguments);
         this.label = 'Meter';
+        this.locale = '';
         this.max = 100;
         this.min = 0;
         this.showValue = false;
@@ -64,7 +77,7 @@ let HelixHeadlessMeter = class HelixHeadlessMeter extends HelixElement {
         return distance === 0 ? 'good' : distance === 1 ? 'fair' : 'poor';
     }
     get text() {
-        return this.valueText || `${Math.round(this.ratio * 100)}%`;
+        return this.valueText || percent(this.ratio, this.locale);
     }
     willUpdate(changed) {
         super.willUpdate(changed);
@@ -74,7 +87,7 @@ let HelixHeadlessMeter = class HelixHeadlessMeter extends HelixElement {
         this.internals.ariaValueMax = String(max);
         this.internals.ariaValueNow = String(this.reading);
         this.internals.ariaValueText =
-            this.valueText || (this.beyond ? `${Math.round(this.ratio * 100)}%` : null);
+            this.valueText || (this.beyond ? percent(this.ratio, this.locale) : null);
     }
     renderRound() {
         const bounds = this.thresholds;
@@ -134,6 +147,9 @@ __decorate([
 __decorate([
     property()
 ], HelixHeadlessMeter.prototype, "label", void 0);
+__decorate([
+    property()
+], HelixHeadlessMeter.prototype, "locale", void 0);
 __decorate([
     property({ type: Number })
 ], HelixHeadlessMeter.prototype, "low", void 0);

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

@@ -1,4 +1,4 @@
-import { HelixElement } from '@fusion.dev/helix-core';
+import { AriaForwardController, HelixElement } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
 /**
  * @summary A set of destinations, with a marker on the current one.
@@ -15,7 +15,9 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  *
  * The component moves a marker to the current item. It finds the current item
  * by reading `aria-current`, so the attribute that screen readers announce also
- * places the marker.
+ * places the marker. Any value but `false` counts, so a sidebar of sections on
+ * one page can mark the section in view with `aria-current="location"`. Where
+ * several are marked, `page` wins.
  *
  * Set `orientation="vertical"` to stack the destinations in a column, for a
  * sidebar.
@@ -35,8 +37,14 @@ export declare class HelixHeadlessNavigation extends HelixElement {
     private readonly indicator;
     /**
      * The landmark's name, read by screen readers.
+     *
+     * An `aria-label` or `aria-labelledby` on the host names the landmark too,
+     * and wins over this, so a footer navigation written the usual way is not a
+     * second "Main".
      */
     label: string;
+    /** Carries a host `aria-label` and `aria-labelledby` to the `<nav>`. */
+    protected readonly aria: AriaForwardController;
     /**
      * Stacks the destinations in a column, for a sidebar, where unset is a row
      * for a header or a footer. The marker follows the current destination down

package/dist/navigation/root/navigation-root.js

@@ -4,19 +4,30 @@ 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, HelixElement, IndicatorController } from '@fusion.dev/helix-core';
+import { AriaForwardController, customElement, HelixElement, IndicatorController, } from '@fusion.dev/helix-core';
 import { html } from 'lit';
 import { property } from 'lit/decorators.js';
 let HelixHeadlessNavigation = class HelixHeadlessNavigation extends HelixElement {
     constructor() {
         super(...arguments);
         this.indicator = new IndicatorController(this, {
-            active: () => this.items.find((item) => item.getAttribute('aria-current') === 'page'),
+            active: () => {
+                const items = this.items;
+                const marked = (item) => {
+                    const current = item.getAttribute('aria-current');
+                    return current !== null && current !== 'false';
+                };
+                return (items.find((item) => item.getAttribute('aria-current') === 'page') ?? items.find(marked));
+            },
             indicator: () => this.partNamed('indicator'),
             observe: () => this.items,
             surface: () => this.partNamed('nav'),
         });
         this.label = 'Main';
+        this.aria = new AriaForwardController(this, {
+            label: true,
+            target: () => this.partNamed('nav'),
+        });
     }
     get items() {
         const slot = this.renderRoot.querySelector('slot');

package/dist/notifications/group/notification-group.d.ts

@@ -33,6 +33,7 @@ declare const HelixHeadlessNotificationGroup_base: (new (...args: any[]) => impo
  *
  * @event {HelixBeforeCloseEvent} helix-before-close - Fired before the group collapses. Cancelable.
  * @event {HelixBeforeOpenEvent} helix-before-open - Fired before the group expands. Cancelable: cancel it to keep the group collapsed.
+ * @event {ToggleEvent} toggle - The group expanded or collapsed. The event carries `newState` and `oldState`.
  *
  * @csspart actions - The trailing region of the header.
  * @csspart count - The number of notifications in the group.

package/dist/notifications/notification/notification.d.ts

@@ -96,6 +96,13 @@ export declare class HelixHeadlessNotification extends HelixHeadlessNotification
      */
     get read(): boolean;
     set read(next: boolean);
+    /**
+     * What a screen reader hears before an unread notification's text.
+     *
+     * The unread mark is drawn, so a reader who cannot see it hears this word in
+     * its place. Translate it with the rest of your interface.
+     */
+    unreadLabel: string;
     /**
      * @internal Read by the list to identify its children across the light DOM,
      * which is cheaper than `instanceof` and is why this is public rather than
@@ -192,6 +199,11 @@ export declare class HelixHeadlessNotification extends HelixHeadlessNotification
     protected render(): TemplateResult;
     private readonly handleActions;
     private readonly handleDismiss;
+    /**
+     * Where focus goes when this row leaves: the next row's first control, the
+     * one before, then the first control left in the feed.
+     */
+    private neighbor;
 }
 declare global {
     interface HTMLElementTagNameMap {

package/dist/notifications/notification/notification.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 { customElement, HelixElement, HelixReadEvent, hostAria, MixinDismissible, requestChange, slotFilled, } from '@fusion.dev/helix-core';
+import { customElement, deepActiveElement, deepContains, focusableElements, HelixElement, HelixReadEvent, hostAria, MixinDismissible, requestChange, slotFilled, } from '@fusion.dev/helix-core';
 import { x } from '@fusion.dev/helix-icons';
 import { nothing } from 'lit';
 import { property } from 'lit/decorators.js';
@@ -17,6 +17,7 @@ let HelixHeadlessNotification = class HelixHeadlessNotification extends MixinDis
         this.at = '';
         this.defaultRead = false;
         this.locale = '';
+        this.unreadLabel = 'Unread';
         this.isNotification = true;
         this.readState = undefined;
         this.handleActions = () => {
@@ -25,7 +26,9 @@ let HelixHeadlessNotification = class HelixHeadlessNotification extends MixinDis
         this.handleDismiss = (event) => {
             event.stopPropagation();
             if (this.dismiss()) {
+                const next = deepContains(this, deepActiveElement()) ? this.neighbor() : null;
                 this.remove();
+                next?.focus();
             }
         };
     }
@@ -105,7 +108,7 @@ let HelixHeadlessNotification = class HelixHeadlessNotification extends MixinDis
         return html `<div part="item">
       <span part="media"><slot name="media"></slot></span>
       <div part="body">
-        <div part="label"><slot></slot></div>
+        <div part="label">${this.read ? nothing : html `<span role="img" aria-label=${this.unreadLabel}></span>`}<slot></slot></div>
         <slot name="description"></slot>
         <slot name="detail"></slot>
         <span part="actions"><slot name="actions" @slotchange=${this.handleActions}></slot></span>
@@ -116,6 +119,29 @@ let HelixHeadlessNotification = class HelixHeadlessNotification extends MixinDis
       </div>
     </div>`;
     }
+    neighbor() {
+        let feed = this.parentElement;
+        while (feed && !('markEveryoneRead' in feed)) {
+            feed = feed.parentElement;
+        }
+        const rows = feed
+            ? feed.items
+            : [...(this.parentElement?.children ?? [])].filter((one) => 'isNotification' in one);
+        const at = rows.indexOf(this);
+        const order = [...rows.slice(at + 1), ...rows.slice(0, Math.max(at, 0)).reverse()];
+        for (const row of order) {
+            const target = row.shadowRoot?.querySelector('[part="dismiss"]') ?? focusableElements(row)[0];
+            if (target) {
+                return target;
+            }
+        }
+        if (!feed) {
+            return null;
+        }
+        return (feed.shadowRoot?.querySelector('[part="mark-all"]') ??
+            focusableElements(feed).find((one) => !this.contains(one)) ??
+            null);
+    }
 };
 __decorate([
     property()
@@ -129,6 +155,9 @@ __decorate([
 __decorate([
     property({ type: Boolean })
 ], HelixHeadlessNotification.prototype, "read", null);
+__decorate([
+    property({ attribute: 'unread-label' })
+], HelixHeadlessNotification.prototype, "unreadLabel", void 0);
 HelixHeadlessNotification = __decorate([
     customElement('helix-headless-notification')
 ], HelixHeadlessNotification);

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

@@ -202,6 +202,13 @@ export declare class HelixHeadlessNotifications extends HelixHeadlessNotificatio
     private markEmpty;
     protected updated(changed: PropertyValues): void;
     protected render(): TemplateResult;
+    /**
+     * Marks everything read, and keeps focus in the feed.
+     *
+     * The button shows only while something is unread, so the press that
+     * succeeds removes the button it was made on. Focus moves to the first row's
+     * control, or the first control left in the feed.
+     */
     private readonly handleMarkAll;
 }
 declare global {

package/dist/notifications/root/notifications-root.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 { customElement, HelixElement, HelixReadEvent, hostAria, MixinCollection, markRegion, } from '@fusion.dev/helix-core';
+import { customElement, focusableElements, HelixElement, HelixReadEvent, hostAria, MixinCollection, markRegion, } from '@fusion.dev/helix-core';
 import { html, nothing } from 'lit';
 import { property } from 'lit/decorators.js';
 let HelixHeadlessNotifications = class HelixHeadlessNotifications extends MixinCollection(HelixElement) {
@@ -20,8 +20,23 @@ let HelixHeadlessNotifications = class HelixHeadlessNotifications extends MixinC
         this.handleRead = () => {
             queueMicrotask(() => this.requestUpdate());
         };
-        this.handleMarkAll = () => {
+        this.handleMarkAll = (event) => {
+            const button = event.currentTarget;
+            const focused = this.shadowRoot?.activeElement === button;
             this.markEveryoneRead();
+            if (!focused) {
+                return;
+            }
+            void this.updateComplete.then(() => {
+                if (button.isConnected) {
+                    return;
+                }
+                const target = this.items
+                    .map((row) => row.shadowRoot?.querySelector('[part="dismiss"]') ??
+                    focusableElements(row)[0])
+                    .find((one) => one !== undefined) ?? focusableElements(this)[0];
+                target?.focus();
+            });
         };
     }
     static { this.shadowRootOptions = {

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

@@ -18,8 +18,9 @@ declare const HelixHeadlessNumberInput_base: (new (...args: any[]) => import("@f
  *
  * `inputmode="decimal"` keeps the numeric keypad on phones.
  *
- * Validity still comes from the platform: `min`, `max`, and `step` are mirrored
- * onto the host's own `setValidity`.
+ * Validity follows the platform's rules: `min`, `max`, and `step` are checked
+ * and reported through the host's own `setValidity`, under the platform's flag
+ * names.
  *
  * Stepping is separate from typing, so a number is not corrected while you type
  * it.
@@ -31,6 +32,9 @@ declare const HelixHeadlessNumberInput_base: (new (...args: any[]) => import("@f
  * @documentation https://fusion.dev/helix/components/number-input
  *
  * @slot end - Content after the number, such as a unit.
+ * @slot feedback - The message that says what is wrong, for content richer than a string. It shows while there is a message.
+ * @slot hint - Help under the control, for content richer than the `hint` text.
+ * @slot label - The label, for content richer than the `label` text.
  * @slot start - Content before the number, such as a unit or an icon.
  *
  * @event {Event} change - The user finished changing the value. Relayed from the native field.
@@ -88,6 +92,15 @@ export declare class HelixHeadlessNumberInput extends HelixHeadlessNumberInput_b
      * what a reader wants from a whole key.
      */
     largeStep?: number;
+    /**
+     * The locale a typed number is read in, such as `de-DE`. Empty reads it in
+     * the browser's language.
+     *
+     * Where the locale writes a decimal comma, `1,5` is read as one and a half,
+     * which is what the decimal keypad on a phone in that locale types. A dot is
+     * read as a decimal point in every locale.
+     */
+    locale: string;
     /**
      * The largest value allowed.
      *
@@ -132,14 +145,29 @@ export declare class HelixHeadlessNumberInput extends HelixHeadlessNumberInput_b
      */
     scrub: boolean;
     /**
-     * How far one step moves.
+     * How far one step moves. A value off the step grid, counted from `min`, is
+     * invalid, as it is in a native number field.
      */
     step: number;
-    /** Focus is delegated to the field, so the host is never the focus target. */
-    static shadowRootOptions: ShadowRootInit;
+    /**
+     * The message the browser shows when the number is off the step grid, with
+     * `{below}` and `{above}` filled in with the nearest valid values.
+     */
+    stepMismatchMessage?: string;
+    /**
+     * What a screen reader says for the value, with `{value}` filled in, such as
+     * `{value} kilograms`.
+     *
+     * A unit slotted into `end` is drawn beside the number and is not part of
+     * what the spinbutton announces, so it goes here too. Empty announces the
+     * number alone.
+     */
+    valueText: string;
     private get control();
     /** The value as a number, or `null` where the field holds nothing usable. */
     private get numeric();
+    /** Whether `value` is on the step grid, counted from `min`. */
+    private onStep;
     /**
      * A value pulled into range and onto the step grid.
      *
@@ -254,7 +282,19 @@ export declare class HelixHeadlessNumberInput extends HelixHeadlessNumberInput_b
      * the same as preventing one.
      */
     private readonly handleBlur;
-    /** Relayed, because `change` does not cross a shadow boundary on its own. */
+    /**
+     * Pulls a typed number into range and onto the step grid, and returns
+     * whether that moved the value.
+     */
+    private settle;
+    /**
+     * Relayed, because `change` does not cross a shadow boundary on its own.
+     *
+     * **Settled first.** The field's `change` arrives before its `blur`, so
+     * relaying it as it came announced the number as typed, 150 in a field whose
+     * `max` is 100, and the clamp that followed sent `input` alone: a consumer
+     * saving on `change` kept 150 while the form submitted 100.
+     */
     private readonly handleChange;
     /**
      * The four keys a spinner answers, which `Input` does not bind.
@@ -274,7 +314,13 @@ export declare class HelixHeadlessNumberInput extends HelixHeadlessNumberInput_b
      * message is what a native spinner would have said.
      */
     private sync;
-    /** Puts the cursor in the field. */
+    /**
+     * Puts the cursor in the field.
+     *
+     * **No `delegatesFocus`**, because the platform's delegate is the first
+     * focusable element, which is the Decrease stepper: a label pressed for the
+     * field landed on it, and the arrows then did nothing.
+     */
     focus(options?: FocusOptions): void;
     /** Selects the number, so typing replaces it. */
     select(): void;
@@ -287,6 +333,15 @@ export declare class HelixHeadlessNumberInput extends HelixHeadlessNumberInput_b
     private releaseCaret;
     protected willUpdate(changed: PropertyValues): void;
     protected updated(changed: PropertyValues): void;
+    /**
+     * Enter submits the form, as it does in a native text field.
+     *
+     * On `keypress`, where the platform runs its own implicit submission, so a
+     * consumer who prevents the `keydown` for Enter stops this too.
+     */
+    private readonly handleKeypress;
+    /** @internal A single line of text counts against implicit submission. */
+    protected get blocksImplicitSubmission(): boolean;
     protected render(): TemplateResult;
     /**
      * The value as a number, or `NaN` while the control is empty.