@fusion.dev/helix-core 0.143.0 → 0.145.0

package/dist/mixins/mixin-dismissible/mixin-dismissible.d.ts

@@ -13,6 +13,8 @@ export declare class DismissibleElement {
     dismiss(): boolean;
     /** The event, built but not dispatched, for a caller that owns the timing. */
     protected dismissEvent(): HelixDismissEvent;
+    /** Where focus lands when a neighbor that held it is removed: the dismiss control. */
+    protected get returnFocusTo(): HTMLElement | null;
 }
 /**
  * Grafts `dismissible`, its label, and the event that says so.

package/dist/mixins/mixin-dismissible/mixin-dismissible.js

@@ -21,6 +21,9 @@ export const MixinDismissible = (Base) => {
                 .join('');
             return new HelixDismissEvent({ label: own.trim() });
         }
+        get returnFocusTo() {
+            return this.shadowRoot?.querySelector('[part~="dismiss"]') ?? null;
+        }
         dismiss() {
             const neighbors = deepContains(this, deepActiveElement()) ? this.neighbors() : [];
             const event = this.dismissEvent();
@@ -53,11 +56,12 @@ export const MixinDismissible = (Base) => {
                     return;
                 }
                 for (const neighbor of neighbors) {
-                    const control = neighbor.isConnected &&
-                        neighbor.shadowRoot?.querySelector('[part~="dismiss"]');
+                    const control = neighbor.isConnected && neighbor.returnFocusTo;
                     if (control) {
                         control.focus();
-                        return;
+                        if (deepContains(neighbor, deepActiveElement())) {
+                            return;
+                        }
                     }
                 }
             };

package/dist/mixins/mixin-field/mixin-field.d.ts

@@ -20,6 +20,8 @@ export declare class MixinFieldInterface {
     protected labelId: string;
     /** Whether a label is drawn at all, in either shape. */
     protected get labeled(): boolean;
+    /** The element in the shadow root a reader lands on and hears the name of. */
+    protected get namedControl(): HTMLElement | null;
     /**
      * Help text shown under the control. A validation message replaces it.
      *

package/dist/mixins/mixin-field/mixin-field.js

@@ -6,6 +6,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 };
 import { html, nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
+import { auditName } from '../../utils/audit-name/audit-name.js';
 import { hostAria } from '../../utils/host-aria/host-aria.js';
 const HINT_ID = 'helix-hint';
 const FEEDBACK_ID = 'helix-feedback';
@@ -36,6 +37,11 @@ export const MixinField = (Base) => {
             this.touched = false;
             this.shownFeedback = '';
         }
+        get namedControl() {
+            return (this.renderRoot?.querySelector(`#${this.controlId}`) ??
+                this.renderRoot?.querySelector('input, button, select, textarea') ??
+                null);
+        }
         get labeled() {
             return (this.label !== '' ||
                 Boolean(this.getAttribute('aria-label')) ||
@@ -160,6 +166,8 @@ export const MixinField = (Base) => {
             this.addEventListener('invalid', touch);
             this.addEventListener('change', touch);
             this.renderRoot.addEventListener('slotchange', this.noteSlotted);
+            auditName(this, () => this.namedControl, 'Give it a `label`, an `aria-label`, words in its label, or a `<label for>` that names it.', () => this.labeled ||
+                [...this.children].some((child) => child.slot === 'label' && (child.textContent ?? '').trim() !== ''));
         }
     }
     __decorate([

package/dist/mixins/mixin-picker-editing/mixin-picker-editing.d.ts

@@ -19,7 +19,10 @@ export declare class MixinPickerEditingInterface {
     protected editing: boolean;
     /** The caret has left, so the field renders again. */
     protected readonly handleBlur: () => void;
-    /** Focusing the field opens the picker, and only from outside the element. */
+    /**
+     * A press that focuses the field opens the picker, and only from outside the
+     * element. Focus that arrives by Tab or from a script opens nothing.
+     */
     protected readonly handleFocus: (event: FocusEvent) => void;
     /**
      * Whether the value is locked. A read-only control still submits its value.
@@ -37,8 +40,8 @@ export declare class MixinPickerEditingInterface {
     requestOpen(next: boolean): boolean;
 }
 /**
- * Grafts the typing half of a picker field: it opens on arrival, holds the
- * value while the caret is in it, and refuses while read-only.
+ * Grafts the typing half of a picker field: a press into it opens the picker,
+ * it holds the value while the caret is in it, and it refuses while read-only.
  *
  * **Over `MixinPickerField` and not part of it, because Color Input takes the
  * one and not the other.** Date Input and Time Input show a rendering while
@@ -46,9 +49,16 @@ export declare class MixinPickerEditingInterface {
  * while somebody is, because `Intl` formats and does not parse and a document
  * being edited must not be a rendering of something else. That split needs to
  * know when the caret is in the field, which is `editing`; and a reader who
- * reaches such a field is choosing, so arriving opens the picker. A color has
- * neither: `#ff0000` is what is typed and what is shown, and a reader who has
- * the hex pastes it and never opens anything. `readOnly` comes along here for
+ * presses into such a field is choosing, so the press opens the picker. A color
+ * has neither: `#ff0000` is what is typed and what is shown, and a reader who
+ * has the hex pastes it and never opens anything.
+ *
+ * **Tab into the field opens nothing.** It did, and a reader moving through a
+ * form with a screen reader heard a dialog appear at every date and every
+ * time they passed. React Aria's DatePicker opens on its button alone and the
+ * APG date picker combobox opens on its button or Down; here the trigger and
+ * ArrowDown open it from the keyboard, and a press into the text opens it for
+ * a pointer, which is where the reader has already shown what they came for. `readOnly` comes along here for
  * the two that take this mixin; Color Input declares its own, the same
  * property refusing the same two requests.
  */

package/dist/mixins/mixin-picker-editing/mixin-picker-editing.js

@@ -14,10 +14,16 @@ export const MixinPickerEditing = (Base) => {
             this.handleBlur = () => {
                 this.editing = false;
             };
+            this.pressing = false;
+            this.handlePress = (event) => {
+                this.pressing = event.type === 'pointerdown' && event.composedPath()[0] === this.control;
+            };
             this.handleFocus = (event) => {
                 this.editing = !this.returning;
+                const pressed = this.pressing;
+                this.pressing = false;
                 const from = event.relatedTarget;
-                if (this.open || this.isDisabled || this.returning) {
+                if (!pressed || this.open || this.isDisabled || this.returning) {
                     return;
                 }
                 if (from instanceof Node && this.renderRoot?.contains?.(from)) {
@@ -38,6 +44,18 @@ export const MixinPickerEditing = (Base) => {
             }
             return super.requestOpen(next);
         }
+        connectedCallback() {
+            super.connectedCallback();
+            this.addEventListener('pointerdown', this.handlePress);
+            this.addEventListener('pointercancel', this.handlePress);
+            this.addEventListener('click', this.handlePress);
+        }
+        disconnectedCallback() {
+            super.disconnectedCallback();
+            this.removeEventListener('pointerdown', this.handlePress);
+            this.removeEventListener('pointercancel', this.handlePress);
+            this.removeEventListener('click', this.handlePress);
+        }
     }
     __decorate([
         property({ attribute: 'readonly', reflect: true, type: Boolean })

package/dist/mixins/mixin-picker-field/mixin-picker-field.d.ts

@@ -125,10 +125,11 @@ export declare class MixinPickerFieldInterface {
  * same way, and for the same reason: a mixin reads a part out of whatever host
  * applies it.
  *
- * **Opening on focus, `readOnly` and the idle rendering are not here.** They
- * are `MixinPickerEditing`'s, because Color Input takes neither of the first
- * and last: a hex is pasted and read at a glance, so its field neither renders
- * nor opens on arrival. Color Input declares its own `readOnly`.
+ * **Opening on a press into the text, `readOnly` and the idle rendering are
+ * not here.** They are `MixinPickerEditing`'s, because Color Input takes
+ * neither of the first and last: a hex is pasted and read at a glance, so its
+ * field neither renders nor opens when pressed. Color Input declares its own
+ * `readOnly`.
  *
  * **Three things the two typed families share stay with them.** `renderTrigger`
  * differs only by its icon and would still be the wrong thing to lift: a part a

package/dist/mixins/mixin-picker-field/mixin-picker-field.js

@@ -7,6 +7,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 import { property } from 'lit/decorators.js';
 import { PopoverController } from '../../controllers/popover-controller/popover-controller.js';
 import { reportValues } from '../../utils/report-values/report-values.js';
+import { tabStops } from '../../utils/tab-stops/tab-stops.js';
 export const MixinPickerField = (Base) => {
     class PickerFieldElement extends Base {
         constructor() {
@@ -51,13 +52,23 @@ export const MixinPickerField = (Base) => {
             };
             this.handleSurfaceKeydown = (event) => {
                 const surface = this.partNamed('surface');
-                if (event.key !== 'Escape' ||
+                if ((event.key !== 'Escape' && event.key !== 'Tab') ||
                     !this.open ||
                     event.defaultPrevented ||
                     !surface ||
                     !event.composedPath().includes(surface)) {
                     return;
                 }
+                if (event.key === 'Tab') {
+                    const stops = tabStops(surface);
+                    const at = event.composedPath()[0];
+                    const edge = event.shiftKey ? stops[0] : stops.at(-1);
+                    if (edge !== undefined && at === edge) {
+                        event.preventDefault();
+                        (event.shiftKey ? stops.at(-1) : stops[0])?.focus();
+                    }
+                    return;
+                }
                 event.stopPropagation();
                 event.preventDefault();
                 this.requestOpen(false);

package/dist/mixins/mixin-segmented-field/mixin-segmented-field.d.ts

@@ -0,0 +1,67 @@
+import { type TemplateResult } from 'lit';
+import type { HelixFormElement } from '../../helix-form-element/helix-form-element.js';
+import { type SegmentedKind, type SegmentOptions } from '../../utils/date-segments/date-segments.js';
+import type { MixinControllerOpenInterface } from '../mixin-controller-open/mixin-controller-open.js';
+import type { MixinControllerValueInterface } from '../mixin-controller-value/mixin-controller-value.js';
+import type { MixinFieldInterface } from '../mixin-field/mixin-field.js';
+import type { MixinPickerFieldInterface } from '../mixin-picker-field/mixin-picker-field.js';
+type Constructor<T> = new (...args: any[]) => T;
+/** What this is applied over: a picker field, which `MixinPickerField` makes. */
+type SegmentedBase = HelixFormElement & MixinControllerOpenInterface & MixinControllerValueInterface & MixinFieldInterface & MixinPickerFieldInterface;
+/**
+ * The public surface `MixinSegmentedField` adds.
+ *
+ * Declared separately because TypeScript cannot emit declarations for an
+ * anonymous class that has private members (TS4094).
+ */
+export declare class MixinSegmentedFieldInterface {
+    /** What a screen reader hears for a segment with nothing in it. */
+    emptySegmentLabel: string;
+    /**
+     * Whether the field is a row of segments, one for each part of the date or
+     * time, in place of a line of text.
+     */
+    segmented: boolean;
+    /** Whether the segments are drawn: `segmented`, where the family can hold them. */
+    protected get segmentsShown(): boolean;
+    /** The row of segments, the group a description is carried to, or `null` while none is drawn. */
+    protected get segmentGroup(): HTMLElement | null;
+    /** Whether this family can show segments in its current shape. */
+    protected get segmentable(): boolean;
+    /** A date or a time. */
+    protected get segmentedKind(): SegmentedKind;
+    /** The locale the segments are laid out and named in. */
+    protected get segmentLocale(): string;
+    /** The clock and the seconds a time is laid out with. */
+    protected get segmentOptions(): SegmentOptions;
+    /** The row of segments, in the locale's order, with what it writes between them. */
+    protected renderSegments(): TemplateResult;
+}
+/**
+ * Grafts the segmented field React Aria's DateField and TimeField are, and Web
+ * Awesome's time input has, onto a picker field: one `spinbutton` for each part
+ * of the date or the time, in the order the locale writes them.
+ *
+ * **Typing into a text field asks the reader to know the format.** Date Input
+ * and Time Input read ISO, `2026-08-04` and `14:30`, because `Intl` formats and
+ * does not parse, and a reader in Germany who types `4.8.2026` is refused. A
+ * segment needs no format: the month is a month, set with digits or the arrow
+ * keys, and the layout puts it where the locale does, so the field reads
+ * `04.08.2026` in German and `08/04/2026` in English with nothing to parse.
+ *
+ * **What a segment does with a key**, which is React Aria's: digits fill it and
+ * move on once it cannot take another, Up and Down step it and wrap, Home and
+ * End go to its ends, Backspace and Delete empty it, Left and Right move between
+ * segments along the line of text, and Alt+Down opens the picker. Each segment
+ * is a tab stop, as each is in React Aria.
+ *
+ * **The value is whole or empty.** A date with no year is no date, so the value
+ * stays empty while any segment is, and the field reports `badInput` as a
+ * native date input does with a half-typed date. The arithmetic is
+ * `date-segments`, so this draws and listens and nothing else.
+ *
+ * **Opt-in, with `segmented`**, because the text field is what every example and
+ * every form already holds, and a row of segments draws differently.
+ */
+export declare const MixinSegmentedField: <T extends Constructor<SegmentedBase>>(Base: T) => Constructor<MixinSegmentedFieldInterface> & T;
+export {};

package/dist/mixins/mixin-segmented-field/mixin-segmented-field.js

@@ -0,0 +1,243 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    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 { html, nothing } from 'lit';
+import { property, state } from 'lit/decorators.js';
+import { isPartial, isTwelveHourLayout, segmentKey, segmentLayout, segmentName, segmentRange, segmentsOf, segmentsValue, segmentText, segmentValueText, shownValue, } from '../../utils/date-segments/date-segments.js';
+import { inlineStep } from '../../utils/inline-step/inline-step.js';
+export const MixinSegmentedField = (Base) => {
+    class SegmentedFieldElement extends Base {
+        constructor() {
+            super(...arguments);
+            this.emptySegmentLabel = 'Empty';
+            this.segmented = false;
+            this.parts = {};
+            this.typed = '';
+            this.own = false;
+            this.entered = undefined;
+            this.handleSegmentKeydown = (event) => {
+                const element = event.currentTarget;
+                const kind = element.dataset.segment;
+                const twelve = isTwelveHourLayout(this.layout);
+                if (event.key === 'ArrowDown' && event.altKey) {
+                    event.preventDefault();
+                    this.handleTriggerClick();
+                    return;
+                }
+                const along = inlineStep(this, event.key);
+                if (along !== 0) {
+                    event.preventDefault();
+                    this.typed = '';
+                    this.moveFocus(element, along);
+                    return;
+                }
+                if (event.key === 'Tab') {
+                    this.typed = '';
+                    if (this.open) {
+                        this.requestOpen(false);
+                    }
+                    return;
+                }
+                if (event.metaKey || event.ctrlKey || event.altKey) {
+                    this.typed = '';
+                    return;
+                }
+                if (this.readOnly || this.isDisabled) {
+                    return;
+                }
+                const edit = segmentKey(event.key, {
+                    kind,
+                    locale: this.segmentLocale,
+                    segments: this.parts,
+                    twelve,
+                    typed: this.typed,
+                });
+                if (edit) {
+                    event.preventDefault();
+                    this.typed = edit.typed;
+                    this.take(edit.segments);
+                    if (edit.advance) {
+                        this.moveFocus(element, 1);
+                    }
+                }
+            };
+            this.handleSegmentsFocusIn = (event) => {
+                this.typed = '';
+                if (!this.segmentElements.includes(event.relatedTarget)) {
+                    this.entered = this.value;
+                }
+            };
+            this.handleSegmentsFocusOut = (event) => {
+                if (this.segmentElements.includes(event.relatedTarget)) {
+                    return;
+                }
+                if (this.entered !== undefined && this.entered !== this.value) {
+                    this.announceChange();
+                }
+                this.entered = undefined;
+            };
+            this.handleLabelPress = (event) => {
+                if (!this.segmentsShown || this.isDisabled) {
+                    return;
+                }
+                const label = this.renderRoot?.querySelector?.('[part~="label"]');
+                if (label && event.composedPath().includes(label)) {
+                    this.anchor?.focus();
+                }
+            };
+        }
+        get segmentable() {
+            return true;
+        }
+        get segmentsShown() {
+            return this.segmented && this.segmentable;
+        }
+        get segmentedKind() {
+            return 'date';
+        }
+        get segmentLocale() {
+            return '';
+        }
+        get segmentOptions() {
+            return {};
+        }
+        get layout() {
+            return segmentLayout(this.segmentedKind, this.segmentLocale, this.segmentOptions);
+        }
+        get anchor() {
+            if (this.segmentsShown) {
+                return this.renderRoot?.querySelector('[part~="segment"]') ?? null;
+            }
+            return super.anchor;
+        }
+        get segmentGroup() {
+            return this.renderRoot?.querySelector('[part="segments"]') ?? null;
+        }
+        get segmentElements() {
+            return [...(this.renderRoot?.querySelectorAll('[part~="segment"]') ?? [])];
+        }
+        take(next) {
+            this.parts = next;
+            const value = segmentsValue(this.segmentedKind, next, this.layout);
+            if (value === this.value) {
+                this.sync();
+                return;
+            }
+            this.own = true;
+            if (!this.requestValue(value)) {
+                this.own = false;
+                this.parts = segmentsOf(this.segmentedKind, this.value);
+            }
+        }
+        moveFocus(from, by) {
+            const all = this.segmentElements;
+            all[all.indexOf(from) + by]?.focus();
+        }
+        willUpdate(changed) {
+            super.willUpdate(changed);
+            const own = this.own;
+            this.own = false;
+            if (!own &&
+                this.segmentsShown &&
+                segmentsValue(this.segmentedKind, this.parts, this.layout) !== this.value) {
+                this.parts = segmentsOf(this.segmentedKind, this.value);
+            }
+        }
+        formResetCallback() {
+            super.formResetCallback();
+            this.parts = {};
+            this.typed = '';
+        }
+        connectedCallback() {
+            super.connectedCallback();
+            this.addEventListener('click', this.handleLabelPress);
+        }
+        disconnectedCallback() {
+            super.disconnectedCallback();
+            this.removeEventListener('click', this.handleLabelPress);
+        }
+        get blocksImplicitSubmission() {
+            return this.segmentsShown || super.blocksImplicitSubmission;
+        }
+        sync() {
+            super.sync();
+            if (!this.segmentsShown) {
+                return;
+            }
+            const anchor = this.anchor ?? undefined;
+            const partial = isPartial(this.segmentedKind, this.parts, this.layout);
+            const message = this.validate();
+            if (partial) {
+                this.internals.setValidity({ badInput: true }, this.badInputMessage ||
+                    (this.segmentedKind === 'date' ? 'Enter a whole date.' : 'Enter a whole time.'), anchor);
+            }
+            else if (this.required && this.value === '') {
+                this.internals.setValidity({ valueMissing: true }, this.valueMissingMessage ||
+                    (this.segmentedKind === 'date' ? 'Enter a date.' : 'Enter a time.'), anchor);
+            }
+            else if (message !== '') {
+                this.internals.setValidity({ badInput: true }, message, anchor);
+            }
+            else {
+                this.internals.setValidity({});
+            }
+            this.refreshFeedback();
+        }
+        renderSegments() {
+            const layout = this.layout;
+            const twelve = isTwelveHourLayout(layout);
+            const locale = this.segmentLocale;
+            return html `<div
+        part="segments"
+        id=${this.controlId}
+        role="group"
+        aria-labelledby=${this.labeled ? this.labelId : nothing}
+        aria-describedby=${this.describedBy ?? nothing}
+        aria-invalid=${this.invalidity ?? nothing}
+        @focusin=${this.handleSegmentsFocusIn}
+        @focusout=${this.handleSegmentsFocusOut}
+        @keypress=${this.handleKeypress}
+      >
+        ${layout.map((slot) => {
+                if ('literal' in slot) {
+                    return html `<span part="literal" aria-hidden="true">${slot.literal}</span>`;
+                }
+                const kind = slot.kind;
+                const shown = shownValue(kind, this.parts, twelve);
+                const { max, min } = segmentRange(kind, this.parts, twelve);
+                const text = segmentText(kind, this.parts, twelve, locale);
+                const empty = shown === undefined;
+                return html `<span
+            part="segment${empty ? ' segment-placeholder' : ''}"
+            data-segment=${kind}
+            role="spinbutton"
+            tabindex=${this.isDisabled ? '-1' : '0'}
+            inputmode=${kind === 'dayPeriod' ? nothing : 'numeric'}
+            aria-label=${segmentName(kind, locale)}
+            aria-valuemin=${min}
+            aria-valuemax=${max}
+            aria-valuenow=${shown ?? nothing}
+            aria-valuetext=${empty ? this.emptySegmentLabel : segmentValueText(kind, this.parts, twelve, locale)}
+            aria-disabled=${this.isDisabled ? 'true' : nothing}
+            aria-readonly=${this.readOnly ? 'true' : nothing}
+            @keydown=${this.handleSegmentKeydown}
+            >${text}</span
+          >`;
+            })}
+      </div>`;
+        }
+    }
+    __decorate([
+        property({ attribute: 'empty-segment-label' })
+    ], SegmentedFieldElement.prototype, "emptySegmentLabel", void 0);
+    __decorate([
+        property({ type: Boolean })
+    ], SegmentedFieldElement.prototype, "segmented", void 0);
+    __decorate([
+        state()
+    ], SegmentedFieldElement.prototype, "parts", void 0);
+    return SegmentedFieldElement;
+};

package/dist/utils/arrow/arrow.d.ts

@@ -0,0 +1,15 @@
+import type { Placement, Side } from '../../controllers/floating-controller/floating-controller.js';
+/**
+ * How far a panel's arrow reaches past the edge it sits on, which is what the
+ * panel's offset adds so the gap is measured to the point.
+ *
+ * A square of side `n` turned forty-five degrees about its center reaches
+ * `n / sqrt(2)` from it, and the arrow is placed with its center on the
+ * panel's edge. Read from the element rather than assumed, because the size
+ * is a hook a theme may move. `offsetWidth` rather than a rect, which reports
+ * the turned box and would count the reach twice. Zero for no arrow, and while
+ * the panel is closed and unrendered, when there is nothing to place.
+ */
+export declare const arrowReach: (arrow: HTMLElement | null | undefined) => number;
+/** The side of its anchor a placement puts a panel on: `top-start` is `top`. */
+export declare const sideOf: (placement: Placement) => Side;

package/dist/utils/arrow/arrow.js

@@ -0,0 +1,2 @@
+export const arrowReach = (arrow) => (arrow?.offsetWidth ?? 0) / Math.SQRT2;
+export const sideOf = (placement) => placement.split('-')[0];

package/dist/utils/audit-name/audit-name.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Whether an element has an accessible name, by the routes a page names a
+ * control: its own `aria-label`, `aria-labelledby` or `title`, a `<label>`, a
+ * `placeholder`, and its content where its role is named by its content.
+ *
+ * **An estimate, cheap on purpose.** It answers whether any route holds words,
+ * which is what the warning is about, and leaves the order the routes win in
+ * to the browser.
+ */
+export declare const hasName: (element: HTMLElement) => boolean;
+/**
+ * Warns once, through the runtime channel, when a control has no accessible
+ * name: none on the host, and none on the control inside it.
+ *
+ * **Read a task after the control first renders**, so a label that arrives in
+ * the same pass counts: slotted, written by a framework beside the control, or
+ * forwarded from a `<label for>`. One timer serves every control that asked in
+ * that task, and an element is read once in its life, so a name taken away
+ * later is not reported.
+ *
+ * **In every build.** Every runtime warning in the library reports through the
+ * same channel whatever the build, and a project that wants the console quiet
+ * tells `@fusion.dev/helix-diagnostics` with `core.warnings: false`.
+ *
+ * `also` answers for a name the component gave through its internals, which no
+ * attribute shows. `fix` is the sentence that says how to name it.
+ */
+export declare const auditName: (host: HTMLElement, control: () => HTMLElement | null, fix: string, also?: () => boolean) => void;

package/dist/utils/audit-name/audit-name.js

@@ -0,0 +1,95 @@
+import { reportRuntime } from '../report-runtime/report-runtime.js';
+const nameText = (node) => {
+    if (node instanceof HTMLSlotElement) {
+        return node.assignedNodes({ flatten: true }).map(nameText).join('');
+    }
+    if (node.nodeType === Node.TEXT_NODE) {
+        return node.textContent ?? '';
+    }
+    if (!(node instanceof Element)) {
+        return '';
+    }
+    if ((node instanceof HTMLElement && node.hidden) || node.getAttribute('aria-hidden') === 'true') {
+        return '';
+    }
+    const said = node.getAttribute('aria-label') ?? node.getAttribute('alt');
+    if (said?.trim()) {
+        return said;
+    }
+    return [...node.childNodes].map(nameText).join('');
+};
+const namesWithWords = (ids, from) => {
+    const root = from.getRootNode();
+    return (ids ?? '')
+        .split(/\s+/)
+        .filter(Boolean)
+        .some((id) => {
+        const found = root.getElementById?.(id);
+        return found ? nameText(found).trim() !== '' : false;
+    });
+};
+const NAMED_BY_CONTENT = new Set([
+    'button',
+    'checkbox',
+    'link',
+    'menuitem',
+    'menuitemcheckbox',
+    'menuitemradio',
+    'option',
+    'radio',
+    'switch',
+    'tab',
+]);
+export const hasName = (element) => {
+    for (const attribute of ['aria-label', 'title', 'placeholder']) {
+        if (element.getAttribute(attribute)?.trim()) {
+            return true;
+        }
+    }
+    if (namesWithWords(element.getAttribute('aria-labelledby'), element)) {
+        return true;
+    }
+    const referenced = element
+        .ariaLabelledByElements;
+    if ((referenced ?? []).some((one) => nameText(one).trim() !== '')) {
+        return true;
+    }
+    const labels = element.labels;
+    if ([...(labels ?? [])].some((label) => nameText(label).trim() !== '')) {
+        return true;
+    }
+    const role = element.getAttribute('role') ?? (element.localName === 'button' ? 'button' : '');
+    return NAMED_BY_CONTENT.has(role) && nameText(element).trim() !== '';
+};
+const audited = new WeakSet();
+const waiting = new Map();
+const readWaiting = () => {
+    const checks = [...waiting.values()];
+    waiting.clear();
+    for (const check of checks) {
+        check();
+    }
+};
+export const auditName = (host, control, fix, also) => {
+    if (audited.has(host) || waiting.has(host)) {
+        return;
+    }
+    if (waiting.size === 0) {
+        setTimeout(readWaiting, 0);
+    }
+    waiting.set(host, () => {
+        if (!host.isConnected) {
+            return;
+        }
+        audited.add(host);
+        const inner = control();
+        if (also?.() || hasName(host) || (inner !== null && hasName(inner))) {
+            return;
+        }
+        reportRuntime({
+            kind: 'missing-name',
+            message: `<${host.localName}> has no accessible name, so a screen reader announces it by its role alone. ${fix}`,
+            tag: host.localName,
+        });
+    });
+};