@fusion.dev/helix-core 0.143.0 → 0.145.0

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

@@ -0,0 +1,14 @@
+const HEADING = 'h1, h2, h3, h4, h5, h6, [role="heading"]';
+export const headingIn = (elements) => {
+    for (const one of elements) {
+        const found = one.matches(HEADING) ? one : one.querySelector(HEADING);
+        if (found) {
+            return found;
+        }
+    }
+    return null;
+};
+export const headingsIn = (elements) => {
+    const heading = headingIn(elements);
+    return heading ? [heading] : [...elements];
+};

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

@@ -0,0 +1,23 @@
+/**
+ * Writes and reads numbers in a locale with `Intl.NumberFormat` options, for a
+ * control that shows a number and takes one typed: a currency, a percent, a
+ * unit, or grouped thousands. React Aria's NumberField and Slider take the same
+ * `formatOptions`.
+ *
+ * **Formatters are kept**, by locale and options, since one is expensive to
+ * build and cheap to call, and a control formats on every update.
+ */
+/** Writes a number in a locale with `Intl.NumberFormat` options. */
+export declare const formatNumber: (value: 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
+ * 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.
+ */
+export declare const parseNumber: (text: string, locale?: string, options?: Intl.NumberFormatOptions) => number | null;

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

@@ -0,0 +1,55 @@
+const held = new Map();
+const formatter = (locale, options) => {
+    const key = `${locale}|${JSON.stringify(options ?? {})}`;
+    let found = held.get(key);
+    if (!found) {
+        found = new Intl.NumberFormat(locale || undefined, options);
+        held.set(key, found);
+    }
+    return found;
+};
+export const formatNumber = (value, locale = '', options) => formatter(locale, options).format(value);
+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 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 percent = options?.style === 'percent' && /[%\u066a\u2030]/u.test(text);
+    let read = text.replace(/[\s\u00a0\u202f]/gu, '');
+    for (const one of dropped) {
+        read = read.replace(new RegExp(literal(one), 'gu'), '');
+    }
+    read = read.replace(/[\u2212\u2012\u2013]/gu, '-');
+    const separator = group.trim() || group;
+    if (read.includes(separator) && !grouped(read, separator, decimal)) {
+        if (group !== '.' || read.includes(decimal)) {
+            return null;
+        }
+    }
+    if (group !== '.' || decimal === '.') {
+        read = read.replace(new RegExp(literal(separator), 'gu'), '');
+    }
+    else if (read.includes(decimal)) {
+        read = read.replaceAll(group, '');
+    }
+    else {
+        read = read.replaceAll(group, '.');
+    }
+    read = read.replace(decimal, '.');
+    if (!/^[+-]?(\d+\.?\d*|\.\d+)$/u.test(read)) {
+        return null;
+    }
+    const parsed = Number(read);
+    if (!Number.isFinite(parsed)) {
+        return null;
+    }
+    return percent ? parsed / 100 : parsed;
+};

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

@@ -0,0 +1,23 @@
+/** What `onApple` and `appleTouch` read of the browser: the parts of `navigator` they need. */
+export interface Platform {
+    readonly maxTouchPoints?: number;
+    readonly platform?: string;
+    readonly userAgent?: string;
+}
+/**
+ * Whether the browser is iOS or iPadOS, where VoiceOver reads a
+ * `role="spinbutton"` text field as a slider a reader cannot type in. React
+ * Aria's NumberField drops the role there for the same reason. An iPad asks
+ * for the desktop site and reports itself as a Mac, so a Mac with a touch
+ * screen counts too.
+ */
+export declare const appleTouch: (platform: Platform | undefined) => boolean;
+/**
+ * Whether the keyboard in front of the reader is an Apple one, which labels
+ * its modifiers with glyphs and whose platform modifier is Command.
+ *
+ * From the user agent, as every application asks it; `false` on a server,
+ * which has no keyboard to ask. Kbd draws `⌘K` or `Ctrl+K` from it and reads
+ * `mod` as the key it names.
+ */
+export declare const onApple: (platform?: Platform | undefined) => boolean;

package/dist/utils/platform/platform.js

@@ -0,0 +1,11 @@
+export const appleTouch = (platform) => {
+    if (!platform) {
+        return false;
+    }
+    const agent = platform.userAgent ?? '';
+    if (/iPhone|iPad|iPod/u.test(agent)) {
+        return true;
+    }
+    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 ?? '');

package/dist/utils/range-add/range-add.d.ts

@@ -0,0 +1,19 @@
+/**
+ * What a range adds to a selection of many, as arithmetic over the items on
+ * show.
+ *
+ * Pure and in core, because Listbox (Shift with Home or End) and Data Table
+ * (Shift with an arrow, Home or End, over rows) take in a range the same way,
+ * and a spec can hold it without a page.
+ */
+/**
+ * The selection after Shift with Home or End: every option shown from the
+ * highlight to the end the key went to, added after what was selected, or
+ * `null` where nothing new is taken in.
+ *
+ * `from` is where the highlight was, as an index into `shown`, or `-1` for no
+ * highlight, which takes in the end alone. `to` is the end the key went to.
+ * APG's multiple-selection listbox, and the same rule over a data table's
+ * rows.
+ */
+export declare const rangeAdd: (values: readonly string[], shown: readonly string[], from: number, to: number) => string[] | null;

package/dist/utils/range-add/range-add.js

@@ -0,0 +1,5 @@
+export const rangeAdd = (values, shown, from, to) => {
+    const [start, end] = from < 0 ? [to, to] : [Math.min(from, to), Math.max(from, to)];
+    const added = shown.slice(start, end + 1).filter((value) => !values.includes(value));
+    return added.length > 0 ? [...values, ...added] : null;
+};

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

@@ -34,3 +34,17 @@ export type ColorBytes = [number, number, number];
  * @param value A resolved color, as `getComputedStyle` reports one.
  */
 export declare const readColor: (value: string) => ColorBytes | undefined;
+/**
+ * A computed color as `rgb()`, or `rgba()` where it is see-through, which
+ * every SVG reader can draw.
+ *
+ * A theme's colors compute to `oklch()` or `color()`, which a browser draws
+ * and an image editor opening a saved file may not, so the color is painted
+ * onto one fresh pixel and read back, its alpha with it. Unlike `readColor`,
+ * which refuses what it cannot tell apart from its ground, this keeps what the
+ * pixel says: a computed style is always a color the engine parsed. A page with
+ * no canvas keeps the color as it is.
+ *
+ * @param color A resolved color, as `getComputedStyle` reports one.
+ */
+export declare const rgbOf: (color: string) => string;

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

@@ -34,3 +34,16 @@ export const readColor = (value) => {
     known.set(value, read);
     return read ? [...read] : undefined;
 };
+export const rgbOf = (color) => {
+    const pixel = typeof document === 'undefined' ? null : document.createElement('canvas');
+    const context = pixel?.getContext?.('2d', { willReadFrequently: true });
+    if (!context) {
+        return color;
+    }
+    context.fillStyle = color;
+    context.fillRect(0, 0, 1, 1);
+    const [red, green, blue, alpha] = context.getImageData(0, 0, 1, 1).data;
+    return alpha === 255
+        ? `rgb(${red}, ${green}, ${blue})`
+        : `rgba(${red}, ${green}, ${blue}, ${(alpha ?? 0) / 255})`;
+};

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

@@ -130,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

@@ -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 = 'ariaControlsElements' | '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, a Tour stop names and
+ * describes its panel, and a Tab points its control at the panel it shows.
+ */
+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

@@ -30,8 +30,12 @@ export type RuntimeKind =
  | 'misread-direction'
 /** A React handler prop names an event the element never dispatches itself. */
  | 'misplaced-handler'
+/** An Image has no `alt`, so a screen reader announces its file name. */
+ | '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. */
+ | '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. */
@@ -66,7 +70,7 @@ export type RuntimeKind =
  | '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. */
+/** A Text is rendered as a label, a deprecated value whose shadow root reaches no control. */
  | 'unreachable-label'
 /** A virtualized list's box has no height of its own, so its window never settles. */
  | 'unsettled-window'

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

@@ -3,12 +3,22 @@
  *
  * `Intl` decides between a twelve and a twenty-four hour clock, because that is
  * a property of the locale rather than of any component: `en-US` gets `2:30 PM`
- * and `en-GB` gets `14:30` without either being configured. There is no flag to
- * force one, deliberately. A product that needs to override its reader's own
- * convention has a locale problem rather than a component one, and the value is
- * 24 hour regardless.
+ * and `en-GB` gets `14:30` without either being configured. This function takes
+ * no flag to force one. A family that offers the choice, such as Time Picker
+ * and Time Input with `hour-cycle`, passes it in the locale, as its `-u-hc-`
+ * extension (`en-US-u-hc-h23`). The value is 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));
 };