@motionscript/charts 0.1.0-alpha.5 → 0.1.0-alpha.7

package/src/bar-chart/index.ts

@@ -5,8 +5,8 @@
  * which is what lets a scene swap one for the other without re-theming — and
  * brings its own category axis, since a band scale is not a continuous one.
  */
-export { BarChart } from "./bar-chart"
-export type { BarChartProps } from "./bar-chart"
+export { BarChart, barChartDomain } from "./bar-chart"
+export type { BarChartDomain, BarChartProps, BarChartValues } from "./bar-chart"
 export { ChartBars } from "./chart-bars"
 export type { BarGeometry, ChartBarsProps } from "./chart-bars"
 export { CategoryAxis } from "./category-axis"

package/src/bar-chart/shared.ts

@@ -9,7 +9,7 @@
  *
  * Kept renderer-agnostic (no `Node` imports) so a host's inspector mapping
  * can build a partial {@link BarChartTheme} without
- * pulling the node classes in.
+ * pulling the components in.
  */
 
 import {
@@ -294,7 +294,7 @@ function lerpBarStyle(
 }
 
 /**
- * {@link BarChart}'s `theme` @property mapper: merges the author's partial
+ * {@link BarChart}'s `theme` entry's resolve: merges the author's partial
  * {@link BarChartTheme} onto `previous` (falling back to
  * {@link DEFAULT_BAR_CHART_THEME} on first resolution), fully resolving every
  * leaf so the tween below always has resolved data to interpolate.
@@ -318,7 +318,7 @@ export function resolveBarChartTheme(
   }
 }
 
-/** {@link BarChart}'s `theme` @property tween — leaf by leaf. */
+/** {@link BarChart}'s `theme` entry's lerp — leaf by leaf. */
 export function lerpBarChartTheme(
   from: BarChartConfig,
   to: BarChartConfig,

package/src/engine.ts

@@ -7,20 +7,22 @@
  * axis, the legend and the number formatting stay a real dependency. That is
  * not a size decision — it is the only arrangement that works.
  *
- * A chart identifies its own parts, and the engine keys signal machinery to
- * class identity: `@property` installs against the class it was applied with,
- * and the renderer asks `instanceof` about what it is drawing. Copy
- * `VerticalAxis` alongside your fork and there are now two of it — two classes
- * answering one name, and whichever one your chart did not get renders as
- * nothing at all, with no error. Keeping the kit external makes that
+ * A chart identifies its own parts by component identity (`VerticalAxis.is`).
+ * Copy `VerticalAxis` alongside your fork and there are now two of it — two
+ * components answering one name, and whichever one your chart did not get is
+ * a part it never finds, with no error. Keeping the kit external makes that
  * impossible rather than unlikely.
  *
  * It also means a fix to the axis reaches a forked chart without a re-add,
  * which is the half of the bargain you get back for it.
  */
 export * from "./kit/shared"
+export * from "./kit/cartesian"
 export * from "./kit/chart-border"
 export * from "./kit/chart-canvas"
 export * from "./kit/chart-legend"
+export * from "./kit/entries"
+export * from "./kit/motion"
+export * from "./kit/paints"
 export * from "./kit/vertical-axis"
 export * from "@motionscript/sdk/component"

package/src/kit/cartesian.ts

@@ -0,0 +1,81 @@
+import { Rect, type ChildView, type Node2D, type Size2D } from "@motionscript/sdk"
+
+import { VerticalAxis } from "./vertical-axis"
+
+/**
+ * Headroom above the plot, in px.
+ *
+ * Two jobs, and the second is why it is real padding on the composition rather
+ * than a number the point-mapping math imagines: a series peaking at the top of
+ * the scale isn't flush to the top edge, **and** the top marker, which is
+ * centred on that top grid line, has somewhere to be. Without it the marker's
+ * upper half is drawn above the chart's own box.
+ */
+export const TOP_HEADROOM = 24
+
+/** The parts of a cartesian chart's frame, as {@link cartesianFrame} arranges them. */
+export interface CartesianParts {
+  /** The value axis, left of the plot. */
+  readonly axis: Node2D
+  /** The plot panel: the box the grid and the marks share. */
+  readonly plot: Node2D
+  /** An invisible twin of the value axis, reserving its gutter under the plot. */
+  readonly gutter: Node2D
+  /** What sits under the plot, top to bottom: the other axis, then the legend. */
+  readonly below: readonly Node2D[]
+}
+
+/**
+ * The frame the line and bar charts share: the value axis beside the plot, and
+ * under them the gutter beside the rows below the plot, so those rows start at
+ * the plot's left edge rather than the chart's.
+ */
+export function cartesianFrame(parts: CartesianParts): Node2D {
+  return new Rect({
+    flow: "vertical",
+    width: "fill",
+    height: "fill",
+    padding: { top: TOP_HEADROOM },
+    children: [
+      new Rect({ flow: "horizontal", height: "fill", width: "fill", children: [parts.axis, parts.plot] }),
+      new Rect({
+        flow: "horizontal",
+        width: "fill",
+        children: [parts.gutter, new Rect({ flow: "vertical", width: "fill", gap: 20, children: [...parts.below] })],
+      }),
+    ],
+  }) as unknown as Node2D
+}
+
+/** A cartesian frame's parts, as a command reaches them through its chart's children. */
+export interface CartesianViews {
+  readonly axis: ChildView
+  /** The plot panel's own children: the grid, the marks, the border. */
+  readonly plot: readonly ChildView[]
+  readonly below: readonly ChildView[]
+}
+
+/**
+ * The frame among a chart's children: the last child shaped as
+ * {@link cartesianFrame} builds it. The chart builds it after the children it
+ * was given, and a document adds its own later still, so it is found by shape.
+ */
+export function cartesianViews(children: readonly ChildView[]): CartesianViews | null {
+  for (let i = children.length - 1; i >= 0; i--) {
+    const frame = children[i]
+    if (!Rect.is(frame)) continue
+    const [top, bottom] = frame.children
+    const axis = top?.children[0]
+    const plot = top?.children[1]
+    const below = bottom?.children[1]
+    if (!axis || !VerticalAxis.is(axis) || !plot || !below) continue
+    return { axis, plot: plot.children, below: below.children }
+  }
+  return null
+}
+
+/** A part's laid-out size, or nothing before it is built or laid out. */
+export function laidOutSize(node: Node2D | undefined): Size2D {
+  const bounds = node?.layoutBounds
+  return { width: bounds?.width ?? 0, height: bounds?.height ?? 0 }
+}

package/src/kit/chart-border.ts

@@ -1,16 +1,18 @@
 import {
-  type AssetScope,
   Graphics2D,
-  Node2D,
+  Types,
+  component2d,
   strokeOps,
-  property,
+  type NodeOf,
+  // Named so this component's emitted type reaches `Node2D` through the sdk, not core.
+  type Node2D as _Node2D,
   type Node2DProps,
-  type RenderContext2D,
   type Stroke,
+  type StrokeResolved,
 } from "@motionscript/sdk"
 
+import { loadPaints } from "./paints"
 import { DEFAULT_PLOT_AREA } from "./shared"
-import { declarePaints } from "@motionscript/sdk/component"
 
 export interface ChartBorderProps extends Node2DProps {
   /**
@@ -23,39 +25,26 @@ export interface ChartBorderProps extends Node2DProps {
 
 /**
  * The thick **frame** around a cartesian chart's plot: an empty rect wearing an
- * inside stroke, sized from its allocated `layoutBounds`.
+ * inside stroke, sized from its box.
  *
  * Split out of {@link ChartCanvas} (the filled + gridded backdrop) so it can be
  * placed *after* the marks in the tree — the box then frames the plot **over**
  * them, so a line or a column running to the edge tucks cleanly under the border
  * rather than sitting on top of it.
  */
-export class ChartBorder extends Node2D<ChartBorderProps> {
-  @property({
-    default: DEFAULT_PLOT_AREA.stroke,
-    mapper: strokeOps.resolve,
-    tween: strokeOps.lerp,
-  })
-  declare stroke: Stroke
-
-  /**
-   * This node extends `Node2D` rather than `ShapeNode`, so nothing declares the
-   * paint props it carries — see {@link declarePaints}.
-   */
-  override declareAssets(assets: AssetScope): void {
-    super.declareAssets(assets)
-    declarePaints(this, assets)
-  }
-
-  protected renderSelf(ctx: RenderContext2D): void {
-    const W = this.layoutBounds.width
-    const H = this.layoutBounds.height
-    if (W <= 0 || H <= 0) return
-
+export const ChartBorder = component2d({
+  key: "chartBorder",
+  state: {
+    stroke: Types.custom<Stroke, StrokeResolved[]>(DEFAULT_PLOT_AREA.stroke, { resolve: strokeOps.resolve, lerp: strokeOps.lerp }),
+  },
+  load: (loader, state) => loadPaints(loader, { strokes: [state.stroke] }),
+  render: (ctx, state) => {
+    const { width, height } = ctx.size
+    if (width <= 0 || height <= 0) return
     // Empty rect (no fill) with the themed stroke, so the frame sits over the
     // marks but the box interior stays clear.
-    ctx.draw(
-      new Graphics2D().rect({ x: 0, y: 0, width: W, height: H }).stroke(this.stroke)
-    )
-  }
-}
+    ctx.draw(new Graphics2D().rect({ x: 0, y: 0, width, height }).stroke(state.stroke))
+  },
+})
+
+export type ChartBorder = NodeOf<typeof ChartBorder>

package/src/kit/chart-canvas.ts

@@ -1,26 +1,30 @@
 import {
-  type AssetScope,
   Graphics2D,
-  Node2D,
+  Types,
+  component2d,
   fillOps,
   shadowOps,
   strokeOps,
-  property,
   type Fill,
+  type FillResolved,
+  type NodeOf,
+  // Named so this component's emitted type reaches `Node2D` through the sdk, not core.
+  type Node2D as _Node2D,
   type Node2DProps,
-  type RenderContext2D,
   type Shadow,
+  type ShadowResolved,
   type Stroke,
   type StrokeResolved,
 } from "@motionscript/sdk"
 
+import { fresh } from "./entries"
+import { loadPaints } from "./paints"
 import {
   DEFAULT_PLOT_AREA,
   DEFAULT_X_AXIS,
   DEFAULT_Y_AXIS,
   type Range,
 } from "./shared"
-import { declarePaints } from "@motionscript/sdk/component"
 
 export interface ChartCanvasProps extends Node2DProps {
   /** Fill of the plot panel behind the marks. */
@@ -47,11 +51,13 @@ export interface ChartCanvasProps extends Node2DProps {
   yExtent: Range
 }
 
+const strokeEntry = (initial: Stroke) =>
+  Types.custom<Stroke, StrokeResolved[]>(initial, { resolve: strokeOps.resolve, lerp: strokeOps.lerp })
+
 /**
  * The plot **backdrop** of a cartesian chart: a filled panel with a grid of
- * faint lines spanning both directions across it. Drawn as one {@link Graphics2D}
- * command list, sized from its allocated `layoutBounds` and centred on the node
- * origin.
+ * faint lines spanning both directions across it, sized from its box and centred
+ * on its origin.
  *
  * The thick frame is a **separate** {@link ChartBorder} node so it can be drawn
  * *over* the marks while this panel sits under them. Grid lines are placed from
@@ -59,99 +65,58 @@ export interface ChartCanvasProps extends Node2DProps {
  * {@link ChartCanvasProps.xExtent}/`yExtent` — so each line lands under its
  * marker whether or not the markers are evenly spaced.
  */
-export class ChartCanvas extends Node2D<ChartCanvasProps> {
-  @property({
-    default: DEFAULT_PLOT_AREA.fill,
-    mapper: fillOps.resolve,
-    tween: fillOps.lerp,
-  })
-  declare fill: Fill
-  @property({
-    default: DEFAULT_PLOT_AREA.shadow,
-    mapper: shadowOps.resolve,
-    tween: shadowOps.lerp,
-  })
-  declare shadow: Shadow
-  @property({
-    default: DEFAULT_X_AXIS.lineStyle,
-    mapper: strokeOps.resolve,
-    tween: strokeOps.lerp,
-  })
-  declare xGridStroke: Stroke
-  @property({
-    default: DEFAULT_Y_AXIS.lineStyle,
-    mapper: strokeOps.resolve,
-    tween: strokeOps.lerp,
-  })
-  declare yGridStroke: Stroke
-  @property({ default: () => [] as number[] }) declare xMarkers: number[]
-  @property({ default: () => [] as number[] }) declare yMarkers: number[]
-  @property({ default: () => [0, 1] as Range }) declare xExtent: Range
-  @property({ default: () => [0, 1] as Range }) declare yExtent: Range
-
-  /**
-   * This node extends `Node2D` rather than `ShapeNode`, so nothing declares the
-   * paint props it carries — see {@link declarePaints}. The grid strokes are
-   * named past the conventional slots, so they are passed explicitly.
-   */
-  override declareAssets(assets: AssetScope): void {
-    super.declareAssets(assets)
-    declarePaints(this, assets, {
-      strokes: [this.xGridStroke as StrokeResolved[], this.yGridStroke as StrokeResolved[]],
-    })
-  }
-
-  protected renderSelf(ctx: RenderContext2D): void {
-    const W = this.layoutBounds.width
-    const H = this.layoutBounds.height
+export const ChartCanvas = component2d({
+  key: "chartCanvas",
+  state: {
+    fill: Types.custom<Fill, FillResolved[]>(DEFAULT_PLOT_AREA.fill, { resolve: fillOps.resolve, lerp: fillOps.lerp }),
+    shadow: Types.custom<Shadow, ShadowResolved[]>(DEFAULT_PLOT_AREA.shadow, { resolve: shadowOps.resolve, lerp: shadowOps.lerp }),
+    xGridStroke: strokeEntry(DEFAULT_X_AXIS.lineStyle),
+    yGridStroke: strokeEntry(DEFAULT_Y_AXIS.lineStyle),
+    xMarkers: fresh<number[]>(() => []),
+    yMarkers: fresh<number[]>(() => []),
+    xExtent: fresh<Range>(() => [0, 1]),
+    yExtent: fresh<Range>(() => [0, 1]),
+  },
+  // The grid strokes are named past the conventional slots, so they are named here.
+  load: (loader, state) =>
+    loadPaints(loader, { fills: [state.fill], shadows: [state.shadow], strokes: [state.xGridStroke, state.yGridStroke] }),
+  render: (ctx, state) => {
+    const { width: W, height: H } = ctx.size
     if (W <= 0 || H <= 0) return
 
     // Plot panel, centred on the origin (node space is y-up, origin centre).
-    ctx.draw(
-      new Graphics2D()
-        .rect({ x: 0, y: 0, width: W, height: H })
-        .shadow(this.shadow)
-        .fill(this.fill)
-    )
+    ctx.draw(new Graphics2D().rect({ x: 0, y: 0, width: W, height: H }).shadow(state.shadow).fill(state.fill))
 
-    const [xMin, xMax] = this.xExtent
-    const [yMin, yMax] = this.yExtent
+    const [xMin, xMax] = state.xExtent
+    const [yMin, yMax] = state.yExtent
     // Fraction of a marker across its extent; guard a zero-width extent.
     const xFrac = (v: number) => (xMax <= xMin ? 0 : (v - xMin) / (xMax - xMin))
     const yFrac = (v: number) => (yMax <= yMin ? 0 : (v - yMin) / (yMax - yMin))
     // Skip markers landing on (or outside) the edges — they'd sit under the border.
     const interior = (f: number) => f > 1e-6 && f < 1 - 1e-6
 
-    const xStroke = (this.xGridStroke as StrokeResolved[])[0]
+    const xStroke = state.xGridStroke[0]
     if (xStroke) {
       const xGrid = new Graphics2D()
-      for (const v of this.xMarkers) {
+      for (const v of state.xMarkers) {
         const f = xFrac(v)
         if (!interior(f)) continue
-        xGrid.rect({
-          x: -W / 2 + f * W,
-          y: 0,
-          width: xStroke.weight,
-          height: H,
-        })
+        xGrid.rect({ x: -W / 2 + f * W, y: 0, width: xStroke.weight, height: H })
       }
       ctx.draw(xGrid.fill(xStroke.fill))
     }
 
-    const yStroke = (this.yGridStroke as StrokeResolved[])[0]
+    const yStroke = state.yGridStroke[0]
     if (yStroke) {
       const yGrid = new Graphics2D()
-      for (const v of this.yMarkers) {
+      for (const v of state.yMarkers) {
         const f = yFrac(v)
         if (!interior(f)) continue
-        yGrid.rect({
-          x: 0,
-          y: -H / 2 + f * H,
-          width: W,
-          height: yStroke.weight,
-        })
+        yGrid.rect({ x: 0, y: -H / 2 + f * H, width: W, height: yStroke.weight })
       }
       ctx.draw(yGrid.fill(yStroke.fill))
     }
-  }
-}
+  },
+})
+
+export type ChartCanvas = NodeOf<typeof ChartCanvas>