@motionscript/charts 0.1.1-alpha.0 → 0.1.1-alpha.1

package/src/kit/vertical-axis.ts

@@ -5,7 +5,6 @@ import {
   Types,
   component2d,
   insetsOps,
-  textOps,
   type NodeOf,
   // Named so this component's emitted type reaches `Node2D` and its props through the sdk, not core.
   type Node2D,
@@ -13,6 +12,7 @@ import {
 } from "@motionscript/sdk"
 import { enterBudget } from "@motionscript/sdk/component"
 
+import { boundText } from "./cartesian"
 import { asParts, fresh } from "./entries"
 import { armed, arrival, arrivalOf, arrivalsEntry, beats, frameEase, type Arrival } from "./motion"
 import {
@@ -30,11 +30,65 @@ export function markerCaption(s: { readonly markers: readonly number[]; readonly
   return (index >= 0 ? s.captions[index] : undefined) ?? formatMarker(value)
 }
 
+/** The gap between an axis's markers and the plot, and between the markers and the caption, read off its config. */
+export function axisPads(axis: AxisConfig, side: "top" | "right"): { tick: number; title: number } {
+  return { tick: insetsOps.resolve(axis.tickPadding)[side], title: insetsOps.resolve(axis.titlePadding)[side] }
+}
+
+/**
+ * A column of right-aligned captions beside the plot: `place(i)` is caption
+ * `i`'s centre height in the column (y-up), whose height it is handed. The
+ * value axis and a horizontal bar chart's category axis are both this column.
+ */
+export function captionColumn(spec: {
+  readonly count: number
+  readonly axis: () => AxisConfig
+  readonly text: (i: number) => string
+  readonly place: (i: number, height: number) => number
+  readonly arrivals: () => Readonly<Record<string, Arrival>>
+  readonly opacity?: (i: number) => number
+  readonly label: string
+}): Node2D {
+  const pads = () => axisPads(spec.axis(), "right")
+  const markers = Array.from({ length: spec.count }, (_, i) => {
+    const column = () => (marker.parent as Node2D | null)?.layoutBounds ?? { width: 0, height: 0 }
+    const marker: Node2D = new Text({
+      ...boundText(() => spec.axis().labelStyle),
+      text: () => spec.text(i),
+      // Right-aligned against the tick padding: freeform children sit on the content box's centre.
+      x: () => (column().width - pads().tick) / 2 - marker.layoutBounds.width / 2 + arrivalOf(spec.arrivals(), i).shift,
+      y: () => spec.place(i, column().height),
+      opacity: () => arrivalOf(spec.arrivals(), i).opacity * (spec.opacity?.(i) ?? 1),
+    })
+    return marker
+  })
+  const children: Node2D[] = []
+  if (spec.label !== "") {
+    // Node2D space is y-up and rotation is clockwise, so -90° reads bottom-to-top.
+    children.push(
+      new RotatedBox({
+        angle: -90,
+        width: "hug",
+        height: "hug",
+        children: new Text({
+          ...boundText(() => spec.axis().titleStyle),
+          text: spec.label,
+          opacity: () => arrivalOf(spec.arrivals(), "label").opacity,
+          x: () => arrivalOf(spec.arrivals(), "label").shift,
+        }),
+      }) as unknown as Node2D
+    )
+  }
+  children.push(new Rect({ height: "fill", width: "hug", padding: () => ({ right: pads().tick }), children: markers }) as unknown as Node2D)
+  return new Rect({ flow: "horizontal", gap: () => pads().title, height: "fill", children }) as unknown as Node2D
+}
+
 /**
  * The numeric vertical axis the cartesian charts share: a column of {@link Text}
  * markers, highest at the top, each centred on its value's fraction across
- * `range`. Caption and position are bound, so a rescale tweens live; only the
- * marker count is fixed at construction. The resting state is landed.
+ * `range` and right-aligned against the plot. Caption and position are bound, so
+ * a rescale tweens live; only the marker count is fixed at construction. The
+ * resting state is landed.
  */
 export const VerticalAxis = component2d({
   key: "verticalAxis",
@@ -52,61 +106,26 @@ export const VerticalAxis = component2d({
   // A node made of markers would otherwise hug them.
   defaults: { width: "fill", height: "fill" },
   children: (state) => {
-    const tickPad = insetsOps.resolve(state.axis.tickPadding).right
-    const titlePad = insetsOps.resolve(state.axis.titlePadding).right
-
-    const row: Node2D[] = []
-    // The row's parent is the axis, whose box the markers are placed in.
-    const box = () => (row[0]?.parent as Node2D | null | undefined)?.layoutBounds ?? { width: 0, height: 0 }
     const sorted = () => [...state.markers].sort((a, b) => b - a)
     const fracAt = (value: number | undefined) => {
       if (value === undefined) return 0
       const [min, max] = state.range
       return max <= min ? 0 : (value - min) / (max - min)
     }
-
     // A slot with no value (the live list is shorter than the column built) renders empty, not its neighbour.
-    const markers = state.markers.map((_, i) => {
-      const marker: Node2D = new Text({
-        ...textOps.styleProps(state.axis.labelStyle),
-        text: () => {
+    return asParts([
+      captionColumn({
+        count: state.markers.length,
+        axis: () => state.axis,
+        text: (i) => {
           const value = sorted()[i]
           return value === undefined ? "" : markerCaption(state, value)
         },
-        y: () => {
-          // Node2D space is y-up, so the fraction runs from the bottom.
-          const height = box().height
-          const centred = (fracAt(sorted()[i]) - 0.5) * height
-          // Held inside the top edge for a theme whose markers are taller than the headroom; only the top, since the chart's own axis and legend lie below.
-          const limit = height / 2 - marker.layoutBounds.height / 2
-          return Math.min(centred, limit)
-        },
-        opacity: () => arrivalOf(state.arrivals, i).opacity,
-        x: () => arrivalOf(state.arrivals, i).shift,
-      })
-      return marker
-    })
-
-    const children: Node2D[] = []
-    if (state.label !== "") {
-      // Node2D space is y-up and rotation is clockwise, so -90° reads bottom-to-top.
-      children.push(
-        new RotatedBox({
-          angle: -90,
-          width: "hug",
-          height: "hug",
-          children: new Text({
-            ...textOps.styleProps(state.axis.titleStyle),
-            text: state.label,
-            opacity: () => arrivalOf(state.arrivals, "label").opacity,
-            x: () => arrivalOf(state.arrivals, "label").shift,
-          }),
-        })
-      )
-    }
-    children.push(new Rect({ height: "fill", width: "hug", padding: { right: tickPad }, children: markers }))
-    row.push(new Rect({ flow: "horizontal", gap: titlePad, children }))
-    return asParts(row)
+        place: (i, height) => (fracAt(sorted()[i]) - 0.5) * height,
+        arrivals: () => state.arrivals,
+        label: state.label,
+      }),
+    ])
   },
   commands: {
     /**

package/src/line-chart/chart-line.ts

@@ -1,67 +1,83 @@
 import {
   Graphics2D,
   Types,
+  clamp,
   component2d,
+  fillOps,
   strokeOps,
+  type Fill,
+  type FillResolved,
   type NodeOf,
   // Named so this component's emitted type reaches `Node2D` and its props through the sdk, not core.
   type Node2D as _Node2D,
   type Node2DProps as _Node2DProps,
+  type PathCommand,
+  type RenderContext,
   type Stroke,
   type StrokeResolved,
   type Vector2,
 } from "@motionscript/sdk"
 
+import { fade } from "../kit/cartesian"
 import { fresh } from "../kit/entries"
 import { frameEase } from "../kit/motion"
 import { loadPaints } from "../kit/paints"
 import { SPOTLIGHT_DIM } from "../kit/shared"
 import {
   EMPTY_REGION_BOX,
+  clipPolygonToBox,
   clipPolylineToBox,
+  cutAt,
+  curvePoints,
   hasRegion,
+  type LineCurve,
   type RegionBox,
 } from "./shared"
 
-/** The prefix of `pts` revealed at fraction `p`, measured by cumulative arc length so the trace keeps a steady pace over uneven spacing. */
-function tracePoints(pts: Vector2[], p: number): Vector2[] {
-  if (p >= 1 || pts.length < 2) return pts
-  if (p <= 0) return []
-
-  const segLen: number[] = []
-  let total = 0
-  for (let i = 1; i < pts.length; i++) {
-    const d = Math.hypot(pts[i].x - pts[i - 1].x, pts[i].y - pts[i - 1].y)
-    segLen.push(d)
-    total += d
-  }
-  if (total === 0) return pts
-
-  let target = total * p
-  const out: Vector2[] = [pts[0]]
-  for (let i = 0; i < segLen.length; i++) {
-    if (target >= segLen[i]) {
-      out.push(pts[i + 1])
-      target -= segLen[i]
-    } else {
-      const t = segLen[i] === 0 ? 0 : target / segLen[i]
-      out.push({
-        x: pts[i].x + (pts[i + 1].x - pts[i].x) * t,
-        y: pts[i].y + (pts[i + 1].y - pts[i].y) * t,
-      })
-      break
-    }
-  }
-  return out
+/** The x a trace at `progress` has reached, across `points` ordered along x. */
+export function traceX(points: readonly Vector2[], progress: number): number {
+  if (points.length === 0) return 0
+  const first = points[0].x
+  const last = points[points.length - 1].x
+  return progress >= 1 ? Infinity : first + (last - first) * progress
 }
 
-/** One series of a {@link LineChart}: a rounded polyline through pre-mapped pixel `points`, one {@link Graphics2D} command list. `progress` traces it in; `enabled` shows or hides it wholesale. */
+/** The drawn path at `progress`: the whole curve once traced, else the part left of the trace. */
+function traced(points: readonly Vector2[], curve: LineCurve, progress: number): Vector2[] {
+  const path = curvePoints(points, curve)
+  return progress >= 1 ? path : cutAt(path, traceX(points, progress))
+}
+
+const curveEntry = () => Types.custom<LineCurve>("smooth")
+
+/** A closed outline as path commands. */
+function outlineCommands(points: readonly Vector2[]): PathCommand[] {
+  return [...points.map((p, i): PathCommand => ({ type: i === 0 ? "M" : "L", x: p.x, y: p.y })), { type: "Z" }]
+}
+
+function fillOutline(ctx: RenderContext, outline: readonly Vector2[], fill: FillResolved[], opacity: number): void {
+  if (outline.length < 3 || opacity <= 0) return
+  const { width, height } = ctx.size
+  // A frame symmetric about the origin, so the outline draws where its points say rather than re-centred on itself.
+  const centerBounds: [number, number, number, number] = [-width / 2, -height / 2, width / 2, height / 2]
+  ctx.draw(new Graphics2D().path({ data: outlineCommands(outline), centerBounds }).fill(fill).opacity(opacity))
+}
+
+/**
+ * One series of a {@link LineChart}: its line through pre-mapped pixel `points`,
+ * shaped by `curve`, and a dot on each point. `progress` traces it in from the
+ * left; `enabled` shows or hides it wholesale.
+ */
 export const ChartLine = component2d({
   key: "chartLine",
   state: {
     /** In this node's pixel space (origin at centre, y-up), mapped by the parent and ordered along x. */
     points: fresh<Vector2[]>(() => []),
+    curve: curveEntry(),
     stroke: Types.custom<Stroke, StrokeResolved[]>([], { resolve: strokeOps.resolve, lerp: strokeOps.lerp }),
+    /** A dot of `dotSize` on each point, in `dotFill`; none at size 0. */
+    dotSize: 0,
+    dotFill: Types.custom<Fill, FillResolved[]>([], { resolve: fillOps.resolve, lerp: fillOps.lerp }),
     /** Trace from the left end, `[0, 1]`. Rests at 1 so a paused editor canvas paints the line; `enter` drives it from 0. */
     progress: 1,
     /** Whether the line is drawn at all, flipped alongside its legend entry. */
@@ -70,7 +86,7 @@ export const ChartLine = component2d({
     spotlight: fresh<RegionBox>(() => EMPTY_REGION_BOX),
     dimOpacity: SPOTLIGHT_DIM,
   },
-  load: (loader, state) => loadPaints(loader, { strokes: [state.stroke] }),
+  load: (loader, state) => loadPaints(loader, { fills: [state.dotFill], strokes: [state.stroke] }),
   commands: {
     /**
      * Trace the line from `from` to `to`; `showSeries`/`hideSeries` are this with
@@ -90,39 +106,145 @@ export const ChartLine = component2d({
         })
       },
     },
+    /** Hold the line fully traced while its chart moves it, switched on throughout a show and off once a hide lands. */
+    hold: {
+      args: { shown: Types.boolean(true) },
+      run: (timeline) => {
+        const { shown } = timeline.args
+        return timeline.animate((t) => ({ progress: 1, enabled: shown || t < 1 }), { eased: false })
+      },
+    },
   },
   render: (ctx, state) => {
     if (!state.enabled) return
     const pts = state.points
-    if (pts.length < 2) return
-
-    const p = Math.max(0, Math.min(1, state.progress))
-    if (p <= 0) return
+    const p = clamp(state.progress, 0, 1)
+    if (pts.length === 0 || p <= 0) return
 
-    const drawn = tracePoints(pts, p)
-    if (drawn.length < 2) return
+    const box = state.spotlight
+    const lit = hasRegion(box)
+    const dim = clamp(state.dimOpacity, 0, 1)
     const stroke = state.stroke
-    const radius = (stroke[0]?.weight ?? 0) * 2
+    const weight = stroke[0]?.weight ?? 0
+    const drawn = traced(pts, state.curve, p)
 
-    const box = state.spotlight
-    if (!hasRegion(box)) {
-      ctx.draw(new Graphics2D().line({ points: drawn, radius }).stroke(stroke))
-      return
+    if (drawn.length >= 2 && weight > 0) {
+      // Rounded corners only where the line has corners to round.
+      const radius = state.curve === "linear" ? weight * 2 : 0
+      ctx.draw(new Graphics2D().line({ points: drawn, radius }).stroke(stroke).opacity(lit ? dim : 1))
+      // One `draw` per run: shapes chained before `stroke()` combine into one surface, and stroking a union of disjoint open paths paints nothing.
+      if (lit) for (const run of clipPolylineToBox(drawn, box)) ctx.draw(new Graphics2D().line({ points: run, radius }).stroke(stroke))
     }
 
-    // Dim the whole line, then redraw the stretches inside the region at full strength: the bright run keeps continuous geometry and round joins, and the boundary lands on the region edge.
-    ctx.draw(
-      new Graphics2D()
-        .line({ points: drawn, radius })
-        .stroke(stroke)
-        .opacity(Math.max(0, Math.min(1, state.dimOpacity)))
-    )
-
-    // One `draw` per run: shapes chained before `stroke()` combine into one surface, and stroking a union of disjoint open paths paints nothing.
-    for (const run of clipPolylineToBox(drawn, box)) {
-      ctx.draw(new Graphics2D().line({ points: run, radius }).stroke(stroke))
+    const size = state.dotSize
+    if (size <= 0) return
+    const reach = traceX(pts, p)
+    const bright = new Graphics2D()
+    const dimmed = new Graphics2D()
+    let brightAny = false
+    let dimAny = false
+    for (const pt of pts) {
+      // A dot grows in as the trace passes it.
+      const grown = reach === Infinity ? 1 : clamp((reach - pt.x) / (size * 2), 0, 1)
+      if (grown <= 0) continue
+      const inside = !lit || (pt.x >= box.left && pt.x <= box.right && pt.y >= box.bottom && pt.y <= box.top)
+      ;(inside ? bright : dimmed).ellipse({ x: pt.x, y: pt.y, width: size * grown, height: size * grown })
+      if (inside) brightAny = true
+      else dimAny = true
     }
+    if (dimAny) ctx.draw(dimmed.fill(state.dotFill).opacity(dim))
+    if (brightAny) ctx.draw(bright.fill(state.dotFill))
   },
 })
 
 export type ChartLine = NodeOf<typeof ChartLine>
+
+/**
+ * The fill under one series of a {@link LineChart}: down to `base` (the series
+ * below it in a stack) or, without one, to the `baseline`. Drawn by its own node
+ * so every area sits under every line; the chart binds its trace, switch and
+ * opacity to its line's, so the two move as one.
+ */
+export const ChartArea = component2d({
+  key: "chartArea",
+  state: {
+    /** The series' points, as its line has them. */
+    points: fresh<Vector2[]>(() => []),
+    /** The line the area fills down to, at the same x positions; empty for the baseline. */
+    base: fresh<Vector2[]>(() => []),
+    /** Pixel y of the baseline. */
+    baseline: 0,
+    curve: curveEntry(),
+    area: Types.custom<"none" | "solid" | "gradient">("solid"),
+    /** The series colour; the area paints it at `areaOpacity`, a gradient fading it out towards the bottom. */
+    fill: Types.custom<Fill, FillResolved[]>([], { resolve: fillOps.resolve, lerp: fillOps.lerp }),
+    areaOpacity: 0.4,
+    progress: 1,
+    enabled: true,
+    spotlight: fresh<RegionBox>(() => EMPTY_REGION_BOX),
+    dimOpacity: SPOTLIGHT_DIM,
+  },
+  load: (loader, state) => loadPaints(loader, { fills: [state.fill] }),
+  render: (ctx, state) => {
+    const pts = state.points
+    const p = clamp(state.progress, 0, 1)
+    if (!state.enabled || state.area === "none" || pts.length < 2 || p <= 0 || state.fill.length === 0) return
+    const outlineAt = (progress: number) => {
+      const top = traced(pts, state.curve, progress)
+      if (top.length < 2) return []
+      const base = state.base.length === pts.length
+        ? traced(state.base, state.curve, progress)
+        : [{ x: top[0].x, y: state.baseline }, { x: top[top.length - 1].x, y: state.baseline }]
+      return [...top, ...[...base].reverse()]
+    }
+    // The gradient spans the whole area's height, so it holds still while the area traces in and across a spotlight's cut.
+    const span = verticalSpan(outlineAt(1))
+    const paint = (outline: readonly Vector2[], opacity: number) =>
+      fillOutline(ctx, outline, areaFill(state.fill, state.area, state.areaOpacity, span, verticalSpan(outline)), opacity)
+    const outline = outlineAt(p)
+    const box = state.spotlight
+    if (!hasRegion(box)) {
+      paint(outline, 1)
+      return
+    }
+    paint(outline, clamp(state.dimOpacity, 0, 1))
+    paint(clipPolygonToBox(outline, box), 1)
+  },
+})
+
+interface Span {
+  readonly top: number
+  readonly bottom: number
+}
+
+function verticalSpan(points: readonly Vector2[]): Span {
+  let top = -Infinity
+  let bottom = Infinity
+  for (const p of points) {
+    if (p.y > top) top = p.y
+    if (p.y < bottom) bottom = p.y
+  }
+  return { top, bottom }
+}
+
+/**
+ * The area's paint for an outline spanning `own`: the series colour at
+ * `opacity`, or for a gradient that colour fading to nearly nothing across
+ * `whole`. A gradient maps onto the bounds of the shape it fills, so its ends
+ * are placed in `own`'s unit box (y-up) at `whole`'s top and bottom.
+ */
+export function areaFill(colour: FillResolved[], area: "none" | "solid" | "gradient", opacity: number, whole: Span, own: Span): FillResolved[] {
+  const top = colour[colour.length - 1]
+  if (area !== "gradient" || top?.type !== "solid" || !(own.top > own.bottom)) return fade(colour, opacity) as FillResolved[]
+  const [r, g, b, a] = top.color
+  const middle = (own.top + own.bottom) / 2
+  const half = (own.top - own.bottom) / 2
+  return fillOps.resolve({
+    type: "linear-gradient",
+    colors: [[r, g, b, a * opacity], [r, g, b, a * opacity * 0.04]],
+    start: { x: 0, y: (whole.top - middle) / half },
+    end: { x: 0, y: (whole.bottom - middle) / half },
+  })
+}
+
+export type ChartArea = NodeOf<typeof ChartArea>

package/src/line-chart/chart-region.ts

@@ -14,10 +14,10 @@ import {
   type StrokeResolved,
 } from "@motionscript/sdk"
 
+import { rule } from "../kit/chart-canvas"
 import { fresh } from "../kit/entries"
 import { loadPaints } from "../kit/paints"
 import {
-  DEFAULT_CHART_THEME,
   EMPTY_REGION_BOX,
   hasRegion,
   type RegionBox,
@@ -26,7 +26,7 @@ import {
 /**
  * The call-out of a {@link LineChart}: a washed rectangle with a dashed rule on
  * each bounded edge, drawn from the pre-mapped `box`. Dimming the series outside
- * is {@link ChartLine}'s job, clipped against the same box so the two agree on
+ * is the line's and area's job, clipped against the same box so they agree on
  * the boundary. An unbounded edge is the plot's own border, and a rule there
  * would assert a limit the author did not set.
  */
@@ -35,8 +35,8 @@ export const ChartRegion = component2d({
   state: {
     /** In this node's pixel space (origin at centre, y-up), mapped by the parent. A degenerate box draws nothing. */
     box: fresh<RegionBox>(() => EMPTY_REGION_BOX),
-    stroke: Types.custom<Stroke, StrokeResolved[]>(DEFAULT_CHART_THEME.region.stroke, { resolve: strokeOps.resolve, lerp: strokeOps.lerp }),
-    fill: Types.custom<Fill, FillResolved[]>(DEFAULT_CHART_THEME.region.fill, { resolve: fillOps.resolve, lerp: fillOps.lerp }),
+    stroke: Types.custom<Stroke, StrokeResolved[]>({ weight: 2, fill: "white/70", dash: [14, 12], cap: "butt", align: "center" }, { resolve: strokeOps.resolve, lerp: strokeOps.lerp }),
+    fill: Types.custom<Fill, FillResolved[]>("white/6", { resolve: fillOps.resolve, lerp: fillOps.lerp }),
     /** Driven by the chart's `regionReveal`, so the rules and the series' dimming move as one. */
     reveal: 0,
   },
@@ -59,17 +59,13 @@ export const ChartRegion = component2d({
 
     if (state.stroke.length === 0) return
 
-    // One `draw` per rule: stroking a union of disjoint open paths paints nothing.
-    const rule = (points: { x: number; y: number }[]) =>
-      ctx.draw(new Graphics2D().line({ points }).stroke(state.stroke).opacity(r))
-
     if (box.xBounded) {
       const half = (height / 2) * r
-      for (const x of [box.left, box.right]) rule([{ x, y: cy - half }, { x, y: cy + half }])
+      for (const x of [box.left, box.right]) rule(ctx, { x, y: cy - half }, { x, y: cy + half }, state.stroke, r)
     }
     if (box.yBounded) {
       const half = (width / 2) * r
-      for (const y of [box.bottom, box.top]) rule([{ x: cx - half, y }, { x: cx + half, y }])
+      for (const y of [box.bottom, box.top]) rule(ctx, { x: cx - half, y }, { x: cx + half, y }, state.stroke, r)
     }
   },
 })

package/src/line-chart/index.ts

@@ -1,27 +1,31 @@
 export { LineChart, lineChartDomains } from "./line-chart"
-export type { LineChartDomains, LineChartValues } from "./line-chart"
+export type { LineChartDomains, LineChartStyle, LineChartValues } from "./line-chart"
 export { ChartRegion } from "./chart-region"
-export { ChartLine } from "./chart-line"
-export { HorizontalAxis } from "./horizontal-axis"
+export { ChartArea, ChartLine, areaFill, traceX } from "./chart-line"
 export {
-  DEFAULT_CHART_THEME,
   EMPTY_REGION_BOX,
+  LINE_LABELS,
+  LINE_MARKS,
+  clipPolygonToBox,
   clipPolylineToBox,
+  curvePoints,
+  cutAt,
   hasRegion,
-  lerpChartTheme,
-  resolveChartTheme,
+
   resolveRegionBox,
   resolveYScale,
   seriesPoints,
+  stackExtent,
+  stackSeries,
   yExtent,
 } from "./shared"
 export type {
-  ChartConfig,
-  ChartTheme,
+  LineCurve,
   LineSeries,
+  LineStack,
   PlotRegion,
   RegionBox,
-  RegionConfig,
+  StackedSeries,
 } from "./shared"
-export { formatInstant, parseInstant, resolveXScale } from "./x-scale"
+export { EVERY_SAMPLE, formatInstant, parseInstant, resolveXScale } from "./x-scale"
 export type { XScale, XScaleKind } from "./x-scale"