@fusion.dev/helix-core 0.142.1 → 0.144.0

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

@@ -1,5 +1,10 @@
 /** One point in a series: what it is called, what it is worth, and when. */
 export interface SeriesPoint {
+    /**
+     * The row the reading is in, counting from zero, which is its place among
+     * the rows `readRows` reads and so the category it is drawn at.
+     */
+    at: number;
     /**
      * The row's own label, taken from its header cell.
      */
@@ -50,8 +55,31 @@ export interface Series {
  * the second reads `12abc` as 12: a value that is nearly a number is a mistake
  * worth dropping rather than rounding off, and a dropped point is visible where
  * a silently truncated one is not.
+ *
+ * **A dropped point keeps its place.** Each point carries `at`, the row it was
+ * read from, and a chart draws it at that row's category. Counted by position
+ * in `points`, a blank in March slid April's reading under March's label, and a
+ * blank in the first column took a category off the axis for every series.
+ * `byRow` lays a series out one slot per row with the blanks left empty.
  */
 export declare const readSeries: (table: Element) => Series[];
+/**
+ * A series laid out one slot per row, with nothing in a slot whose cell was
+ * blank or did not parse.
+ *
+ * This is the shape a chart drawing categories wants: slot `i` is the reading at
+ * the `i`th row, which is the label under it and the row the tooltip reads.
+ */
+export declare const byRow: (series: Series | undefined, rows: number) => (SeriesPoint | undefined)[];
+/**
+ * A series cut into its unbroken runs, where a run ends at a row with no
+ * reading.
+ *
+ * A line drawn through a gap claims a value in the gap. Drawn as runs, the
+ * line stops at the last reading before a blank and starts again at the first
+ * one after it.
+ */
+export declare const unbroken: (series: Series) => SeriesPoint[][];
 /** One cell of a row, as a reader sees it and as a chart measures it. */
 export interface RowCell {
     /**
@@ -102,3 +130,9 @@ export interface Row {
  * on render, rows only where a pointer has stopped.
  */
 export declare const readRows: (table: Element) => Row[];
+/**
+ * A series name as it is matched: trimmed and in lower case, since a column's
+ * heading is matched without regard to case or surrounding space everywhere a
+ * name is written, in `lines`, `hidden-series` and `hide()` alike.
+ */
+export declare const seriesKey: (name: string) => string;

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

@@ -6,13 +6,13 @@ const isGrid = (element) => element.getAttribute('role') === 'table' ||
     /^helix-(headless-)?table$/i.test(element.tagName);
 const readGrid = (grid) => {
     const columns = [...grid.querySelectorAll(COLUMNS)];
-    const rows = [...grid.querySelectorAll(ROWS)];
+    const rows = gridRows(grid);
     const names = columns.slice(1).map((cell) => cell.textContent?.trim() ?? '');
     const cellsOf = (row) => [...row.querySelectorAll(CELLS)];
     const count = Math.max(0, ...rows.map((row) => cellsOf(row).length - 1));
     return Array.from({ length: count }, (_, column) => ({
         name: names[column] ?? grid.getAttribute('label') ?? '',
-        points: rows.flatMap((row) => {
+        points: rows.flatMap((row, at) => {
             const cells = cellsOf(row);
             const head = cells[0];
             const cell = cells[column + 1];
@@ -26,6 +26,7 @@ const readGrid = (grid) => {
             return Number.isFinite(value) && raw.trim() !== ''
                 ? [
                     {
+                        at,
                         label: head?.textContent?.trim() ?? '',
                         value,
                         ...(tone ? { tone } : {}),
@@ -36,6 +37,7 @@ const readGrid = (grid) => {
         }),
     }));
 };
+const gridRows = (grid) => [...grid.querySelectorAll(ROWS)].filter((row) => row.querySelector(CELLS) !== null);
 const plotted = (series) => series.filter((one) => one.points.length > 0);
 export const readSeries = (table) => {
     if (isGrid(table)) {
@@ -49,7 +51,7 @@ export const readSeries = (table) => {
     const columns = Math.max(0, ...rows.map((row) => row.cells.length - 1));
     return plotted(Array.from({ length: columns }, (_, column) => ({
         name: names[column] ?? element.caption?.textContent?.trim() ?? '',
-        points: rows.flatMap((row) => {
+        points: rows.flatMap((row, at) => {
             const head = row.cells[0];
             const cell = row.cells[column + 1];
             if (!cell) {
@@ -62,6 +64,7 @@ export const readSeries = (table) => {
             return Number.isFinite(value) && raw.trim() !== ''
                 ? [
                     {
+                        at,
                         label: head?.textContent?.trim() ?? '',
                         value,
                         ...(tone ? { tone } : {}),
@@ -72,6 +75,30 @@ export const readSeries = (table) => {
         }),
     })));
 };
+export const byRow = (series, rows) => {
+    const slots = Array.from({ length: rows }, () => undefined);
+    for (const point of series?.points ?? []) {
+        if (point.at >= 0 && point.at < rows) {
+            slots[point.at] = point;
+        }
+    }
+    return slots;
+};
+export const unbroken = (series) => {
+    const runs = [];
+    let previous;
+    for (const point of series.points) {
+        const run = runs.at(-1);
+        if (run && previous && point.at === previous.at + 1) {
+            run.push(point);
+        }
+        else {
+            runs.push([point]);
+        }
+        previous = point;
+    }
+    return runs;
+};
 export const readRows = (table) => {
     const cell = (name, element) => {
         if (!element) {
@@ -100,7 +127,7 @@ export const readRows = (table) => {
         const names = [...table.querySelectorAll(COLUMNS)]
             .slice(1)
             .map((one) => one.textContent?.trim() ?? '');
-        return [...table.querySelectorAll(ROWS)].map((one) => {
+        return gridRows(table).map((one) => {
             const cells = [...one.querySelectorAll(CELLS)];
             return row(cells[0], cells.slice(1), names);
         });
@@ -111,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

@@ -26,14 +26,20 @@ export type RuntimeKind =
  | '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. */
+ | 'misread-direction'
 /** A React handler prop names an event the element never dispatches itself. */
  | '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. */
  | 'missing-stencil-parts'
+/** 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. */
  | 'missing-trigger'
 /** An area chart was handed a negative number, which it draws as none. */
@@ -42,6 +48,8 @@ export type RuntimeKind =
  | 'not-a-graph'
 /** The browser refused picture in picture. */
  | 'picture-in-picture-refused'
+/** A Grid's `min` is no length it can write, so the grid lays out by its column count. */
+ | 'refused-length'
 /** A React handler prop is a removed callback, which never ran from JSX. */
  | 'removed-callback'
 /** A React handler prop uses Solid's `on:`, which React reads as another event's name. */
@@ -56,8 +64,12 @@ export type RuntimeKind =
  | 'two-default-operators'
 /** 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. */
+ | 'unknown-icon'
 /** A tooltip's trigger does not name it in `aria-describedby`, so it is not read out. */
  | 'unlinked-trigger'
+/** A Text rendered as a label wraps or names a control, which its shadow root cannot reach. */
+ | 'unreachable-label'
 /** A virtualized list's box has no height of its own, so its window never settles. */
  | 'unsettled-window'
 /** A slotted trigger is a plain element, which cannot be told it opens something. */

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/scroll-lock/scroll-lock.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Stops the page behind a modal surface from scrolling.
+ *
+ * `showModal()` makes the page inert and leaves it scrollable, so a wheel over
+ * the backdrop moves the page under the dialog. `overflow: hidden` on the root
+ * stops that, and `scrollbar-gutter: stable` keeps the space a classic
+ * scrollbar took, so the page does not shift sideways when it goes. What the
+ * root carried before is put back when the last holder lets go.
+ *
+ * Dialog, Drawer and Lightbox hold it, and Toast reads who does.
+ */
+export declare const lockScroll: (holder: Element) => void;
+/** Lets go of the page, and gives it back once nothing else holds it. */
+export declare const unlockScroll: (holder: Element) => void;
+/** The surfaces holding the page still, in the order they took it. */
+export declare const scrollHolders: () => Element[];

package/dist/utils/scroll-lock/scroll-lock.js

@@ -0,0 +1,30 @@
+const SCROLL_LOCK = Symbol.for('fusion.helix.scroll-lock');
+const record = () => globalThis[SCROLL_LOCK];
+export const lockScroll = (holder) => {
+    const globals = globalThis;
+    const root = document.documentElement;
+    globals[SCROLL_LOCK] ??= { gutter: '', holders: new Set(), overflow: '' };
+    const lock = globals[SCROLL_LOCK];
+    if (lock.holders.has(holder)) {
+        return;
+    }
+    if (lock.holders.size === 0) {
+        lock.overflow = root.style.overflow;
+        lock.gutter = root.style.scrollbarGutter;
+        if (window.innerWidth > root.clientWidth) {
+            root.style.scrollbarGutter = 'stable';
+        }
+        root.style.overflow = 'hidden';
+    }
+    lock.holders.add(holder);
+};
+export const unlockScroll = (holder) => {
+    const lock = record();
+    if (!lock?.holders.delete(holder) || lock.holders.size > 0) {
+        return;
+    }
+    const root = document.documentElement;
+    root.style.overflow = lock.overflow;
+    root.style.scrollbarGutter = lock.gutter;
+};
+export const scrollHolders = () => [...(record()?.holders ?? [])];

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));
 };