@motionscript/charts 0.0.0-stage → 0.1.0-alpha.0

package/src/bar-chart/shared.ts

@@ -0,0 +1,354 @@
+/**
+ * Types and pure helpers specific to the {@link BarChart} family: how a row's
+ * values become the spans its columns cover, how the value axis is scaled around
+ * them, and the theme the bars add to the shared chart vocabulary.
+ *
+ * Everything a line or a pie chart would want too — what a series is, the axis
+ * domain model, the theme leaf resolvers, the legend and plot-panel branches —
+ * lives in `nodes/chart-kit/shared.ts` and is imported here.
+ *
+ * Kept renderer-agnostic (no `Node` imports) so the studio's inspector mapping
+ * (`bar-chart-props.ts`) can build a partial {@link BarChartTheme} without
+ * pulling the node classes in.
+ */
+
+import {
+  fillOps,
+  lerpNumber,
+  shadowOps,
+  strokeOps,
+  textOps,
+  type DataRecord,
+  type Fill,
+  type Shadow,
+  type ShadowResolved,
+  type Stroke,
+  type StrokeResolved,
+  type TextStyle,
+} from "@motionscript/core"
+
+import {
+  CHART_PALETTE,
+  DEFAULT_LEGEND,
+  DEFAULT_PLOT_AREA,
+  DEFAULT_SERIES_FILLS,
+  DEFAULT_X_AXIS,
+  DEFAULT_Y_AXIS,
+  SPOTLIGHT_DIM,
+  lerpAxisConfig,
+  lerpLegendConfig,
+  lerpPlotArea,
+  lerpSeriesFills,
+  niceStep,
+  num,
+  resolveAxisConfig,
+  resolveLegendConfig,
+  resolvePlotArea,
+  resolveSeriesFills,
+  text,
+  type AxisConfig,
+  type ChartSeries,
+  type LegendConfig,
+  type LegendTheme,
+  type PlotAreaConfig,
+  type Range,
+} from "../kit/shared"
+
+/**
+ * One series in a {@link BarChart}: a column of the table drawn as one bar per
+ * row — side by side with its siblings within each category's slot, or stacked
+ * on top of them.
+ *
+ * The family-wide {@link ChartSeries} under a name that says what it draws here.
+ */
+export type BarSeries = ChartSeries
+
+/**
+ * One drawn bar's span in **data units**: the value its base sits at and the
+ * value its far end reaches.
+ *
+ * A span rather than a height because that is the one shape both modes fit. A
+ * grouped bar runs from zero to its value; a stacked segment runs from the
+ * running total below it to that total plus its own value. Negative values fall
+ * out of the same arithmetic — the span simply runs the other way — so a chart
+ * with a loss in it needs no special case, only a baseline that isn't the floor.
+ */
+export interface BarSpan {
+  /** Value the bar's base sits at — 0 when grouped, the running total when stacked. */
+  from: number
+  /** Value its far end reaches. */
+  to: number
+  /** The value this bar plots — `to - from`, kept for the figure printed on it. */
+  value: number
+}
+
+/**
+ * The spans one row's bars cover, one per series, in series order.
+ *
+ * Stacking is a running sum in the order the series are listed, which is also
+ * the order they're drawn: series 0 sits on the baseline and each later one
+ * rides on what's below it. A zero-valued series still yields a (degenerate)
+ * span so the returned list stays index-aligned with the series list.
+ */
+export function barSpans(
+  row: DataRecord,
+  series: BarSeries[],
+  stacked: boolean
+): BarSpan[] {
+  let running = 0
+  return series.map((s) => {
+    const value = num(row, s.field)
+    if (!stacked) return { from: 0, to: value, value }
+    const from = running
+    running += value
+    return { from, to: running, value }
+  })
+}
+
+/**
+ * The index of the series whose segment ends a row's stack — the one that gets
+ * the rounded cap, so a stack reads as one capped column rather than a pile of
+ * separate boxes. `-1` when every value in the row is zero.
+ *
+ * Read off the *last non-zero* series rather than the last one listed, so a
+ * series that happens to be 0 in this row doesn't take the cap and leave the
+ * segment below it square.
+ */
+export function stackCapIndex(row: DataRecord, series: BarSeries[]): number {
+  let last = -1
+  for (let i = 0; i < series.length; i++) {
+    if (num(row, series[i].field) !== 0) last = i
+  }
+  return last
+}
+
+/** The captions beneath the baseline: one per row, read off the category column. */
+export function barCategories(data: DataRecord[], field: string): string[] {
+  return data.map((row) => text(row, field))
+}
+
+/**
+ * The `[min, max]` of everything the chart draws, **zero always included**.
+ *
+ * Zero is in the range whatever the data says, because a bar chart's baseline is
+ * zero: a scale starting at 40 draws a column three times its neighbour for a
+ * 10% difference, which is the classic way to lie with one. A chart that really
+ * does want a cropped axis says so with an explicit range.
+ */
+export function barValueExtent(
+  data: DataRecord[],
+  series: BarSeries[],
+  stacked: boolean
+): Range {
+  let lo = 0
+  let hi = 0
+  for (const row of data) {
+    for (const span of barSpans(row, series, stacked)) {
+      lo = Math.min(lo, span.from, span.to)
+      hi = Math.max(hi, span.from, span.to)
+    }
+  }
+  return lo < hi ? [lo, hi] : [0, 1]
+}
+
+/**
+ * Effective value scale: the explicit `range`, else the data's extent nudged out
+ * to tidy step bounds so the markers read as round numbers.
+ *
+ * `divisions` is how many segments the auto-range is stepped into (one fewer
+ * than the marker count), so the ticks the axis draws land on the bounds this
+ * picks.
+ */
+export function resolveBarScale(
+  data: DataRecord[],
+  series: BarSeries[],
+  stacked: boolean,
+  range: Range | undefined,
+  divisions: number
+): Range {
+  if (range) return range
+  const [lo, hi] = barValueExtent(data, series, stacked)
+  const segments = Math.max(1, Math.round(divisions))
+  const step = niceStep((hi - lo) / segments || 1)
+  return [Math.floor(lo / step) * step, Math.ceil(hi / step) * step]
+}
+
+// ---- Theme ---------------------------------------------------------------
+
+/** How the columns themselves are drawn and how the slot is divided up. */
+export interface BarStyleConfig {
+  /**
+   * Radius of a column's far-end corners, in px. Only the outer end rounds — an
+   * interior stacked segment stays square, so the stack reads as one column.
+   */
+  cornerRadius: number
+  /**
+   * Fraction of its category's slot the bars fill, `[0, 1]`. The remainder is
+   * the channel between one category and the next, which is what makes a bar
+   * chart read as groups rather than as a solid block.
+   */
+  slotFill: number
+  /** Gap between the grouped bars *within* one slot, in px. Ignored when stacked. */
+  groupGap: number
+  /** Optional outline on every column. */
+  stroke: Stroke
+  /** Optional drop shadow on every column. */
+  shadow: Shadow
+}
+
+/** A {@link BarChart}'s full, resolved visual theme. */
+export interface BarChartConfig {
+  /**
+   * Default per-series bar paint, cycled by series index (`i % length`). A
+   * series' own `fill`, when set, replaces its entry outright.
+   */
+  seriesFills: Fill[]
+  bar: BarStyleConfig
+  /** The category axis beneath the baseline. */
+  xAxis: AxisConfig
+  /** The numeric value axis up the left. */
+  yAxis: AxisConfig
+  plotArea: PlotAreaConfig
+  legend: LegendConfig
+  /** The figure printed on each column, when the chart prints them. */
+  valueStyle: TextStyle
+  /** How far everything *outside* a spotlit series or category fades. */
+  spotlight: { dimOpacity: number }
+}
+
+/** Author-facing partial theme — every branch optional and deep-merged. */
+export type BarChartTheme = {
+  seriesFills?: Fill[]
+  bar?: Partial<BarStyleConfig>
+  xAxis?: Partial<AxisConfig>
+  yAxis?: Partial<AxisConfig>
+  plotArea?: Partial<PlotAreaConfig>
+  legend?: LegendTheme
+  valueStyle?: TextStyle
+  spotlight?: Partial<BarChartConfig["spotlight"]>
+}
+
+/** The bar chart's out-of-the-box look. */
+export const DEFAULT_BAR_CHART_THEME: BarChartConfig = {
+  seriesFills: DEFAULT_SERIES_FILLS,
+  bar: {
+    cornerRadius: 6,
+    slotFill: 0.72,
+    groupGap: 6,
+    stroke: [],
+    shadow: [],
+  },
+  // A category axis names its slots, so its captions are set like a caption
+  // rather than like a numeric marker: same size, less weight than the line
+  // chart's ticks, and centred on the slot.
+  xAxis: {
+    ...DEFAULT_X_AXIS,
+    labelStyle: { ...DEFAULT_X_AXIS.labelStyle, fontWeight: 600 },
+    tickPadding: 16,
+  },
+  yAxis: DEFAULT_Y_AXIS,
+  plotArea: DEFAULT_PLOT_AREA,
+  legend: DEFAULT_LEGEND,
+  valueStyle: {
+    fontSize: 24,
+    fontWeight: 700,
+    textAlign: "center",
+    fill: CHART_PALETTE.markerColor,
+  },
+  spotlight: { dimOpacity: SPOTLIGHT_DIM },
+}
+
+function resolveBarStyle(
+  bar: Partial<BarStyleConfig> | undefined,
+  previous: BarStyleConfig
+): BarStyleConfig {
+  return {
+    cornerRadius: bar?.cornerRadius ?? previous.cornerRadius,
+    slotFill: bar?.slotFill ?? previous.slotFill,
+    groupGap: bar?.groupGap ?? previous.groupGap,
+    stroke: strokeOps.resolve(bar?.stroke ?? previous.stroke),
+    shadow: shadowOps.resolve(bar?.shadow ?? previous.shadow),
+  }
+}
+
+function lerpBarStyle(
+  from: BarStyleConfig,
+  to: BarStyleConfig,
+  t: number
+): BarStyleConfig {
+  return {
+    cornerRadius: lerpNumber(from.cornerRadius, to.cornerRadius, t),
+    slotFill: lerpNumber(from.slotFill, to.slotFill, t),
+    groupGap: lerpNumber(from.groupGap, to.groupGap, t),
+    stroke: strokeOps.lerp(
+      from.stroke as StrokeResolved[],
+      to.stroke as StrokeResolved[],
+      t
+    ),
+    shadow: shadowOps.lerp(
+      from.shadow as ShadowResolved[],
+      to.shadow as ShadowResolved[],
+      t
+    ),
+  }
+}
+
+/**
+ * {@link BarChart}'s `theme` @property mapper: 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.
+ */
+export function resolveBarChartTheme(
+  theme: BarChartTheme | undefined,
+  previous?: BarChartConfig
+): BarChartConfig {
+  const base = previous ?? DEFAULT_BAR_CHART_THEME
+  return {
+    seriesFills: resolveSeriesFills(theme?.seriesFills, base.seriesFills),
+    bar: resolveBarStyle(theme?.bar, base.bar),
+    xAxis: resolveAxisConfig(theme?.xAxis, base.xAxis),
+    yAxis: resolveAxisConfig(theme?.yAxis, base.yAxis),
+    plotArea: resolvePlotArea(theme?.plotArea, base.plotArea),
+    legend: resolveLegendConfig(theme?.legend, base.legend),
+    valueStyle: textOps.resolveStyle(theme?.valueStyle, base.valueStyle),
+    spotlight: {
+      dimOpacity: theme?.spotlight?.dimOpacity ?? base.spotlight.dimOpacity,
+    },
+  }
+}
+
+/** {@link BarChart}'s `theme` @property tween — leaf by leaf. */
+export function lerpBarChartTheme(
+  from: BarChartConfig,
+  to: BarChartConfig,
+  t: number
+): BarChartConfig {
+  return {
+    seriesFills: lerpSeriesFills(from.seriesFills, to.seriesFills, t),
+    bar: lerpBarStyle(from.bar, to.bar, t),
+    xAxis: lerpAxisConfig(from.xAxis, to.xAxis, t),
+    yAxis: lerpAxisConfig(from.yAxis, to.yAxis, t),
+    plotArea: lerpPlotArea(from.plotArea, to.plotArea, t),
+    legend: lerpLegendConfig(from.legend, to.legend, t),
+    valueStyle: textOps.lerpStyle(from.valueStyle, to.valueStyle, t),
+    spotlight: {
+      dimOpacity: lerpNumber(
+        from.spotlight.dimOpacity,
+        to.spotlight.dimOpacity,
+        t
+      ),
+    },
+  }
+}
+
+/** The paint series `index` is drawn in: its own override, else the palette's entry. */
+export function resolveBarFill(
+  palette: Fill[],
+  series: BarSeries,
+  index: number
+): Fill {
+  if (series.fill != null) return fillOps.resolve(series.fill)
+  if (palette.length === 0) return "white"
+  return palette[index % palette.length]
+}

package/src/engine.ts

@@ -0,0 +1,26 @@
+/**
+ * The chart **kit**: everything the three charts share, and the one thing a
+ * copied chart does not copy.
+ *
+ * `ms add line-chart` writes `line-chart/*` into your project and rewrites its
+ * reach for these to `@motionscript/charts`, so the plot panel, the value
+ * 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
+ * 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/chart-border"
+export * from "./kit/chart-canvas"
+export * from "./kit/chart-legend"
+export * from "./kit/vertical-axis"
+export * from "@motionscript/core/component"

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from "./line-chart";
+export * from "./bar-chart";
+export * from "./pie-chart";
+export * from "./engine";
+export { NODES } from "./nodes";

package/src/kit/chart-border.ts

@@ -0,0 +1,61 @@
+import {
+  type AssetScope,
+  Graphics2D,
+  Node2D,
+  strokeOps,
+  property,
+  type Node2DProps,
+  type RenderContext2D,
+  type Stroke,
+} from "@motionscript/core"
+
+import { DEFAULT_PLOT_AREA } from "./shared"
+import { declarePaints } from "@motionscript/core/component"
+
+export interface ChartBorderProps extends Node2DProps {
+  /**
+   * The plot's thick frame stroke. The stroke resolver's default `align` is
+   * `'inside'`, so the whole weight sits within the layout box unless the theme
+   * overrides it.
+   */
+  stroke: Stroke
+}
+
+/**
+ * The thick **frame** around a cartesian chart's plot: an empty rect wearing an
+ * inside stroke, sized from its allocated `layoutBounds`.
+ *
+ * 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
+
+    // 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)
+    )
+  }
+}

package/src/kit/chart-canvas.ts

@@ -0,0 +1,157 @@
+import {
+  type AssetScope,
+  Graphics2D,
+  Node2D,
+  fillOps,
+  shadowOps,
+  strokeOps,
+  property,
+  type Fill,
+  type Node2DProps,
+  type RenderContext2D,
+  type Shadow,
+  type Stroke,
+  type StrokeResolved,
+} from "@motionscript/core"
+
+import {
+  DEFAULT_PLOT_AREA,
+  DEFAULT_X_AXIS,
+  DEFAULT_Y_AXIS,
+  type Range,
+} from "./shared"
+import { declarePaints } from "@motionscript/core/component"
+
+export interface ChartCanvasProps extends Node2DProps {
+  /** Fill of the plot panel behind the marks. */
+  fill: Fill
+  /** Drop shadow of the panel. Default none. */
+  shadow: Shadow
+  /** Stroke of the vertical grid lines (one per {@link xMarkers}). */
+  xGridStroke: Stroke
+  /** Stroke of the horizontal grid lines (one per {@link yMarkers}). */
+  yGridStroke: Stroke
+  /**
+   * Data-unit x positions to draw a vertical grid line at — one per horizontal
+   * axis marker, so a line lands under every marker regardless of spacing.
+   * Positions at (or past) an {@link xExtent} edge coincide with the border and
+   * are skipped. Pass an empty list for a chart whose horizontal axis is
+   * categorical and so has no numeric position to rule at.
+   */
+  xMarkers: number[]
+  /** Data-unit y positions to draw a horizontal grid line at. */
+  yMarkers: number[]
+  /** `[min, max]` of the horizontal scale — maps {@link xMarkers} into the panel. */
+  xExtent: Range
+  /** `[min, max]` of the vertical scale — maps {@link yMarkers} into the panel. */
+  yExtent: Range
+}
+
+/**
+ * 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.
+ *
+ * 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
+ * the axis marker positions (in data units) mapped into the panel through
+ * {@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
+    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)
+    )
+
+    const [xMin, xMax] = this.xExtent
+    const [yMin, yMax] = this.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]
+    if (xStroke) {
+      const xGrid = new Graphics2D()
+      for (const v of this.xMarkers) {
+        const f = xFrac(v)
+        if (!interior(f)) continue
+        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]
+    if (yStroke) {
+      const yGrid = new Graphics2D()
+      for (const v of this.yMarkers) {
+        const f = yFrac(v)
+        if (!interior(f)) continue
+        yGrid.rect({
+          x: 0,
+          y: -H / 2 + f * H,
+          width: W,
+          height: yStroke.weight,
+        })
+      }
+      ctx.draw(yGrid.fill(yStroke.fill))
+    }
+  }
+}