@fusion.dev/helix-core 0.143.0 → 0.144.0

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

@@ -138,3 +138,4 @@ export const readRows = (table) => {
         .map((one) => one.textContent?.trim() ?? '');
     return [...(element.tBodies[0]?.rows ?? [])].map((one) => row(one.cells[0], [...one.cells].slice(1), names));
 };
+export const seriesKey = (name) => name.trim().toLowerCase();

package/dist/utils/reflect-elements/reflect-elements.d.ts

@@ -0,0 +1,37 @@
+/** The ARIA properties that take elements rather than ids. */
+export type ElementsProperty = 'ariaDescribedByElements' | 'ariaLabelledByElements';
+/**
+ * Writes elements onto an ARIA element-reflection property of `target`, or
+ * clears it, and says whether the property is now this caller's.
+ *
+ * Element references, because the words are in the light DOM and the panel in
+ * a shadow root, which an IDREF cannot cross. Nothing is written where the
+ * engine has no reflection, which keeps the fallback name, and the answer is
+ * then `owned` as it was. **An empty list clears the property only where the
+ * caller wrote it**, which `owned` says, so a name another hand wrote stays.
+ *
+ * Dialog and Drawer name their panel by its header this way, Popover by its
+ * first heading, Dialog describes itself by its body, and a Tour stop names
+ * and describes its panel.
+ */
+export declare const reflectElements: (target: Element | null | undefined, property: ElementsProperty, elements: readonly Element[], owned: boolean) => boolean;
+/**
+ * Adds `by` to the elements that describe `target`, where that is safe, and
+ * says whether `target` is now described by it.
+ *
+ * Through element reflection, and only where no framework is watching:
+ *
+ * - **Inside a shadow root**, such as the `<button>` a Helix button draws, it
+ *   is always safe. That markup is the component's own, and no server sent it.
+ * - **In the light DOM**, the element is the consumer's, and reflection writes
+ *   an empty `aria-describedby` onto it. So it is written only when `light` is
+ *   set, which a caller does once a reader has acted on the page, after any
+ *   hydration, and never where the consumer wrote `aria-describedby` or
+ *   `aria-labelledby` themselves, which are theirs to keep.
+ *
+ * Existing references are kept, so a field's hint still describes it. Tooltip
+ * describes its trigger this way.
+ */
+export declare const linkDescription: (target: Element, by: Element, light: boolean) => boolean;
+/** Takes `by` back off the elements that describe `target`, leaving the rest. */
+export declare const unlinkDescription: (target: Element, by: Element) => void;

package/dist/utils/reflect-elements/reflect-elements.js

@@ -0,0 +1,40 @@
+export const reflectElements = (target, property, elements, owned) => {
+    const element = target;
+    if (!element || !(property in element)) {
+        return owned;
+    }
+    if (elements.length > 0) {
+        element[property] = elements;
+        return true;
+    }
+    if (owned) {
+        element[property] = null;
+    }
+    return false;
+};
+export const linkDescription = (target, by, light) => {
+    const element = target;
+    if (!('ariaDescribedByElements' in element)) {
+        return false;
+    }
+    const current = element.ariaDescribedByElements ?? [];
+    if (current.includes(by)) {
+        return true;
+    }
+    const shadowed = typeof ShadowRoot !== 'undefined' && target.getRootNode() instanceof ShadowRoot;
+    if (!shadowed &&
+        (!light || target.hasAttribute('aria-describedby') || target.hasAttribute('aria-labelledby'))) {
+        return false;
+    }
+    element.ariaDescribedByElements = [...current, by];
+    return true;
+};
+export const unlinkDescription = (target, by) => {
+    const element = target;
+    const current = element.ariaDescribedByElements;
+    if (!current?.includes(by)) {
+        return;
+    }
+    const rest = current.filter((one) => one !== by);
+    element.ariaDescribedByElements = rest.length > 0 ? rest : null;
+};

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

@@ -13,6 +13,15 @@ export interface Relative {
     /** The reading, in the caller's locale. */
     text: string;
 }
+/**
+ * How a reading is written: `style` is `Intl.RelativeTimeFormat`'s, from
+ * "3 hours ago" at `long` to "3h ago" at `narrow` in English, and `numeric`
+ * says whether a day back is "yesterday" (`auto`) or "1 day ago" (`always`).
+ */
+export interface RelativeOptions {
+    numeric?: 'always' | 'auto';
+    style?: 'long' | 'narrow' | 'short';
+}
 /**
  * A formatter for one locale, kept.
  *
@@ -20,5 +29,8 @@ export interface Relative {
  * testable at all: a function that reads `Date.now()` internally can only be
  * tested by waiting or by replacing a global, and both produce specs that fail
  * on a slow machine.
+ *
+ * Long and `auto` unless `options` says otherwise, which is what a person
+ * says aloud and what every caller wanted before Format Date offered the rest.
  */
-export declare const relativeTime: (locale: string) => ((from: Date, now: Date) => Relative);
+export declare const relativeTime: (locale: string, options?: RelativeOptions) => ((from: Date, now: Date) => Relative);

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

@@ -8,11 +8,14 @@ const UNITS = [
     { ms: 2_629_800_000, unit: 'month' },
     { ms: 31_557_600_000, unit: 'year' },
 ];
-export const relativeTime = (locale) => {
-    let format = held.get(locale);
+export const relativeTime = (locale, options = {}) => {
+    const numeric = options.numeric ?? 'auto';
+    const style = options.style ?? 'long';
+    const key = `${locale}|${numeric}|${style}`;
+    let format = held.get(key);
     if (!format) {
-        format = new Intl.RelativeTimeFormat(locale || undefined, { numeric: 'auto' });
-        held.set(locale, format);
+        format = new Intl.RelativeTimeFormat(locale || undefined, { numeric, style });
+        held.set(key, format);
     }
     const found = format;
     return (from, now) => {

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

@@ -32,6 +32,8 @@ export type RuntimeKind =
  | 'misplaced-handler'
 /** 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. */
+ | '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. */

package/dist/utils/roving-stop/roving-stop.d.ts

@@ -0,0 +1,20 @@
+/** How `rovingStop` reads an item. */
+export interface RovingOptions<T> {
+    /** Whether an item cannot take the stop. Defaults to none. */
+    disabled?: (item: T) => boolean;
+    /** Whether an item is chosen, which takes the stop before the first. Defaults to none. */
+    selected?: (item: T) => boolean;
+}
+/**
+ * The item that holds a group's one tab stop: the one the reader was last on,
+ * then the first chosen one, then the first that can be reached.
+ *
+ * A composite widget is one Tab stop whose items the arrow keys move between,
+ * and Tab coming back lands where the reader left. A disabled item never holds
+ * it, so a group whose first item is disabled can still be entered from the
+ * keyboard. `last` is ignored once it has left `items`.
+ *
+ * Tag Group, a Toggle Group that presses several, and a Notifications feed
+ * choose their stop this way.
+ */
+export declare const rovingStop: <T>(items: readonly T[], last: T | undefined, { disabled, selected }?: RovingOptions<T>) => T | undefined;

package/dist/utils/roving-stop/roving-stop.js

@@ -0,0 +1,3 @@
+export const rovingStop = (items, last, { disabled = () => false, selected = () => false } = {}) => (last !== undefined && items.includes(last) && !disabled(last) ? last : undefined) ??
+    items.find((item) => selected(item) && !disabled(item)) ??
+    items.find((item) => !disabled(item));

package/dist/utils/swipe/swipe.d.ts

@@ -0,0 +1,63 @@
+/** The edge of the window a surface leaves through when it is swiped away. */
+export type SwipeEdge = 'bottom' | 'left' | 'right' | 'top';
+/** Which way along the screen a swipe is read. */
+export type SwipeAxis = 'x' | 'y';
+/**
+ * How fast a release has to be moving, in pixels per millisecond, to count as
+ * a fling: the surface then goes on in the direction it was thrown, whatever
+ * distance it had covered.
+ */
+export declare const FLING = 0.5;
+/**
+ * The edge a surface placed at `placement` leaves through, resolved against the
+ * writing direction. `start` and `end` are logical, so on a right-to-left page
+ * the end is the left edge.
+ */
+export declare const swipeEdge: (placement: 'bottom' | 'end' | 'start' | 'top', rtl: boolean) => SwipeEdge;
+/** The axis a swipe toward `edge` is read along. */
+export declare const swipeAxis: (edge: SwipeEdge) => SwipeAxis;
+/** How far a movement of `dx` and `dy` went toward `edge`, negative when it went away. */
+export declare const towardEdge: (edge: SwipeEdge, dx: number, dy: number) => number;
+/** A distance toward `edge` as a physical offset, for a `translate`. */
+export declare const edgeOffset: (edge: SwipeEdge, travel: number) => {
+    x: number;
+    y: number;
+};
+/**
+ * The fractions of a surface a reader can leave on screen, read from a list
+ * such as `"0.5 1"`. Each is above zero and at most one, and the list is sorted
+ * with no repeats. Where nothing usable is written, the one point is `1`: the
+ * whole surface.
+ */
+export declare const parseSnapPoints: (text: string | null | undefined) => number[];
+/** What a release asks of `settleSwipe`. */
+export interface SwipeRelease {
+    /** The snap points, from `parseSnapPoints`. */
+    points: readonly number[];
+    /** The surface's size along the axis, in pixels. */
+    size: number;
+    /** How far the surface sits toward its edge, from fully shown, in pixels. */
+    travel: number;
+    /** How fast it was moving toward its edge at the release, in pixels per millisecond. */
+    velocity: number;
+}
+/**
+ * The fraction of the surface to rest at after a release, and `0` to dismiss it.
+ *
+ * A fling goes on to the next point in the direction it was thrown, and
+ * flinging toward the edge from the smallest point dismisses. Otherwise the
+ * surface rests at the nearest point, dismissal counted as the point at zero, so
+ * a surface with the one point `1` goes once it is dragged more than halfway.
+ */
+export declare const settleSwipe: ({ points, size, travel, velocity }: SwipeRelease) => number;
+/** How far toward its edge a surface resting at `fraction` sits, in pixels. */
+export declare const snapTravel: (size: number, fraction: number) => number;
+/**
+ * Which way a swipe across a row of items moves: `1` to the next, `-1` to the
+ * previous, `0` to stay.
+ *
+ * Dragging the picture toward the start of the line brings the next one in,
+ * so the next item is a drag leftward on a left-to-right page and rightward on
+ * a right-to-left one. A quarter of the width, or a fling, is enough.
+ */
+export declare const swipeStep: (dx: number, vx: number, width: number, rtl: boolean) => -1 | 0 | 1;

package/dist/utils/swipe/swipe.js

@@ -0,0 +1,48 @@
+export const FLING = 0.5;
+export const swipeEdge = (placement, rtl) => {
+    if (placement === 'top' || placement === 'bottom') {
+        return placement;
+    }
+    return (placement === 'end') !== rtl ? 'right' : 'left';
+};
+export const swipeAxis = (edge) => edge === 'left' || edge === 'right' ? 'x' : 'y';
+export const towardEdge = (edge, dx, dy) => ({ bottom: dy, left: -dx, right: dx, top: -dy })[edge];
+export const edgeOffset = (edge, travel) => ({
+    x: edge === 'right' ? travel : edge === 'left' ? -travel : 0,
+    y: edge === 'bottom' ? travel : edge === 'top' ? -travel : 0,
+});
+export const parseSnapPoints = (text) => {
+    const points = [
+        ...new Set((text ?? '')
+            .split(/[\s,]+/)
+            .map(Number)
+            .filter((one) => Number.isFinite(one) && one > 0 && one <= 1)),
+    ].sort((a, b) => a - b);
+    return points.length > 0 ? points : [1];
+};
+export const settleSwipe = ({ points, size, travel, velocity }) => {
+    if (size <= 0) {
+        return points[points.length - 1] ?? 1;
+    }
+    const shown = Math.max(0, Math.min(1, 1 - travel / size));
+    const stops = [0, ...points];
+    if (velocity >= FLING) {
+        return [...stops].reverse().find((one) => one < shown) ?? 0;
+    }
+    if (velocity <= -FLING) {
+        return stops.find((one) => one > shown) ?? stops[stops.length - 1] ?? 1;
+    }
+    return stops.reduce((best, one) => (Math.abs(one - shown) < Math.abs(best - shown) ? one : best));
+};
+export const snapTravel = (size, fraction) => Math.round((1 - fraction) * size);
+export const swipeStep = (dx, vx, width, rtl) => {
+    const along = rtl ? dx : -dx;
+    const speed = rtl ? vx : -vx;
+    if (speed >= FLING || (speed > -FLING && along > width / 4)) {
+        return 1;
+    }
+    if (speed <= -FLING || along < -width / 4) {
+        return -1;
+    }
+    return 0;
+};

package/dist/utils/tab-stops/tab-stops.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Every element in `root` that Tab stops at, in the order Tab reaches them,
+ * through shadow roots and slots.
+ *
+ * Through them because a panel's controls are inside the component it holds,
+ * and often a button's inside that, so a light-DOM query such as
+ * `focusableElements` finds none of them. Walked in the composed tree's order:
+ * a host's shadow root in place of its children, and a slot's assigned
+ * elements in place of its fallback. A host that delegates its focus is
+ * passed through to what it delegates to, and anything `hidden`, `inert`,
+ * disabled or without a box is left out.
+ *
+ * `MixinPickerField` keeps Tab inside a picker's panel with it, reading the
+ * first and last of these as the ends of the dialog.
+ */
+export declare const tabStops: (root: Element) => HTMLElement[];

package/dist/utils/tab-stops/tab-stops.js

@@ -0,0 +1,22 @@
+export const tabStops = (root) => {
+    const found = [];
+    const visit = (node) => {
+        const element = node;
+        if (element.hidden || element.inert) {
+            return;
+        }
+        if (element.tabIndex >= 0 &&
+            !element.shadowRoot?.delegatesFocus &&
+            !element.disabled &&
+            element.getClientRects().length > 0) {
+            found.push(element);
+        }
+        const assigned = node instanceof HTMLSlotElement ? node.assignedElements() : [];
+        const children = assigned.length > 0 ? assigned : [...(node.shadowRoot ?? node).children];
+        for (const child of children) {
+            visit(child);
+        }
+    };
+    visit(root);
+    return found;
+};

package/dist/utils/value-as/value-as.d.ts

@@ -55,6 +55,26 @@ export declare const valueAsMinutes: (value: string) => number | null;
 export declare const minutesAsValue: (minutes: number) => string;
 /** Whether a value is a time these controls can hold, which is minute precision. */
 export declare const isTimeValue: (value: string) => boolean;
+/**
+ * The seconds since midnight a value names, or `null` where it is not a time.
+ *
+ * **To the second, which is what Time Picker and Time Input hold under
+ * `seconds`.** `valueAsMinutes` above stays at minute precision for the
+ * controls that never carry one. Both shapes are read whatever a control
+ * writes, so a value with seconds handed to a field without them is a time it
+ * can judge, off its step, rather than text it cannot read.
+ */
+export declare const valueAsSeconds: (value: string) => number | null;
+/**
+ * Whether a value is a time a control holds: `HH:mm`, or either shape where it
+ * holds `seconds`.
+ */
+export declare const isClockValue: (value: string, seconds?: boolean) => boolean;
+/**
+ * Seconds since midnight as `HH:mm`, or `HH:mm:ss` with `seconds`, wrapping
+ * rather than running off the day.
+ */
+export declare const secondsAsValue: (at: number, seconds?: boolean) => string;
 /**
  * The number a value holds, or `NaN`.
  *

package/dist/utils/value-as/value-as.js

@@ -53,5 +53,21 @@ export const minutesAsValue = (minutes) => {
     return `${String(Math.floor(whole / 60)).padStart(2, '0')}:${String(whole % 60).padStart(2, '0')}`;
 };
 export const isTimeValue = (value) => valueAsMinutes(value) !== null;
+const CLOCK = /^([01]\d|2[0-3]):([0-5]\d)(?::([0-5]\d))?$/;
+const DAY_SECONDS = 86_400;
+export const valueAsSeconds = (value) => {
+    const parts = CLOCK.exec(value.trim());
+    if (!parts) {
+        return null;
+    }
+    return Number(parts[1]) * 3600 + Number(parts[2]) * 60 + Number(parts[3] ?? 0);
+};
+export const isClockValue = (value, seconds = false) => valueAsSeconds(value) !== null && (seconds || value.trim().length === 5);
+export const secondsAsValue = (at, seconds = false) => {
+    const whole = ((Math.round(at) % DAY_SECONDS) + DAY_SECONDS) % DAY_SECONDS;
+    const pad = (part) => String(part).padStart(2, '0');
+    const clock = `${pad(Math.floor(whole / 3600))}:${pad(Math.floor(whole / 60) % 60)}`;
+    return seconds ? `${clock}:${pad(whole % 60)}` : clock;
+};
 export const valueAsNumber = (value) => value.trim() === '' ? Number.NaN : Number(value);
 export const numberAsValue = (count) => (Number.isNaN(count) ? '' : String(count));

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

@@ -9,6 +9,16 @@
  * 24 hour regardless.
  *
  * A value this cannot read is handed back unchanged, so a field showing what is
- * being typed shows the letters rather than blanking under the reader.
+ * being typed shows the letters rather than blanking under the reader. Minute
+ * precision, as `valueAsMinutes` reads: `writeClock` is the same writing to the
+ * second.
  */
 export declare const writeTime: (value: string, locale?: string) => string;
+/**
+ * A time written the way the locale writes one, with its seconds where asked.
+ *
+ * Reads both `HH:mm` and `HH:mm:ss`, as `valueAsSeconds` does, which is what
+ * Time Picker and Time Input hold; a locale with its clock set by `clockLocale`
+ * writes on that clock. A value that is not a time is handed back unchanged.
+ */
+export declare const writeClock: (value: string, locale: string, seconds?: boolean) => string;

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

@@ -1,12 +1,12 @@
-import { valueAsMinutes } from '../value-as/value-as.js';
-export const writeTime = (value, locale) => {
-    const minutes = valueAsMinutes(value);
-    if (minutes === null) {
+import { valueAsMinutes, valueAsSeconds } from '../value-as/value-as.js';
+export const writeTime = (value, locale) => valueAsMinutes(value) === null ? value : writeClock(value, locale ?? '');
+export const writeClock = (value, locale, seconds = false) => {
+    const at = valueAsSeconds(value);
+    if (at === null) {
         return value;
     }
-    const at = new Date(Date.UTC(2000, 0, 1, Math.floor(minutes / 60), minutes % 60));
     return new Intl.DateTimeFormat(locale || undefined, {
-        timeStyle: 'short',
+        timeStyle: seconds ? 'medium' : 'short',
         timeZone: 'UTC',
-    }).format(at);
+    }).format(new Date(at * 1000));
 };

package/dist/utils/written-list/written-list.d.ts

@@ -43,3 +43,21 @@ export declare const writtenList: (source: WrittenList) => string[];
  * playback rate, and only the caller knows that a rate of zero is not a rate.
  */
 export declare const writtenNumbers: (source: WrittenList) => number[];
+/**
+ * A value list: the entries between commas, trimmed, with the empty ones
+ * dropped.
+ *
+ * **Commas only**, which is the value rule `writtenList` describes beside it: a
+ * value may hold a space, and `value="New York, Paris"` is two cities. Select,
+ * Listbox, Checkbox Group, Tag Group, Toggle Group, Date Picker, Time Picker
+ * and Legend's hidden series all read their lists this way.
+ */
+export declare const commaList: (value: string) => string[];
+/**
+ * A list with `value` taken out where it is in it, or added at the end where
+ * it is not.
+ *
+ * With `order`, the result is put in that order and holds only what `order`
+ * holds, so a set of pressed items reads the same whichever was pressed first.
+ */
+export declare const toggleValue: (list: readonly string[], value: string, order?: readonly string[]) => string[];

package/dist/utils/written-list/written-list.js

@@ -4,3 +4,11 @@ export const writtenList = (source) => (Array.isArray(source) ? source.join(' ')
 export const writtenNumbers = (source) => writtenList(source)
     .map(Number)
     .filter((one) => Number.isFinite(one));
+export const commaList = (value) => value
+    .split(',')
+    .map((one) => one.trim())
+    .filter((one) => one !== '');
+export const toggleValue = (list, value, order) => {
+    const next = list.includes(value) ? list.filter((one) => one !== value) : [...list, value];
+    return order ? order.filter((one) => next.includes(one)) : next;
+};

package/dist/version.d.ts

@@ -6,4 +6,4 @@
  * release, so the two never disagree; a spec beside this holds them to it.
  * Nothing else in the running code knows which release it is.
  */
-export declare const VERSION = "0.143.0";
+export declare const VERSION = "0.144.0";

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = '0.143.0';
+export const VERSION = '0.144.0';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fusion.dev/helix-core",
   "description": "Helix element primitives: base classes, mixins, decorators, utilities.",
-  "version": "0.143.0",
+  "version": "0.144.0",
   "license": "MIT",
   "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
   "repository": {
@@ -34,11 +34,11 @@
   "bugs": "https://github.com/project-fusion/fusion/issues",
   "dependencies": {
     "@floating-ui/dom": "^1.8.0",
-    "@fusion.dev/helix-icons": "0.143.0"
+    "@fusion.dev/helix-icons": "0.144.0"
   },
   "devDependencies": {
-    "@fusion.dev/helix-cem": "0.143.0",
-    "@fusion.dev/helix-testing": "0.143.0",
+    "@fusion.dev/helix-cem": "0.144.0",
+    "@fusion.dev/helix-testing": "0.144.0",
     "@lit-labs/ssr": "^4.1.0",
     "lit": "^3.2.1"
   },