insomni-plot 0.1.0-alpha.0

package/src/stats/rolling-window.test.ts

@@ -0,0 +1,237 @@
+import { describe, expect, test } from "vite-plus/test";
+
+import { rollingWindow } from "./rolling-window.ts";
+
+interface Row {
+  t: number;
+  v: number;
+  ok?: boolean;
+}
+
+function rows(values: readonly number[], xs?: readonly number[]): Row[] {
+  return values.map((v, i) => ({ t: xs ? xs[i]! : i, v }));
+}
+
+describe("rollingWindow", () => {
+  test("window of 1 (count) is identity for mean", () => {
+    const data = rows([1, 4, 2, 5, 3]);
+    const out = rollingWindow(data, {
+      x: (d) => d.t,
+      y: (d) => d.v,
+      window: 1,
+    });
+    expect(out).toHaveLength(5);
+    for (const p of out) {
+      expect(p.y).toBeCloseTo(data[p.sourceIndex]!.v, 9);
+      expect(p.count).toBe(1);
+    }
+  });
+
+  test("window of 0 (count) coerces to 1 → identity for mean", () => {
+    const data = rows([10, 20, 30, 40]);
+    const out = rollingWindow(data, {
+      x: (d) => d.t,
+      y: (d) => d.v,
+      window: 0,
+    });
+    expect(out.map((p) => p.y)).toEqual([10, 20, 30, 40]);
+  });
+
+  test("window ≥ data extent (domain) collapses to a single flat value", () => {
+    const data = rows([1, 2, 3, 4, 5]);
+    const out = rollingWindow(data, {
+      x: (d) => d.t,
+      y: (d) => d.v,
+      window: { value: 1_000_000, unit: "domain" },
+      statistic: "mean",
+    });
+    const mean = (1 + 2 + 3 + 4 + 5) / 5;
+    for (const p of out) expect(p.y).toBeCloseTo(mean, 9);
+    // Every window saw all 5 points.
+    expect(out.every((p) => p.count === 5)).toBe(true);
+  });
+
+  test("centered domain window includes neighbors within ±value/2", () => {
+    // xs = 0..9 step 1. 3-day window → ±1.5 → 3-wide.
+    const data = rows([0, 1, 2, 3, 4, 5, 6, 7, 8, 9]);
+    const out = rollingWindow(data, {
+      x: (d) => d.t,
+      y: (d) => d.v,
+      window: { value: 3, unit: "domain" },
+      statistic: "mean",
+    });
+    // Interior point at t=4: window contains v=3,4,5 → mean 4.
+    expect(out[4]!.y).toBeCloseTo(4, 9);
+    expect(out[4]!.count).toBe(3);
+    // Edge point at t=0: window contains v=0,1 only → mean 0.5.
+    expect(out[0]!.y).toBeCloseTo(0.5, 9);
+    expect(out[0]!.count).toBe(2);
+  });
+
+  test("filter excludes points from both window contents and output series", () => {
+    const data: Row[] = [
+      { t: 0, v: 10, ok: true },
+      { t: 1, v: 100, ok: false }, // excluded
+      { t: 2, v: 20, ok: true },
+      { t: 3, v: 999, ok: false }, // excluded
+      { t: 4, v: 30, ok: true },
+    ];
+    const out = rollingWindow(data, {
+      x: (d) => d.t,
+      y: (d) => d.v,
+      window: { value: 10_000, unit: "domain" },
+      statistic: "mean",
+      filter: (d) => d.ok === true,
+    });
+    // Only 3 accepted rows emitted.
+    expect(out).toHaveLength(3);
+    // Mean is over {10, 20, 30} = 20 — filtered values not in window either.
+    for (const p of out) expect(p.y).toBeCloseTo(20, 9);
+    // sourceIndex points back to accepted rows only.
+    expect(out.map((p) => p.sourceIndex).sort((a, b) => a - b)).toEqual([0, 2, 4]);
+  });
+
+  test("Date-typed x axis is coerced to millis and produces a numeric output x", () => {
+    const start = new Date("2025-01-01T00:00:00Z").getTime();
+    const day = 24 * 3600_000;
+    const data = [
+      { t: new Date(start), v: 1 },
+      { t: new Date(start + day), v: 2 },
+      { t: new Date(start + 2 * day), v: 3 },
+    ];
+    const out = rollingWindow(data, {
+      x: (d) => d.t,
+      y: (d) => d.v,
+      window: { value: day, unit: "domain" },
+      statistic: "mean",
+    });
+    expect(out).toHaveLength(3);
+    expect(typeof out[0]!.x).toBe("number");
+    expect(out[0]!.x).toBe(start);
+    expect(out[2]!.x).toBe(start + 2 * day);
+  });
+
+  test("count-window picks k nearest items by axis", () => {
+    const data = rows([10, 20, 30, 40, 50]);
+    // k = 3 centered at i=2 → indices 1..3 → {20, 30, 40} → mean 30.
+    const out = rollingWindow(data, {
+      x: (d) => d.t,
+      y: (d) => d.v,
+      window: { value: 3, unit: "count" },
+      statistic: "mean",
+    });
+    expect(out[2]!.y).toBeCloseTo(30, 9);
+    expect(out[2]!.count).toBe(3);
+    // Edge i=0: clipped window is {10, 20, 30} → mean 20.
+    expect(out[0]!.y).toBeCloseTo(20, 9);
+    expect(out[0]!.count).toBe(3);
+  });
+
+  test("quantile statistic respects the requested p", () => {
+    const data = rows([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
+    const out = rollingWindow(data, {
+      x: (d) => d.t,
+      y: (d) => d.v,
+      window: { value: 1000, unit: "domain" }, // covers all
+      statistic: { kind: "quantile", p: 0.9 },
+    });
+    // 90th percentile of 1..10 (type-7) = 9.1.
+    expect(out[0]!.y).toBeCloseTo(9.1, 6);
+  });
+
+  test("stddev statistic matches sample stddev", () => {
+    const data = rows([2, 4, 4, 4, 5, 5, 7, 9]);
+    const out = rollingWindow(data, {
+      x: (d) => d.t,
+      y: (d) => d.v,
+      window: { value: 1000, unit: "domain" },
+      statistic: "stddev",
+    });
+    // Sample stddev of [2,4,4,4,5,5,7,9] ≈ 2.138.
+    expect(out[0]!.y).toBeCloseTo(2.138, 2);
+  });
+
+  test("custom statistic function receives window values and items", () => {
+    const data = rows([1, 2, 3, 4, 5]);
+    let lastN = -1;
+    const out = rollingWindow(data, {
+      x: (d) => d.t,
+      y: (d) => d.v,
+      window: 3,
+      statistic: (values, items) => {
+        lastN = items.length;
+        // Custom: range = max - min.
+        let lo = Infinity;
+        let hi = -Infinity;
+        for (const v of values) {
+          if (v < lo) lo = v;
+          if (v > hi) hi = v;
+        }
+        return hi - lo;
+      },
+    });
+    expect(lastN).toBeGreaterThan(0);
+    // Interior 3-window over consecutive integers → range 2.
+    expect(out[2]!.y).toBe(2);
+  });
+
+  test("axis='y' slides on y and aggregates x", () => {
+    // Same y values, distinct x — rolling over y should pull adjacent x's.
+    const data = [
+      { t: 100, v: 1 },
+      { t: 200, v: 2 },
+      { t: 300, v: 3 },
+      { t: 400, v: 4 },
+    ];
+    const out = rollingWindow(data, {
+      x: (d) => d.t,
+      y: (d) => d.v,
+      window: 3,
+      statistic: "mean",
+      axis: "y",
+    });
+    // Sorted by y already. Interior point v=2: window over y={1,2,3} → mean(x)=200.
+    const interior = out.find((p) => p.y === 2)!;
+    expect(interior).toBeDefined();
+    expect(interior.x).toBeCloseTo(200, 6);
+  });
+
+  test("output is sorted by slide axis (x by default)", () => {
+    // Unsorted input.
+    const data = rows([5, 1, 3, 2, 4], [50, 10, 30, 20, 40]);
+    const out = rollingWindow(data, {
+      x: (d) => d.t,
+      y: (d) => d.v,
+      window: 1,
+    });
+    const xs = out.map((p) => p.x);
+    for (let i = 1; i < xs.length; i++) {
+      expect(xs[i]!).toBeGreaterThanOrEqual(xs[i - 1]!);
+    }
+  });
+
+  test("non-finite x or y rows are dropped", () => {
+    const data: Row[] = [
+      { t: 0, v: 1 },
+      { t: Number.NaN, v: 2 },
+      { t: 2, v: Number.POSITIVE_INFINITY },
+      { t: 3, v: 4 },
+    ];
+    const out = rollingWindow(data, {
+      x: (d) => d.t,
+      y: (d) => d.v,
+      window: 1,
+    });
+    expect(out).toHaveLength(2);
+    expect(out.map((p) => p.sourceIndex).sort((a, b) => a - b)).toEqual([0, 3]);
+  });
+
+  test("empty input → empty output", () => {
+    const out = rollingWindow([], {
+      x: (d: Row) => d.t,
+      y: (d: Row) => d.v,
+      window: 5,
+    });
+    expect(out).toEqual([]);
+  });
+});

package/src/stats/rolling-window.ts

@@ -0,0 +1,256 @@
+// ---------------------------------------------------------------------------
+// rollingWindow — sliding-window statistic over an ordered numeric series
+// ---------------------------------------------------------------------------
+// Generic time-series / ordered-domain transform. The output is a new series
+// of `{ x, y, sourceIndex, count }` points that can be fed straight into a
+// `lineMark` / `pointMark` / `areaMark` to render a moving statistic
+// (rolling mean, median, stddev, quantile, …) on top of the raw geom.
+//
+// Composition example:
+//   const smoothed = rollingWindow(rows, {
+//     x: (d) => d.ts,
+//     y: (d) => d.weightKg,
+//     window: { value: 7 * 24 * 3600_000, unit: 'domain' },
+//     statistic: 'mean',
+//     filter: (d) => d.accepted,
+//   });
+//   lineMark({ data: smoothed, x: (d) => d.x, y: (d) => d.y, curve: 'basis' });
+//
+// The transform is pure: callers re-run it when the `window` option changes.
+// The chart doesn't rebuild scales/axes — only the dependent mark's data
+// rebinds — so changing window is cheap from the consumer's perspective.
+
+import { quantile } from "./index.ts";
+
+export type RollingStatisticKind = "mean" | "median" | "min" | "max" | "sum" | "stddev";
+
+/**
+ * Statistic to compute over each window. Strings cover the common cases;
+ * `{ kind: 'quantile', p }` picks an arbitrary quantile (0..1); a function
+ * receives the windowed `(values, items)` and returns any scalar — use it for
+ * custom stats (mode, trimmed mean, sign of slope, …).
+ */
+export type RollingStatistic<T> =
+  | RollingStatisticKind
+  | { kind: "quantile"; p: number }
+  | ((values: readonly number[], items: readonly T[]) => number);
+
+/**
+ * Window size.
+ *
+ * - A bare number is interpreted as `unit: 'count'` (k nearest items by axis
+ *   value, including self). Most predictable across axis types.
+ * - `{ value, unit: 'domain' }` — sliding window of `value` data-axis units,
+ *   centered on the current item. For a time axis pass milliseconds (e.g.
+ *   `7 * 24 * 3_600_000` for a 7-day window). For a numeric axis the value is
+ *   in the axis's own units.
+ * - `{ value, unit: 'count' }` — explicit count-window form.
+ */
+export type RollingWindow = number | { value: number; unit: "domain" | "count" };
+
+export type RollingAxis = "x" | "y";
+
+export interface RollingWindowOptions<T> {
+  x: (datum: T, index: number) => number | Date;
+  y: (datum: T, index: number) => number;
+  window: RollingWindow;
+  /** Default `"mean"`. */
+  statistic?: RollingStatistic<T>;
+  /**
+   * Points failing the filter are excluded from every window *and* not
+   * emitted on the output series — they vanish from both the aggregation
+   * and the line that connects the results.
+   */
+  filter?: (datum: T, index: number) => boolean;
+  /**
+   * Axis the window slides along. Default `"x"` (slide on x, aggregate y);
+   * `"y"` flips (slide on y, aggregate x). Output is sorted by the slide
+   * axis so a `lineMark` connecting the points draws monotonically.
+   */
+  axis?: RollingAxis;
+}
+
+export interface RollingPoint {
+  x: number;
+  y: number;
+  /** Index into the original input `data` array. */
+  sourceIndex: number;
+  /** Number of points (after filter) that fell in this window. */
+  count: number;
+}
+
+interface PreparedItem<T> {
+  axisVal: number;
+  otherVal: number;
+  item: T;
+  sourceIndex: number;
+}
+
+function coerceNumeric(value: number | Date): number {
+  return value instanceof Date ? value.getTime() : value;
+}
+
+function resolveWindow(window: RollingWindow): { value: number; unit: "domain" | "count" } {
+  if (typeof window === "number") return { value: window, unit: "count" };
+  return { value: window.value, unit: window.unit };
+}
+
+function computeStat<T>(
+  statistic: RollingStatistic<T>,
+  values: readonly number[],
+  items: readonly T[],
+): number {
+  if (typeof statistic === "function") return statistic(values, items);
+  const n = values.length;
+  if (n === 0) return Number.NaN;
+
+  if (typeof statistic === "object") {
+    // Quantile — only object variant today.
+    const sorted = values.slice().sort((a, b) => a - b);
+    return quantile(sorted, statistic.p);
+  }
+
+  switch (statistic) {
+    case "mean": {
+      let s = 0;
+      for (const v of values) s += v;
+      return s / n;
+    }
+    case "sum": {
+      let s = 0;
+      for (const v of values) s += v;
+      return s;
+    }
+    case "min": {
+      let m = values[0]!;
+      for (let i = 1; i < n; i++) {
+        const v = values[i]!;
+        if (v < m) m = v;
+      }
+      return m;
+    }
+    case "max": {
+      let m = values[0]!;
+      for (let i = 1; i < n; i++) {
+        const v = values[i]!;
+        if (v > m) m = v;
+      }
+      return m;
+    }
+    case "median": {
+      const sorted = values.slice().sort((a, b) => a - b);
+      return quantile(sorted, 0.5);
+    }
+    case "stddev": {
+      if (n < 2) return 0;
+      let s = 0;
+      for (const v of values) s += v;
+      const mean = s / n;
+      let sq = 0;
+      for (const v of values) {
+        const d = v - mean;
+        sq += d * d;
+      }
+      // Sample stddev (Bessel-corrected). Matches the convention used by
+      // `stats/index.ts`'s internal helpers.
+      return Math.sqrt(sq / (n - 1));
+    }
+  }
+}
+
+export function rollingWindow<T>(
+  data: readonly T[],
+  options: RollingWindowOptions<T>,
+): RollingPoint[] {
+  const axis: RollingAxis = options.axis ?? "x";
+  const statistic: RollingStatistic<T> = options.statistic ?? "mean";
+  const window = resolveWindow(options.window);
+  const filter = options.filter;
+  const xAcc = options.x;
+  const yAcc = options.y;
+
+  const prepared: PreparedItem<T>[] = [];
+  for (let i = 0; i < data.length; i++) {
+    const datum = data[i]!;
+    if (filter && !filter(datum, i)) continue;
+    const xv = coerceNumeric(xAcc(datum, i));
+    const yv = yAcc(datum, i);
+    if (!Number.isFinite(xv) || !Number.isFinite(yv)) continue;
+    const axisVal = axis === "x" ? xv : yv;
+    const otherVal = axis === "x" ? yv : xv;
+    prepared.push({ axisVal, otherVal, item: datum, sourceIndex: i });
+  }
+
+  const n = prepared.length;
+  if (n === 0) return [];
+
+  prepared.sort((a, b) => a.axisVal - b.axisVal);
+
+  const out: RollingPoint[] = Array.from({ length: n });
+  const tmpValues: number[] = [];
+  const tmpItems: T[] = [];
+
+  if (window.unit === "domain") {
+    // Centered domain window: include j where |axisVal[j] - axisVal[i]| ≤ half.
+    const half = Math.max(0, window.value / 2);
+    let lo = 0;
+    let hi = 0;
+    for (let i = 0; i < n; i++) {
+      const center = prepared[i]!.axisVal;
+      while (lo < n && prepared[lo]!.axisVal < center - half) lo++;
+      if (hi < lo) hi = lo;
+      while (hi < n && prepared[hi]!.axisVal <= center + half) hi++;
+      tmpValues.length = 0;
+      tmpItems.length = 0;
+      for (let j = lo; j < hi; j++) {
+        tmpValues.push(prepared[j]!.otherVal);
+        tmpItems.push(prepared[j]!.item);
+      }
+      const statVal = computeStat(statistic, tmpValues, tmpItems);
+      const cur = prepared[i]!;
+      const outX = axis === "x" ? cur.axisVal : statVal;
+      const outY = axis === "x" ? statVal : cur.axisVal;
+      out[i] = {
+        x: outX,
+        y: outY,
+        sourceIndex: cur.sourceIndex,
+        count: tmpValues.length,
+      };
+    }
+  } else {
+    // Count window: k nearest items by axis distance, including self.
+    const k = Math.max(1, Math.floor(window.value));
+    for (let i = 0; i < n; i++) {
+      // Center k-window on i with two-sided clipping at the array edges.
+      let lo = i - Math.floor((k - 1) / 2);
+      let hi = lo + k;
+      if (lo < 0) {
+        hi -= lo;
+        lo = 0;
+      }
+      if (hi > n) {
+        const overflow = hi - n;
+        lo = Math.max(0, lo - overflow);
+        hi = n;
+      }
+      tmpValues.length = 0;
+      tmpItems.length = 0;
+      for (let j = lo; j < hi; j++) {
+        tmpValues.push(prepared[j]!.otherVal);
+        tmpItems.push(prepared[j]!.item);
+      }
+      const statVal = computeStat(statistic, tmpValues, tmpItems);
+      const cur = prepared[i]!;
+      const outX = axis === "x" ? cur.axisVal : statVal;
+      const outY = axis === "x" ? statVal : cur.axisVal;
+      out[i] = {
+        x: outX,
+        y: outY,
+        sourceIndex: cur.sourceIndex,
+        count: tmpValues.length,
+      };
+    }
+  }
+
+  return out;
+}

package/src/test-setup.ts

@@ -0,0 +1,19 @@
+// Test setup: stub window.matchMedia before any module (including insomni)
+// evaluates it. jsdom does not implement matchMedia, but insomni/src/config.ts
+// calls it at module-evaluation time to detect coarse-pointer devices.
+if (typeof window !== "undefined" && !window.matchMedia) {
+  Object.defineProperty(window, "matchMedia", {
+    writable: true,
+    configurable: true,
+    value: (_query: string) => ({
+      matches: false,
+      media: _query,
+      onchange: null,
+      addListener: () => {},
+      removeListener: () => {},
+      addEventListener: () => {},
+      removeEventListener: () => {},
+      dispatchEvent: () => false,
+    }),
+  });
+}

package/src/viewport/axis-state.d.ts

@@ -0,0 +1,72 @@
+import { type AxisScale, type BandScale, type BandScaleOptions, type ContinuousScale, type DateDomain, type NumericDomain, type TimeScale } from "../scales.ts";
+export interface ContinuousAxisConfig {
+    type: "linear" | "log" | "sqrt";
+    domain: NumericDomain;
+}
+export interface TimeAxisConfig {
+    type: "time";
+    domain: DateDomain;
+}
+export interface BandAxisConfig<T = unknown> extends BandScaleOptions {
+    type: "band";
+    domain: readonly T[];
+}
+export type ViewportAxisConfig<T = unknown> = ContinuousAxisConfig | TimeAxisConfig | BandAxisConfig<T>;
+export type VisibleDomainInput = readonly [number, number] | readonly [Date, Date];
+interface Transform {
+    to: (v: number) => number;
+    from: (v: number) => number;
+}
+export interface ContinuousAxisState {
+    kind: "continuous";
+    type: "linear" | "log" | "sqrt" | "time";
+    transform: Transform;
+    t0: number;
+    t1: number;
+    baseT0: number;
+    baseT1: number;
+    r0: number;
+    r1: number;
+    /**
+     * Memoized scale instance for the current (t0, t1, r0, r1, type, transform)
+     * tuple. Null after construction and after any mutation; populated lazily by
+     * `buildScale` / `applyAxis`. Pan/zoom/setVisibleDomain/clampAxisToBase/
+     * resetAxis/setAxisRange/copyContinuous all clear it via `invalidateScale`.
+     */
+    scaleCache: ContinuousScale | TimeScale | null;
+}
+export interface BandAxisState<T> {
+    kind: "band";
+    domain: readonly T[];
+    options: BandScaleOptions;
+    r0: number;
+    r1: number;
+    /** See `ContinuousAxisState.scaleCache`. */
+    scaleCache: BandScale<T> | null;
+}
+export type AxisState<T> = ContinuousAxisState | BandAxisState<T>;
+export declare function createAxisState<T>(config: ViewportAxisConfig<T>, r0: number, r1: number): AxisState<T>;
+export declare function buildScale<T>(state: AxisState<T>): AxisScale<T>;
+export declare function panAxis(axis: AxisState<unknown>, dPx: number): boolean;
+export declare function setAxisVisibleDomain(axis: AxisState<unknown>, domain: VisibleDomainInput, minZoom: number, maxZoom: number): boolean;
+export declare function zoomAxis(axis: AxisState<unknown>, anchorPx: number, factor: number, minZoom: number, maxZoom: number): boolean;
+export declare function clampAxisToBase(axis: AxisState<unknown>, overshoot: number, drift: number): boolean;
+export declare function setAxisRange(axis: AxisState<unknown>, r0: number, r1: number): void;
+export declare function resetAxis(axis: AxisState<unknown>): boolean;
+export declare function readVisibleDomain(axis: AxisState<unknown>): unknown;
+export declare function invertAxis(axis: AxisState<unknown>, localPx: number): unknown;
+export declare function applyAxis(axis: AxisState<unknown>, value: unknown): number;
+export interface LinearAxisFn {
+    readonly t0: number;
+    readonly t1: number;
+    readonly r0: number;
+    readonly r1: number;
+}
+/**
+ * If the axis is a linear, continuous, non-time axis, return its current
+ * (t0, t1, r0, r1) tuple. Otherwise return null. Used by callers that want
+ * to hoist the linear projection out of a hot loop.
+ */
+export declare function asLinearAxisFn(axis: AxisState<unknown>): LinearAxisFn | null;
+export declare function copyContinuous(source: AxisState<unknown>, target: AxisState<unknown>): void;
+export {};