@matchstick-trading/primitives 0.0.10

package/dist/core/scrubber-gesture.d.ts

@@ -0,0 +1,66 @@
+/**
+ * The scrub gesture as plain data in, plain data out. Everything here works on a fraction of the
+ * track, 0 to 1, and knows nothing about time, sequences or events: the host turns a committed fraction into a
+ * place in its session. That keeps the rules testable without a DOM and keeps the Scrubber usable on any ruler.
+ */
+/** Clamp a track fraction to [0, 1]; a value that is not a finite number becomes 0. */
+export declare function clampFraction(value: number): number;
+export type ScrubGestureEvent = {
+    type: 'down';
+    fraction: number;
+} | {
+    type: 'move';
+    fraction: number;
+}
+/**
+ * `fraction` is where the release itself landed: pointer input coalesces, so the release can be measurably ahead
+ * of the last move. When it is left out the last previewed fraction is used. `loading` is whether the host is
+ * already busy with another navigation at the moment of release, passed in as data so the decision lives here.
+ */
+ | {
+    type: 'up';
+    fraction?: number;
+    loading?: boolean;
+} | {
+    type: 'cancel';
+};
+export interface ScrubGestureResult {
+    /** The next preview fraction; null when no drag is in progress. */
+    dragFraction: number | null;
+    /** Non-null exactly once per gesture: the fraction to commit when the pointer is released. */
+    commit: number | null;
+    begin: boolean;
+    end: boolean;
+}
+/**
+ * Moving only ever changes the preview; only a release, with a drag in progress, commits, and it commits once.
+ * A release while the host is loading ends the gesture without committing, so two navigations are never in
+ * flight at once. A cancelled gesture (the pointer left the window) never commits.
+ */
+export declare function reduceScrubGesture(event: ScrubGestureEvent, dragFraction: number | null): ScrubGestureResult;
+/** The two pointer fields a scrub gate reads, named so the gates are testable without a DOM event. */
+export interface ScrubPointer {
+    /** 0 is the primary button (left, or a pen or touch contact). */
+    button: number;
+    /** False for any additional simultaneous contact in a multi-touch gesture. */
+    isPrimary: boolean;
+}
+/** Whether a pointer-down may start a scrub. A right-click, middle-click or second finger is left to the browser. */
+export declare function isPrimaryScrubPointer(event: ScrubPointer): boolean;
+/** Whether a move, up or cancel belongs to the pointer that began the drag now in progress (a second contact cannot hijack it). */
+export declare function isActiveScrubPointer(pointerId: number, activePointerId: number | null): boolean;
+/** Where a pointer sits along a track, as a fraction. A track with no width reads as 0. */
+export declare function fractionFromPointer(clientX: number, left: number, width: number): number;
+export type ScrubKeyAction = {
+    type: 'step';
+    direction: -1 | 1;
+} | {
+    type: 'jump';
+    fraction: number;
+};
+/**
+ * Arrow keys step one event, which only the host can define, so they resolve to a direction. Home and End jump to
+ * the ends; PageUp and PageDown move 10% of the track. Any other key is left alone (null).
+ */
+export declare function resolveScrubKey(key: string, currentFraction: number): ScrubKeyAction | null;
+//# sourceMappingURL=scrubber-gesture.d.ts.map

package/dist/core/scrubber-gesture.js

@@ -0,0 +1,69 @@
+/**
+ * The scrub gesture as plain data in, plain data out. Everything here works on a fraction of the
+ * track, 0 to 1, and knows nothing about time, sequences or events: the host turns a committed fraction into a
+ * place in its session. That keeps the rules testable without a DOM and keeps the Scrubber usable on any ruler.
+ */
+/** Clamp a track fraction to [0, 1]; a value that is not a finite number becomes 0. */
+export function clampFraction(value) {
+    if (!Number.isFinite(value))
+        return 0;
+    return value < 0 ? 0 : value > 1 ? 1 : value;
+}
+const IDLE = { commit: null, begin: false, end: false };
+/**
+ * Moving only ever changes the preview; only a release, with a drag in progress, commits, and it commits once.
+ * A release while the host is loading ends the gesture without committing, so two navigations are never in
+ * flight at once. A cancelled gesture (the pointer left the window) never commits.
+ */
+export function reduceScrubGesture(event, dragFraction) {
+    switch (event.type) {
+        case 'down':
+            return { dragFraction: clampFraction(event.fraction), commit: null, begin: true, end: false };
+        case 'move':
+            return dragFraction === null ? { dragFraction, ...IDLE } : { dragFraction: clampFraction(event.fraction), ...IDLE };
+        case 'up':
+            if (dragFraction === null)
+                return { dragFraction: null, ...IDLE };
+            if (event.loading)
+                return { dragFraction: null, commit: null, begin: false, end: true };
+            return { dragFraction: null, commit: clampFraction(event.fraction ?? dragFraction), begin: false, end: true };
+        case 'cancel':
+            return dragFraction === null ? { dragFraction: null, ...IDLE } : { dragFraction: null, commit: null, begin: false, end: true };
+    }
+}
+/** Whether a pointer-down may start a scrub. A right-click, middle-click or second finger is left to the browser. */
+export function isPrimaryScrubPointer(event) {
+    return event.button === 0 && event.isPrimary;
+}
+/** Whether a move, up or cancel belongs to the pointer that began the drag now in progress (a second contact cannot hijack it). */
+export function isActiveScrubPointer(pointerId, activePointerId) {
+    return activePointerId !== null && pointerId === activePointerId;
+}
+/** Where a pointer sits along a track, as a fraction. A track with no width reads as 0. */
+export function fractionFromPointer(clientX, left, width) {
+    if (!(width > 0))
+        return 0;
+    return clampFraction((clientX - left) / width);
+}
+/**
+ * Arrow keys step one event, which only the host can define, so they resolve to a direction. Home and End jump to
+ * the ends; PageUp and PageDown move 10% of the track. Any other key is left alone (null).
+ */
+export function resolveScrubKey(key, currentFraction) {
+    switch (key) {
+        case 'ArrowLeft':
+            return { type: 'step', direction: -1 };
+        case 'ArrowRight':
+            return { type: 'step', direction: 1 };
+        case 'Home':
+            return { type: 'jump', fraction: 0 };
+        case 'End':
+            return { type: 'jump', fraction: 1 };
+        case 'PageUp':
+            return { type: 'jump', fraction: clampFraction(currentFraction + 0.1) };
+        case 'PageDown':
+            return { type: 'jump', fraction: clampFraction(currentFraction - 0.1) };
+        default:
+            return null;
+    }
+}

package/dist/core/selection.d.ts

@@ -0,0 +1,24 @@
+/** What is selected on a chart, or null for nothing. */
+export type ChartSelection = {
+    kind: 'drawing' | 'series' | 'study';
+    id: string;
+} | null;
+/** True when two selections point at the same thing. */
+export declare function sameSelection(a: ChartSelection, b: ChartSelection): boolean;
+/**
+ * A tap on clear chart (no drawing, no study under it). With something selected, it only puts the selection away. With
+ * nothing selected it selects the series when one is mounted (`seriesId`), and otherwise changes nothing. Returns the
+ * same value when nothing changes.
+ */
+export declare function selectionAfterClearTap(selection: ChartSelection, seriesId: string | null): ChartSelection;
+/** A tap on something selectable (a study line) selects it, whatever was selected before. */
+export declare function selectionAfterTap(selection: ChartSelection, hit: ChartSelection, seriesId: string | null): ChartSelection;
+/** Escape clears whatever is selected. */
+export declare function selectionAfterEscape(selection: ChartSelection): ChartSelection;
+/** The names a selection can be described with, per kind and id. A missing name falls back to the id. */
+export type SelectionNames = {
+    [K in 'drawing' | 'series' | 'study']?: Readonly<Record<string, string>>;
+};
+/** The words for a live region: what is selected now, or that nothing is. */
+export declare function describeSelection(selection: ChartSelection, names?: SelectionNames): string;
+//# sourceMappingURL=selection.d.ts.map

package/dist/core/selection.js

@@ -0,0 +1,33 @@
+// One selection for a chart: a drawing, the bar series or a study, never more than one. The rules are plain functions
+// so any framework layer (and a test) can use them.
+/** True when two selections point at the same thing. */
+export function sameSelection(a, b) {
+    return a === b || (a !== null && b !== null && a.kind === b.kind && a.id === b.id);
+}
+/**
+ * A tap on clear chart (no drawing, no study under it). With something selected, it only puts the selection away. With
+ * nothing selected it selects the series when one is mounted (`seriesId`), and otherwise changes nothing. Returns the
+ * same value when nothing changes.
+ */
+export function selectionAfterClearTap(selection, seriesId) {
+    if (selection !== null)
+        return null;
+    return seriesId !== null ? { kind: 'series', id: seriesId } : selection;
+}
+/** A tap on something selectable (a study line) selects it, whatever was selected before. */
+export function selectionAfterTap(selection, hit, seriesId) {
+    if (hit === null)
+        return selectionAfterClearTap(selection, seriesId);
+    return sameSelection(selection, hit) ? selection : hit;
+}
+/** Escape clears whatever is selected. */
+export function selectionAfterEscape(selection) {
+    return selection === null ? selection : null;
+}
+/** The words for a live region: what is selected now, or that nothing is. */
+export function describeSelection(selection, names = {}) {
+    if (selection === null)
+        return 'Selection cleared.';
+    const name = names[selection.kind]?.[selection.id] ?? selection.id;
+    return `Selected ${selection.kind}: ${name}.`;
+}

package/dist/core/series.d.ts

@@ -0,0 +1,161 @@
+/** Why a point has no number. `value` has one. */
+export type PointKind = 'value' | 'missing' | 'market-closed' | 'not-applicable' | 'halted' | 'unknown';
+/** One point on a series. `t` is ISO-8601 UTC, for example `2026-01-05T14:30:00Z`. Only `value` carries `v`. */
+export type SeriesPoint = {
+    t: string;
+    kind: 'value';
+    v: number;
+} | {
+    t: string;
+    kind: Exclude<PointKind, 'value'>;
+};
+/** Which calendar decided `market-closed`. A label: the host fills it and nothing here resolves it. */
+export interface SeriesCalendar {
+    id: string;
+    version?: string;
+    tz: string;
+}
+export interface DataSeries {
+    id: string;
+    label: string;
+    unit?: string;
+    calendar?: SeriesCalendar;
+    /** Strictly increasing in time. */
+    points: SeriesPoint[];
+}
+/** `exact`: same instant. `asof`: the latest point at or before, within `toleranceMs`. `none`: no cross-series comparison. */
+export type AlignMode = 'exact' | 'asof' | 'none';
+export interface SeriesSet {
+    schemaVersion: '0';
+    alignment: {
+        mode: AlignMode;
+        toleranceMs?: number;
+        primary: string;
+    };
+    /** Half-open `[start, end)`: a point at `end` is outside it. */
+    window?: {
+        start: string;
+        end: string;
+    };
+    series: DataSeries[];
+}
+export declare const POINT_KINDS: readonly PointKind[];
+/** One problem found at the boundary, with the path to it (`series.1.points.3.t`). */
+export interface SeriesIssue {
+    path: (string | number)[];
+    message: string;
+}
+export type SeriesValidation = {
+    ok: true;
+    value: SeriesSet;
+} | {
+    ok: false;
+    issues: SeriesIssue[];
+};
+/**
+ * Check a value at the boundary (a recorded session, an adapter's output, a hand-built set). Every problem is returned
+ * in one pass, not only the first. The input is not changed.
+ */
+export declare function validateSeriesSet(input: unknown): SeriesValidation;
+/** The outcome shape Standard Schema v1 uses, kept local so the core imports nothing. */
+type StandardResult<T> = {
+    value: T;
+    issues?: undefined;
+} | {
+    issues: ReadonlyArray<{
+        message: string;
+        path?: ReadonlyArray<string | number>;
+    }>;
+    value?: undefined;
+};
+/**
+ * `validateSeriesSet` as a Standard Schema (v1), so any validator-aware tool can run it at a boundary, for example
+ * `check(seriesSetSchema, data)` from `@fieldtest/core`. Imports nothing.
+ */
+export declare const seriesSetSchema: {
+    readonly '~standard': {
+        readonly version: 1;
+        readonly vendor: 'matchstick-primitives';
+        readonly validate: (value: unknown) => StandardResult<SeriesSet>;
+        readonly types?: {
+            readonly input: SeriesSet;
+            readonly output: SeriesSet;
+        };
+    };
+};
+/** What `report` finds. It reads and never repairs. */
+export type FindingKind = 'gap-kind-differs' | 'no-point' | 'feed-stopped' | 'unclassified';
+export interface SeriesFinding {
+    /** An ISO time, on the primary's grid for the comparison findings. */
+    t: string;
+    kind: FindingKind;
+    /** The series involved: the primary first, then the other, for a comparison. */
+    series: string[];
+    detail: string;
+}
+/**
+ * Where the series in a set disagree, read on the primary's timestamps. In order: every `unknown` point in the window
+ * (`unclassified`), a series that stops before the window ends (`feed-stopped`), then for each primary point and
+ * each other series, no point within tolerance (`no-point`) or two different kinds (`gap-kind-differs`).
+ *
+ * `not-applicable` against anything is expected (a warm-up) and is not reported. `unknown` against another gap kind
+ * cannot disagree, but `unknown` against a value does. `halted` is an ordinary kind. With mode `none` there is no
+ * comparison across series. The set is not changed; run `validateSeriesSet` first for a set from outside.
+ */
+export declare function report(set: SeriesSet): SeriesFinding[];
+/** What a series is at one bar: a number, a kind of nothing, or `no-point` when the series has no point there. */
+export type AlignedState = PointKind | 'no-point';
+export interface AlignedSeries {
+    id: string;
+    label: string;
+    /** One entry per bar; `null` for any bar without a finite value. Zero stays zero. */
+    values: Array<number | null>;
+    /** One entry per bar: why `values` is null there, or `value`. */
+    states: AlignedState[];
+}
+export interface AlignOptions {
+    mode?: AlignMode;
+    /** For `asof`: how far back a point may be and still count. Milliseconds. */
+    toleranceMs?: number;
+}
+/**
+ * Put a series on the bars' clock: for each bar time, the point at that instant (`exact`) or the latest point at or
+ * before it within the tolerance (`asof`). A bar with no point gets `null` and the state `no-point`. Nothing is carried
+ * across a gap kind and no zero is invented. `none` is read as `exact`.
+ */
+export declare function alignSeries(barTimes: readonly number[], series: DataSeries, options?: AlignOptions): AlignedSeries;
+/**
+ * Turn a value-per-bar array (a study, or anything made by position) into points on the bars' clock. A number is a
+ * value; `null`, NaN and infinity become `gapKind` (default `not-applicable`, which is what a warm-up is).
+ */
+export declare function pointsFromValues(barTimes: ReadonlyArray<number | {
+    timestamp: number;
+}>, values: ReadonlyArray<number | null | undefined>, gapKind?: Exclude<PointKind, 'value'>): SeriesPoint[];
+/** A series as a part receives it: on its own clock (`points`), or by position (`values`, the shim). */
+export interface SeriesInput {
+    id: string;
+    label: string;
+    points?: ReadonlyArray<SeriesPoint>;
+    /** Kept for now so existing code keeps drawing: one value per bar by position. It will be removed in a later version. */
+    values?: ReadonlyArray<number | null>;
+}
+export interface ResolvedSeries {
+    /** One entry per bar; `null` for none. */
+    values: ReadonlyArray<number | null>;
+    /** Why a bar has no value; absent for the position shim, which cannot say. */
+    states?: AlignedState[];
+    /** Plain sentences about what is wrong with the input, empty when nothing is. Nothing is repaired. */
+    problems: string[];
+}
+/**
+ * The values to draw for one series on these bars. `points` are placed by time (see `alignSeries`); `values` are read by
+ * position. Problems are returned in words and the series is still drawn as far as it can be: a length that does not
+ * match the bars, a series with no value on any bar, points out of time order.
+ */
+export declare function resolveSeries(barTimes: readonly number[], input: SeriesInput, options?: AlignOptions): ResolvedSeries;
+/** The ids used by more than one series, once each. */
+export declare function duplicateIds(items: ReadonlyArray<{
+    id: string;
+}>): string[];
+export {};
+//# sourceMappingURL=series.d.ts.map