@fusion.dev/helix-core 0.0.0-dev

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

@@ -0,0 +1,78 @@
+/** One point in a series: what it is called, what it is worth, and when. */
+export interface SeriesPoint {
+    /**
+     * The row's own label, taken from its header cell.
+     */
+    label: string;
+    /**
+     * The number the cell holds.
+     */
+    value: number;
+    /**
+     * The machine-readable instant, if the row header carries a `<time>`.
+     */
+    when?: string;
+}
+/** One column of a table, read as a series. */
+export interface Series {
+    /**
+     * The column's name, from the header row, or the table's caption where the
+     * table has one column and therefore one series to name.
+     */
+    name: string;
+    /**
+     * The rows, in the order the table gives them.
+     */
+    points: SeriesPoint[];
+}
+export declare const readSeries: (table: Element) => Series[];
+/** One cell of a row, as a reader sees it and as a chart measures it. */
+export interface RowCell {
+    /**
+     * The column's name, from the header.
+     */
+    name: string;
+    /**
+     * The cell's own text, which is what a reader sees.
+     */
+    text: string;
+    /**
+     * The number behind it, where there is one.
+     */
+    value?: number;
+}
+/** One row of a table, headed and with every cell in it. */
+export interface Row {
+    /**
+     * Every cell in the row, in order, numeric or not.
+     */
+    cells: RowCell[];
+    /**
+     * The row's own label, from its header cell.
+     */
+    label: string;
+    /**
+     * The machine-readable instant, if the row header carries a `<time>`.
+     */
+    when?: string;
+}
+/**
+ * Reads a table as rows rather than as columns.
+ *
+ * **Everything `readSeries` throws away on purpose, a tooltip needs.** That
+ * function answers "what should I draw", so it keeps the parsed number and
+ * discards the cell's text, and it drops a column whose cells are not numbers
+ * at all. A chart drawing `128000` and a tooltip saying `128000` would be the
+ * chart overruling the table, which already decided that number reads `$128k`;
+ * and a column of notes beside the figures is exactly the extra a reader wants
+ * when their pointer is resting on a reading.
+ *
+ * So this keeps both, and keeps the columns nothing plotted. A chart of two
+ * series over a table of four columns still has four columns to show.
+ *
+ * The traversal is the same shape as `readSeries` and deliberately separate.
+ * Folding them into one pass returning both would make every caller who wants
+ * one build the other, and the two are asked for at different moments: series
+ * on render, rows only where a pointer has stopped.
+ */
+export declare const readRows: (table: Element) => Row[];

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

@@ -0,0 +1,187 @@
+/**
+ * Reads a table as series, one per data column.
+ *
+ * **The table is the chart's accessible representation, not a fallback for
+ * one.** Every chart here takes its numbers from real markup rather than from a
+ * property, so the page is readable with no script at all, sortable by anything
+ * that sorts tables, and correct in a screen reader without a parallel
+ * description that has to be kept in step by hand. A `values` array would be
+ * easier to pass and would make the accessible version the thing nobody
+ * maintains.
+ *
+ * The shape is the ordinary one: a header row naming the series, a first column
+ * of row headers, and numbers in the rest. A single-column table has one series
+ * and takes its name from the caption, since a header row of one is usually
+ * absent.
+ *
+ * `data-value` wins over the cell's text, because `$1.2k` is what a reader
+ * should see and is not a number. `Number()` rather than `parseFloat`, because
+ * 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 grid's own rows and cells, by role and by tag.
+ *
+ * **Both, because `helix-table` sets its roles through `ElementInternals`.**
+ * That writes no attribute at all, which is the whole point of it: the
+ * semantics reach the accessibility tree and never the DOM. So a selector of
+ * `[role="row"]` matches a hand-rolled grid and matches nothing at all in this
+ * library's own table, and a selector of the tag matches ours and nothing
+ * anybody else builds. Neither alone is the answer. */
+const ROWS = 'helix-table-row, helix-headless-table-row, [role="row"]';
+const CELLS = 'helix-table-cell, helix-headless-table-cell, [role="cell"], [role="gridcell"], [role="rowheader"]';
+const COLUMNS = 'helix-table-column, helix-headless-table-column, [role="columnheader"]';
+/** Whether an element is a grid rather than a document table. */
+const isGrid = (element) => element.getAttribute('role') === 'table' ||
+    element.getAttribute('role') === 'grid' ||
+    /^helix-(headless-)?table$/i.test(element.tagName);
+/**
+ * Reads a grid built from roles rather than from table markup.
+ *
+ * The shape is the same question asked of different elements: a first row of
+ * column headers naming the series, a first cell per row labeling it, and
+ * numbers in the rest. `helix-table` puts its columns beside its rows rather
+ * than inside a header row, so the columns are looked for in the whole grid and
+ * the rows are read separately.
+ *
+ * **A paginated grid reads as the page it is showing.** That is worth knowing
+ * before pointing a chart at one: a table element holds every row it has, and a
+ * grid may be holding twenty of two thousand. The chart is not wrong, the
+ * question was.
+ */
+const readGrid = (grid) => {
+    const columns = [...grid.querySelectorAll(COLUMNS)];
+    const rows = [...grid.querySelectorAll(ROWS)];
+    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) => {
+            const cells = cellsOf(row);
+            const head = cells[0];
+            const cell = cells[column + 1];
+            if (!cell) {
+                return [];
+            }
+            const raw = cell.dataset?.value ?? cell.textContent ?? '';
+            const value = Number(raw.trim());
+            const when = head?.querySelector('time')?.getAttribute('datetime');
+            const tone = cell.dataset?.tone;
+            return Number.isFinite(value) && raw.trim() !== ''
+                ? [
+                    {
+                        label: head?.textContent?.trim() ?? '',
+                        value,
+                        ...(tone ? { tone } : {}),
+                        ...(when ? { when } : {}),
+                    },
+                ]
+                : [];
+        }),
+    }));
+};
+/* A column with no numbers in it is not a series.
+ *
+ * Both readers build one entry per data column and then drop the rows whose
+ * cells will not parse, so a column of notes came back as a series with a name
+ * and no points. Nothing drew it, which is why it went unseen, and `Legend`
+ * named it anyway: a swatch in the palette against a column no chart plotted,
+ * and every series after it shifted a color.
+ *
+ * Found the moment tables grew columns a tooltip wanted and a drawing did not,
+ * which is the arrangement `readRows` exists for. */
+const plotted = (series) => series.filter((one) => one.points.length > 0);
+export const readSeries = (table) => {
+    if (isGrid(table)) {
+        return plotted(readGrid(table));
+    }
+    const element = table;
+    const names = [...(element.tHead?.rows[0]?.cells ?? [])]
+        .slice(1)
+        .map((cell) => cell.textContent?.trim() ?? '');
+    const rows = [...(element.tBodies[0]?.rows ?? [])];
+    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) => {
+            const head = row.cells[0];
+            const cell = row.cells[column + 1];
+            if (!cell) {
+                return [];
+            }
+            const raw = cell.dataset.value ?? cell.textContent ?? '';
+            const value = Number(raw.trim());
+            const when = head?.querySelector('time')?.getAttribute('datetime');
+            const tone = cell.dataset.tone;
+            return Number.isFinite(value) && raw.trim() !== ''
+                ? [
+                    {
+                        label: head?.textContent?.trim() ?? '',
+                        value,
+                        ...(tone ? { tone } : {}),
+                        ...(when ? { when } : {}),
+                    },
+                ]
+                : [];
+        }),
+    })));
+};
+/**
+ * Reads a table as rows rather than as columns.
+ *
+ * **Everything `readSeries` throws away on purpose, a tooltip needs.** That
+ * function answers "what should I draw", so it keeps the parsed number and
+ * discards the cell's text, and it drops a column whose cells are not numbers
+ * at all. A chart drawing `128000` and a tooltip saying `128000` would be the
+ * chart overruling the table, which already decided that number reads `$128k`;
+ * and a column of notes beside the figures is exactly the extra a reader wants
+ * when their pointer is resting on a reading.
+ *
+ * So this keeps both, and keeps the columns nothing plotted. A chart of two
+ * series over a table of four columns still has four columns to show.
+ *
+ * The traversal is the same shape as `readSeries` and deliberately separate.
+ * Folding them into one pass returning both would make every caller who wants
+ * one build the other, and the two are asked for at different moments: series
+ * on render, rows only where a pointer has stopped.
+ */
+export const readRows = (table) => {
+    const cell = (name, element) => {
+        if (!element) {
+            return undefined;
+        }
+        const text = element.textContent?.trim() ?? '';
+        const raw = element.dataset?.value ?? text;
+        const value = Number(raw.trim());
+        return {
+            name,
+            text,
+            ...(Number.isFinite(value) && raw.trim() !== '' ? { value } : {}),
+        };
+    };
+    const row = (head, rest, names) => {
+        const when = head?.querySelector('time')?.getAttribute('datetime');
+        return {
+            cells: rest
+                .map((one, index) => cell(names[index] ?? '', one))
+                .filter((one) => one !== undefined),
+            label: head?.textContent?.trim() ?? '',
+            ...(when ? { when } : {}),
+        };
+    };
+    if (isGrid(table)) {
+        const names = [...table.querySelectorAll(COLUMNS)]
+            .slice(1)
+            .map((one) => one.textContent?.trim() ?? '');
+        return [...table.querySelectorAll(ROWS)].map((one) => {
+            const cells = [...one.querySelectorAll(CELLS)];
+            return row(cells[0], cells.slice(1), names);
+        });
+    }
+    const element = table;
+    const names = [...(element.tHead?.rows[0]?.cells ?? [])]
+        .slice(1)
+        .map((one) => one.textContent?.trim() ?? '');
+    return [...(element.tBodies[0]?.rows ?? [])].map((one) => row(one.cells[0], [...one.cells].slice(1), names));
+};

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

@@ -0,0 +1,24 @@
+/** What one timestamp reads as, and when that stops being true. */
+export interface Relative {
+    /**
+     * Milliseconds until `text` would be different, or `Infinity` where it never
+     * will be within a session worth planning for.
+     *
+     * Floored at a second so a caller cannot be handed a zero and schedule a busy
+     * loop, and capped at an hour: an item three years old changes text in about
+     * a year, and a timer set for a year is a timer that is really "never" while
+     * looking like a number.
+     */
+    next: number;
+    /** The reading, in the caller's locale. */
+    text: string;
+}
+/**
+ * A formatter for one locale, kept.
+ *
+ * `now` is a parameter rather than read from the clock, which is what makes this
+ * 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.
+ */
+export declare const relativeTime: (locale: string) => ((from: Date, now: Date) => Relative);

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

@@ -0,0 +1,84 @@
+/**
+ * A timestamp read the way a person reads one, and the moment it stops being true.
+ *
+ * **The second half is the point.** "2 minutes ago" is correct for sixty seconds
+ * and wrong for the rest of the session, and a feed a user leaves open is
+ * exactly where that shows: every item drifts, quietly, and the panel ends up
+ * describing when the page loaded rather than when anything happened. So this
+ * returns the text and the milliseconds until that text changes, which is what
+ * lets a caller schedule one update instead of polling and lets a page hold one
+ * timer instead of one per item.
+ *
+ * `Intl.RelativeTimeFormat` with `numeric: 'auto'` is what produces "yesterday"
+ * rather than "1 day ago", which is what a reader would say. Cached per locale
+ * for the reason `formatNumbers` is: the constructor is expensive, the call is
+ * cheap, and a feed of fifty items formats fifty times per update.
+ */
+const held = new Map();
+/** How long each unit lasts, in milliseconds, largest last. */
+const UNITS = [
+    { ms: 1000, unit: 'second' },
+    { ms: 60_000, unit: 'minute' },
+    { ms: 3_600_000, unit: 'hour' },
+    { ms: 86_400_000, unit: 'day' },
+    { ms: 604_800_000, unit: 'week' },
+    { ms: 2_629_800_000, unit: 'month' },
+    { ms: 31_557_600_000, unit: 'year' },
+];
+/**
+ * A formatter for one locale, kept.
+ *
+ * `now` is a parameter rather than read from the clock, which is what makes this
+ * 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.
+ */
+export const relativeTime = (locale) => {
+    let format = held.get(locale);
+    if (!format) {
+        format = new Intl.RelativeTimeFormat(locale || undefined, { numeric: 'auto' });
+        held.set(locale, format);
+    }
+    const found = format;
+    return (from, now) => {
+        /* Signed from the timestamp's point of view, not the reader's:
+           `Intl.RelativeTimeFormat` takes a negative count for the past, so
+           `format(-2, 'minute')` is "2 minutes ago" and `format(2, 'minute')` is "in
+           2 minutes". Computed as `now - from` the sign is backwards and every past
+           item reads as the future, which is the shape of it that looks like a
+           working feed until you read one. */
+        const elapsed = from.getTime() - now.getTime();
+        if (!Number.isFinite(elapsed)) {
+            return { next: Number.POSITIVE_INFINITY, text: '' };
+        }
+        /* Under a minute is "now" rather than a count of seconds. A feed that
+           reports 3, then 4, then 5 seconds ago is a feed that moves under the
+           reader while they are trying to read it, and the precision is worth
+           nothing: nobody acts differently at seven seconds than at four. */
+        const size = Math.abs(elapsed);
+        if (size < 60_000) {
+            /* Floored, which `Relative.next` has always said this is and this branch
+               alone was not: at 59,999 milliseconds the remainder is one, so a caller
+               is re-armed inside the callback that fired it. Nothing had noticed
+               because both readers go through the shared ticker, whose own
+               `Math.max(1000, ...)` was absorbing it; a caller scheduling for itself
+               would have had the busy loop the type promised it would not. */
+            return { next: Math.max(1000, 60_000 - size), text: found.format(0, 'second') };
+        }
+        let chosen = UNITS[1];
+        for (const unit of UNITS) {
+            if (size >= unit.ms) {
+                chosen = unit;
+            }
+        }
+        const count = Math.trunc(elapsed / chosen.ms);
+        /* Time until the count ticks over, which is the remainder of the current
+           unit rather than the whole of one: an item read at 90 seconds is "1 minute
+           ago" for another 30 seconds, not another 60. */
+        const remaining = chosen.ms - (size % chosen.ms);
+        return {
+            next: Math.max(1000, Math.min(remaining, 3_600_000)),
+            text: found.format(count, chosen.unit),
+        };
+    };
+};

package/dist/utils/request-change/request-change.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Announces a change, then applies it unless a listener refused.
+ *
+ * One path for every stateful change in the library. The four controller
+ * mixins call it, and so does any component whose state is not one of theirs,
+ * so a fault here is a fault in every stateful component at once.
+ *
+ * **The order is the whole point.** The event goes first and carries the state
+ * being *proposed*, so a listener calling `preventDefault()` stops it before
+ * anything moves. A component that mutated itself and then announced it would
+ * leave a consumer reacting to a decision already made.
+ *
+ * **Control is an action, not a mode.** This used to decide whether to apply by
+ * asking if the consumer had declared ownership, which meant an element that
+ * had been handed a `value` applied nothing and waited to be told. That is
+ * gone: the element always owns its state and always applies it, and a consumer
+ * takes over for one interaction by refusing here and assigning their own. See
+ * 294 for the argument, which is that a mode forks the event vocabulary by prop
+ * presence, has no ergonomic spelling in HTML, and is invisible enough to need
+ * an audit to make it audible.
+ *
+ * **The audit went with it, and that is not a loss.** It existed to warn that
+ * `value="Ada"` looks like the native seed and was not one. It is one now, so
+ * the trap it detected cannot happen and the machinery to detect it, two
+ * `WeakMap`s and a warning judged on the second request, has nothing to do.
+ *
+ * Returns whether the change was applied, so a caller that needs to know (a key
+ * handler deciding whether to also move focus) can ask.
+ *
+ * **There is one channel, and it is the event.** `onCheckedChange`,
+ * `onOpenChange`, `onValueChange` and `onActiveChange` were a second one,
+ * invoked from here once the state had been applied. They were removed on
+ * 19 Aug 2026, for working in fewer places than the thing they duplicated:
+ * React takes any `on[A-Z]` prop into its own branch and calls
+ * `addEventListener('CheckedChange', …)` with it, an event nothing dispatches,
+ * so no consumer writing JSX could reach one.
+ */
+export interface ChangeRequestOptions<T> {
+    /** Applies the change. Called only if no listener refused it. */
+    apply: (next: T) => void;
+    /** Builds the cancelable event announcing the change. */
+    event: (next: T) => Event;
+    /** The element announcing the change. */
+    host: EventTarget;
+    /** The state being requested. */
+    next: T;
+}
+export declare const requestChange: <T>({ apply, event, host, next, }: ChangeRequestOptions<T>) => boolean;

package/dist/utils/request-change/request-change.js

@@ -0,0 +1,7 @@
+export const requestChange = ({ apply, event, host, next, }) => {
+    if (!host.dispatchEvent(event(next))) {
+        return false;
+    }
+    apply(next);
+    return true;
+};

package/dist/utils/resolve-active-item/resolve-active-item.d.ts

@@ -0,0 +1,28 @@
+/** The least a thing must be for this to pick one of them. */
+export interface ActivatableItem {
+    /** Whether it can be the current one. A disabled item is skipped. */
+    disabled?: boolean;
+    /** What identifies it, and what the value is compared against. */
+    value: string;
+}
+/**
+ * Which item a value names, or the first that could stand in for it.
+ *
+ * `items.find(match) ?? items[0]` was written by hand in four components and it
+ * is not the obvious line it looks like. It is what makes a set whose `value`
+ * names nothing still show something, which is every set before its consumer
+ * has chosen and every set whose current item has just been removed.
+ *
+ * The fallback skips disabled items and the match does not. A consumer who
+ * names a disabled item meant it, and quietly moving to another would be the
+ * component overruling them; but falling back *onto* a disabled item is the
+ * component choosing, and it should not choose something out of play. Every
+ * hand-written copy took `items[0]` either way, so a set opening on a disabled
+ * first item showed it as current.
+ *
+ * A plain function rather than only a method on `MixinControllerActive`,
+ * because the components that need it are split across two mixins: a set whose
+ * value is submitted takes `MixinControllerValue` and cannot also take the
+ * active one without two properties called `value`.
+ */
+export declare const resolveActiveItem: <Item extends ActivatableItem>(value: string, items: Item[]) => Item | undefined;

package/dist/utils/resolve-active-item/resolve-active-item.js

@@ -0,0 +1,21 @@
+/**
+ * Which item a value names, or the first that could stand in for it.
+ *
+ * `items.find(match) ?? items[0]` was written by hand in four components and it
+ * is not the obvious line it looks like. It is what makes a set whose `value`
+ * names nothing still show something, which is every set before its consumer
+ * has chosen and every set whose current item has just been removed.
+ *
+ * The fallback skips disabled items and the match does not. A consumer who
+ * names a disabled item meant it, and quietly moving to another would be the
+ * component overruling them; but falling back *onto* a disabled item is the
+ * component choosing, and it should not choose something out of play. Every
+ * hand-written copy took `items[0]` either way, so a set opening on a disabled
+ * first item showed it as current.
+ *
+ * A plain function rather than only a method on `MixinControllerActive`,
+ * because the components that need it are split across two mixins: a set whose
+ * value is submitted takes `MixinControllerValue` and cannot also take the
+ * active one without two properties called `value`.
+ */
+export const resolveActiveItem = (value, items) => items.find((item) => item.value === value) ?? items.find((item) => !item.disabled);

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

@@ -0,0 +1,32 @@
+/** A control whose text the element may have to put back. */
+type TextControl = HTMLInputElement | HTMLTextAreaElement;
+/**
+ * Holds the caret across a write the element does not make itself.
+ *
+ * **Lit's `.value` binding moves the caret to the end, and only a controlled
+ * field notices.** Measured in Chrome with real typing: place the caret after
+ * `Ada` in `Ada Lovelace` and press one key, and an uncontrolled field reports
+ * `AdaX Lovelace` with the caret at 4, while a controlled one reports the same
+ * text with the caret at 13. Editing the middle of a controlled field was
+ * impossible: every keystroke threw the caret to the end.
+ *
+ * The asymmetry is the interesting part. Uncontrolled, `handleInput` runs
+ * `restoreValue` after the state has moved, so the control already holds the
+ * new text and the call returns early; when Lit's binding then assigns the same
+ * string, Chrome leaves the selection alone. Controlled, the control has been
+ * put *back* to the old text while the consumer decides, so Lit assigns a
+ * genuinely different string and the platform resets the selection, as it does
+ * for any assignment to `value`.
+ *
+ * So the selection is taken before the update and put back after it, mapped by
+ * however much the text grew or shrank, which is the same arithmetic
+ * `restoreValue` does in one step. Returned as a closure rather than a pair of
+ * fields so the two halves cannot be called out of order.
+ *
+ * The binding itself has to stay: it is what Lit SSR serializes, and a field
+ * that filled in at hydration would flash empty for every reader on a slow
+ * connection.
+ */
+export declare const holdCaret: (control: TextControl) => (() => void);
+export declare const restoreValue: (control: TextControl, next: string) => void;
+export {};

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

@@ -0,0 +1,84 @@
+/*
+ * Puts a value back into a text control without moving the reader's caret.
+ *
+ * A controlled input has to restore what the element holds whenever the native
+ * control has moved and the answer has not followed, which is a refusal or a
+ * consumer who owns the value and has not answered yet. Assigning `value` is
+ * how that is done, and per spec assigning a *different* string moves the text
+ * entry cursor to the end. Measured: caret at index three in `abcdef`, assign
+ * `abcXdef`, caret at seven. Assigning the same string leaves it alone, which
+ * is why this was invisible until a consumer was slow.
+ *
+ * So a React consumer holding the value in state, which commits after the
+ * event, put the caret at the end of the field after every single keystroke.
+ * Typing in the middle of a word was impossible, and the class JSDoc claimed
+ * the caret was the platform's business.
+ *
+ * The offset is adjusted by the length difference rather than clamped, because
+ * the common case is exactly one character wide: the reader typed, the element
+ * restored the shorter previous string, and the caret belongs one place back.
+ * Clamping alone would leave it one to the right of where the reader was, which
+ * is the same bug at a smaller size.
+ *
+ * Nothing is restored when the value already matches, since the assignment
+ * itself is what moves the caret and there is nothing to assign.
+ */
+/**
+ * Holds the caret across a write the element does not make itself.
+ *
+ * **Lit's `.value` binding moves the caret to the end, and only a controlled
+ * field notices.** Measured in Chrome with real typing: place the caret after
+ * `Ada` in `Ada Lovelace` and press one key, and an uncontrolled field reports
+ * `AdaX Lovelace` with the caret at 4, while a controlled one reports the same
+ * text with the caret at 13. Editing the middle of a controlled field was
+ * impossible: every keystroke threw the caret to the end.
+ *
+ * The asymmetry is the interesting part. Uncontrolled, `handleInput` runs
+ * `restoreValue` after the state has moved, so the control already holds the
+ * new text and the call returns early; when Lit's binding then assigns the same
+ * string, Chrome leaves the selection alone. Controlled, the control has been
+ * put *back* to the old text while the consumer decides, so Lit assigns a
+ * genuinely different string and the platform resets the selection, as it does
+ * for any assignment to `value`.
+ *
+ * So the selection is taken before the update and put back after it, mapped by
+ * however much the text grew or shrank, which is the same arithmetic
+ * `restoreValue` does in one step. Returned as a closure rather than a pair of
+ * fields so the two halves cannot be called out of order.
+ *
+ * The binding itself has to stay: it is what Lit SSR serializes, and a field
+ * that filled in at hydration would flash empty for every reader on a slow
+ * connection.
+ */
+export const holdCaret = (control) => {
+    const { selectionDirection, selectionEnd, selectionStart } = control;
+    const held = control.value.length;
+    return () => {
+        /* Null on a control with no selection, `<input type="range">` among them,
+           where `setSelectionRange` throws rather than declining. */
+        if (selectionStart === null || selectionEnd === null) {
+            return;
+        }
+        const delta = control.value.length - held;
+        const at = (point) => Math.max(0, Math.min(control.value.length, point + delta));
+        control.setSelectionRange(at(selectionStart), at(selectionEnd), selectionDirection ?? undefined);
+    };
+};
+export const restoreValue = (control, next) => {
+    if (control.value === next) {
+        return;
+    }
+    const { selectionDirection, selectionEnd, selectionStart } = control;
+    const delta = next.length - control.value.length;
+    control.value = next;
+    /* A control with no selection is done here, and this is a guard rather than a
+       tidiness: `<input type="range">` reports `selectionStart` as null and
+       *throws* `InvalidStateError` from `setSelectionRange`. Measured. The slider
+       restores through this same util, which is what makes the check load-bearing
+       rather than defensive. */
+    if (selectionStart === null || selectionEnd === null) {
+        return;
+    }
+    const at = (point) => Math.max(0, Math.min(next.length, point + delta));
+    control.setSelectionRange(at(selectionStart), at(selectionEnd), selectionDirection ?? undefined);
+};

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

@@ -0,0 +1,23 @@
+/** A mapping from one numeric interval onto another. */
+export type Scale = (value: number) => number;
+/** The smallest and largest of a set of numbers, as a scale's domain. */
+export declare const extent: (values: readonly number[]) => [number, number];
+/**
+ * Maps a domain onto a range, linearly.
+ *
+ * A pure function rather than a controller, which is the distinction the rules
+ * draw: a controller reacts to a host's lifecycle, and this is arithmetic on
+ * four numbers. It holds nothing, subscribes to nothing, and can be called from
+ * `render` without anything being wired up first.
+ *
+ * The range is given rather than assumed, so an inverted one is ordinary: SVG
+ * counts down from the top, so a chart passes `[height, 0]` and gets a larger
+ * value drawn higher without anything here knowing why.
+ *
+ * **A flat domain maps to the middle of the range, and that is the case worth
+ * naming.** Every value being equal makes the domain zero wide, and the obvious
+ * arithmetic divides by it: seven identical readings drew a line at `NaN`, which
+ * an `<svg>` renders as no line at all rather than as an error. A flat series is
+ * a real thing to plot and it should come out as a flat line halfway up.
+ */
+export declare const linear: (domain: readonly [number, number], range: readonly [number, number]) => Scale;

package/dist/utils/scale/scale.js

@@ -0,0 +1,32 @@
+/** The smallest and largest of a set of numbers, as a scale's domain. */
+export const extent = (values) => [
+    Math.min(...values),
+    Math.max(...values),
+];
+/**
+ * Maps a domain onto a range, linearly.
+ *
+ * A pure function rather than a controller, which is the distinction the rules
+ * draw: a controller reacts to a host's lifecycle, and this is arithmetic on
+ * four numbers. It holds nothing, subscribes to nothing, and can be called from
+ * `render` without anything being wired up first.
+ *
+ * The range is given rather than assumed, so an inverted one is ordinary: SVG
+ * counts down from the top, so a chart passes `[height, 0]` and gets a larger
+ * value drawn higher without anything here knowing why.
+ *
+ * **A flat domain maps to the middle of the range, and that is the case worth
+ * naming.** Every value being equal makes the domain zero wide, and the obvious
+ * arithmetic divides by it: seven identical readings drew a line at `NaN`, which
+ * an `<svg>` renders as no line at all rather than as an error. A flat series is
+ * a real thing to plot and it should come out as a flat line halfway up.
+ */
+export const linear = (domain, range) => {
+    const [from, to] = domain;
+    const [start, end] = range;
+    const span = to - from;
+    if (span === 0) {
+        return () => (start + end) / 2;
+    }
+    return (value) => start + ((value - from) / span) * (end - start);
+};