insomni-plot 0.1.0-alpha.0

package/src/viewport/axis-state.ts

@@ -0,0 +1,476 @@
+// ---------------------------------------------------------------------------
+// Per-axis state machine: transform, domain endpoints, range endpoints,
+// pan/zoom math, scale rebuild. The DataViewport composes one of these per
+// axis (x, y) and orchestrates them.
+// ---------------------------------------------------------------------------
+
+import {
+  bandScale,
+  linearScale,
+  logScale,
+  logTransform,
+  logUntransform,
+  signedSqrt,
+  signedSquare,
+  sqrtScale,
+  timeScale,
+  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;
+}
+
+const LINEAR_T: Transform = { to: (v) => v, from: (v) => v };
+const LOG_T: Transform = { to: logTransform, from: logUntransform };
+const SQRT_T: Transform = { to: signedSqrt, from: signedSquare };
+
+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>;
+
+// ---------------------------------------------------------------------------
+// Construction
+// ---------------------------------------------------------------------------
+
+export function createAxisState<T>(
+  config: ViewportAxisConfig<T>,
+  r0: number,
+  r1: number,
+): AxisState<T> {
+  if (config.type === "band") {
+    const options: BandScaleOptions = {};
+    if (config.padding !== undefined) options.padding = config.padding;
+    if (config.paddingInner !== undefined) options.paddingInner = config.paddingInner;
+    if (config.paddingOuter !== undefined) options.paddingOuter = config.paddingOuter;
+    if (config.align !== undefined) options.align = config.align;
+    return {
+      kind: "band",
+      domain: [...config.domain],
+      options,
+      r0,
+      r1,
+      scaleCache: null,
+    };
+  }
+
+  const transform = pickTransform(config.type);
+  let d0: number;
+  let d1: number;
+  if (config.type === "time") {
+    d0 = config.domain[0].getTime();
+    d1 = config.domain[1].getTime();
+  } else {
+    d0 = config.domain[0];
+    d1 = config.domain[1];
+  }
+  if (config.type === "log") {
+    if (d0 === 0 || d1 === 0) {
+      throw new Error("log axis domain values must be non-zero.");
+    }
+    if (Math.sign(d0) !== Math.sign(d1)) {
+      throw new Error("log axis domain values must share the same sign.");
+    }
+  }
+
+  const t0 = transform.to(d0);
+  const t1 = transform.to(d1);
+  return {
+    kind: "continuous",
+    type: config.type,
+    transform,
+    t0,
+    t1,
+    baseT0: t0,
+    baseT1: t1,
+    r0,
+    r1,
+    scaleCache: null,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Cache helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Drop the memoized scale. Call from every mutator that touches t0/t1/r0/r1/
+ * domain/options so the next `buildScale`/`applyAxis`/`invertAxis` rebuilds.
+ * Cheap (single null write); the hot path is the cache hit, not invalidation.
+ */
+function invalidateScale(axis: AxisState<unknown>): void {
+  axis.scaleCache = null;
+}
+
+function pickTransform(type: "linear" | "log" | "sqrt" | "time"): Transform {
+  switch (type) {
+    case "linear":
+    case "time":
+      return LINEAR_T;
+    case "log":
+      return LOG_T;
+    case "sqrt":
+      return SQRT_T;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Scale rebuild
+// ---------------------------------------------------------------------------
+
+function buildContinuousScale(state: ContinuousAxisState): ContinuousScale | TimeScale {
+  const { transform, t0, t1, r0, r1, type } = state;
+  let d0 = transform.from(t0);
+  let d1 = transform.from(t1);
+
+  if (type === "log") {
+    const eps = 1e-12;
+    if (d0 <= 0) d0 = eps;
+    if (d1 <= 0) d1 = eps;
+  }
+
+  switch (type) {
+    case "linear":
+      return linearScale([d0, d1], [r0, r1]);
+    case "log":
+      return logScale([d0, d1], [r0, r1]);
+    case "sqrt":
+      return sqrtScale([d0, d1], [r0, r1]);
+    case "time":
+      return timeScale([new Date(d0), new Date(d1)], [r0, r1]);
+  }
+}
+
+function buildBandScale<T>(state: BandAxisState<T>): BandScale<T> {
+  return bandScale(state.domain, [state.r0, state.r1], state.options);
+}
+
+export function buildScale<T>(state: AxisState<T>): AxisScale<T> {
+  if (state.kind === "continuous") {
+    return getContinuousScale(state) as unknown as AxisScale<T>;
+  }
+  return getBandScale(state) as unknown as AxisScale<T>;
+}
+
+function getContinuousScale(state: ContinuousAxisState): ContinuousScale | TimeScale {
+  let cached = state.scaleCache;
+  if (cached === null) {
+    cached = buildContinuousScale(state);
+    state.scaleCache = cached;
+  }
+  return cached;
+}
+
+function getBandScale<T>(state: BandAxisState<T>): BandScale<T> {
+  let cached = state.scaleCache;
+  if (cached === null) {
+    cached = buildBandScale(state);
+    state.scaleCache = cached;
+  }
+  return cached;
+}
+
+// ---------------------------------------------------------------------------
+// Pan / zoom
+// ---------------------------------------------------------------------------
+
+export function panAxis(axis: AxisState<unknown>, dPx: number): boolean {
+  if (axis.kind !== "continuous") return false;
+  const span = axis.r1 - axis.r0;
+  if (span === 0) return false;
+  const delta = (-dPx * (axis.t1 - axis.t0)) / span;
+  if (delta === 0) return false;
+  axis.t0 += delta;
+  axis.t1 += delta;
+  invalidateScale(axis);
+  return true;
+}
+
+export function setAxisVisibleDomain(
+  axis: AxisState<unknown>,
+  domain: VisibleDomainInput,
+  minZoom: number,
+  maxZoom: number,
+): boolean {
+  if (axis.kind !== "continuous") return false;
+
+  const r0 = domain[0];
+  const r1 = domain[1];
+  const d0 = typeof r0 === "number" ? r0 : r0.getTime();
+  const d1 = typeof r1 === "number" ? r1 : r1.getTime();
+  if (!Number.isFinite(d0) || !Number.isFinite(d1)) return false;
+
+  if (axis.type === "log") {
+    if (d0 === 0 || d1 === 0) {
+      throw new Error("log axis domain values must be non-zero.");
+    }
+    if (Math.sign(d0) !== Math.sign(d1)) {
+      throw new Error("log axis domain values must share the same sign.");
+    }
+  }
+
+  const reqT0 = axis.transform.to(d0);
+  const reqT1 = axis.transform.to(d1);
+  if (!Number.isFinite(reqT0) || !Number.isFinite(reqT1)) return false;
+  if (reqT0 === reqT1) return false;
+
+  const baseSpan = axis.baseT1 - axis.baseT0;
+  if (baseSpan === 0) return false;
+
+  const reqSpan = reqT1 - reqT0;
+  const baseAbs = Math.abs(baseSpan);
+  const minAbs = baseAbs / maxZoom;
+  const maxAbs = baseAbs / minZoom;
+  const absReq = Math.abs(reqSpan);
+
+  let nextT0 = reqT0;
+  let nextT1 = reqT1;
+  if (absReq < minAbs || absReq > maxAbs) {
+    const clampedAbs = absReq < minAbs ? minAbs : maxAbs;
+    const sign = Math.sign(reqSpan) || 1;
+    const center = (reqT0 + reqT1) / 2;
+    const half = (sign * clampedAbs) / 2;
+    nextT0 = center - half;
+    nextT1 = center + half;
+  }
+
+  if (nextT0 === axis.t0 && nextT1 === axis.t1) return false;
+  axis.t0 = nextT0;
+  axis.t1 = nextT1;
+  invalidateScale(axis);
+  return true;
+}
+
+export function zoomAxis(
+  axis: AxisState<unknown>,
+  anchorPx: number,
+  factor: number,
+  minZoom: number,
+  maxZoom: number,
+): boolean {
+  if (axis.kind !== "continuous") return false;
+  if (!Number.isFinite(factor) || factor <= 0) return false;
+
+  const baseSpan = axis.baseT1 - axis.baseT0;
+  const curSpan = axis.t1 - axis.t0;
+  if (curSpan === 0 || baseSpan === 0) return false;
+
+  let newSpan = curSpan / factor;
+  const signSpan = Math.sign(baseSpan);
+  const minAbs = Math.abs(baseSpan) / maxZoom;
+  const maxAbs = Math.abs(baseSpan) / minZoom;
+  const absNew = Math.abs(newSpan);
+  if (absNew < minAbs) newSpan = signSpan * minAbs;
+  else if (absNew > maxAbs) newSpan = signSpan * maxAbs;
+
+  if (newSpan === curSpan) return false;
+
+  const range = axis.r1 - axis.r0;
+  if (range === 0) return false;
+  const anchorT = axis.t0 + ((anchorPx - axis.r0) * curSpan) / range;
+  const newT0 = anchorT - ((anchorPx - axis.r0) * newSpan) / range;
+  axis.t0 = newT0;
+  axis.t1 = newT0 + newSpan;
+  invalidateScale(axis);
+  return true;
+}
+
+// ---------------------------------------------------------------------------
+// Pan-bound clamping (per-axis)
+// ---------------------------------------------------------------------------
+
+function clampOffset(
+  s0: number,
+  V: number,
+  c0: number,
+  L: number,
+  overshoot: number,
+  drift: number,
+): number {
+  const offset = s0 - c0;
+  let lo: number;
+  let hi: number;
+  if (V < L) {
+    const m = Math.abs(overshoot) * V;
+    lo = -m;
+    hi = L - V + m;
+  } else {
+    const m = Math.abs(drift) * V;
+    lo = L - V - m;
+    hi = m;
+  }
+  if (offset < lo) return lo - offset;
+  if (offset > hi) return hi - offset;
+  return 0;
+}
+
+export function clampAxisToBase(
+  axis: AxisState<unknown>,
+  overshoot: number,
+  drift: number,
+): boolean {
+  if (axis.kind !== "continuous") return false;
+  const baseSpan = axis.baseT1 - axis.baseT0;
+  const visSpan = axis.t1 - axis.t0;
+  if (baseSpan === 0 || visSpan === 0) return false;
+  const reversed = baseSpan < 0;
+  const c0 = reversed ? axis.baseT1 : axis.baseT0;
+  const c1 = reversed ? axis.baseT0 : axis.baseT1;
+  const sLow = reversed ? axis.t1 : axis.t0;
+  const sHigh = reversed ? axis.t0 : axis.t1;
+  const L = c1 - c0;
+  const V = sHigh - sLow;
+  if (V === 0) return false;
+  const delta = clampOffset(sLow, V, c0, L, overshoot, drift);
+  if (delta === 0) return false;
+  axis.t0 += delta;
+  axis.t1 += delta;
+  invalidateScale(axis);
+  return true;
+}
+
+// ---------------------------------------------------------------------------
+// Misc accessors
+// ---------------------------------------------------------------------------
+
+export function setAxisRange(axis: AxisState<unknown>, r0: number, r1: number): void {
+  if (axis.r0 === r0 && axis.r1 === r1) return;
+  axis.r0 = r0;
+  axis.r1 = r1;
+  invalidateScale(axis);
+}
+
+export function resetAxis(axis: AxisState<unknown>): boolean {
+  if (axis.kind !== "continuous") return false;
+  if (axis.t0 === axis.baseT0 && axis.t1 === axis.baseT1) return false;
+  axis.t0 = axis.baseT0;
+  axis.t1 = axis.baseT1;
+  invalidateScale(axis);
+  return true;
+}
+
+export function readVisibleDomain(axis: AxisState<unknown>): unknown {
+  if (axis.kind === "band") return [...axis.domain];
+  const d0 = axis.transform.from(axis.t0);
+  const d1 = axis.transform.from(axis.t1);
+  if (axis.type === "time") {
+    return [new Date(d0), new Date(d1)] as const;
+  }
+  return [d0, d1] as const;
+}
+
+export function invertAxis(axis: AxisState<unknown>, localPx: number): unknown {
+  if (axis.kind === "continuous") {
+    const range = axis.r1 - axis.r0;
+    if (range === 0) return axis.transform.from(axis.t0);
+    const t = axis.t0 + ((localPx - axis.r0) * (axis.t1 - axis.t0)) / range;
+    const value = axis.transform.from(t);
+    return axis.type === "time" ? new Date(value) : value;
+  }
+  const scale = getBandScale(axis);
+  const bw = scale.bandwidth();
+  for (const v of axis.domain) {
+    const start = scale(v);
+    if (localPx >= start && localPx <= start + bw) return v;
+  }
+  return undefined;
+}
+
+export function applyAxis(axis: AxisState<unknown>, value: unknown): number {
+  if (axis.kind === "continuous") {
+    const scale = getContinuousScale(axis);
+    if (axis.type === "time") {
+      return (scale as TimeScale)(value as Date);
+    }
+    return (scale as ContinuousScale)(value as number);
+  }
+  return getBandScale(axis)(value);
+}
+
+// ---------------------------------------------------------------------------
+// Linear-axis fast-path helper
+// ---------------------------------------------------------------------------
+
+export interface LinearAxisFn {
+  readonly t0: number; // domain start (transformed)
+  readonly t1: number; // domain end (transformed)
+  readonly r0: number; // range start (px, axis-local)
+  readonly r1: number; // range end (px, axis-local)
+}
+
+/**
+ * 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 function asLinearAxisFn(axis: AxisState<unknown>): LinearAxisFn | null {
+  if (axis.kind !== "continuous") return null;
+  if (axis.type !== "linear") return null;
+  const { t0, t1, r0, r1 } = axis;
+  return { t0, t1, r0, r1 };
+}
+
+export function copyContinuous(source: AxisState<unknown>, target: AxisState<unknown>): void {
+  if (source.kind !== "continuous" || target.kind !== "continuous") return;
+  if (source.type !== target.type) return;
+  if (target.t0 === source.t0 && target.t1 === source.t1) return;
+  target.t0 = source.t0;
+  target.t1 = source.t1;
+  invalidateScale(target);
+}

package/src/viewport.d.ts

@@ -0,0 +1,170 @@
+import { type Frame, type FrameRect, type ResolvedCameraState, type Vec2 } from "insomni";
+import type { CameraViewport, ViewportLike } from "insomni/viewport";
+import type { AxisScale, DateDomain, NumericDomain } from "./scales.ts";
+import { type AxisState, type ViewportAxisConfig, type VisibleDomainInput } from "./viewport/axis-state.ts";
+export type { BandAxisConfig, ContinuousAxisConfig, TimeAxisConfig, ViewportAxisConfig, VisibleDomainInput, } from "./viewport/axis-state.ts";
+/**
+ * Per-axis margin spec. A bare number applies to both axes. Values are
+ * fractions of the *visible* span and apply symmetrically to both edges.
+ */
+export type PanBoundsMargin = number | {
+    x?: number;
+    y?: number;
+};
+export interface PanBoundsMargins {
+    /** Pan-past-content allowance when content is larger than the viewport. */
+    overshoot?: PanBoundsMargin;
+    /** Content drift allowance when content fits inside the viewport. */
+    drift?: PanBoundsMargin;
+}
+export interface DataPanBoundsOptions extends PanBoundsMargins {
+}
+export interface DataViewportOptions<X = unknown, Y = unknown> {
+    /** Frame in pixel space (relative to parent if `parent` is supplied). */
+    frame: Frame;
+    /** Optional parent viewport — `frame` is interpreted in the parent's space. */
+    parent?: ViewportLike;
+    x: ViewportAxisConfig<X>;
+    y: ViewportAxisConfig<Y>;
+    /** Minimum domain-span multiplier (relative to base). Default: 0.001 */
+    minZoom?: number;
+    /** Maximum domain-span multiplier (relative to base). Default: 1000 */
+    maxZoom?: number;
+    /**
+     * Pan-bound the visible domain to the axis base domain (the initial domain
+     * passed in `x` / `y`). When zoomed in, panning stops at content edges
+     * (plus margin); when zoomed out far enough that content fits in view,
+     * the viewport cannot pan content off-screen. Zoom itself remains
+     * unrestricted past content — this only governs pan position.
+     */
+    panBounds?: DataPanBoundsOptions;
+}
+export type ZoomFactor = number | {
+    x?: number;
+    y?: number;
+};
+export interface LinearProjector {
+    /** sx = worldX * txSlope + txConst */
+    readonly txSlope: number;
+    readonly txConst: number;
+    /** sy = worldY * tySlope + tyConst */
+    readonly tySlope: number;
+    readonly tyConst: number;
+}
+export interface DataViewport<X = unknown, Y = unknown> {
+    readonly mode: "data";
+    /** Frame relative to `parent` (or absolute if no parent). */
+    readonly frame: Frame;
+    /** Frame in root / canvas space — walks the parent chain on each read. */
+    readonly absoluteFrame: Frame;
+    /** Parent viewport, if this is a nested viewport. */
+    readonly parent: ViewportLike | null;
+    /** Mutable rect equal to `absoluteFrame`, refreshed in place on each access. */
+    readonly clipRect: FrameRect;
+    /** Identity camera (data-mode pan/zoom flows through axis scales). */
+    readonly camera: ResolvedCameraState;
+    readonly x: AxisScale<X>;
+    readonly y: AxisScale<Y>;
+    readonly visibleXDomain: NumericDomain | DateDomain | readonly X[];
+    readonly visibleYDomain: NumericDomain | DateDomain | readonly Y[];
+    /** Pan by pixel deltas in this viewport's frame space. */
+    panBy(dxPx: number, dyPx: number): void;
+    /** Zoom around a screen-pixel anchor in the viewport's absolute frame space. */
+    zoomAt(anchorSx: number, anchorSy: number, factor: ZoomFactor): void;
+    /** Reset to initial domain. */
+    reset(): void;
+    /**
+     * Replace the frame (in the same space as the original frame).
+     *
+     * `reserve` (CSS-px insets) shrinks the axis pixel range without changing
+     * the visible frame extent or `clipRect`. This is how the chart pipeline
+     * tells the viewport about position-scale range reservations
+     * (`framePadding` + per-geom `prepareRange`) so `dataToScreen` matches
+     * where marks actually render. Defaults to zero insets — callers that
+     * don't reserve any space (test viewports, manual mounts) can omit it.
+     */
+    setFrame(frame: Frame, reserve?: AxisRangeReserve): void;
+    /** Convert a screen pixel to data coords. Returns null if outside the absolute frame. */
+    screenToData(sx: number, sy: number): {
+        x: X;
+        y: Y;
+    } | null;
+    /** Convert data coords to screen pixels (absolute). */
+    dataToScreen(dx: X, dy: Y): Vec2;
+    /**
+     * If both axes are linear continuous (not log, not time, not band), return a
+     * pre-computed slope+intercept projector for use in hot loops. Returns null
+     * for mixed or non-linear axis configurations. Recompute once per project
+     * call; do not call per-entry.
+     */
+    getLinearProjector(): LinearProjector | null;
+    /** Set the visible domain absolutely on one or both continuous axes. */
+    setVisibleDomain(domains: {
+        x?: VisibleDomainInput;
+        y?: VisibleDomainInput;
+    }): void;
+    /** Replace the pan-bound config (or clear it with `null`). */
+    setPanBounds(options: DataPanBoundsOptions | null): void;
+    /** Subscribe to any view-state change. */
+    onChange(cb: () => void): () => void;
+    /** @internal */
+    _state: DataInternal;
+}
+/** Anything that can be linked together — `linkViewports` ignores camera viewports. */
+export type Viewport<X = unknown, Y = unknown> = DataViewport<X, Y> | CameraViewport;
+interface MutableFrameRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+interface ResolvedAxisMargin {
+    x: number;
+    y: number;
+}
+interface ResolvedMargins {
+    overshoot: ResolvedAxisMargin;
+    drift: ResolvedAxisMargin;
+}
+export interface DataInternal {
+    mode: "data";
+    frame: Frame;
+    parent: ViewportLike | null;
+    listeners: Set<() => void>;
+    notifying: boolean;
+    clipRect: MutableFrameRect;
+    xAxis: AxisState<unknown>;
+    yAxis: AxisState<unknown>;
+    minZoom: number;
+    maxZoom: number;
+    panBoundsMargins: ResolvedMargins | null;
+    rangeReserve: AxisRangeReserve;
+}
+/**
+ * CSS-px insets that shrink the axis pixel range without changing the frame
+ * extent. Mirrors the chart pipeline's `framePadding` + per-geom
+ * `prepareRange` reservations so `dataToScreen` lines up with where marks
+ * actually render.
+ */
+export interface AxisRangeReserve {
+    readonly left: number;
+    readonly right: number;
+    readonly top: number;
+    readonly bottom: number;
+}
+export declare function createDataViewport<X = unknown, Y = unknown>(options: DataViewportOptions<X, Y>): DataViewport<X, Y>;
+export interface LinkViewportsOptions {
+    /** Sync X axis state. Default: true. */
+    x?: boolean;
+    /** Sync Y axis state. Default: false. */
+    y?: boolean;
+}
+/**
+ * Keep multiple data viewports in sync on selected axes. Camera viewports in
+ * the array are skipped (link only makes sense between like-typed data axes).
+ *
+ * Any pan/zoom/reset on one data viewport propagates the current transformed-
+ * domain endpoints to the others on the linked axes. Requires linked axes to
+ * have matching `type` (e.g. both `linear`, or both `time`).
+ */
+export declare function linkViewports(viewports: readonly Viewport<any, any>[], options?: LinkViewportsOptions): () => void;