@fusion.dev/helix-core 0.145.0 → 0.147.0

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

@@ -8,6 +8,8 @@ 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';
+import { appleTouch } from '../../utils/platform/platform.js';
+import { verdictFlags } from '../../utils/verdict-flags/verdict-flags.js';
 export const MixinSegmentedField = (Base) => {
     class SegmentedFieldElement extends Base {
         constructor() {
@@ -17,6 +19,7 @@ export const MixinSegmentedField = (Base) => {
             this.parts = {};
             this.typed = '';
             this.own = false;
+            this.touchApple = appleTouch(typeof navigator === 'undefined' ? undefined : navigator);
             this.entered = undefined;
             this.handleSegmentKeydown = (event) => {
                 const element = event.currentTarget;
@@ -169,7 +172,7 @@ export const MixinSegmentedField = (Base) => {
             }
             const anchor = this.anchor ?? undefined;
             const partial = isPartial(this.segmentedKind, this.parts, this.layout);
-            const message = this.validate();
+            const fault = verdictFlags(this.validate());
             if (partial) {
                 this.internals.setValidity({ badInput: true }, this.badInputMessage ||
                     (this.segmentedKind === 'date' ? 'Enter a whole date.' : 'Enter a whole time.'), anchor);
@@ -178,8 +181,8 @@ export const MixinSegmentedField = (Base) => {
                 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 if (fault !== null) {
+                this.internals.setValidity(fault[0], fault[1], anchor);
             }
             else {
                 this.internals.setValidity({});
@@ -210,17 +213,24 @@ export const MixinSegmentedField = (Base) => {
                 const { max, min } = segmentRange(kind, this.parts, twelve);
                 const text = segmentText(kind, this.parts, twelve, locale);
                 const empty = shown === undefined;
+                const id = `${this.controlId}-${kind}`;
+                const editable = !this.isDisabled && !this.readOnly;
+                const spin = !this.touchApple;
                 return html `<span
             part="segment${empty ? ' segment-placeholder' : ''}"
+            id=${id}
             data-segment=${kind}
-            role="spinbutton"
+            role=${spin ? 'spinbutton' : 'textbox'}
             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)}
+            enterkeyhint=${editable ? 'next' : nothing}
+            aria-label=${this.labeled ? `${segmentName(kind, locale)},` : segmentName(kind, locale)}
+            aria-labelledby=${this.labeled ? `${id} ${this.labelId}` : nothing}
+            aria-invalid=${this.invalidity ?? nothing}
+            aria-valuemin=${spin ? min : nothing}
+            aria-valuemax=${spin ? max : nothing}
+            aria-valuenow=${spin ? (shown ?? nothing) : nothing}
+            aria-valuetext=${spin ? (empty ? this.emptySegmentLabel : segmentValueText(kind, this.parts, twelve, locale)) : nothing}
             aria-disabled=${this.isDisabled ? 'true' : nothing}
             aria-readonly=${this.readOnly ? 'true' : nothing}
             @keydown=${this.handleSegmentKeydown}

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

@@ -0,0 +1,10 @@
+import type { auditName as audit } from './audit-name.js';
+/**
+ * The missing-name warning in a production build: nothing.
+ *
+ * `#audit-name` resolves here unless the bundler or runtime asks for the
+ * `development` condition, so a production build carries none of the audit's
+ * code. The signature is the audit's, so a call site reads the same in both
+ * builds. See `audit-name.ts`.
+ */
+export declare const auditName: typeof audit;

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

@@ -0,0 +1 @@
+export const auditName = () => { };

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

@@ -1,13 +1,23 @@
 /**
  * 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.
+ * control: its own `aria-label`, `aria-labelledby` or `title`, a `<label>`,
+ * and its content where its role is named by its content.
+ *
+ * **A `placeholder` counts for no route.** A browser names a control by it
+ * where nothing else does, and it is gone from the screen once a person
+ * types, so a field named by it alone loses its label as it is filled.
+ * React Aria's fields warn on the same terms.
  *
  * **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.
+ *
+ * **What the control shows as its value is no name**, so the words in
+ * `shown` count for no route. A Select with no label names its trigger by the
+ * part that shows the choice, and while nothing is chosen that part shows the
+ * placeholder, "Choose", which says nothing about what is being chosen.
  */
-export declare const hasName: (element: HTMLElement) => boolean;
+export declare const hasName: (element: HTMLElement, shown?: Element | null) => 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.
@@ -18,11 +28,19 @@ export declare const hasName: (element: HTMLElement) => boolean;
  * 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`.
+ * **In a development build only.** Every field and Button calls it, so in
+ * production it would cost each of them about 450 bytes gzip for a sentence
+ * meant for the person writing the page. Core imports it as `#audit-name`,
+ * which `package.json` resolves here under the `development` condition (Vite
+ * and webpack in development, `bun --conditions development`,
+ * `node --conditions=development`) and to `audit-name-off.ts`, which does
+ * nothing, everywhere else. Like every runtime warning it reports through the
+ * one channel, 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.
+ * attribute shows. `fix` is the sentence that says how to name it. `shown` is
+ * the part where the control shows its value or its placeholder, whose words
+ * are no name.
  */
-export declare const auditName: (host: HTMLElement, control: () => HTMLElement | null, fix: string, also?: () => boolean) => void;
+export declare const auditName: (host: HTMLElement, control: () => HTMLElement | null, fix: string, also?: () => boolean, shown?: () => Element | null) => void;

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

@@ -1,31 +1,13 @@
+import { nameText } from '../name-text/name-text.js';
 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 namesWithWords = (ids, from, shown) => {
     const root = from.getRootNode();
     return (ids ?? '')
         .split(/\s+/)
         .filter(Boolean)
         .some((id) => {
         const found = root.getElementById?.(id);
-        return found ? nameText(found).trim() !== '' : false;
+        return found ? nameText(found, shown).trim() !== '' : false;
     });
 };
 const NAMED_BY_CONTENT = new Set([
@@ -40,26 +22,32 @@ const NAMED_BY_CONTENT = new Set([
     'switch',
     'tab',
 ]);
-export const hasName = (element) => {
-    for (const attribute of ['aria-label', 'title', 'placeholder']) {
+export const hasName = (element, shown) => {
+    for (const attribute of ['aria-label', 'title']) {
         if (element.getAttribute(attribute)?.trim()) {
             return true;
         }
     }
-    if (namesWithWords(element.getAttribute('aria-labelledby'), element)) {
+    if (namesWithWords(element.getAttribute('aria-labelledby'), element, shown)) {
         return true;
     }
     const referenced = element
         .ariaLabelledByElements;
-    if ((referenced ?? []).some((one) => nameText(one).trim() !== '')) {
+    if ((referenced ?? []).some((one) => nameText(one, shown).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 role = element.getAttribute('role') ?? implicitRole(element);
+    return NAMED_BY_CONTENT.has(role) && nameText(element, shown).trim() !== '';
+};
+const implicitRole = (element) => {
+    if (element.localName === 'button' || element.localName === 'summary') {
+        return 'button';
+    }
+    return element.localName === 'a' && element.hasAttribute('href') ? 'link' : '';
 };
 const audited = new WeakSet();
 const waiting = new Map();
@@ -70,7 +58,7 @@ const readWaiting = () => {
         check();
     }
 };
-export const auditName = (host, control, fix, also) => {
+export const auditName = (host, control, fix, also, shown) => {
     if (audited.has(host) || waiting.has(host)) {
         return;
     }
@@ -83,12 +71,16 @@ export const auditName = (host, control, fix, also) => {
         }
         audited.add(host);
         const inner = control();
-        if (also?.() || hasName(host) || (inner !== null && hasName(inner))) {
+        const value = shown?.();
+        if (also?.() || hasName(host) || (inner !== null && hasName(inner, value))) {
             return;
         }
+        const placeholder = [host, inner].some((one) => one?.getAttribute('placeholder')?.trim());
         reportRuntime({
             kind: 'missing-name',
-            message: `<${host.localName}> has no accessible name, so a screen reader announces it by its role alone. ${fix}`,
+            message: placeholder
+                ? `<${host.localName}> is named only by its placeholder, which is gone once a person types. ${fix}`
+                : `<${host.localName}> has no accessible name, so a screen reader announces it by its role alone. ${fix}`,
             tag: host.localName,
         });
     });

package/dist/utils/audit-source/audit-source-off.d.ts

@@ -0,0 +1,10 @@
+import type { auditSource as audit } from './audit-source.js';
+/**
+ * The missing-table warning in a production build: nothing.
+ *
+ * `#audit-source` resolves here unless the bundler or runtime asks for the
+ * `development` condition, so a production build carries none of the audit's
+ * code. The signature is the audit's, so a call site reads the same in both
+ * builds. See `audit-source.ts`.
+ */
+export declare const auditSource: typeof audit;

package/dist/utils/audit-source/audit-source-off.js

@@ -0,0 +1 @@
+export const auditSource = () => { };

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

@@ -0,0 +1,19 @@
+/**
+ * Reports a chart, a legend or a sparkline whose `for` names no table once the
+ * page has loaded, the one mistake that leaves it drawing nothing and saying
+ * nothing.
+ *
+ * **Read a task after `load`**, so a table later in the markup, or one a
+ * script writes as the page starts, counts. A table a framework renders later
+ * than that is reported, and the chart still draws it when it arrives.
+ *
+ * **In a development build only**, as `missing-name` is: every chart would pay
+ * for a sentence meant for the person writing the page. Core imports it as
+ * `#audit-source`, which `package.json` resolves here under the `development`
+ * condition and to `audit-source-off.ts`, which does nothing, everywhere else.
+ *
+ * `table` answers what `for` resolves to now: the table, or null.
+ */
+export declare const auditSource: (host: HTMLElement & {
+    for: string;
+}, table: () => Element | null) => void;

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

@@ -0,0 +1,27 @@
+import { reportRuntime } from '../report-runtime/report-runtime.js';
+const audited = new WeakSet();
+export const auditSource = (host, table) => {
+    if (host.for === '' || audited.has(host) || typeof document === 'undefined') {
+        return;
+    }
+    audited.add(host);
+    const read = () => {
+        setTimeout(() => {
+            if (host.isConnected && host.for !== '' && !table()) {
+                reportRuntime({
+                    kind: 'missing-table',
+                    message: `<${host.localName} for="${host.for}"> names no table, so it draws nothing. ` +
+                        'Point `for` at the id of a <table>, an element with role="table" or "grid", or a ' +
+                        'helix-table, in the same tree.',
+                    tag: host.localName,
+                });
+            }
+        }, 0);
+    };
+    if (document.readyState === 'complete') {
+        read();
+    }
+    else {
+        window.addEventListener('load', read, { once: true });
+    }
+};

package/dist/utils/calendar/calendar.js

@@ -1,4 +1,4 @@
-import { valueAsDate as asDate, dateAsValue as fromDate } from '../value-as/value-as.js';
+import { valueAsDate as asDate, dateAsValue as fromDate, utcDate } from '../value-as/value-as.js';
 import { writtenList } from '../written-list/written-list.js';
 export const localToday = (now = new Date()) => {
     const month = `${now.getMonth() + 1}`.padStart(2, '0');
@@ -15,13 +15,13 @@ export const weekStartOf = (locale) => {
         return 0;
     }
 };
-export const monthOf = (date) => `${date.getUTCFullYear()}-${String(date.getUTCMonth() + 1).padStart(2, '0')}`;
-export const addDays = (date, days) => new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate() + days));
+export const monthOf = (date) => `${String(date.getUTCFullYear()).padStart(4, '0')}-${String(date.getUTCMonth() + 1).padStart(2, '0')}`;
+export const addDays = (date, days) => utcDate(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate() + days);
 export const sameMonth = (left, right) => left.getUTCFullYear() === right.getUTCFullYear() && left.getUTCMonth() === right.getUTCMonth();
 export const addMonths = (date, months) => {
-    const target = new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth() + months, 1));
-    const last = new Date(Date.UTC(target.getUTCFullYear(), target.getUTCMonth() + 1, 0)).getUTCDate();
-    return new Date(Date.UTC(target.getUTCFullYear(), target.getUTCMonth(), Math.min(date.getUTCDate(), last)));
+    const target = utcDate(date.getUTCFullYear(), date.getUTCMonth() + months, 1);
+    const last = utcDate(target.getUTCFullYear(), target.getUTCMonth() + 1, 0).getUTCDate();
+    return utcDate(target.getUTCFullYear(), target.getUTCMonth(), Math.min(date.getUTCDate(), last));
 };
 export const barredBy = (date, rules) => {
     const iso = fromDate(date);
@@ -72,7 +72,7 @@ export const periodCells = ({ max, min, page, shown, today, view }) => {
     const start = years ? yearPageOf(page) : page;
     return Array.from({ length: 12 }, (_, index) => {
         const at = years ? start + index : index;
-        const first = new Date(Date.UTC(years ? at : start, years ? 0 : index, 1));
+        const first = utcDate(years ? at : start, years ? 0 : index, 1);
         return {
             at,
             chosen: years ? at === shown.getUTCFullYear() : monthOf(first) === monthOf(shown),

package/dist/utils/call-listener/call-listener.d.ts

@@ -0,0 +1,16 @@
+/**
+ * What the three diagnostics slots share: a listener on `globalThis` under a
+ * registered symbol, called where there is one, whose failure is printed once.
+ *
+ * `reportRuntime`, `reportUsage` and `reportRender` each wrote this out, with
+ * a flag and a sentence of its own, and every element carries all three. Kept
+ * as one function, the sentence is one template and the flags one set.
+ */
+/**
+ * Calls the function in `slot` with `args`, and answers what it returned.
+ *
+ * **A listener that throws never breaks the caller.** The error is printed
+ * once per `kind`, saying what happened instead (`after`), and the answer is
+ * `undefined`, as it is where nothing listens.
+ */
+export declare const callListener: (slot: symbol, kind: string, after: string, ...args: unknown[]) => unknown;

package/dist/utils/call-listener/call-listener.js

@@ -0,0 +1,17 @@
+const told = new Set();
+export const callListener = (slot, kind, after, ...args) => {
+    const listener = globalThis[slot];
+    if (typeof listener !== 'function') {
+        return undefined;
+    }
+    try {
+        return listener(...args);
+    }
+    catch (error) {
+        if (!told.has(kind)) {
+            told.add(kind);
+            console.error(`helix: a ${kind} listener threw, and ${after}. Later failures are not printed.`, error);
+        }
+        return undefined;
+    }
+};

package/dist/utils/chord/chord.d.ts

@@ -41,3 +41,17 @@ export interface ChordPress {
  * should go to whatever did want it.
  */
 export declare const matchesChord: (press: ChordPress, keys: string, apple: boolean) => boolean;
+/**
+ * Whether a key press is Control+A, or Command+A on an Apple keyboard: the
+ * press that selects every item of a multiple selection.
+ *
+ * List, Tree, Listbox, Data Table and Virtual List each wrote the test. Either
+ * modifier counts on any platform, as they did, and Alt held is another
+ * shortcut.
+ */
+export declare const selectsAll: (press: {
+    readonly altKey: boolean;
+    readonly ctrlKey: boolean;
+    readonly key: string;
+    readonly metaKey: boolean;
+}) => boolean;

package/dist/utils/chord/chord.js

@@ -51,3 +51,4 @@ export const matchesChord = (press, keys, apple) => {
         (ctrl ? press.ctrlKey : !press.ctrlKey) &&
         (meta ? press.metaKey : !press.metaKey));
 };
+export const selectsAll = (press) => (press.ctrlKey || press.metaKey) && !press.altKey && press.key.toLowerCase() === 'a';

package/dist/utils/clamp/clamp.d.ts

@@ -0,0 +1,7 @@
+/**
+ * `value` held between `low` and `high`.
+ *
+ * Written four times before: Lightbox's zoom, Scroll Area's scrollbar, Color
+ * Picker's channels and core's color reading.
+ */
+export declare const clamp: (value: number, low: number, high: number) => number;

package/dist/utils/clamp/clamp.js

@@ -0,0 +1 @@
+export const clamp = (value, low, high) => Math.min(Math.max(value, low), high);

package/dist/utils/css-color/css-color.js

@@ -1,4 +1,4 @@
-const clamp = (value, low, high) => Math.min(high, Math.max(low, value));
+import { clamp } from '../clamp/clamp.js';
 const toAlpha = (token) => {
     if (token === undefined) {
         return 100;

package/dist/utils/draw-tooltip/draw-tooltip.d.ts

@@ -46,7 +46,7 @@ export interface TooltipAt {
  *
  * The chart's `pointer` is one, and is what every chart passes.
  */
-export type ReadingCursor = Pick<ChartPointerController, 'column' | 'keyed'>;
+export type ReadingCursor = Pick<ChartPointerController, 'column' | 'keyed'> & Partial<Pick<ChartPointerController, 'position' | 'shows'>>;
 /**
  * What a pointer resting on a reading shows, as `Tooltip` pointed at a mark.
  *

package/dist/utils/draw-tooltip/draw-tooltip.js

@@ -10,7 +10,9 @@ export const drawTooltip = (rows, at, tag, where, slotOf, reading) => {
     const row = rows[at];
     const live = reading === undefined || rows.length === 0
         ? nothing
-        : html `<span aria-live="polite" part="live" role="status">${reading.keyed && row ? spokenReading(row, reading.column) : ''}</span>`;
+        : html `<span aria-live="polite" part="live" role="status">${reading.keyed && row
+            ? spokenReading(row, reading.column, (cell) => reading.shows?.(cell) !== false, reading.position)
+            : ''}</span>`;
     if (!row || rows.length === 0) {
         return live;
     }

package/dist/utils/draw-tooltip/spoken-reading.d.ts

@@ -5,6 +5,10 @@ import type { Row } from '../read-series/read-series.js';
  *
  * The table's own text, as the bubble shows it, so the words and the picture
  * agree, and nothing in it is English: the names are the table's headings. A
- * blank cell says nothing and is left out.
+ * blank cell says nothing and is left out, and so is a cell `shows` answers
+ * false for, which is a series a legend hid.
+ *
+ * `position` follows in brackets, such as "2 of 12", where the chart gives
+ * one: last, so the reading is heard before where it stands.
  */
-export declare const spokenReading: (row: Row, column?: number) => string;
+export declare const spokenReading: (row: Row, column?: number, shows?: (cell: number) => boolean, position?: string) => string;

package/dist/utils/draw-tooltip/spoken-reading.js

@@ -1,10 +1,11 @@
-export const spokenReading = (row, column) => {
+export const spokenReading = (row, column, shows = () => true, position = '') => {
+    const after = position === '' ? '' : ` (${position})`;
     const cell = column === undefined ? undefined : row.cells[column];
     if (cell) {
-        return `${row.label}, ${cell.name} ${cell.text}`.trim();
+        return `${`${row.label}, ${cell.name} ${cell.text}`.trim()}${after}`;
     }
     const said = row.cells
-        .filter((one) => one.text.trim() !== '')
+        .filter((one, index) => one.text.trim() !== '' && shows(index))
         .map((one) => `${one.name} ${one.text}`.trim());
-    return said.length === 0 ? row.label : `${row.label}: ${said.join(', ')}`;
+    return `${said.length === 0 ? row.label : `${row.label}: ${said.join(', ')}`}${after}`;
 };

package/dist/utils/elapsed-time/elapsed-time.d.ts

@@ -1,4 +1,4 @@
-import type { Relative } from '../relative-time/relative-time.js';
+import { type Relative } from '../relative-time/relative-time.js';
 /**
  * A formatter for one locale, kept.
  *

package/dist/utils/elapsed-time/elapsed-time.js

@@ -1,10 +1,7 @@
+import { UNITS as TIME_UNITS } from '../relative-time/relative-time.js';
 const held = new Map();
 const dated = new Map();
-const UNITS = [
-    { ms: 60_000, unit: 'minute' },
-    { ms: 3_600_000, unit: 'hour' },
-    { ms: 86_400_000, unit: 'day' },
-];
+const UNITS = TIME_UNITS.slice(1, 4);
 const HORIZON = 604_800_000;
 const compact = (locale) => {
     let found = held.get(locale);

package/dist/utils/heading-level/heading-level.d.ts

@@ -0,0 +1,8 @@
+/**
+ * A heading level a reader can be told: a whole number from 1 to 6, from
+ * the level asked for, or `fallback` where none was.
+ *
+ * `aria-level` takes a whole number, so a fraction is cut to the level below
+ * it, and a level past either end is held at it: `0` is 1 and `9` is 6.
+ */
+export declare const headingLevel: (level: number | undefined, fallback?: number) => number;

package/dist/utils/heading-level/heading-level.js

@@ -0,0 +1,4 @@
+export const headingLevel = (level, fallback = 3) => {
+    const asked = level === undefined || Number.isNaN(level) ? fallback : level;
+    return Math.min(6, Math.max(1, Math.trunc(asked)));
+};

package/dist/utils/host-words/host-words.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The words that name a host, for a part inside its shadow root that must
+ * carry the same name: the list a Select or a Time Picker opens.
+ *
+ * **Words rather than a reference**, because the part is inside the host's
+ * shadow root, and neither an IDREF on the page nor the host's labels reach
+ * it. Read in the order a browser names the host: its `aria-labelledby`, its
+ * `aria-label`, then `own`, the name the component draws itself (its `label`),
+ * then a `<label>` for it. Each element's words are read as a name reads
+ * them, so hidden text is left out and runs of white space are one space.
+ *
+ * Empty where nothing names the host, which leaves the fallback to the caller.
+ */
+export declare const hostWords: (host: HTMLElement & {
+    labels?: NodeList | null;
+}, own?: string) => string;

package/dist/utils/host-words/host-words.js

@@ -0,0 +1,13 @@
+import { elementById } from '../element-by-id/element-by-id.js';
+import { nameText } from '../name-text/name-text.js';
+const wordsOf = (named) => named
+    .map((one) => (one ? nameText(one).replace(/\s+/g, ' ').trim() : ''))
+    .filter(Boolean)
+    .join(' ');
+export const hostWords = (host, own = '') => {
+    const ids = (host.getAttribute('aria-labelledby') ?? '').split(/\s+/).filter(Boolean);
+    return (wordsOf(ids.map((id) => elementById(host, id))) ||
+        host.getAttribute('aria-label')?.trim() ||
+        own ||
+        wordsOf([...(host.labels ?? [])]));
+};

package/dist/utils/implicit-submit/implicit-submit.d.ts

@@ -0,0 +1,25 @@
+/** Whether `element` is a submit button, native or Helix. */
+export declare const submits: (element: Element) => boolean;
+/** The form's default button, the first submit button in it, native or Helix. */
+export declare const defaultButton: (form: HTMLFormElement) => Element | undefined;
+/** Whether `target` is a native field of `form` that Enter submits it from. */
+export declare const submitsOnEnter: (target: EventTarget | undefined, form: HTMLFormElement) => boolean;
+/**
+ * Submits a control's form the way pressing Enter in a native text field does.
+ *
+ * A Helix control's own input is in a shadow root and has no form owner, so
+ * the platform never runs implicit submission for it. This runs it: the form's
+ * default button is activated, the first submit button in it, a Helix one
+ * included. With none, the form is submitted when it holds no more than one
+ * field that counts against implicit submission, and nothing happens
+ * otherwise.
+ *
+ * **A module of its own rather than a method on the base**, so its code ships
+ * only with the controls that submit on Enter (Input, Number Input, Pin Input,
+ * Combobox, the picker fields and Button) and not with Switch, Checkbox or
+ * Slider. `form` is the control's `form`, and a control with none submits
+ * nothing.
+ *
+ * @reference https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#implicit-submission implicit submission
+ */
+export declare const submitImplicitly: (form: HTMLFormElement | null) => void;

package/dist/utils/implicit-submit/implicit-submit.js

@@ -0,0 +1,52 @@
+import { HelixFormElement } from '../../helix-form-element/helix-form-element.js';
+const BLOCKING_TYPES = new Set([
+    'date',
+    'datetime-local',
+    'email',
+    'month',
+    'number',
+    'password',
+    'search',
+    'tel',
+    'text',
+    'time',
+    'url',
+    'week',
+]);
+const hooks = (element) => element;
+export const submits = (element) => {
+    if (element instanceof HelixFormElement) {
+        return hooks(element).submitsForm;
+    }
+    if (element instanceof HTMLButtonElement) {
+        return element.type === 'submit';
+    }
+    return (element instanceof HTMLInputElement && (element.type === 'submit' || element.type === 'image'));
+};
+export const defaultButton = (form) => [...form.elements].find((element) => submits(element));
+export const submitsOnEnter = (target, form) => target instanceof HTMLInputElement && target.form === form && BLOCKING_TYPES.has(target.type);
+export const submitImplicitly = (form) => {
+    if (!form) {
+        return;
+    }
+    const button = defaultButton(form);
+    if (button) {
+        if (button.matches(':disabled')) {
+            return;
+        }
+        if (button instanceof HelixFormElement) {
+            hooks(button).activate();
+        }
+        else {
+            ;
+            button.click();
+        }
+        return;
+    }
+    const blocking = [...form.elements].filter((element) => element instanceof HelixFormElement
+        ? hooks(element).blocksImplicitSubmission
+        : element instanceof HTMLInputElement && BLOCKING_TYPES.has(element.type));
+    if (blocking.length <= 1) {
+        form.requestSubmit();
+    }
+};