@fusion.dev/helix-core 0.145.0 → 0.147.0

package/dist/utils/load-more/load-more.d.ts

@@ -0,0 +1,25 @@
+/** Where a scrolling set stands, for the question of whether to ask for more. */
+export interface EndInSight {
+    /** The length the set last asked for more at, or `-1` where it never has. */
+    askedAt: number;
+    /** The set's length now, which the answer is kept for. */
+    count: number;
+    /** How far below the bottom of the box the set goes, in pixels. */
+    remaining: number;
+    /** The box's own height, in pixels: one screen. */
+    screen: number;
+}
+/**
+ * Whether a reader has come within one screen of the end of a set, and the
+ * set has not already asked for more at this length: React Aria's
+ * `onLoadMore` rule.
+ *
+ * **Once for each length**, so a scroll that goes on asks again only after the
+ * next page arrived and the length moved. False while the box has no height or
+ * the set no items, so a list that has not been laid out asks for nothing.
+ * The caller keeps `askedAt`, setting it to `count` when this answers true.
+ *
+ * Listbox asks this of its own scroll, and `VirtualizeController.endInSight`
+ * of the rows it lays out, so the two lists ask on the same terms.
+ */
+export declare const endInSight: ({ askedAt, count, remaining, screen }: EndInSight) => boolean;

package/dist/utils/load-more/load-more.js

@@ -0,0 +1 @@
+export const endInSight = ({ askedAt, count, remaining, screen }) => count > 0 && screen > 0 && askedAt !== count && remaining <= screen;

package/dist/utils/locale-of/locale-of.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The locale an element speaks: `own`, the element's own `locale` property,
+ * where one is set, and otherwise the `lang` of the nearest element with one,
+ * read out through any shadow root the element is drawn in.
+ *
+ * **The page's language is the default a reader expects.** A date picker on a
+ * page written `lang="de"` that names its months in English and starts its
+ * weeks on Sunday is a widget that ignored the one place the page said what
+ * language it is in; Shoelace and Web Awesome read the same attribute.
+ * `lang=""` is the page saying it does not know, and answers empty.
+ *
+ * Empty where nothing says, which every `Intl` call here takes as the
+ * runtime's own locale, and empty for a bare language the runtime already
+ * speaks (see `usable`). Read when asked rather than watched, so a page that
+ * changes its `lang` is answered in the new one on the element's next render.
+ * A server shim with no `closest` answers `own`, or empty.
+ */
+export declare const localeOf: (element: Element, own?: string) => string;

package/dist/utils/locale-of/locale-of.js

@@ -0,0 +1,26 @@
+let runtime;
+const usable = (lang) => {
+    try {
+        const asked = new Intl.Locale(lang);
+        runtime ??= new Intl.Locale(new Intl.DateTimeFormat().resolvedOptions().locale);
+        return asked.region === undefined && asked.language === runtime.language ? '' : asked.toString();
+    }
+    catch {
+        return '';
+    }
+};
+export const localeOf = (element, own = '') => {
+    if (own) {
+        return own;
+    }
+    let from = element;
+    while (from && typeof from.closest === 'function') {
+        const found = from.closest('[lang]');
+        if (found) {
+            return usable(found.getAttribute('lang') ?? '');
+        }
+        const root = from.getRootNode?.();
+        from = root?.host ?? null;
+    }
+    return '';
+};

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

@@ -0,0 +1,12 @@
+/**
+ * The words a node gives a name computed from its content: its text, read
+ * through slots, and the `aria-label` or `alt` of a picture in it, such as an
+ * icon named by its own label. A node hidden from the reader gives none, and
+ * so does `shown`, the part where a control shows its value.
+ *
+ * **In every build.** `AriaForwardController` asks it whether a control's own
+ * label has words in it, which decides where the host's label goes, so it is
+ * kept apart from the missing-name warning, which only a development build
+ * carries.
+ */
+export declare const nameText: (node: Node, shown?: Element | null) => string;

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

@@ -0,0 +1,25 @@
+export const nameText = (node, shown) => {
+    if (node === shown) {
+        return '';
+    }
+    if (node instanceof HTMLSlotElement) {
+        return node
+            .assignedNodes({ flatten: true })
+            .map((one) => nameText(one, shown))
+            .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((one) => nameText(one, shown)).join('');
+};

package/dist/utils/nearest/nearest.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The value in `values` nearest `target`, the first of two at the same
+ * distance, or `undefined` for none.
+ *
+ * Drawer's `snapTo` and Rating's reading of a score between its steps each
+ * wrote this loop. Given in ascending order, a target halfway between two
+ * goes to the lower, which is the rule both kept.
+ */
+export declare const nearest: (values: Iterable<number>, target: number) => number | undefined;

package/dist/utils/nearest/nearest.js

@@ -0,0 +1,9 @@
+export const nearest = (values, target) => {
+    let found;
+    for (const one of values) {
+        if (found === undefined || Math.abs(one - target) < Math.abs(found - target)) {
+            found = one;
+        }
+    }
+    return found;
+};

package/dist/utils/number-format/number-format.d.ts

@@ -9,13 +9,23 @@
  */
 /** Writes a number in a locale with `Intl.NumberFormat` options. */
 export declare const formatNumber: (value: number, locale?: string, options?: Intl.NumberFormatOptions) => string;
+/**
+ * A reading in words: `value` written with `options` where they say another
+ * style, and otherwise `share`, from 0 to 1, as a percentage, whole unless
+ * `options` say more.
+ *
+ * Meter and Progress each wrote this, with the value each holds to its range
+ * and the share of it that is filled.
+ */
+export declare const readingText: (value: number, share: number, locale?: string, options?: Intl.NumberFormatOptions) => string;
 /**
  * Reads a number written in a locale with the same options it is shown with,
  * or `null` where the text is no number.
  *
  * The locale's group separators are dropped and its decimal separator read as
  * a point, so `1.234,5` in `de-DE` is 1234.5. A currency sign, a percent sign
- * and a unit the options write are dropped too, and a percent is read back as
+ * and a unit the options write are dropped too, in the plural and the
+ * singular, and a percent is read back as
  * the fraction it shows: `25 %` is 0.25. A point is read as a decimal point in
  * a locale that groups with something else, which is what a decimal keypad
  * types.

package/dist/utils/number-format/number-format.js

@@ -9,19 +9,31 @@ const formatter = (locale, options) => {
     return found;
 };
 export const formatNumber = (value, locale = '', options) => formatter(locale, options).format(value);
+const WHOLE_PERCENT = { maximumFractionDigits: 0, style: 'percent' };
+export const readingText = (value, share, locale = '', options) => options && options.style !== 'percent'
+    ? formatNumber(value, locale, options)
+    : formatNumber(share, locale, options ?? WHOLE_PERCENT);
 const grouped = (text, separator, decimal) => {
     const whole = (text.split(decimal)[0] ?? '').replace(/^[+-]/u, '');
     return new RegExp(`^\\d{1,3}(${literal(separator)}\\d{3})+$`, 'u').test(whole);
 };
 const literal = (text) => text.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
 export const parseNumber = (text, locale = '', options) => {
-    const parts = formatter(locale, options).formatToParts(-12345.6);
-    const of = (type) => parts.filter((part) => part.type === type).map((part) => part.value);
+    const format = formatter(locale, options);
+    const parts = format.formatToParts(-12345.6);
+    const one = format.formatToParts(1);
+    const of = (type, from = parts) => from.filter((part) => part.type === type).map((part) => part.value);
     const group = of('group')[0] ?? ',';
     const decimal = of('decimal')[0] ?? '.';
-    const dropped = [...of('currency'), ...of('percentSign'), ...of('unit'), ...of('literal')]
-        .map((one) => one.trim())
-        .filter(Boolean);
+    const named = (from) => [
+        ...of('currency', from),
+        ...of('percentSign', from),
+        ...of('unit', from),
+        ...of('literal', from),
+    ];
+    const dropped = [...new Set([...named(parts), ...named(one)].map((word) => word.trim()))]
+        .filter(Boolean)
+        .sort((a, b) => b.length - a.length);
     const percent = options?.style === 'percent' && /[%\u066a\u2030]/u.test(text);
     let read = text.replace(/[\s\u00a0\u202f]/gu, '');
     for (const one of dropped) {

package/dist/utils/own-rule/own-rule.d.ts

@@ -0,0 +1,16 @@
+/**
+ * A page's own rule for a field's value: a message, a list of them, or `true`,
+ * `null` or nothing to accept the value. Input's and Textarea's `validate`.
+ */
+export type OwnRule = (value: string) => string | string[] | true | null | undefined;
+/**
+ * Applies a page's own rule after the native verdict was copied, as React
+ * Aria's TextField `validate` does: only while the browser finds nothing
+ * wrong, so a required empty field says the browser's sentence first. A list
+ * of messages is joined with spaces, and the message is a `customError`
+ * anchored at the control, so the bubble points at the text.
+ *
+ * A function rather than a member of `MixinField`, so only the fields that
+ * take `validate` carry it.
+ */
+export declare const applyOwnRule: (internals: ElementInternals, control: HTMLInputElement | HTMLTextAreaElement, rule: OwnRule | undefined, value: string) => void;

package/dist/utils/own-rule/own-rule.js

@@ -0,0 +1,7 @@
+export const applyOwnRule = (internals, control, rule, value) => {
+    const own = control.validity.valid ? rule?.(value) : undefined;
+    const message = Array.isArray(own) ? own.join(' ') : typeof own === 'string' ? own : '';
+    if (message !== '') {
+        internals.setValidity({ customError: true }, message, control);
+    }
+};

package/dist/utils/plain-click/plain-click.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Whether a click is a plain press of the main button, with no Command,
+ * Control, Shift or Alt held.
+ *
+ * A link pressed any other way opens where the browser opens it, a new tab or
+ * a new window, so an element that acts on a link's click first (a tab
+ * choosing itself, a skip link moving focus, an outline scrolling) leaves
+ * every other click to the browser.
+ */
+export declare const plainClick: (event: MouseEvent) => boolean;

package/dist/utils/plain-click/plain-click.js

@@ -0,0 +1 @@
+export const plainClick = (event) => event.button === 0 && !event.metaKey && !event.ctrlKey && !event.shiftKey && !event.altKey;

package/dist/utils/platform/platform.d.ts

@@ -21,3 +21,11 @@ export declare const appleTouch: (platform: Platform | undefined) => boolean;
  * `mod` as the key it names.
  */
 export declare const onApple: (platform?: Platform | undefined) => boolean;
+/**
+ * Whether the browser runs on Android, where TalkBack reads no `aria-sort`.
+ *
+ * React Aria's table header describes its sort order in words there for the
+ * same reason, so a reader who cannot hear the state still hears which way a
+ * column is sorted. From the user agent; `false` on a server.
+ */
+export declare const onAndroid: (platform?: Platform | undefined) => boolean;

package/dist/utils/platform/platform.js

@@ -9,3 +9,4 @@ export const appleTouch = (platform) => {
     return platform.platform === 'MacIntel' && (platform.maxTouchPoints ?? 0) > 1;
 };
 export const onApple = (platform = typeof navigator === 'undefined' ? undefined : navigator) => platform !== undefined && /mac|iphone|ipad|ipod/i.test(platform.userAgent ?? '');
+export const onAndroid = (platform = typeof navigator === 'undefined' ? undefined : navigator) => platform !== undefined && /android/i.test(platform.userAgent ?? '');

package/dist/utils/press-type/press-type.d.ts

@@ -0,0 +1,20 @@
+import type { PressPointerType } from '../../events/details.js';
+/** What the control saw before the click, which the click does not carry everywhere. */
+export interface RecentPress {
+    /** Whether Enter or Space started this press. */
+    key?: boolean;
+    /** The `pointerType` of the last `pointerdown` on the control. */
+    pointer?: string;
+}
+/**
+ * What a `click` came from, for `HelixPressEvent`.
+ *
+ * **Read in order.** The click's own pointer kind first, which Chromium and
+ * Firefox put on it. Then a key, which the caller saw start the press, because
+ * a keyboard press and a script's `click()` arrive alike. Then, for a click
+ * with a press count (`detail` above zero), the last pointer's kind, or
+ * `mouse` where none was seen, which is how Safari's click arrives. A click
+ * with none of these is `virtual`, as React Aria reads one: a screen reader's
+ * press or a script's `click()`.
+ */
+export declare const pressType: (click: MouseEvent, recent?: RecentPress) => PressPointerType;

package/dist/utils/press-type/press-type.js

@@ -0,0 +1,15 @@
+const POINTERS = new Set(['mouse', 'pen', 'touch']);
+export const pressType = (click, recent = {}) => {
+    const own = click.pointerType ?? '';
+    if (POINTERS.has(own)) {
+        return own;
+    }
+    if (recent.key === true) {
+        return 'keyboard';
+    }
+    if (click.detail > 0) {
+        const last = recent.pointer ?? '';
+        return POINTERS.has(last) ? last : 'mouse';
+    }
+    return 'virtual';
+};

package/dist/utils/read-series/read-series.d.ts

@@ -136,3 +136,17 @@ export declare const readRows: (table: Element) => Row[];
  * name is written, in `lines`, `hidden-series` and `hide()` alike.
  */
 export declare const seriesKey: (name: string) => string;
+/** Where the highest and the lowest readings are, by place, or none. */
+export interface Extremes {
+    /** The place of the highest reading, the first where several tie. */
+    high?: number;
+    /** The place of the lowest reading, the first where several tie. */
+    low?: number;
+}
+/**
+ * Where the highest and the lowest readings stand. A blank slot is passed
+ * over, and a list with nothing in it has neither.
+ *
+ * Sparkline's overview and Heatmap's busiest place each looked for these.
+ */
+export declare const extremesOf: (slots: readonly (number | undefined)[]) => Extremes;

package/dist/utils/read-series/read-series.js

@@ -139,3 +139,18 @@ export const readRows = (table) => {
     return [...(element.tBodies[0]?.rows ?? [])].map((one) => row(one.cells[0], [...one.cells].slice(1), names));
 };
 export const seriesKey = (name) => name.trim().toLowerCase();
+export const extremesOf = (slots) => {
+    const found = {};
+    slots.forEach((value, at) => {
+        if (value === undefined) {
+            return;
+        }
+        if (found.high === undefined || value > slots[found.high]) {
+            found.high = at;
+        }
+        if (found.low === undefined || value < slots[found.low]) {
+            found.low = at;
+        }
+    });
+    return found;
+};

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

@@ -1,3 +1,11 @@
+/**
+ * How long each unit lasts, in milliseconds, largest last. `elapsedTime`
+ * reads its minute, hour and day from here.
+ */
+export declare const UNITS: Array<{
+    ms: number;
+    unit: Intl.RelativeTimeFormatUnit;
+}>;
 /** What one timestamp reads as, and when that stops being true. */
 export interface Relative {
     /**

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

@@ -1,5 +1,5 @@
 const held = new Map();
-const UNITS = [
+export const UNITS = [
     { ms: 1000, unit: 'second' },
     { ms: 60_000, unit: 'minute' },
     { ms: 3_600_000, unit: 'hour' },
@@ -25,7 +25,10 @@ export const relativeTime = (locale, options = {}) => {
         }
         const size = Math.abs(elapsed);
         if (size < 60_000) {
-            return { next: Math.max(1000, 60_000 - size), text: found.format(0, 'second') };
+            return {
+                next: Math.max(1000, 60_000 - size),
+                text: found.format(elapsed > 0 ? 0 : -0, 'second'),
+            };
         }
         let chosen = UNITS[1];
         for (const unit of UNITS) {

package/dist/utils/report-render/report-render.js

@@ -1,18 +1,6 @@
+import { callListener } from '../call-listener/call-listener.js';
 export const RENDER_SLOT = Symbol.for('fusion.dev/helix/render');
 export const measuring = () => typeof globalThis[RENDER_SLOT] === 'function';
-let told = false;
 export const reportRender = (element, start, duration) => {
-    const listener = globalThis[RENDER_SLOT];
-    if (typeof listener !== 'function') {
-        return;
-    }
-    try {
-        listener(element, { duration, start });
-    }
-    catch (error) {
-        if (!told) {
-            told = true;
-            console.error('helix: a render listener threw, and the element rendered as usual. Later failures are not printed.', error);
-        }
-    }
+    callListener(RENDER_SLOT, 'render', 'the element rendered as usual', element, { duration, start });
 };

package/dist/utils/report-runtime/report-runtime.d.ts

@@ -18,12 +18,12 @@
  */
 /** What went wrong, stable across versions, so it can be counted. */
 export type RuntimeKind = 
+/** A deprecated property, attribute or slot was used; the message names what replaces it. */
+'deprecated'
 /** Another class asked for a tag that is already registered: two copies of Helix. */
-'duplicate-registration'
+ | 'duplicate-registration'
 /** The browser refused fullscreen, usually for a frame without the permission. */
  | 'fullscreen-refused'
-/** An Avatar Group's `max` is past the number the fold is written for. */
- | 'max-past-fold'
 /** A rating's `min` is no score between 0 and its `max`. */
  | 'min-out-of-range'
 /** A Stat was given one of Trend's directions, `up`, `down` or `neutral`, which lay nothing out. */
@@ -34,12 +34,17 @@ export type RuntimeKind =
  | 'missing-alt'
 /** The three.js driver could not load its layout, so the notes stay where they started. */
  | 'missing-layout'
-/** A control has no accessible name, so a screen reader announces it by its role alone. */
+/**
+ * A control has no accessible name, so a screen reader announces it by its role alone.
+ * Reported in development builds only (the `development` export condition).
+ */
  | 'missing-name'
 /** A selectable Data Table has no `row-key`, so it knows each row by its place. */
  | 'missing-row-key'
 /** A stencil names parts the shape does not have. */
  | 'missing-stencil-parts'
+/** A chart, a legend or a sparkline names no table with `for`. Development builds only. */
+ | 'missing-table'
 /** A Skip Link's `href` names no element in its tree, so a press moves focus nowhere. */
  | 'missing-target'
 /** A tooltip's `for` names no element in its own tree. */
@@ -64,6 +69,8 @@ export type RuntimeKind =
  | 'too-many-rows'
 /** A filter field marks more than one operator as its default. */
  | 'two-default-operators'
+/** A Quote's text starts or ends with a quotation mark, so the browser's marks double it. */
+ | 'typed-marks'
 /** A React handler prop names an event nothing dispatches. */
  | 'unknown-event'
 /** An Icon's `name` is in no icon set it can read, so it draws nothing. */

package/dist/utils/report-runtime/report-runtime.js

@@ -1,7 +1,7 @@
+import { callListener } from '../call-listener/call-listener.js';
 export const RUNTIME_SLOT = Symbol.for('fusion.dev/helix/runtime');
 export const RUNTIME_LOG = Symbol.for('fusion.dev/helix/runtime-log');
 const KEPT = 200;
-let told = false;
 export const reportRuntime = (event) => {
     const store = globalThis;
     const log = Array.isArray(store[RUNTIME_LOG]) ? store[RUNTIME_LOG] : [];
@@ -9,19 +9,7 @@ export const reportRuntime = (event) => {
         log.push(event);
     }
     store[RUNTIME_LOG] = log;
-    let quiet = false;
-    const listener = store[RUNTIME_SLOT];
-    if (typeof listener === 'function') {
-        try {
-            quiet = listener(event) === true;
-        }
-        catch (error) {
-            if (!told) {
-                told = true;
-                console.error('helix: a runtime listener threw, and the warning is printed here. Later failures are not printed.', error);
-            }
-        }
-    }
+    const quiet = callListener(RUNTIME_SLOT, 'runtime', 'the warning is printed here', event) === true;
     if (quiet) {
         return;
     }

package/dist/utils/report-usage/report-usage.js

@@ -1,4 +1,5 @@
 import { VERSION } from '../../version.js';
+import { callListener } from '../call-listener/call-listener.js';
 export const USAGE_SLOT = Symbol.for('fusion.dev/helix/usage');
 export const VERSIONS_SLOT = Symbol.for('fusion.dev/helix/versions');
 export const noteVersion = () => {
@@ -9,19 +10,6 @@ export const noteVersion = () => {
     }
     store[VERSIONS_SLOT] = listed;
 };
-let told = false;
 export const reportUsage = (element) => {
-    const listener = globalThis[USAGE_SLOT];
-    if (typeof listener !== 'function') {
-        return;
-    }
-    try {
-        listener(element);
-    }
-    catch (error) {
-        if (!told) {
-            told = true;
-            console.error('helix: a usage listener threw, and the element rendered as usual. Later failures are not printed.', error);
-        }
-    }
+    callListener(USAGE_SLOT, 'usage', 'the element rendered as usual', element);
 };

package/dist/utils/row-data/row-data.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The value at `path` in a row of data, or `undefined` where the path leads
+ * nowhere: the field a Table or Data Table column, a Data Table's `row-key`
+ * or a Virtual List's template hole names.
+ *
+ * A dot separates keys, so `author.name` reads `row.author.name`. A key that
+ * holds a dot itself is read whole first, so a flat record with a key such as
+ * `"v1.2"` keeps working. An empty path reads nothing, and so does a row that
+ * is no record. `undefined` is drawn as an empty cell: a missing key is a hole
+ * in the data, and drawing "undefined" tells a reader the software is broken.
+ *
+ * Written here rather than taken from a library, because the whole of what is
+ * needed is "walk the keys and stop at the first thing that is not an object".
+ */
+export declare const valueAt: (row: unknown, path: string) => unknown;

package/dist/utils/row-data/row-data.js

@@ -0,0 +1,17 @@
+export const valueAt = (row, path) => {
+    if (path === '' || row === null || typeof row !== 'object') {
+        return undefined;
+    }
+    const record = row;
+    if (path in record) {
+        return record[path];
+    }
+    let value = record;
+    for (const key of path.split('.')) {
+        if (value === null || typeof value !== 'object') {
+            return undefined;
+        }
+        value = value[key];
+    }
+    return value;
+};