@motionscript/plot 0.0.0-stage → 0.1.0-alpha.3

package/src/graph2d/graph2d.ts

@@ -0,0 +1,586 @@
+import {
+  node,
+  Clip,
+  Fills,
+  Graphics2D,
+  Node2D,
+  clamp,
+  lerpNumber,
+  property,
+  type Color,
+  type Node2DProps,
+  type NormalizedColor,
+  type RenderContext2D,
+} from "@motionscript/sdk"
+
+import { sampleBudget, type PixelRect } from "./curve"
+import { CurveRunsCache, runsKeyOf } from "./curve-cache"
+import {
+  formatTick,
+  inflate,
+  labelLadder,
+  labelWidthEm,
+  planeBox,
+  resolvePlane,
+  tickLadder,
+  toPx,
+  toPy,
+  type PlaneView,
+  type ResolvedPlane,
+  type TickLadder,
+} from "./plane"
+import {
+  PLANE_SOURCE,
+  planeUniforms,
+  planeVisible,
+  type PlaneStyle,
+} from "./plane-fill"
+import {
+  compileCurveCached,
+  lerpColor,
+  lerpCurves,
+  resolveColor,
+  snapFlag,
+  snapValue,
+  type CurveResolved,
+} from "./shared"
+
+// --- Authored props --------------------------------------------------------
+// The loose shapes a caller writes. Each has a matching `*Resolved` type below:
+// what the `@property` mapper turns it into and what the tween interpolates.
+
+/** One plotted curve, `y = f(x)`. */
+export interface Graph2DEquation {
+  /** Identity across list changes — see {@link Graph2D.equations}. */
+  id: string | number
+  /** The expression, evaluated as `y = f(x)` (e.g. `sin(x)`, `log(x)`). */
+  expression: string
+  /** The curve's colour: any {@link Color} — a CSS string or an RGBA tuple. */
+  color: Color
+  /** Whether the curve is drawn. Defaults to true. */
+  visible?: boolean
+  /** How opaque the curve is, 0–1. Defaults to 1. */
+  opacity?: number
+}
+
+/** The paper the curves are drawn on: the grid, the axes and their numbers. */
+export interface Graph2DGrid {
+  /** Whether to rule the plane at all. Defaults to true. */
+  showGrid?: boolean
+  /** Whether to draw the faint lines between the numbered ones. Defaults to true. */
+  showMinorGrid?: boolean
+  /** Whether to draw the two lines through the origin. Defaults to true. */
+  showAxes?: boolean
+  /** Whether to number the axes. Defaults to true. */
+  showLabels?: boolean
+  colorGrid?: Color
+  colorMinorGrid?: Color
+  colorAxis?: Color
+  colorLabel?: Color
+  /** Width of a grid line. The minor lines are drawn at two thirds of it. */
+  lineWidth?: number
+  /** Width of the two axis lines. */
+  axisWidth?: number
+  /** Size of the axis numbers. Also sets how close two of them may sit. */
+  fontSize?: number
+  /** Family the axis numbers are set in. Empty takes the built-in face. */
+  fontFamily?: string
+}
+
+export interface Graph2DProps extends Node2DProps {
+  /** The curves to plot, each evaluated as `y = f(x)` across the visible range. */
+  equations: Graph2DEquation[]
+  /** Graph x at the centre of the box — see {@link PlaneView}. */
+  centerX: number
+  /** Graph y at the centre of the box. */
+  centerY: number
+  /** Width of the visible window, in graph units. */
+  xSpan: number
+  /**
+   * Height of the visible window in graph units, or **0 to keep units square**,
+   * which is the default and almost always what you want. See {@link PlaneView}.
+   */
+  ySpan: number
+  grid: Graph2DGrid
+  /** The paper's colour. */
+  background: Color
+  /** How opaque the paper is, 0–1. At 0 the graph draws over whatever is behind it. */
+  backgroundOpacity: number
+  /** How thick a plotted curve is drawn. */
+  lineWidth: number
+}
+
+// --- Resolved props --------------------------------------------------------
+// Canonical, fully defaulted, interpolatable. Nothing here is optional, so the
+// draw never re-derives a default and the tweens never test for one.
+
+/** {@link Graph2DGrid} after {@link resolveGrid}. */
+interface GridResolved {
+  showGrid: boolean
+  showMinorGrid: boolean
+  showAxes: boolean
+  showLabels: boolean
+  colorGrid: NormalizedColor
+  colorMinorGrid: NormalizedColor
+  colorAxis: NormalizedColor
+  colorLabel: NormalizedColor
+  lineWidth: number
+  axisWidth: number
+  fontSize: number
+  fontFamily: string
+}
+
+/**
+ * The grid a node with nothing said about it draws — the same dark palette the
+ * 3D graph opens on, so the two read as one family when they share a scene.
+ */
+const DEFAULT_GRID: GridResolved = {
+  showGrid: true,
+  showMinorGrid: true,
+  showAxes: true,
+  showLabels: true,
+  colorGrid: resolveColor("#374151"),
+  colorMinorGrid: resolveColor("#1f2937"),
+  colorAxis: resolveColor("#6b7280"),
+  colorLabel: resolveColor("#9ca3af"),
+  lineWidth: 2,
+  axisWidth: 3,
+  fontSize: 22,
+  fontFamily: "",
+}
+
+/** How far a curve may run past the box before it is cut away, in stroke widths. */
+const CLIP_MARGIN = 1
+
+/**
+ * How close two stacked numbers may sit before the ladder steps up, in font
+ * sizes.
+ *
+ * Only the vertical one lives here. Across, how close two numbers may sit
+ * depends on how *long* they are — five characters near the origin, fourteen at
+ * a deep zoom — so that ladder is built by `labelLadder`, which measures what it
+ * just produced and widens itself once if it has to. Down, a number is one line
+ * whatever it says.
+ */
+const LABEL_PITCH_Y = 2.6
+const LABEL_GAP = 0.45
+/**
+ * Narrowest the box a number is aligned within may be, in font sizes.
+ *
+ * Deliberately wider than the numbers an ordinary view carries, so a
+ * right-aligned `-1200` and a right-aligned `5` end in the same place. It only
+ * ever grows from here — see `labelWidthEm`.
+ */
+const LABEL_BOX = 6
+
+/**
+ * A 2D function grapher — any number of `y = f(x)` curves over a ruled plane,
+ * with numbered axes.
+ *
+ *   <Graph2D
+ *     width={960} height={540}
+ *     equations={[{ id: 1, expression: "log(x)", color: "#3B82F6" }]}
+ *   />
+ *
+ * The sibling of {@link Graph3D}, and deliberately built the same way: the same
+ * little expression language, the same equation tiles, the same match-by-id
+ * tween over the list. What it does *not* share is the hard part, which is not
+ * the maths but the drawing — see `curve.ts`, which exists because the obvious
+ * sampling loop cuts `log(x)` off in mid-air, silently drops `1/x` entirely on a
+ * fixed-point rasterizer, and puts a visible polygonal kink wherever a curve
+ * turns sharply.
+ *
+ * Every prop is a `@property`, so a constant, a `() => signal()` binding, and
+ * `set()`/`to()` on a ref all work and agree. The non-scalar props each declare
+ * a `mapper` (loose authored shape → one canonical internal shape) and a `tween`
+ * (how that shape interpolates) — without the tween, `to({ grid: … })` would hold
+ * the old value and snap at the end, which is the standard trap for an
+ * object-valued attribute.
+ *
+ * **The view is four plain numbers, not a transform.** `centerX`/`centerY` and
+ * `xSpan`/`ySpan` are each independently tweenable, which is what makes "pan
+ * across while zooming in" one command and what keeps every frame reproducible
+ * under scrubbing and export. The canvas's pan/zoom gesture writes exactly these
+ * four, so a view flown by hand is a view a `to` can animate afterwards.
+ */
+@node({
+  key: "graph2d",
+  parentKey: "node",
+  forkable: true,
+  layout: {
+    children: "freeform",
+    defaultWidthMode: "fixed",
+    defaultHeightMode: "fixed",
+    acceptsChildren: true,
+  },
+  seed: {
+    width: 960,
+    height: 540,
+  },
+})
+export class Graph2D extends Node2D<Graph2DProps> {
+  /**
+   * The plotted curves.
+   *
+   * The mapper compiles each expression **once per write** (memoised by source),
+   * so the draw — which re-runs every frame — never re-parses; and it folds
+   * `visible`/`opacity` into a single number, so hiding is expressible as a
+   * fade. An expression that doesn't parse is dropped and the rest still draw,
+   * which is what lets the inspector commit on every keystroke.
+   *
+   * The tween matches the two lists by `id` — see `lerpCurves`.
+   */
+  @property({ default: [], mapper: resolveEquations, tween: lerpCurves })
+  declare equations: Graph2DEquation[]
+
+  @property({ default: 0 }) declare centerX: number
+  @property({ default: 0 }) declare centerY: number
+  @property({ default: 20 }) declare xSpan: number
+  @property({ default: 0 }) declare ySpan: number
+
+  /** The paper. Flags snap at the end of a tween; the rest lerp. */
+  @property({ default: {}, mapper: resolveGrid, tween: lerpGrid })
+  declare grid: Graph2DGrid
+
+  @property({ default: "#111827", mapper: resolveColor, tween: lerpColor })
+  declare background: Color
+  @property({ default: 1 }) declare backgroundOpacity: number
+  @property({ default: 5 }) declare lineWidth: number
+
+  /**
+   * The node's one piece of memoisation, and it earns its keep: a graph that is
+   * holding still re-samples nothing at all. See `curve-cache.ts`.
+   */
+  private readonly runs = new CurveRunsCache()
+
+  /** Where the node is looking, as the four props hold it. */
+  private get view(): PlaneView {
+    return {
+      centerX: this.centerX,
+      centerY: this.centerY,
+      xSpan: this.xSpan,
+      ySpan: this.ySpan,
+    }
+  }
+
+  /**
+   * Confines every mark to the node's own box — its own drawing as well as its
+   * children's, which is why this is `clipPathSelf` and not `clipSelf`.
+   *
+   * Belt and braces over the geometric clipping in `curve.ts` rather than a
+   * substitute for it: that clipping is what keeps astronomical coordinates away
+   * from the rasterizer, and this is what stops a stroke's half-width and its
+   * round joins from painting a hair outside the frame at the edges.
+   */
+  protected override clipPathSelf(): Clip | null {
+    const width = this.layoutBounds.width
+    const height = this.layoutBounds.height
+    if (width <= 0 || height <= 0) return null
+    return new Clip().rect({ x: 0, y: 0, width, height })
+  }
+
+  // ---- Drawing ------------------------------------------------------------
+
+  protected override renderSelf(ctx: RenderContext2D): void {
+    const width = this.layoutBounds.width
+    const height = this.layoutBounds.height
+    if (width <= 0 || height <= 0) return
+
+    const plane = resolvePlane(this.view, width, height)
+    const grid = this.grid as unknown as GridResolved
+    const box = planeBox(plane)
+
+    // One ladder per axis, chosen from the *scale* rather than from a fixed
+    // count: what decides how finely the plane is ruled is how close two numbers
+    // would sit on screen, which is the only thing that stays true as the view is
+    // flown around.
+    const xTicks = labelLadder(plane.xMin, plane.xMax, plane.scaleX, grid.fontSize)
+    const yTicks = tickLadder(
+      plane.yMin,
+      plane.yMax,
+      plane.scaleY,
+      grid.fontSize * LABEL_PITCH_Y
+    )
+
+    this.drawPlane(ctx, plane, grid, xTicks, yTicks)
+    if (grid.showLabels) this.drawLabels(ctx, plane, box, grid, xTicks, yTicks)
+
+    this.drawCurves(ctx, plane, box)
+  }
+
+  /**
+   * The paper, the two orders of ruling and the two axes — one rect, one shader,
+   * one draw, whatever the zoom.
+   *
+   * This was six hundred filled rects and three draws, and the rect count is the
+   * part that mattered: it changed as the ladder stepped, and the renderer keys
+   * its geometry cache by shape *index*, so a grid that gained a line invalidated
+   * every curve behind it. One shape means the curves' keys never move. See
+   * `plane-fill.ts` for why the built-in grid fill can't do this job and for what
+   * the phase uniforms are protecting against.
+   */
+  private drawPlane(
+    ctx: RenderContext2D,
+    plane: ResolvedPlane,
+    grid: GridResolved,
+    xTicks: TickLadder,
+    yTicks: TickLadder
+  ): void {
+    const style: PlaneStyle = {
+      paper: this.background as NormalizedColor,
+      paperOpacity: clamp01(this.backgroundOpacity),
+      showGrid: grid.showGrid,
+      showMinorGrid: grid.showMinorGrid,
+      showAxes: grid.showAxes,
+      colorGrid: grid.colorGrid,
+      colorMinorGrid: grid.colorMinorGrid,
+      colorAxis: grid.colorAxis,
+      lineWidth: grid.lineWidth,
+      axisWidth: grid.axisWidth,
+    }
+    // Nothing to paint at all — clear paper, no rulings, no axes — is a whole
+    // fragment pass over the box that would come out transparent.
+    if (!planeVisible(style)) return
+
+    ctx.draw(
+      new Graphics2D()
+        .rect({ x: 0, y: 0, width: plane.width, height: plane.height })
+        .fill(
+          Fills.shader(PLANE_SOURCE, {
+            uniforms: planeUniforms(plane, style, xTicks, yTicks),
+            coords: "local",
+          })
+        )
+    )
+  }
+
+  /**
+   * The numbers along each axis.
+   *
+   * Pinned to the frame when their axis has left it, which is the behaviour
+   * every map and every grapher has and the reason it is worth the arithmetic:
+   * pan far enough that the origin is off screen and a graph whose numbers went
+   * with it is a graph you can no longer read. The row also flips to the other
+   * side of its axis when there is no room on the near one, so a view sitting
+   * just above the x-axis still numbers it.
+   */
+  private drawLabels(
+    ctx: RenderContext2D,
+    plane: ResolvedPlane,
+    box: PixelRect,
+    grid: GridResolved,
+    xTicks: TickLadder,
+    yTicks: TickLadder
+  ): void {
+    const labels = new Graphics2D()
+    const gap = grid.fontSize * LABEL_GAP
+    // Per axis, because the two ladders carry different numbers: a view can be
+    // ten units wide and a billionth of one tall.
+    const xBox = grid.fontSize * Math.max(LABEL_BOX, labelWidthEm(xTicks))
+    const yBox = grid.fontSize * Math.max(LABEL_BOX, labelWidthEm(yTicks))
+    const font = {
+      fontSize: grid.fontSize,
+      // An empty family is dropped rather than passed on: the renderer's font
+      // provider holds only what the manifest registered, so asking it for a
+      // family called `""` shapes against nothing and paints no glyphs. Left
+      // unset it inherits the scene's own default face.
+      ...(grid.fontFamily === "" ? {} : { fontFamily: grid.fontFamily }),
+      wrap: false,
+    }
+
+    // The x-axis row: under the axis when there is room beneath it, over it when
+    // there isn't.
+    const axisY = clamp(toPy(plane, 0), box.bottom, box.top)
+    const under = axisY - gap - grid.fontSize >= box.bottom
+    const rowY = under ? axisY - gap - grid.fontSize / 2 : axisY + gap + grid.fontSize / 2
+
+    for (const x of xTicks.major) {
+      labels.text({
+        ...font,
+        text: formatTick(x, xTicks.step),
+        x: toPx(plane, x),
+        y: rowY,
+        width: xBox,
+        textAlign: "center",
+      })
+    }
+
+    // The y-axis column: to the left of the axis when there is room, to the
+    // right when the axis is against the left edge.
+    // Room for a couple of characters, not for the whole alignment box: the box
+    // is deliberately wide (a right-aligned `-1200` and a right-aligned `5` end
+    // in the same place), and demanding all of it would push the column to the
+    // wrong side of an axis that has plenty of room for the numbers it holds.
+    const axisX = clamp(toPx(plane, 0), box.left, box.right)
+    const leftOf = axisX - gap - grid.fontSize * 1.5 >= box.left
+    const columnX = leftOf ? axisX - gap - yBox / 2 : axisX + gap + yBox / 2
+
+    // Zero belongs to the row, not the column: drawn in both it would be two
+    // numbers stacked on the origin. Skipped only when the row is actually
+    // showing it, so a view with the y-axis off screen still numbers its own 0.
+    const rowHasZero = plane.xMin <= 0 && 0 <= plane.xMax
+
+    for (const y of yTicks.major) {
+      if (y === 0 && rowHasZero) continue
+      labels.text({
+        ...font,
+        text: formatTick(y, yTicks.step),
+        x: columnX,
+        y: toPy(plane, y),
+        width: yBox,
+        textAlign: leftOf ? "right" : "left",
+      })
+    }
+
+    ctx.draw(labels.fill(Fills.color(grid.colorLabel)))
+  }
+
+  /**
+   * The curves themselves, one stroked polyline per run.
+   *
+   * One `draw` per run rather than one per curve, and that is not an
+   * optimisation to undo: shapes chained before a `stroke()` are combined into a
+   * single surface, and stroking a union of disjoint open paths paints nothing —
+   * so a curve that leaves the frame and comes back would lose *both* halves.
+   * `ChartLine` learned the same thing about its spotlight runs.
+   */
+  private drawCurves(
+    ctx: RenderContext2D,
+    plane: ResolvedPlane,
+    box: PixelRect
+  ): void {
+    const equations = this.equations as unknown as CurveResolved[]
+    const weight = Math.max(0.1, this.lineWidth)
+    const clip = inflate(box, weight * CLIP_MARGIN)
+    const key = runsKeyOf(plane, clip)
+
+    // What actually has to be sampled, counted before any of it is — so a frame
+    // where five of six curves are unchanged hands the whole evaluation budget
+    // to the one that moved rather than reserving five sixths of it for work
+    // that is already done.
+    const live: string[] = []
+    let misses = 0
+    for (const equation of equations) {
+      // Fully faded out (hidden, or the far end of a cross-fade): sample nothing.
+      if (equation.opacity <= 0.001) continue
+      live.push(equation.id)
+      if (!this.runs.holds(equation.id, equation.sample, key)) misses++
+    }
+    const budget = misses > 0 ? sampleBudget(misses) : undefined
+    this.runs.retain(live)
+
+    for (const equation of equations) {
+      if (equation.opacity <= 0.001) continue
+
+      const stroke = {
+        weight,
+        fill: Fills.color(equation.color, {
+          opacity: clamp01(equation.opacity),
+        }),
+        // Round on both counts because this is a *curve*: a miter join on a
+        // sharp turn throws a spike, and a butt cap leaves a visible flat end
+        // wherever a run stops at a domain edge.
+        cap: "round" as const,
+        join: "round" as const,
+      }
+
+      const runs = this.runs.runs(
+        equation.id,
+        equation.sample,
+        key,
+        plane,
+        clip,
+        budget
+      )
+      for (const run of runs) {
+        if (run.length < 2) continue
+        ctx.draw(new Graphics2D().line({ points: run, radius: 0 }).stroke(stroke))
+      }
+    }
+  }
+}
+
+// --- Mappers & tweens ------------------------------------------------------
+
+/** Mapper for {@link Graph2D.equations}. */
+function resolveEquations(
+  input: Graph2DEquation[] | undefined
+): CurveResolved[] {
+  if (!input) return []
+  const out: CurveResolved[] = []
+  for (const equation of input) {
+    const sample = compileCurveCached(equation.expression)
+    if (!sample) continue // unparseable or empty — drop it, keep the rest
+    out.push({
+      id: String(equation.id),
+      sample,
+      color: resolveColor(equation.color),
+      opacity: equation.visible === false ? 0 : (equation.opacity ?? 1),
+    })
+  }
+  return out
+}
+
+/**
+ * Mapper for {@link Graph2D.grid}.
+ *
+ * Merges onto `previous` rather than onto the bare defaults, which is what makes
+ * a partial write mean "change this much and leave the rest". It matters most on
+ * a `to` command, whose target states only the fields that command touches: a
+ * tween that dims the grid must not silently hand the axis numbers back to their
+ * default size on the way.
+ */
+function resolveGrid(
+  input: Graph2DGrid | undefined,
+  previous?: GridResolved
+): GridResolved {
+  const base = previous ?? DEFAULT_GRID
+  return {
+    showGrid: input?.showGrid ?? base.showGrid,
+    showMinorGrid: input?.showMinorGrid ?? base.showMinorGrid,
+    showAxes: input?.showAxes ?? base.showAxes,
+    showLabels: input?.showLabels ?? base.showLabels,
+    colorGrid: colorOr(input?.colorGrid, base.colorGrid),
+    colorMinorGrid: colorOr(input?.colorMinorGrid, base.colorMinorGrid),
+    colorAxis: colorOr(input?.colorAxis, base.colorAxis),
+    colorLabel: colorOr(input?.colorLabel, base.colorLabel),
+    lineWidth: input?.lineWidth ?? base.lineWidth,
+    axisWidth: input?.axisWidth ?? base.axisWidth,
+    fontSize: input?.fontSize ?? base.fontSize,
+    fontFamily: input?.fontFamily ?? base.fontFamily,
+  }
+}
+
+function colorOr(
+  input: Color | undefined,
+  fallback: NormalizedColor
+): NormalizedColor {
+  return input === undefined ? fallback : resolveColor(input)
+}
+
+/** Tween for {@link Graph2D.grid}. */
+function lerpGrid(
+  from: GridResolved,
+  to: GridResolved,
+  t: number
+): GridResolved {
+  return {
+    showGrid: snapFlag(from.showGrid, to.showGrid, t),
+    showMinorGrid: snapFlag(from.showMinorGrid, to.showMinorGrid, t),
+    showAxes: snapFlag(from.showAxes, to.showAxes, t),
+    showLabels: snapFlag(from.showLabels, to.showLabels, t),
+    colorGrid: lerpColor(from.colorGrid, to.colorGrid, t),
+    colorMinorGrid: lerpColor(from.colorMinorGrid, to.colorMinorGrid, t),
+    colorAxis: lerpColor(from.colorAxis, to.colorAxis, t),
+    colorLabel: lerpColor(from.colorLabel, to.colorLabel, t),
+    lineWidth: lerpNumber(from.lineWidth, to.lineWidth, t),
+    axisWidth: lerpNumber(from.axisWidth, to.axisWidth, t),
+    fontSize: lerpNumber(from.fontSize, to.fontSize, t),
+    // A face has no halfway point, so it changes once the tween lands.
+    fontFamily: snapValue(from.fontFamily, to.fontFamily, t),
+  }
+}
+
+function clamp01(value: number): number {
+  return Number.isFinite(value) ? clamp(value, 0, 1) : 1
+}

package/src/graph2d/index.ts

@@ -0,0 +1,31 @@
+/**
+ * The Graph 2D node — a **native** node type (see `node-types.ts` /
+ * `NODE_CLASS_BY_KEY`) like the 3D graph beside it: built, themed and animated
+ * from the inspector rather than loaded as a code package.
+ *
+ * It plots any number of `y = f(x)` curves over a ruled plane, sampling each
+ * from an expression the author types. The language is shared with the 3D graph
+ * (`nodes/graph-kit/expression`) and lives in this package rather than in a maths
+ * library for the same two reasons: an expression is a value stored in a scene
+ * document, so compiling it as JavaScript would make every scene file an
+ * execution vector; and a curve is a few thousand evaluations per frame, which a
+ * general evaluator would not survive.
+ *
+ * What is genuinely this node's own is `curve.ts`. Turning `y = f(x)` into
+ * polylines is where a grapher is actually won or lost — the naive loop cuts
+ * `log(x)` off in mid-air, silently drops `1/x` on a fixed-point rasterizer, and
+ * kinks visibly wherever a curve turns — and that module is the four fixes for
+ * it, written out with the reasoning.
+ *
+ * Unlike the 3D graph there *is* a pointer here: double-clicking the node opens a
+ * pan/zoom session on the canvas. It stays reproducible because what the gesture
+ * writes is the same four plain numbers a `to` command animates — see
+ * `plane-camera.ts`, which holds the arithmetic and no DOM.
+ */
+export * from "./curve";
+export * from "./curve-cache";
+export * from "./curve-error";
+export * from "./graph2d";
+export * from "./plane";
+export * from "./plane-fill";
+export * from "./shared";