insomni-plot 0.1.0-alpha.0

package/src/viewport.ts

@@ -0,0 +1,510 @@
+import {
+  createFrame,
+  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 {
+  applyAxis,
+  asLinearAxisFn,
+  buildScale,
+  clampAxisToBase,
+  copyContinuous,
+  createAxisState,
+  invertAxis,
+  panAxis,
+  readVisibleDomain,
+  resetAxis,
+  setAxisRange,
+  setAxisVisibleDomain,
+  zoomAxis,
+  type AxisState,
+  type ViewportAxisConfig,
+  type VisibleDomainInput,
+} from "./viewport/axis-state.ts";
+
+export type {
+  BandAxisConfig,
+  ContinuousAxisConfig,
+  TimeAxisConfig,
+  ViewportAxisConfig,
+  VisibleDomainInput,
+} from "./viewport/axis-state.ts";
+
+// ---------------------------------------------------------------------------
+// Pan-bound margin types
+// ---------------------------------------------------------------------------
+
+/**
+ * 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 {}
+
+// ---------------------------------------------------------------------------
+// Viewport options
+// ---------------------------------------------------------------------------
+
+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 };
+
+// ---------------------------------------------------------------------------
+// Linear projector
+// ---------------------------------------------------------------------------
+
+export interface LinearProjector {
+  /** sx = worldX * txSlope + txConst */
+  readonly txSlope: number;
+  readonly txConst: number;
+  /** sy = worldY * tySlope + tyConst */
+  readonly tySlope: number;
+  readonly tyConst: number;
+}
+
+// ---------------------------------------------------------------------------
+// DataViewport public type
+// ---------------------------------------------------------------------------
+
+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;
+
+// ---------------------------------------------------------------------------
+// Internal representation
+// ---------------------------------------------------------------------------
+
+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;
+}
+
+const ZERO_RESERVE: AxisRangeReserve = Object.freeze({ left: 0, right: 0, top: 0, bottom: 0 });
+
+function sameReserve(a: AxisRangeReserve, b: AxisRangeReserve): boolean {
+  return a.left === b.left && a.right === b.right && a.top === b.top && a.bottom === b.bottom;
+}
+
+const IDENTITY_CAMERA: ResolvedCameraState = Object.freeze({ x: 0, y: 0, zoom: 1, rotation: 0 });
+
+// ---------------------------------------------------------------------------
+// Pan-bound margin resolution
+// ---------------------------------------------------------------------------
+
+function resolveAxisMargin(spec: PanBoundsMargin | undefined): ResolvedAxisMargin {
+  if (spec === undefined) return { x: 0, y: 0 };
+  if (typeof spec === "number") return { x: spec, y: spec };
+  return { x: spec.x ?? 0, y: spec.y ?? 0 };
+}
+
+function resolveMargins(opts: PanBoundsMargins): ResolvedMargins {
+  return {
+    overshoot: resolveAxisMargin(opts.overshoot),
+    drift: resolveAxisMargin(opts.drift),
+  };
+}
+
+function clampDataState(state: DataInternal): boolean {
+  const m = state.panBoundsMargins;
+  if (!m) return false;
+  let changed = false;
+  if (clampAxisToBase(state.xAxis, m.overshoot.x, m.drift.x)) changed = true;
+  if (clampAxisToBase(state.yAxis, m.overshoot.y, m.drift.y)) changed = true;
+  return changed;
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+export function createDataViewport<X = unknown, Y = unknown>(
+  options: DataViewportOptions<X, Y>,
+): DataViewport<X, Y> {
+  const frame = options.frame;
+  const parent = options.parent ?? null;
+
+  const state: DataInternal = {
+    mode: "data",
+    frame,
+    parent,
+    xAxis: createAxisState(options.x, 0, frame.width) as AxisState<unknown>,
+    yAxis: createAxisState(options.y, frame.height, 0) as AxisState<unknown>,
+    minZoom: options.minZoom ?? 0.001,
+    maxZoom: options.maxZoom ?? 1000,
+    listeners: new Set(),
+    notifying: false,
+    clipRect: { x: frame.x, y: frame.y, width: frame.width, height: frame.height },
+    panBoundsMargins: options.panBounds ? resolveMargins(options.panBounds) : null,
+    rangeReserve: ZERO_RESERVE,
+  };
+
+  const notify = () => notifyListeners(state);
+
+  const viewport: DataViewport<X, Y> = {
+    mode: "data",
+    get frame() {
+      return state.frame;
+    },
+    get absoluteFrame() {
+      return absoluteFrame(state);
+    },
+    get parent() {
+      return state.parent;
+    },
+    get clipRect() {
+      return refreshClipRect(state);
+    },
+    get camera() {
+      return IDENTITY_CAMERA;
+    },
+    get x() {
+      return buildScale(state.xAxis) as AxisScale<X>;
+    },
+    get y() {
+      return buildScale(state.yAxis) as AxisScale<Y>;
+    },
+    get visibleXDomain() {
+      return readVisibleDomain(state.xAxis) as NumericDomain | DateDomain | readonly X[];
+    },
+    get visibleYDomain() {
+      return readVisibleDomain(state.yAxis) as NumericDomain | DateDomain | readonly Y[];
+    },
+
+    panBy(dxPx, dyPx) {
+      let changed = false;
+      if (dxPx !== 0) changed = panAxis(state.xAxis, dxPx) || changed;
+      if (dyPx !== 0) changed = panAxis(state.yAxis, dyPx) || changed;
+      if (clampDataState(state)) changed = true;
+      if (changed) notify();
+    },
+
+    zoomAt(anchorSx, anchorSy, factor) {
+      const fx = typeof factor === "number" ? factor : (factor.x ?? 1);
+      const fy = typeof factor === "number" ? factor : (factor.y ?? 1);
+      const abs = absoluteFrame(state);
+      const localX = anchorSx - abs.x;
+      const localY = anchorSy - abs.y;
+      let changed = false;
+      if (fx !== 1) {
+        changed = zoomAxis(state.xAxis, localX, fx, state.minZoom, state.maxZoom) || changed;
+      }
+      if (fy !== 1) {
+        changed = zoomAxis(state.yAxis, localY, fy, state.minZoom, state.maxZoom) || changed;
+      }
+      if (clampDataState(state)) changed = true;
+      if (changed) notify();
+    },
+
+    reset() {
+      let changed = false;
+      if (resetAxis(state.xAxis)) changed = true;
+      if (resetAxis(state.yAxis)) changed = true;
+      if (changed) notify();
+    },
+
+    setFrame(nextFrame, reserve) {
+      const r = reserve ?? ZERO_RESERVE;
+      const frameUnchanged = sameFrame(state.frame, nextFrame);
+      const reserveUnchanged = sameReserve(state.rangeReserve, r);
+      if (frameUnchanged && reserveUnchanged) {
+        state.frame = nextFrame;
+        return;
+      }
+      state.frame = nextFrame;
+      state.rangeReserve = r;
+      // X axis: pixel range [reserve.left, width - reserve.right] (low→high).
+      // Y axis: pixel range [height - reserve.bottom, reserve.top] (high→low,
+      // since data ascends upward but pixel y descends).
+      setAxisRange(state.xAxis, r.left, nextFrame.width - r.right);
+      setAxisRange(state.yAxis, nextFrame.height - r.bottom, r.top);
+      refreshClipRect(state);
+      notify();
+    },
+
+    screenToData(sx, sy) {
+      const f = absoluteFrame(state);
+      if (sx < f.x || sx > f.x + f.width || sy < f.y || sy > f.y + f.height) return null;
+      const lx = sx - f.x;
+      const ly = sy - f.y;
+      const xd = invertAxis(state.xAxis, lx);
+      const yd = invertAxis(state.yAxis, ly);
+      if (xd === undefined || yd === undefined) return null;
+      return { x: xd as X, y: yd as Y };
+    },
+
+    dataToScreen(dx, dy) {
+      const f = absoluteFrame(state);
+      const px = applyAxis(state.xAxis, dx);
+      const py = applyAxis(state.yAxis, dy);
+      return { x: px + f.x, y: py + f.y };
+    },
+
+    getLinearProjector() {
+      const fx = asLinearAxisFn(state.xAxis);
+      const fy = asLinearAxisFn(state.yAxis);
+      if (!fx || !fy) return null;
+      const f = absoluteFrame(state);
+      const txSlope = (fx.r1 - fx.r0) / (fx.t1 - fx.t0);
+      const txConst = fx.r0 - fx.t0 * txSlope + f.x;
+      const tySlope = (fy.r1 - fy.r0) / (fy.t1 - fy.t0);
+      const tyConst = fy.r0 - fy.t0 * tySlope + f.y;
+      return { txSlope, txConst, tySlope, tyConst };
+    },
+
+    setVisibleDomain(domains) {
+      let changed = false;
+      if (domains.x !== undefined) {
+        changed =
+          setAxisVisibleDomain(state.xAxis, domains.x, state.minZoom, state.maxZoom) || changed;
+      }
+      if (domains.y !== undefined) {
+        changed =
+          setAxisVisibleDomain(state.yAxis, domains.y, state.minZoom, state.maxZoom) || changed;
+      }
+      if (clampDataState(state)) changed = true;
+      if (changed) notify();
+    },
+
+    setPanBounds(panBounds) {
+      state.panBoundsMargins = panBounds ? resolveMargins(panBounds) : null;
+      if (clampDataState(state)) notify();
+    },
+
+    onChange(cb) {
+      state.listeners.add(cb);
+      return () => {
+        state.listeners.delete(cb);
+      };
+    },
+
+    _state: state,
+  };
+
+  return viewport;
+}
+
+// ---------------------------------------------------------------------------
+// Parent-chain helpers
+// ---------------------------------------------------------------------------
+
+function absoluteFrame(state: DataInternal): Frame {
+  if (!state.parent) return state.frame;
+  const parentAbs = state.parent.absoluteFrame;
+  if (parentAbs.x === 0 && parentAbs.y === 0) return state.frame;
+  return createFrame({
+    x: state.frame.x + parentAbs.x,
+    y: state.frame.y + parentAbs.y,
+    width: state.frame.width,
+    height: state.frame.height,
+  });
+}
+
+function refreshClipRect(state: DataInternal): FrameRect {
+  const abs = absoluteFrame(state);
+  const rect = state.clipRect;
+  rect.x = abs.x;
+  rect.y = abs.y;
+  rect.width = abs.width;
+  rect.height = abs.height;
+  return rect;
+}
+
+function notifyListeners(state: DataInternal): void {
+  if (state.notifying) return;
+  state.notifying = true;
+  try {
+    for (const cb of state.listeners) cb();
+  } finally {
+    state.notifying = false;
+  }
+}
+
+function sameFrame(a: Frame, b: Frame): boolean {
+  return a.x === b.x && a.y === b.y && a.width === b.width && a.height === b.height;
+}
+
+// ---------------------------------------------------------------------------
+// Link helper
+// ---------------------------------------------------------------------------
+
+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 function linkViewports(
+  viewports: readonly Viewport<any, any>[],
+  options: LinkViewportsOptions = {},
+): () => void {
+  const linkX = options.x ?? true;
+  const linkY = options.y ?? false;
+  if (viewports.length < 2 || (!linkX && !linkY)) return () => {};
+
+  let propagating = false;
+  const unsubs: Array<() => void> = [];
+
+  for (const source of viewports) {
+    if (source.mode !== "data") continue;
+    const sourceState = source._state;
+    const unsub = source.onChange(() => {
+      if (propagating) return;
+      propagating = true;
+      try {
+        for (const target of viewports) {
+          if (target === source) continue;
+          if (target.mode !== "data") continue;
+          const targetState = target._state;
+          if (linkX) copyContinuous(sourceState.xAxis, targetState.xAxis);
+          if (linkY) copyContinuous(sourceState.yAxis, targetState.yAxis);
+          for (const cb of targetState.listeners) cb();
+        }
+      } finally {
+        propagating = false;
+      }
+    });
+    unsubs.push(unsub);
+  }
+
+  return () => {
+    for (const unsub of unsubs) unsub();
+  };
+}