@matchstick-trading/primitives 0.0.10

package/dist/PanelsParts.js

@@ -0,0 +1,387 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useCallback, useContext, useEffect, useMemo, useRef, useState } from 'react';
+import { buttonFace } from './accessible-name.js';
+import { useChart } from './ChartParts.js';
+import { chartFrame, priceTicks, tickDecimals } from './core/chart-scale.js';
+import { AXIS_BOTTOM, describeMove, MAIN_PANEL, moveSeries, moveTargets, normalizeLayout, panelBands, panelOf, reconcileLayout } from './core/panels.js';
+import { duplicateIds, resolveSeries } from './core/series.js';
+import { PanelsContext } from './panels-context.js';
+import { SelectionContext } from './selection-context.js';
+const HIDDEN = { position: 'absolute', width: 1, height: 1, margin: -1, padding: 0, overflow: 'hidden', clip: 'rect(0 0 0 0)', whiteSpace: 'nowrap', border: 0 };
+/** The layout the `panel` fields of the series ask for: `main` first, then each named panel in the order first seen. */
+function initialLayout(series, named = []) {
+    const panels = [{ id: MAIN_PANEL, label: 'Main' }];
+    // A band named in `panels` that no series asks for is not made: a band with no series is removed.
+    for (const n of named)
+        if (n.id !== MAIN_PANEL && series.some((s) => s.panel === n.id))
+            panels.push(n);
+    const placement = {};
+    for (const s of series) {
+        if (!s.panel || s.panel === MAIN_PANEL)
+            continue;
+        if (!panels.some((p) => p.id === s.panel))
+            panels.push({ id: s.panel, label: s.panel });
+        placement[s.id] = s.panel;
+    }
+    return { panels, placement };
+}
+const finite = (v) => v !== null && v !== undefined && Number.isFinite(v);
+/** Holds the layout, says each move in a polite live region and tells Chart how tall the first band is. Wrap the Chart in it. */
+function Root({ series: given, panels: named, layout, onLayoutChange, align, children }) {
+    // A list that is not a list, or an entry that is not a series, is left out and named in the problems, not thrown at render.
+    const series = useMemo(() => (Array.isArray(given) ? given.filter((s) => s !== null && typeof s === 'object' && typeof s.id === 'string') : []), [given]);
+    const unusable = given === undefined ? 0 : Array.isArray(given) ? given.length - series.length : -1;
+    const [inner, setInner] = useState(() => initialLayout(series, named));
+    // Series that come or go after the first render: a new one starts where it asks, a gone one leaves its panel (an empty panel goes). Done while rendering, so there is no frame with the series in the wrong band.
+    const [seen, setSeen] = useState(() => series.map((s) => s.id));
+    if (layout === undefined && (seen.length !== series.length || series.some((s, i) => s.id !== seen[i]))) {
+        setSeen(series.map((s) => s.id));
+        setInner((was) => reconcileLayout(was, series, seen, named));
+    }
+    const current = useMemo(() => normalizeLayout(layout !== undefined ? layout : inner), [layout, inner]);
+    const latest = useRef(current);
+    latest.current = current;
+    const labels = useRef(new Map());
+    labels.current = new Map(series.map((s) => [s.id, s.label]));
+    const [status, setStatus] = useState('');
+    const pending = useRef(null);
+    const announce = (now) => {
+        const p = pending.current;
+        if (!p || panelOf(now, p.id) !== p.panel)
+            return;
+        pending.current = null;
+        const where = now.panels.find((x) => x.id === p.panel);
+        setStatus(describeMove(labels.current.get(p.id) ?? p.id, where?.label ?? 'a panel'));
+    };
+    const move = useCallback((seriesId, destination) => {
+        const was = latest.current;
+        const next = moveSeries(was, seriesId, destination);
+        if (next === was)
+            return;
+        latest.current = next;
+        if (layout === undefined)
+            setInner(next);
+        onLayoutChange?.(next);
+        // A controlled host may decline the move; it is said only once the layout it gives back has the series there.
+        pending.current = { id: seriesId, panel: panelOf(next, seriesId) };
+        if (layout === undefined)
+            announce(next);
+    }, [layout, onLayoutChange]);
+    useEffect(() => { if (layout !== undefined)
+        announce(current); }, [layout, current]);
+    // Series placed on the bars once per bars array and series object; a crosshair move re-renders without redoing it.
+    const mode = align?.mode;
+    const tolerance = align?.toleranceMs;
+    // One entry per bars array, rebuilt when its length changes (a host may append bars to the same array).
+    const cache = useMemo(() => ({ byBars: new WeakMap() }), [mode, tolerance]);
+    const resolve = useCallback((item, bars) => {
+        let entry = cache.byBars.get(bars);
+        if (!entry || entry.len !== bars.length) {
+            entry = { len: bars.length, times: bars.map((b) => b.timestamp), made: new WeakMap() };
+            cache.byBars.set(bars, entry);
+        }
+        let hit = entry.made.get(item);
+        if (!hit) {
+            hit = resolveSeries(entry.times, item, { mode, toleranceMs: tolerance });
+            entry.made.set(item, hit);
+        }
+        return hit;
+    }, [cache, mode, tolerance]);
+    const problems = useMemo(() => {
+        const out = duplicateIds(series).map((id) => `The series id "${id}" is used more than once. Ids must be unique on a chart.`);
+        if (unusable < 0)
+            out.push('The series given is not a list, so no series is drawn.');
+        else if (unusable > 0)
+            out.push(`${unusable} ${unusable === 1 ? 'entry' : 'entries'} in the series list ${unusable === 1 ? 'is' : 'are'} not a series (an object with a string id) and ${unusable === 1 ? 'was' : 'were'} left out.`);
+        return out;
+    }, [series, unusable]);
+    const mainInclude = useCallback((visible, bars) => {
+        const out = [];
+        for (const s of series) {
+            if (panelOf(current, s.id) !== MAIN_PANEL)
+                continue;
+            const values = resolve(s, bars).values;
+            let low = Infinity;
+            let high = -Infinity;
+            for (let i = visible.first; i <= visible.last; i++) {
+                const v = values[i];
+                if (finite(v)) {
+                    if (v < low)
+                        low = v;
+                    if (v > high)
+                        high = v;
+                }
+            }
+            if (low <= high)
+                out.push(s.style === 'histogram' ? [Math.min(low, 0), Math.max(high, 0)] : [low, high]); // a histogram's bars start at zero
+        }
+        return out;
+    }, [series, current, resolve]);
+    // A series of this Root that is no longer given cannot stay selected. Only ids this Root has had count, so a selection
+    // of the chart's own bar series (a Series.Root, registered after the first render) is never touched here.
+    const selection = useContext(SelectionContext);
+    const selectedId = selection?.selection?.kind === 'series' ? selection.selection.id : null;
+    const had = useRef(new Set());
+    useEffect(() => {
+        const ids = new Set(series.map((s) => s.id));
+        if (selection && selectedId !== null && had.current.has(selectedId) && !ids.has(selectedId)) {
+            queueMicrotask(() => {
+                const now = selection.current();
+                if (now && now.kind === 'series' && now.id === selectedId)
+                    selection.select(null);
+            });
+        }
+        had.current = new Set([...had.current, ...ids]);
+    }, [selection, selectedId, series]);
+    const value = useMemo(() => ({ series, layout: current, move, mainInclude, resolve, problems }), [series, current, move, mainInclude, resolve, problems]);
+    return (_jsxs(PanelsContext.Provider, { value: value, children: [children, _jsx("span", { "data-part": "panels-status", role: "status", "aria-live": "polite", style: HIDDEN, children: status })] }));
+}
+function usePanels(part) {
+    const context = useContext(PanelsContext);
+    if (!context)
+        throw new Error(`Panels.${part} needs a Panels.Root above it.`);
+    return context;
+}
+const NO_ITEMS = [];
+/** Words for a bar with no number, from the reason the series gives. */
+const NO_VALUE_WORDS = {
+    missing: 'missing (the feed has nothing here)',
+    'market-closed': 'market closed',
+    'not-applicable': 'not applicable',
+    halted: 'halted',
+    unknown: 'unknown (the source does not say why)',
+    'no-point': 'no point at this bar',
+};
+const noValueWords = (state) => (state && NO_VALUE_WORDS[state]) || 'no value';
+/**
+ * One sentence on where a series has no value: how many bars, by reason, and when it stops for good. Empty when every
+ * bar has a value, or none does (the problem note says that).
+ */
+function gapSummary(values, states, bars) {
+    if (!states || bars.length === 0)
+        return '';
+    let gaps = 0;
+    let lastValue = -1;
+    const by = {};
+    for (let i = 0; i < bars.length; i++) {
+        if (finite(values[i])) {
+            lastValue = i;
+            continue;
+        }
+        gaps++;
+        const k = noValueWords(states[i]);
+        by[k] = (by[k] ?? 0) + 1;
+    }
+    if (gaps === 0 || lastValue < 0)
+        return '';
+    const parts = Object.entries(by).map(([k, n]) => `${n} ${k}`).join(', ');
+    const stops = lastValue < bars.length - 1 ? ` No value after ${new Date(bars[lastValue].timestamp).toISOString()}.` : '';
+    return `${gaps} of ${bars.length} bars have no value (${parts}).${stops}`;
+}
+const gapCache = new WeakMap();
+/** The gap sentence, kept per resolved series so a crosshair move does not rescan every bar. */
+function gapsOf(resolved, bars) {
+    const hit = gapCache.get(resolved);
+    if (hit && hit.len === bars.length)
+        return hit.text;
+    const text = gapSummary(resolved.values, resolved.states, bars);
+    gapCache.set(resolved, { len: bars.length, text });
+    return text;
+}
+/** Wide enough for a finger: the transparent hit stroke is --mt-touch-target (44px) across. */
+const HIT_WIDTH = 44;
+const num = (n) => n.toFixed(2);
+/** One path per run of consecutive values. */
+function pathOf(frame, values) {
+    let d = '';
+    let run = [];
+    const flush = () => {
+        if (run.length >= 2)
+            d += run.map((i, k) => `${k === 0 ? 'M' : 'L'}${num(frame.x(i))},${num(frame.y(values[i]))}`).join('');
+        run = [];
+    };
+    for (let i = frame.first; i <= frame.last; i++) {
+        if (finite(values[i]))
+            run.push(i);
+        else
+            flush();
+    }
+    flush();
+    return d;
+}
+/**
+ * The bars a band's price scale is taken from: one per bar in view, spanning the values of the series in it (NaN where
+ * none), plus zero for a histogram and any reference levels. Only the window is filled, so a long history costs
+ * nothing; chartFrame reads nothing outside it.
+ */
+function scaleBars(bars, viewport, inBand) {
+    const out = new Array(bars.length);
+    const from = Math.max(0, Math.floor(viewport.start));
+    const to = Math.min(bars.length - 1, Math.ceil(viewport.end) - 1);
+    const extras = [];
+    for (const { item } of inBand) {
+        if (item.style === 'histogram')
+            extras.push(0);
+        for (const l of Array.isArray(item.levels) ? item.levels : [])
+            if (Number.isFinite(l))
+                extras.push(l);
+    }
+    for (let i = from; i <= to; i++) {
+        let low = Infinity;
+        let high = -Infinity;
+        for (const { values } of inBand) {
+            const v = values[i];
+            if (finite(v)) {
+                if (v < low)
+                    low = v;
+                if (v > high)
+                    high = v;
+            }
+        }
+        const has = low <= high;
+        if (has)
+            for (const e of extras) {
+                if (e < low)
+                    low = e;
+                if (e > high)
+                    high = e;
+            }
+        out[i] = { timestamp: bars[i].timestamp, open: has ? low : NaN, high: has ? high : NaN, low: has ? low : NaN, close: has ? high : NaN, volume: 0 };
+    }
+    return out;
+}
+/** The fixed range a band asks for: the widest of the `range`s of its series, or null to follow the data. */
+function fixedRange(inBand) {
+    let low = Infinity;
+    let high = -Infinity;
+    for (const { item } of inBand) {
+        const r = item.range;
+        if (r && Number.isFinite(r[0]) && Number.isFinite(r[1]) && r[0] < r[1]) {
+            if (r[0] < low)
+                low = r[0];
+            if (r[1] > high)
+                high = r[1];
+        }
+    }
+    return low < high ? [low, high] : null;
+}
+function useSeriesSelection(id, label) {
+    const selection = useContext(SelectionContext);
+    const setName = selection?.setName;
+    useEffect(() => { if (setName)
+        setName('series', id, label); }, [setName, id, label]);
+    const sel = selection?.selection;
+    return { selectable: !!selection, selected: !!sel && sel.kind === 'series' && sel.id === id };
+}
+/** Runs of one bar with a value on both sides empty: a line cannot show them, so they are drawn as dots. */
+function loneIndexes(frame, values) {
+    const out = [];
+    for (let i = frame.first; i <= frame.last && out.length < 300; i++) {
+        if (finite(values[i]) && !finite(values[i - 1]) && !finite(values[i + 1]))
+            out.push(i);
+    }
+    return out;
+}
+/** A bar from zero to the value, for each bar in view. */
+function histogramPath(frame, values) {
+    const half = Math.max(0.5, frame.barWidth * 0.35);
+    const zero = frame.y(0);
+    let d = '';
+    for (let i = frame.first; i <= frame.last; i++) {
+        const v = values[i];
+        if (finite(v))
+            d += `M${num(frame.x(i) - half)},${num(zero)}V${num(frame.y(v))}h${num(half * 2)}V${num(zero)}Z`;
+    }
+    return d;
+}
+function SeriesPaths({ item, values, frame, clip }) {
+    const { selectable, selected } = useSeriesSelection(item.id, item.label);
+    const histogram = item.style === 'histogram';
+    const d = histogram ? histogramPath(frame, values) : pathOf(frame, values);
+    const lone = histogram ? [] : loneIndexes(frame, values);
+    if (!d && lone.length === 0)
+        return null;
+    return (_jsxs(_Fragment, { children: [d && _jsx("path", { "data-part": "panel-series", "data-series": item.id, "data-style": histogram ? 'histogram' : undefined, "data-state": selected ? 'selected' : undefined, clipPath: clip, d: d, fill: histogram ? 'currentColor' : 'none', "aria-hidden": "true" }), lone.map((i) => _jsx("circle", { "data-part": "panel-point", "data-series": item.id, "data-state": selected ? 'selected' : undefined, clipPath: clip, cx: num(frame.x(i)), cy: num(frame.y(values[i])), r: 3, fill: "currentColor", "aria-hidden": "true" }, i)), selectable && _jsx("path", { "data-part": "series-hit", "data-select-id": item.id, clipPath: clip, d: d + lone.map((i) => `M${num(frame.x(i))},${num(frame.y(values[i]))}h0`).join(''), fill: "none", stroke: "transparent", strokeWidth: HIT_WIDTH, strokeLinecap: "round", strokeLinejoin: "round", pointerEvents: "stroke", "aria-hidden": "true" })] }));
+}
+function Band({ spec, top, height, items, bars }) {
+    const { frame: main, viewport, active, readoutId } = useChart('Panels.Layer');
+    const { resolve } = usePanels('Layer');
+    const placed = useMemo(() => items.map((item) => ({ item, values: resolve(item, bars).values })), [items, bars, resolve]);
+    const frame = useMemo(() => chartFrame(scaleBars(bars, viewport, placed), viewport, { width: main.width, height }, { volumeShare: 0, axisBottom: 0, priceRange: fixedRange(placed) }), [bars, bars.length, placed, viewport, main.width, height]);
+    const levels = useMemo(() => [...new Set(items.flatMap((it) => (Array.isArray(it.levels) ? it.levels : []).filter(Number.isFinite)))], [items]);
+    const ticks = priceTicks(frame.priceMin, frame.priceMax, 3);
+    const places = tickDecimals(ticks);
+    const clip = `${readoutId}-panel-${spec.id}`;
+    return (_jsxs("g", { "data-part": "panel", "data-panel": spec.id, transform: `translate(0,${top})`, children: [_jsx("defs", { children: _jsx("clipPath", { id: clip, children: _jsx("rect", { x: 0, y: 0, width: frame.plotWidth, height: height }) }) }), _jsx("line", { "data-part": "panel-divider", x1: 0, x2: main.width, y1: 0, y2: 0, "aria-hidden": "true" }), _jsx("g", { "data-part": "panel-grid", "aria-hidden": "true", clipPath: `url(#${clip})`, children: ticks.map((t) => _jsx("line", { x1: 0, x2: frame.plotWidth, y1: frame.y(t), y2: frame.y(t) }, t)) }), _jsx("g", { "data-part": "panel-axis", "aria-hidden": "true", style: { pointerEvents: 'none' }, children: ticks.map((t) => _jsx("text", { x: frame.plotWidth + 6, y: frame.y(t) + 4, textAnchor: "start", children: t.toFixed(places) }, t)) }), levels.map((l) => frame.y(l) >= 0 && frame.y(l) <= height && _jsx("line", { "data-part": "panel-level", x1: 0, x2: frame.plotWidth, y1: frame.y(l), y2: frame.y(l), "aria-hidden": "true" }, `level-${l}`)), _jsx("text", { "data-part": "panel-label", x: 6, y: 14, "aria-hidden": "true", style: { pointerEvents: 'none' }, children: spec.label }), active !== null && _jsx("line", { "data-part": "panel-crosshair", x1: frame.x(active), x2: frame.x(active), y1: 0, y2: height, "aria-hidden": "true", style: { pointerEvents: 'none' } }), placed.map(({ item, values }) => _jsx(SeriesPaths, { item: item, values: values, frame: frame, clip: `url(#${clip})` }, item.id))] }));
+}
+/**
+ * Draws the series in their bands. Put it inside `Chart.Plot`, after the chart's own parts. The series in `main` use the
+ * chart's price scale (and keep themselves in view); every other band has its own scale, grid, price labels and
+ * a divider. With a Selection.Root above, a tap on a series line selects it. A band is never shorter than 40, so give the
+ * chart enough height for the bands you use.
+ */
+function Layer() {
+    const { series, layout, resolve } = usePanels('Layer');
+    const { bars, frame, totalHeight, readoutId } = useChart('Panels.Layer');
+    const bands = useMemo(() => panelBands(layout.panels, totalHeight - AXIS_BOTTOM), [layout.panels, totalHeight]);
+    // One array per panel, kept between renders (a crosshair move re-renders but changes neither the series nor the layout).
+    const byPanel = useMemo(() => {
+        const map = new Map();
+        for (const p of layout.panels)
+            map.set(p.id, []);
+        for (const s of series)
+            map.get(panelOf(layout, s.id))?.push(s);
+        return map;
+    }, [series, layout]);
+    const inPanel = (id) => byPanel.get(id) ?? NO_ITEMS;
+    return (_jsxs("g", { "data-part": "panels", "aria-hidden": "true", children: [_jsx("g", { "data-part": "panel", "data-panel": MAIN_PANEL, clipPath: `url(#${readoutId}-price)`, children: inPanel(MAIN_PANEL).map((item) => _jsx(SeriesPaths, { item: item, values: resolve(item, bars).values, frame: frame, clip: `url(#${readoutId}-price)` }, item.id)) }), layout.panels.slice(1).map((spec, i) => {
+                const band = bands[i + 1];
+                return band ? _jsx(Band, { spec: spec, top: band.top, height: band.height, items: inPanel(spec.id), bars: bars }, spec.id) : null;
+            })] }));
+}
+/**
+ * The series as text: each one's name, its panel, and its value at the crosshair bar (the last bar in view when there is
+ * no crosshair), so the numbers are not only a picture. With a Selection.Root above, each row has a button that selects
+ * the series. Put it outside the SVG, inside `Chart.Root`.
+ */
+function List({ className, format }) {
+    const { series, layout, resolve, problems: setProblems } = usePanels('List');
+    const { active, frame, decimals, bars } = useChart('Panels.List');
+    const selection = useContext(SelectionContext);
+    const at = active ?? frame.last;
+    const f = format ?? ((n) => n.toFixed(decimals));
+    if (series.length === 0 && setProblems.length === 0)
+        return null;
+    return (_jsxs(_Fragment, { children: [setProblems.map((p) => _jsx("p", { "data-part": "panel-problem", role: "note", children: p }, p)), _jsx("ul", { className: className, "data-part": "panel-list", "aria-label": "Series", children: series.map((s) => {
+                    const here = layout.panels.find((p) => p.id === panelOf(layout, s.id));
+                    const resolved = resolve(s, bars);
+                    const v = resolved.values[at];
+                    const selected = !!selection?.selection && selection.selection.kind === 'series' && selection.selection.id === s.id;
+                    const face = buttonFace(s.label, {});
+                    return (_jsxs("li", { "data-part": "panel-list-item", "data-series": s.id, "data-state": selected ? 'selected' : undefined, children: [selection
+                                ? _jsx("button", { type: "button", "data-mt": "", "data-touch-target": "", "data-part": "panel-select", "data-state": selected ? 'selected' : undefined, "aria-pressed": selected, "aria-label": face['aria-label'], onClick: () => selection.select(selected ? null : { kind: 'series', id: s.id }), children: face.content })
+                                : _jsx("span", { "data-part": "panel-name", children: s.label }), _jsxs("span", { "data-part": "panel-where", children: [" ", here?.label ?? 'Main'] }), _jsxs("span", { "data-part": "panel-value", "data-mt-numeric": "", children: [" ", finite(v) ? f(v) : noValueWords(resolved.states?.[at])] }), gapsOf(resolved, bars) && _jsxs("span", { "data-part": "panel-gaps", children: [" ", gapsOf(resolved, bars)] }), resolved.problems.map((p) => _jsxs("span", { "data-part": "panel-problem", role: "note", children: [" ", p] }, p))] }, s.id));
+                }) })] }));
+}
+/**
+ * The way to move a series to another panel without dragging: buttons for where it can go, relative to where it is
+ * (up, down, a new panel above, a new panel below). It shows while a series of the Root is selected (or for `seriesId`)
+ * and says each move in the live region. After a move the focus goes to the group, so a keyboard or screen reader user
+ * is not left on a button that is gone.
+ */
+function Move({ className, seriesId }) {
+    const { series, layout, move } = usePanels('Move');
+    const selection = useContext(SelectionContext);
+    const id = seriesId ?? (selection?.selection?.kind === 'series' ? selection.selection.id : undefined);
+    const item = id === undefined ? undefined : series.find((s) => s.id === id);
+    const group = useRef(null);
+    const [moved, setMoved] = useState(0);
+    useEffect(() => { if (moved > 0)
+        group.current?.focus(); }, [moved]);
+    if (!item)
+        return null;
+    const targets = moveTargets(layout, item.id);
+    return (_jsx("div", { ref: group, className: className, role: "group", tabIndex: -1, "aria-label": `Move ${item.label}`, "data-mt": "", "data-part": "panel-move", "data-series": item.id, children: targets.map((t) => (_jsx("button", { type: "button", "data-mt": "", "data-touch-target": "", "data-part": "panel-move-to", onClick: () => { move(item.id, t.destination); setMoved((n) => n + 1); }, children: t.label }, t.destination.kind === 'panel' ? `to:${t.destination.panelId}` : `new:${t.destination.side}`))) }));
+}
+export { Root, Layer, List, Move, usePanels };

package/dist/Receipt.d.ts

@@ -0,0 +1,11 @@
+import { Root, Field, Hash, CopyButton, ShareNote, Verdict } from './ReceiptParts.js';
+export * from './ReceiptParts.js';
+export declare const Receipt: {
+    Root: typeof Root;
+    Field: typeof Field;
+    Hash: typeof Hash;
+    CopyButton: typeof CopyButton;
+    ShareNote: typeof ShareNote;
+    Verdict: typeof Verdict;
+};
+//# sourceMappingURL=Receipt.d.ts.map

package/dist/Receipt.js

@@ -0,0 +1,5 @@
+import { Root, Field, Hash, CopyButton, ShareNote, Verdict } from './ReceiptParts.js';
+// The parts live in ReceiptParts.js (a client module). The namespace object is built here, outside it, so a server
+// component can write `Receipt.Root`: a property of an object exported from a client module is not reachable there.
+export * from './ReceiptParts.js';
+export const Receipt = { Root, Field, Hash, CopyButton, ShareNote, Verdict };

package/dist/ReceiptParts.d.ts

@@ -0,0 +1,45 @@
+import { type ReactNode } from 'react';
+import { type ReceiptData, type ReceiptHashOf } from './core/receipt-rules.js';
+export interface ReceiptRootProps {
+    receipt: ReceiptData;
+    /** The whole receipt as text, for the Copy receipt button. The host owns the wording. */
+    receiptText: string;
+    /** Writes text to the clipboard; the default is `navigator.clipboard.writeText`. Rejecting means it could not copy. */
+    onCopy?: (text: string) => Promise<void>;
+    className?: string;
+    'aria-label'?: string;
+    children?: ReactNode;
+}
+declare function Root({ receipt, receiptText, onCopy, className, 'aria-label': label, children }: ReceiptRootProps): import("react").JSX.Element;
+/** One labelled fact: a `<dt>` and a `<dd>` for a `<dl>`. */
+declare function Field({ label, children }: {
+    label: string;
+    children: ReactNode;
+}): import("react").JSX.Element;
+/** A digest as recorded, in a focusable `<code>` so a keyboard user can land on it and press Enter or `y`. */
+declare function Hash({ of, className }: {
+    of: ReceiptHashOf;
+    className?: string;
+}): import("react").JSX.Element;
+/**
+ * A button that copies the whole receipt (or just the result hash), then says whether it worked. Only the button that
+ * copied shows the status; a copy by Enter or y shows under the hash button, or the receipt button when there is none.
+ */
+declare function CopyButton({ what, className, statusClassName, children }: {
+    what?: 'receipt' | 'hash';
+    className?: string;
+    statusClassName?: string;
+    children?: ReactNode;
+}): import("react").JSX.Element;
+/** The line that must travel with a copy of non-synthetic data; nothing when there is none. */
+declare function ShareNote({ className }: {
+    className?: string;
+}): import("react").JSX.Element | null;
+/** Whether replaying from the start gave the same result, in words. Tokens.css colours a mismatch. */
+declare function Verdict({ className, matchText, mismatchText }: {
+    className?: string;
+    matchText?: string;
+    mismatchText?: string;
+}): import("react").JSX.Element;
+export { Root, Field, Hash, CopyButton, ShareNote, Verdict };
+//# sourceMappingURL=ReceiptParts.d.ts.map

package/dist/ReceiptParts.js

@@ -0,0 +1,71 @@
+'use client';
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { createContext, useCallback, useContext, useEffect, useMemo, useState } from 'react';
+import { Notice } from './Notice.js';
+import { receiptHash, receiptVerdict, resolveReceiptKey } from './core/receipt-rules.js';
+const Context = createContext(null);
+function useReceipt(part) {
+    const context = useContext(Context);
+    if (!context)
+        throw new Error(`Receipt.${part} needs a Receipt.Root above it.`);
+    return context;
+}
+function Root({ receipt, receiptText, onCopy, className, 'aria-label': label = 'Evidence receipt', children }) {
+    const [status, setStatus] = useState(null);
+    const [hashButtons, setHashButtons] = useState(0);
+    const addHashButton = useCallback(() => {
+        setHashButtons((n) => n + 1);
+        return () => setHashButtons((n) => n - 1);
+    }, []);
+    const copy = useCallback(async (text, what, from) => {
+        try {
+            await (onCopy ? onCopy(text) : navigator.clipboard.writeText(text));
+            setStatus({ text: `${what} copied.`, ok: true, from });
+        }
+        catch {
+            setStatus({ text: 'Could not copy here. Select the text and copy it.', ok: false, from });
+        }
+    }, [onCopy]);
+    const context = useMemo(() => ({ receipt, receiptText, copy, status, hashButtons, addHashButton }), [receipt, receiptText, copy, status, hashButtons, addHashButton]);
+    const onKeyDown = (event) => {
+        if (resolveReceiptKey(event.nativeEvent, event.target) !== 'copy-hash')
+            return;
+        event.preventDefault();
+        event.stopPropagation(); // Enter and y are not for the page's shortcuts while a receipt is focused
+        void copy(receipt.resultHash, 'Result hash', 'key');
+    };
+    return (_jsx(Context.Provider, { value: context, children: _jsx("section", { className: className, "aria-label": label, "data-synthetic": receipt.synthetic ? '' : undefined, "data-verdict": receiptVerdict(receipt), onKeyDown: onKeyDown, children: children }) }));
+}
+/** One labelled fact: a `<dt>` and a `<dd>` for a `<dl>`. */
+function Field({ label, children }) {
+    return (_jsxs(_Fragment, { children: [_jsx("dt", { children: label }), _jsx("dd", { children: children })] }));
+}
+/** A digest as recorded, in a focusable `<code>` so a keyboard user can land on it and press Enter or `y`. */
+function Hash({ of, className }) {
+    const { receipt } = useReceipt('Hash');
+    return _jsx("code", { className: className, "data-mt-numeric": "", tabIndex: 0, children: receiptHash(receipt, of) });
+}
+/**
+ * A button that copies the whole receipt (or just the result hash), then says whether it worked. Only the button that
+ * copied shows the status; a copy by Enter or y shows under the hash button, or the receipt button when there is none.
+ */
+function CopyButton({ what = 'receipt', className, statusClassName, children }) {
+    const { receipt, receiptText, copy, status, hashButtons, addHashButton } = useReceipt('CopyButton');
+    useEffect(() => (what === 'hash' ? addHashButton() : undefined), [what, addHashButton]);
+    const shown = status !== null && (status.from === what || (status.from === 'key' && (what === 'hash' || hashButtons === 0))) ? status : null;
+    return (_jsxs(_Fragment, { children: [_jsx("button", { type: "button", className: className, onClick: () => void (what === 'hash' ? copy(receipt.resultHash, 'Result hash', 'hash') : copy(receiptText, 'Receipt', 'receipt')), children: children ?? (what === 'hash' ? 'Copy result hash' : 'Copy receipt') }), _jsx(Notice, { as: "span", kind: shown === null ? 'info' : shown.ok ? 'ok' : 'error', className: statusClassName, children: shown?.text ?? '' })] }));
+}
+/** The line that must travel with a copy of non-synthetic data; nothing when there is none. */
+function ShareNote({ className }) {
+    const { receipt } = useReceipt('ShareNote');
+    if (!receipt.shareNote)
+        return null;
+    return _jsx("p", { className: className, children: receipt.shareNote });
+}
+/** Whether replaying from the start gave the same result, in words. Tokens.css colours a mismatch. */
+function Verdict({ className, matchText = 'Same two states and the same result hash.', mismatchText = 'Did not reproduce the same result.' }) {
+    const { receipt } = useReceipt('Verdict');
+    const verdict = receiptVerdict(receipt);
+    return _jsx("span", { className: className, "data-mt": "", "data-verdict": verdict, children: verdict === 'match' ? matchText : mismatchText });
+}
+export { Root, Field, Hash, CopyButton, ShareNote, Verdict };

package/dist/Scrubber.d.ts

@@ -0,0 +1,9 @@
+import { Root, Track, Thumb, Mark } from './ScrubberParts.js';
+export * from './ScrubberParts.js';
+export declare const Scrubber: {
+    Root: typeof Root;
+    Track: typeof Track;
+    Thumb: typeof Thumb;
+    Mark: typeof Mark;
+};
+//# sourceMappingURL=Scrubber.d.ts.map

package/dist/Scrubber.js

@@ -0,0 +1,5 @@
+import { Root, Track, Thumb, Mark } from './ScrubberParts.js';
+// The parts live in ScrubberParts.js (a client module). The namespace object is built here, outside it, so a server
+// component can write `Scrubber.Root`: a property of an object exported from a client module is not reachable there.
+export * from './ScrubberParts.js';
+export const Scrubber = { Root, Track, Thumb, Mark };

package/dist/ScrubberParts.d.ts

@@ -0,0 +1,74 @@
+import { type KeyboardEvent, type PointerEvent, type ReactNode } from 'react';
+/**
+ * Scrubber as parts: Root, Track, Thumb, Mark. Headless: the parts render the elements the evidence
+ * ruler always did, add `data-state` / `data-disabled`, and work in fractions of the track. The host owns what a
+ * fraction means (a place in its session), the copy, and the look.
+ *
+ * Root renders no DOM. It owns the preview while a pointer is down, so `useScrubber()` gives a readout the live
+ * fraction; nothing is committed until release, and then exactly once through `onCommit`.
+ */
+interface ScrubberContext {
+    /** Where the thumb is drawn: the preview while dragging, else the committed fraction. */
+    fraction: number;
+    committedFraction: number;
+    dragging: boolean;
+    loading: boolean;
+    trackHandlers: {
+        onPointerDown: (event: PointerEvent<HTMLElement>) => void;
+        onPointerMove: (event: PointerEvent<HTMLElement>) => void;
+        onPointerUp: (event: PointerEvent<HTMLElement>) => void;
+        onPointerCancel: (event: PointerEvent<HTMLElement>) => void;
+    };
+    onThumbKeyDown: (event: KeyboardEvent<HTMLElement>) => void;
+}
+/** The live scrub state, for a readout that must follow the preview. Throws a plain message outside a `Scrubber.Root`. */
+export declare function useScrubber(): Pick<ScrubberContext, 'fraction' | 'committedFraction' | 'dragging' | 'loading'>;
+export interface ScrubberRootProps {
+    /** Where the host's cursor sits on the track, 0 to 1. */
+    fraction: number;
+    /** Another navigation is running: a new scrub does not start, keys do nothing, and a release does not commit. */
+    loading?: boolean;
+    onBeginScrub?: () => void;
+    onEndScrub?: () => void;
+    /** A release (or Home, End, PageUp, PageDown) resolved to this fraction. Called once per gesture. */
+    onCommit: (fraction: number) => void;
+    /** An arrow key: step one event in this direction. The host decides what "one event" is. */
+    onStep: (direction: -1 | 1) => void;
+    children?: ReactNode;
+}
+declare function Root({ fraction: committedInput, loading, onBeginScrub, onEndScrub, onCommit, onStep, children }: ScrubberRootProps): import("react").JSX.Element;
+/** The pressable area. Pointer handlers live here; marks and the thumb go inside it. */
+declare function Track({ className, children }: {
+    className?: string;
+    children?: ReactNode;
+}): import("react").JSX.Element;
+export interface ScrubberThumbProps {
+    className?: string;
+    /** Accessible name. */
+    label?: string;
+    /** What the position means in words (the host's readout); announced with the value. */
+    valueText?: string;
+    /** Ids of elements that describe the thumb, such as the first few gap marks. */
+    describedBy?: string;
+}
+/** The one tab stop: `role="slider"`, positioned at the live fraction. Arrows step, Home/End/PageUp/PageDown jump. */
+declare function Thumb({ className, label, valueText, describedBy }: ScrubberThumbProps): import("react").JSX.Element;
+export interface ScrubberMarkProps {
+    /** Left edge on the track, 0 to 1. */
+    at: number;
+    /** Width on the track, 0 to 1; leave out for a point. */
+    span?: number;
+    /** Accessible name; the mark is an image, not a control, and never a tab stop. */
+    label: string;
+    /** What kind of mark: lets a host style gaps and checkpoints apart. */
+    kind?: string;
+    title?: string;
+    /** `-1` makes the mark focusable by pointer but never a tab stop; leave out for a plain image. */
+    tabIndex?: -1;
+    id?: string;
+    className?: string;
+}
+/** A position on the track that informs but cannot be activated (a declared gap, a verified checkpoint). */
+declare function Mark({ at, span, label, kind, title, tabIndex, id, className }: ScrubberMarkProps): import("react").JSX.Element;
+export { Root, Track, Thumb, Mark };
+//# sourceMappingURL=ScrubberParts.d.ts.map