@fusion.dev/helix-core 0.0.0-dev

package/dist/utils/scale/ticks.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The round numbers a reader would infer inside a domain.
+ *
+ * **A gridline at an arbitrary number is worse than no gridline.** The point of
+ * a rule across a chart is that a reader can name the level it sits at without
+ * being told, so it has to land on a number a person would have picked: 0, 250,
+ * 500, not 187.4. Dividing the domain into equal parts gives the second, and
+ * that is what makes this arithmetic rather than a loop.
+ *
+ * The step is the power of ten below the rough interval, multiplied by whichever
+ * of 1, 2, 5 or 10 lands nearest the count asked for. Those four because they
+ * are the multipliers that keep every tick short in decimal, which is the whole
+ * property being bought: 2.5 divides as evenly as 2 and reads as a worse number.
+ *
+ * **The count is a target and not a promise**, which is the usual surprise.
+ * Asking for five over a domain of 0 to 1000 gives six (0, 200, ... 1000);
+ * asking for five over 0 to 12 gives seven at a step of 2. Forcing the count
+ * would mean forcing the step, which is the thing worth keeping round. A caller
+ * that needs an exact number of rules wants equal division and not this.
+ *
+ * Ticks outside the domain are dropped rather than clamped, so nothing is drawn
+ * off the end of the box and no two rules land on the same line.
+ *
+ * A pure function, for the reason `linear` gives beside it: it holds nothing,
+ * subscribes to nothing, and can be called from `render`.
+ */
+export declare const ticks: (domain: readonly [number, number], count?: number) => number[];

package/dist/utils/scale/ticks.js

@@ -0,0 +1,52 @@
+/**
+ * The round numbers a reader would infer inside a domain.
+ *
+ * **A gridline at an arbitrary number is worse than no gridline.** The point of
+ * a rule across a chart is that a reader can name the level it sits at without
+ * being told, so it has to land on a number a person would have picked: 0, 250,
+ * 500, not 187.4. Dividing the domain into equal parts gives the second, and
+ * that is what makes this arithmetic rather than a loop.
+ *
+ * The step is the power of ten below the rough interval, multiplied by whichever
+ * of 1, 2, 5 or 10 lands nearest the count asked for. Those four because they
+ * are the multipliers that keep every tick short in decimal, which is the whole
+ * property being bought: 2.5 divides as evenly as 2 and reads as a worse number.
+ *
+ * **The count is a target and not a promise**, which is the usual surprise.
+ * Asking for five over a domain of 0 to 1000 gives six (0, 200, ... 1000);
+ * asking for five over 0 to 12 gives seven at a step of 2. Forcing the count
+ * would mean forcing the step, which is the thing worth keeping round. A caller
+ * that needs an exact number of rules wants equal division and not this.
+ *
+ * Ticks outside the domain are dropped rather than clamped, so nothing is drawn
+ * off the end of the box and no two rules land on the same line.
+ *
+ * A pure function, for the reason `linear` gives beside it: it holds nothing,
+ * subscribes to nothing, and can be called from `render`.
+ */
+export const ticks = (domain, count = 5) => {
+    const [low, high] = domain;
+    /* A flat domain has no levels to name. Zero rules rather than one, because a
+       single rule lying exactly under a flat line is a rule nobody can see and a
+       line a reader may take for the grid. */
+    if (!Number.isFinite(low) || !Number.isFinite(high) || low === high || count < 1) {
+        return [];
+    }
+    const rough = (high - low) / count;
+    const magnitude = 10 ** Math.floor(Math.log10(rough));
+    const eased = rough / magnitude;
+    const step = magnitude * (eased >= 7.5 ? 10 : eased >= 3 ? 5 : eased >= 1.5 ? 2 : 1);
+    const found = [];
+    /* From the first multiple of the step at or above the floor, so the run is
+       anchored to the number line rather than to wherever the data happens to
+       start. Two charts of the same shape over different ranges then draw rules
+       at the same levels, which is what makes them comparable at a glance. */
+    for (let at = Math.ceil(low / step) * step; at <= high; at += step) {
+        /* Floating point makes 0.30000000000000004 out of three tenths, and a
+           gridline is a number a reader sees. Rounded to the step's own precision,
+           which is as fine as any tick can legitimately be. */
+        const places = Math.max(0, -Math.floor(Math.log10(step)));
+        found.push(Number(at.toFixed(places)));
+    }
+    return found;
+};

package/dist/utils/scroll-item-into-view/scroll-item-into-view.d.ts

@@ -0,0 +1,10 @@
+/** What the util needs of a scroller and the thing it is bringing into it. */
+export interface ScrollItemOptions {
+    /** Space left between the item and the edge it came in at. */
+    padding?: number;
+    /** The scrolling box. Defaults to the nearest ancestor that scrolls. */
+    scroller?: HTMLElement;
+    /** Whether to animate. Ignored where the reader asked for less motion. */
+    smooth?: boolean;
+}
+export declare const scrollItemIntoView: (item: HTMLElement, options?: ScrollItemOptions) => void;

package/dist/utils/scroll-item-into-view/scroll-item-into-view.js

@@ -0,0 +1,98 @@
+/*
+ * Brings an item into view inside its own scroller, and moves nothing else.
+ *
+ * **Not `Element.scrollIntoView`, and the difference is the whole reason this
+ * exists.** That method walks every scrollable ancestor and scrolls all of
+ * them, so bringing the current item into a tree also scrolls the page the tree
+ * sits on, and on a phone it takes the address bar with it. A reader who
+ * pressed Down in a sidebar did not ask the document to move.
+ *
+ * It also does nothing when the item is already visible, where `scrollIntoView`
+ * with `block: 'nearest'` still nudges. Nudging on every keypress is what makes
+ * a long list feel like it is fighting the reader.
+ *
+ * Both axes, because the components that need this do not agree on one: a
+ * carousel scrolls sideways and a tree scrolls down, and a menu that has run
+ * out of room does both.
+ *
+ * `smooth` is a request rather than an instruction. Animating a scroll the
+ * reader triggered by pressing a key means the list is still moving when the
+ * next press arrives, so this follows `prefers-reduced-motion` and is off by
+ * default for exactly that case.
+ */
+/**
+ * The nearest ancestor that actually scrolls, crossing shadow boundaries.
+ *
+ * This was `item.offsetParent`, which is the nearest *positioned* ancestor and
+ * has nothing whatever to do with overflow. The two coincide often enough to
+ * look right, because a scroller frequently is positioned, and they come apart
+ * exactly where it matters: put anything `position: relative` between the item
+ * and the box that scrolls, and the util scrolled the thing in between, which
+ * does not scroll, and reported nothing. `Tree` passes no scroller at all, so
+ * it had the default on every keypress.
+ *
+ * The walk crosses shadow boundaries through the host, because the item is
+ * almost always in one and `parentElement` is null at the root. Without that
+ * step, a component whose scroller is its own `[part]` would find nothing.
+ *
+ * It stops before the document. Scrolling the page is the one thing this whole
+ * util exists not to do, so finding nothing inside the component and returning
+ * null is the honest answer: the caller no-ops rather than taking the address
+ * bar with it.
+ */
+const scrollingAncestor = (item) => {
+    const stop = item.ownerDocument.body;
+    let node = climb(item);
+    while (node && node !== stop) {
+        const style = getComputedStyle(node);
+        /* Both axes, since the caller may need either, and `overlay` because a
+           scroller styled with it scrolls exactly as `auto` does. `clip` and
+           `hidden` are deliberately not here: they cut the content off and are not
+           something a reader can move. */
+        if (/\b(auto|scroll|overlay)\b/.test(`${style.overflowX} ${style.overflowY}`)) {
+            return node;
+        }
+        node = climb(node);
+    }
+    return null;
+};
+/** Up one, through a shadow root where that is what is above. */
+const climb = (node) => {
+    if (node.parentElement) {
+        return node.parentElement;
+    }
+    const root = node.getRootNode();
+    return root instanceof ShadowRoot ? root.host : null;
+};
+export const scrollItemIntoView = (item, options = {}) => {
+    const { padding = 0, smooth = false } = options;
+    const scroller = options.scroller ?? scrollingAncestor(item);
+    if (!scroller) {
+        return;
+    }
+    /* Measured from the boxes rather than from `offsetLeft`, which is relative to
+       the offset parent and is only the scroller when nothing between them is
+       positioned. The rectangles are relative to the viewport, so the difference
+       between them is the distance regardless of what sits in between. */
+    const box = item.getBoundingClientRect();
+    const view = scroller.getBoundingClientRect();
+    const before = { block: view.top - box.top + padding, inline: view.left - box.left + padding };
+    const after = {
+        block: box.bottom - view.bottom + padding,
+        inline: box.right - view.right + padding,
+    };
+    /* Whichever edge it is past, and nothing when it is past neither. A scroll of
+       zero still fires a `scroll` event and still cancels a smooth one already
+       running, so the early return is behavior rather than an optimisation. */
+    const inline = before.inline > 0 ? -before.inline : after.inline > 0 ? after.inline : 0;
+    const block = before.block > 0 ? -before.block : after.block > 0 ? after.block : 0;
+    if (inline === 0 && block === 0) {
+        return;
+    }
+    const still = globalThis.matchMedia?.('(prefers-reduced-motion: reduce)').matches ?? false;
+    scroller.scrollBy({
+        behavior: smooth && !still ? 'smooth' : 'instant',
+        left: inline,
+        top: block,
+    });
+};

package/dist/utils/slot-filled/slot-filled.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Whether a consumer put anything in a slot.
+ *
+ * **There is no selector for this**, which is why it is script. `slot:empty`
+ * looks like the answer and is not: a slot's children are its *fallback*, and
+ * assigned nodes are not children, so `:empty` is true whenever the fallback is
+ * absent whether or not the consumer slotted anything. `:host(:has(...))` is
+ * invalid CSS, and the server has no children to inspect.
+ *
+ * The answer matters because an empty wrapper is not free. A region that
+ * generates a box is a flex item or a grid item whether or not it holds
+ * anything, so it takes the container's gap: an announcement with no actions
+ * paid the row gap twice, a switch with no label took one for a label that was
+ * not there, and a blockquote with no attribution reserved a full space below
+ * every quote. `display: none` is the only fix, because only a box that is not
+ * generated has no gap beside it.
+ *
+ * Text or an element, because neither alone is the test. An element on its own
+ * counts a whitespace-only span as content; text on its own counts an icon as
+ * nothing.
+ *
+ * `flatten` is deliberate here, unlike the tooltip's emptiness test: this asks
+ * "will anything render", where that one asks "did the consumer provide
+ * anything", and a slot showing its fallback does render.
+ */
+export declare const slotFilled: (slot: HTMLSlotElement | null | undefined) => boolean;

package/dist/utils/slot-filled/slot-filled.js

@@ -0,0 +1,26 @@
+/**
+ * Whether a consumer put anything in a slot.
+ *
+ * **There is no selector for this**, which is why it is script. `slot:empty`
+ * looks like the answer and is not: a slot's children are its *fallback*, and
+ * assigned nodes are not children, so `:empty` is true whenever the fallback is
+ * absent whether or not the consumer slotted anything. `:host(:has(...))` is
+ * invalid CSS, and the server has no children to inspect.
+ *
+ * The answer matters because an empty wrapper is not free. A region that
+ * generates a box is a flex item or a grid item whether or not it holds
+ * anything, so it takes the container's gap: an announcement with no actions
+ * paid the row gap twice, a switch with no label took one for a label that was
+ * not there, and a blockquote with no attribution reserved a full space below
+ * every quote. `display: none` is the only fix, because only a box that is not
+ * generated has no gap beside it.
+ *
+ * Text or an element, because neither alone is the test. An element on its own
+ * counts a whitespace-only span as content; text on its own counts an icon as
+ * nothing.
+ *
+ * `flatten` is deliberate here, unlike the tooltip's emptiness test: this asks
+ * "will anything render", where that one asks "did the consumer provide
+ * anything", and a slot showing its fallback does render.
+ */
+export const slotFilled = (slot) => (slot?.assignedNodes({ flatten: true }) ?? []).some((node) => node.nodeType === Node.ELEMENT_NODE || node.textContent?.trim() !== '');

package/dist/utils/tell-disclosure/tell-disclosure.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Tells a slotted trigger that it opens something, and whether it is open.
+ *
+ * **Two components answered this by writing `aria-expanded` onto the consumer's
+ * element, and that is a hydration mismatch.** `Megamenu` and `SpeedDial` both
+ * did, each with a note saying why: a consumer who has to mirror `open` back
+ * onto their own trigger is a consumer who will forget, and the failure is
+ * silent to everyone who can see the screen. Both notes are right about the
+ * gap. `Popover` refused to write anything, from the day it was written, on the
+ * grounds that a component decorating a consumer's markup after upgrading is
+ * one whose output a React consumer's hydration disagrees with.
+ *
+ * **Popover was right, measured 28 Aug 2026 against React 19.2.8.** Four
+ * families were server-rendered as React emits them and hydrated with the
+ * element definitions loaded either side of `hydrateRoot`:
+ *
+ * ```
+ * case        writes to trigger   hydration mismatch
+ * megamenu    aria-expanded       yes, both load orders
+ * speed dial  aria-expanded       yes, both load orders
+ * popover     nothing             no
+ * menu        nothing             no
+ * ```
+ *
+ * React reports "some attributes of the server rendered HTML didn't match the
+ * client properties. This won't be patched up", and the cost is not the console
+ * line: it answers a mismatch by discarding the server's HTML for that subtree
+ * and rebuilding it, which is what the carousel's own note records blinding an
+ * `<helix-aura>` two sections away.
+ *
+ * **A property crosses the gap that an attribute cannot, and this library
+ * already knew it.** `Menu` tells its items by property "rather than an
+ * attribute for that reason", in those words. React diffs the attributes it
+ * rendered and never looks at a property, so the state reaches the trigger,
+ * lands as `aria-expanded` inside *that element's* shadow root, and the
+ * consumer's markup is exactly what they served. Both positions get what they
+ * were protecting: nothing is written onto the consumer's element, and the
+ * reader is still told what the control does.
+ *
+ * **Set before upgrade is safe**, which is what lets this run without waiting
+ * for a definition: `ReactiveElement` captures an instance property assigned
+ * before it upgrades and re-applies it, so a trigger whose module has not
+ * loaded yet still ends up with the value.
+ *
+ * **A plain element is warned about rather than written to.** A
+ * `<button slot="trigger">` has no shadow root to keep the state out of the
+ * markup and no property to take it, and a consumer cannot mirror it themselves
+ * because the open state belongs to the component. Saying so once is the same
+ * answer `Tooltip` gives about the link it will not write for them. See #322.
+ */
+export declare const tellDisclosure: (trigger: Element | null | undefined, open: boolean) => void;

package/dist/utils/tell-disclosure/tell-disclosure.js

@@ -0,0 +1,76 @@
+/** Triggers already told they cannot carry the state, so it is said once. */
+const warned = new WeakSet();
+/**
+ * Tells a slotted trigger that it opens something, and whether it is open.
+ *
+ * **Two components answered this by writing `aria-expanded` onto the consumer's
+ * element, and that is a hydration mismatch.** `Megamenu` and `SpeedDial` both
+ * did, each with a note saying why: a consumer who has to mirror `open` back
+ * onto their own trigger is a consumer who will forget, and the failure is
+ * silent to everyone who can see the screen. Both notes are right about the
+ * gap. `Popover` refused to write anything, from the day it was written, on the
+ * grounds that a component decorating a consumer's markup after upgrading is
+ * one whose output a React consumer's hydration disagrees with.
+ *
+ * **Popover was right, measured 28 Aug 2026 against React 19.2.8.** Four
+ * families were server-rendered as React emits them and hydrated with the
+ * element definitions loaded either side of `hydrateRoot`:
+ *
+ * ```
+ * case        writes to trigger   hydration mismatch
+ * megamenu    aria-expanded       yes, both load orders
+ * speed dial  aria-expanded       yes, both load orders
+ * popover     nothing             no
+ * menu        nothing             no
+ * ```
+ *
+ * React reports "some attributes of the server rendered HTML didn't match the
+ * client properties. This won't be patched up", and the cost is not the console
+ * line: it answers a mismatch by discarding the server's HTML for that subtree
+ * and rebuilding it, which is what the carousel's own note records blinding an
+ * `<helix-aura>` two sections away.
+ *
+ * **A property crosses the gap that an attribute cannot, and this library
+ * already knew it.** `Menu` tells its items by property "rather than an
+ * attribute for that reason", in those words. React diffs the attributes it
+ * rendered and never looks at a property, so the state reaches the trigger,
+ * lands as `aria-expanded` inside *that element's* shadow root, and the
+ * consumer's markup is exactly what they served. Both positions get what they
+ * were protecting: nothing is written onto the consumer's element, and the
+ * reader is still told what the control does.
+ *
+ * **Set before upgrade is safe**, which is what lets this run without waiting
+ * for a definition: `ReactiveElement` captures an instance property assigned
+ * before it upgrades and re-applies it, so a trigger whose module has not
+ * loaded yet still ends up with the value.
+ *
+ * **A plain element is warned about rather than written to.** A
+ * `<button slot="trigger">` has no shadow root to keep the state out of the
+ * markup and no property to take it, and a consumer cannot mirror it themselves
+ * because the open state belongs to the component. Saying so once is the same
+ * answer `Tooltip` gives about the link it will not write for them. See #322.
+ */
+export const tellDisclosure = (trigger, open) => {
+    if (!trigger) {
+        return;
+    }
+    /* A custom element, which is the only kind that can hold this without putting
+       it in the markup. The tag is the test rather than `'expanded' in trigger`,
+       because the trigger may not have upgraded yet and the property lives on the
+       prototype: asking too early would fall through to the warning for an
+       element that is about to be perfectly capable. */
+    if (trigger.localName.includes('-')) {
+        ;
+        trigger.expanded = open;
+        return;
+    }
+    if (warned.has(trigger)) {
+        return;
+    }
+    warned.add(trigger);
+    console.warn(`<${trigger.localName}> is slotted as a trigger and cannot be told that it opens something. ` +
+        'The state would have to be written onto your markup as `aria-expanded`, which a React ' +
+        "consumer's hydration reports and does not patch up, so it is not written. Slot a " +
+        '`helix-button` or `helix-icon-button`, which carry it inside their own shadow root, or ' +
+        'add `aria-haspopup` and your own `aria-expanded` to this element.');
+};

package/dist/utils/ticker/ticker.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Asks to be run in `delay` milliseconds, and returns the way to stop asking.
+ *
+ * The returned function is the whole of the contract: an element that forgets to
+ * call it on disconnect leaks a closure over itself for the life of the page,
+ * and a panel that opens and closes leaks one per open.
+ */
+export declare const subscribe: (delay: number, run: () => void) => (() => void);

package/dist/utils/ticker/ticker.js

@@ -0,0 +1,55 @@
+const KEY = Symbol.for('helix.ticker');
+const ticker = () => {
+    const global = globalThis;
+    let found = global[KEY];
+    if (!found) {
+        found = { timer: undefined, waiting: new Set() };
+        global[KEY] = found;
+    }
+    return found;
+};
+/** Sets the one timeout, for the soonest thing anybody is waiting on. */
+const schedule = () => {
+    const held = ticker();
+    if (held.timer !== undefined) {
+        clearTimeout(held.timer);
+        held.timer = undefined;
+    }
+    if (held.waiting.size === 0) {
+        return;
+    }
+    const soonest = Math.min(...[...held.waiting].map((one) => one.at));
+    /* Floored at a second: a subscriber handed a zero would be re-armed inside the
+       callback that fired it, which is a busy loop wearing a timer's clothes. */
+    const wait = Math.max(1000, soonest - Date.now());
+    held.timer = setTimeout(() => {
+        held.timer = undefined;
+        const now = Date.now();
+        /* Copied before iterating, because every callback re-subscribes and would
+           otherwise be walked again inside the same pass. */
+        for (const one of [...held.waiting]) {
+            if (one.at <= now) {
+                held.waiting.delete(one);
+                one.run();
+            }
+        }
+        schedule();
+    }, wait);
+};
+/**
+ * Asks to be run in `delay` milliseconds, and returns the way to stop asking.
+ *
+ * The returned function is the whole of the contract: an element that forgets to
+ * call it on disconnect leaks a closure over itself for the life of the page,
+ * and a panel that opens and closes leaks one per open.
+ */
+export const subscribe = (delay, run) => {
+    const held = ticker();
+    const entry = { at: Date.now() + delay, run };
+    held.waiting.add(entry);
+    schedule();
+    return () => {
+        held.waiting.delete(entry);
+        schedule();
+    };
+};

package/dist/utils/tone-marks/tone-marks.d.ts

@@ -0,0 +1,52 @@
+import { type HelixIcon } from '@fusion.dev/helix-icons';
+/**
+ * The four status tones, as a type anything branching on them can take.
+ *
+ * **A subset of `tone` rather than an axis of its own, which is what the rename
+ * records.** This was `HelixSeverity`, and `severity` turned out to be a sixth
+ * spelling of the axis for what a thing *means*: `Callout` and `Toast.Item`
+ * report a status and never a brand role, so they take four of the seven values
+ * and not four values of their own. The components moved with #158; the
+ * vocabulary underneath them was still saying the old word.
+ *
+ * `Status` stays in the name because that is the half of `tone` these are: there
+ * is no mark for `primary` or `accent`, a brand role having nothing to announce.
+ */
+export type HelixStatusTone = 'danger' | 'info' | 'success' | 'warning';
+/** What a tone is drawn as, and what it is called. */
+export interface ToneMark {
+    /** The mark drawn beside the message. Never the only carrier of the meaning. */
+    icon: HelixIcon;
+    /** What a screen reader is told, since the color says nothing to them. */
+    label: string;
+}
+/**
+ * The one status vocabulary.
+ *
+ * It was two, defined identically in `Callout` and in `Toast.Item`, and only one
+ * of the copies carried the comment saying the two must not drift. A reader
+ * meets these marks in a passage and in a message and has to read them as the
+ * same four things, so there is one place they come from.
+ *
+ * **Filled at every tone**, which is what it already was at one of them.
+ * `danger` took `xCircleFill` and the other three took outlines, so a set meant
+ * to be read as one vocabulary had one member drawn a different way. Filled
+ * because a tone mark is a status indicator and not an action: it wants to
+ * read at a glance and at a small size, where an outline at this weight loses
+ * its interior.
+ *
+ * **The label is not the tone name.** `danger` is announced as "Error",
+ * because that is the word a reader understands and `danger` is the word the API
+ * uses. Both matter and they are not the same string.
+ */
+export declare const TONE_MARKS: Record<HelixStatusTone, ToneMark>;
+/**
+ * The mark for a tone, or `undefined` where the name is not one of the four.
+ *
+ * A lookup rather than direct indexing, because `tone` reaches a component as an
+ * attribute and an attribute can say anything, including the three tones that
+ * have no mark. Callers decide what an unknown one means: `Callout` falls back
+ * to `info`, since a callout is always *about* something, and `Toast.Item` draws
+ * nothing, since a message is just the next thing that happened.
+ */
+export declare const toneMark: (tone: string | undefined) => ToneMark | undefined;

package/dist/utils/tone-marks/tone-marks.js

@@ -0,0 +1,36 @@
+import { checkCircleFill, infoFill, warningFill, xCircleFill, } from '@fusion.dev/helix-icons';
+/**
+ * The one status vocabulary.
+ *
+ * It was two, defined identically in `Callout` and in `Toast.Item`, and only one
+ * of the copies carried the comment saying the two must not drift. A reader
+ * meets these marks in a passage and in a message and has to read them as the
+ * same four things, so there is one place they come from.
+ *
+ * **Filled at every tone**, which is what it already was at one of them.
+ * `danger` took `xCircleFill` and the other three took outlines, so a set meant
+ * to be read as one vocabulary had one member drawn a different way. Filled
+ * because a tone mark is a status indicator and not an action: it wants to
+ * read at a glance and at a small size, where an outline at this weight loses
+ * its interior.
+ *
+ * **The label is not the tone name.** `danger` is announced as "Error",
+ * because that is the word a reader understands and `danger` is the word the API
+ * uses. Both matter and they are not the same string.
+ */
+export const TONE_MARKS = {
+    danger: { icon: xCircleFill, label: 'Error' },
+    info: { icon: infoFill, label: 'Information' },
+    success: { icon: checkCircleFill, label: 'Success' },
+    warning: { icon: warningFill, label: 'Warning' },
+};
+/**
+ * The mark for a tone, or `undefined` where the name is not one of the four.
+ *
+ * A lookup rather than direct indexing, because `tone` reaches a component as an
+ * attribute and an attribute can say anything, including the three tones that
+ * have no mark. Callers decide what an unknown one means: `Callout` falls back
+ * to `info`, since a callout is always *about* something, and `Toast.Item` draws
+ * nothing, since a message is just the next thing that happened.
+ */
+export const toneMark = (tone) => tone ? TONE_MARKS[tone] : undefined;

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

@@ -0,0 +1,64 @@
+/**
+ * A date or time control's string value, read as the platform reads it.
+ *
+ * **Six families needed this and none of them could have it alone.** `Date
+ * Input` and `Date Picker` both hold `YYYY-MM-DD`, `Time Input` and `Time
+ * Picker` both hold `HH:mm`, and `Number Input` and `Rating` both hold a
+ * number, so `valueAsDate` and `valueAsNumber` would have been four
+ * implementations of two conversions with four chances to disagree about what
+ * an invalid value returns. Here rather than in a shared folder under
+ * `helix/headless`, because there is no such folder and this is a pure function
+ * of a string: it sits beside `formatNumbers` and `relativeTime`, which are the
+ * same kind of thing.
+ *
+ * **UTC throughout, which is the platform's own choice and looks wrong until it
+ * is explained.** `<input type="date">.valueAsDate` returns midnight UTC rather
+ * than midnight local, so a date that is the same date everywhere does not
+ * become a different one by crossing a timezone. Constructing through
+ * `new Date('2026-08-26')` happens to do this and `new Date(2026, 7, 26)` does
+ * not, and the difference is a whole day for anybody west of Greenwich: the
+ * local constructor gives a `Date` whose UTC date is the 25th. `Date.UTC` says
+ * which one is meant rather than relying on a parse rule.
+ *
+ * **Invalid is `null` and `NaN`, never a thrown error and never a guess.** That
+ * is what the platform answers for a half-typed date, which is most of the
+ * keystrokes a reader makes in one: a control that threw on the way to a valid
+ * value would be unusable, and one that guessed would submit a date nobody
+ * chose.
+ */
+/**
+ * The date a `YYYY-MM-DD` value names, at midnight UTC, or `null`.
+ *
+ * The range check is not decoration. `2026-02-31` matches the pattern and
+ * `Date.UTC` rolls it forward to 3 March, so without reading the parts back a
+ * control would report a date the reader never typed and never saw.
+ */
+export declare const valueAsDate: (value: string) => Date | null;
+/** The `YYYY-MM-DD` value for a date, or the empty string, which is how a control says nothing. */
+export declare const dateAsValue: (date: Date | null) => string;
+/**
+ * The time an `HH:mm` value names, on 1 January 1970 UTC, or `null`.
+ *
+ * The platform's own answer for `<input type="time">`, and the epoch day is
+ * what makes `valueAsNumber` come out as milliseconds since midnight rather
+ * than as an instant nobody meant.
+ */
+export declare const valueAsTime: (value: string) => Date | null;
+/**
+ * The `HH:mm` value for a time, or the empty string.
+ *
+ * Seconds are written only where there are any, because `HH:mm` is what this
+ * library's time controls hold and a trailing `:00` on every value would be a
+ * format change dressed as a conversion.
+ */
+export declare const timeAsValue: (date: Date | null) => string;
+/**
+ * The number a value holds, or `NaN`.
+ *
+ * `Number('')` is zero, which is the trap: an empty control would report a
+ * number it does not hold and a form would submit it. The platform answers
+ * `NaN` for an empty `<input type="number">` and so does this.
+ */
+export declare const valueAsNumber: (value: string) => number;
+/** The value for a number, or the empty string, which is how a control says nothing. */
+export declare const numberAsValue: (count: number) => string;