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

package/src/kit/shared.ts

@@ -0,0 +1,675 @@
+/**
+ * The vocabulary every chart node shares: what a *series* is, how an axis is
+ * scaled and formatted, and the theme leaves each chart's own theme is assembled
+ * from.
+ *
+ * This module exists because the three chart types are three ways of drawing the
+ * same table. A line chart, a bar chart and a pie chart disagree about almost
+ * everything visible — polylines against columns against wedges — and agree
+ * about almost everything underneath: a series is a column with a caption and a
+ * paint, a marker is a number formatted one way, a legend is a swatch beside a
+ * label, and a theme is a tree of paints with one mapper and one tween. Writing
+ * that three times would mean three answers to "how does a chart round its axis"
+ * within one app.
+ *
+ * Kept renderer-agnostic (no `Node` imports) so the studio's own inspector
+ * mappings can build a partial theme without pulling the node classes in, the
+ * same way `line-chart-props.ts` always has.
+ *
+ * **Two conventions run through every resolver and lerp below**, inherited from
+ * the shape system's `resolveStroke`/`resolveShadow`:
+ *
+ * - A **mapper** merges the author's loose, partial input onto a `previous`
+ *   resolved value and resolves every leaf, so the tween always has resolved
+ *   data to interpolate. It is idempotent.
+ * - A **tween** interpolates two resolved values leaf by leaf. Categorical
+ *   fields (`fontFamily`, `textAlign`) and fields that are `undefined` on either
+ *   side **step at the midpoint**, because there is no meaningful in-between and
+ *   defaulting the missing side to 0 would animate a font weight down to nothing
+ *   on the way to "unset".
+ */
+
+import {
+  fillOps,
+  lerpNumber,
+  shadowOps,
+  strokeOps,
+  insetsOps,
+  textOps,
+  type DataRecord,
+  type Fill,
+  type FillResolved,
+  type Insets,
+  type InsetsResolved,
+  type Shadow,
+  type ShadowResolved,
+  type Stroke,
+  type StrokeResolved,
+  type TextStyle,
+} from "@motionscript/core"
+
+/**
+ * One series of a chart: a column of the table, captioned and painted.
+ *
+ * `field` names the column carrying this series' values. What that becomes is
+ * the chart's business — a traced polyline, a column of bars, a wedge — but the
+ * three questions asked of it are the same everywhere: which column, what to
+ * call it, what to paint it, and whether it is currently drawn.
+ *
+ * `fill` is an **override**: omit it and the series takes the theme palette's
+ * entry for its own index, which is what makes a chart nobody has themed come
+ * out in five distinct colours rather than five identical ones.
+ */
+export interface ChartSeries {
+  /** Key into each data row for this series' value. */
+  field: string
+  /** Legend caption for this series. */
+  label: string
+  /**
+   * Paint override for this series' mark and its legend swatch. Omit to take
+   * the theme palette's entry for this series' index.
+   */
+  fill?: Fill
+  /** Whether the series shows by default. Defaults to `true`. */
+  enabled?: boolean
+}
+
+/** A `[min, max]` numeric range in data units. */
+export type Range = [min: number, max: number]
+
+/**
+ * One axis's *data* domain — what it shows — as opposed to {@link AxisConfig},
+ * which is how it's *styled*. Every field is optional: `range`/`ticks` derive
+ * from the plotted data when omitted, and `label` defaults to `""`.
+ */
+export interface AxisDomainConfig {
+  /** Caption drawn alongside the axis. Pass `""` (the default) to hide it. */
+  label?: string
+  /** `[min, max]` of the scale. Derived from the data bounds when omitted. */
+  range?: Range
+  /** Tick values (in data units). Derived (five evenly-spaced) when omitted. */
+  ticks?: number[]
+  /**
+   * How a tick value is written down — a `number-format` pattern such as
+   * `#,##0.00` or `$#,##0`.
+   *
+   * Here rather than in {@link AxisConfig} because it is a statement about the
+   * *numbers*, not about the ink they are set in: `$` on a revenue axis says
+   * what the column holds, and it has to survive a re-theme. It sits beside
+   * `range` and `ticks` for the same reason those do.
+   */
+  format?: string
+}
+
+/**
+ * An axis domain's @property mapper: merges the author's partial input onto
+ * `previous`, so a later partial `.set({ yAxis: {...} })` patches
+ * `label`/`range`/`ticks` independently. `range`/`ticks` staying `undefined`
+ * after the merge is the auto-derive signal the scale getters read.
+ */
+export function resolveAxisDomain(
+  domain: AxisDomainConfig | undefined,
+  previous?: AxisDomainConfig
+): AxisDomainConfig {
+  return {
+    label: domain?.label ?? previous?.label ?? "",
+    range: domain?.range ?? previous?.range,
+    ticks: domain?.ticks ?? previous?.ticks,
+    format: domain?.format ?? previous?.format,
+  }
+}
+
+/**
+ * An axis domain's @property tween: interpolates `range`/`ticks` numerically
+ * (pairwise by index for `ticks`), so a `to` command that restates a range
+ * rescales the plot smoothly. `label`, and either field when one side is in
+ * auto-derive mode, step at the midpoint.
+ */
+export function lerpAxisDomain(
+  from: AxisDomainConfig,
+  to: AxisDomainConfig,
+  t: number
+): AxisDomainConfig {
+  return {
+    label: t < 0.5 ? from.label : to.label,
+    range: lerpOptionalRange(from.range, to.range, t),
+    ticks: lerpOptionalTicks(from.ticks, to.ticks, t),
+    // Steps at the midpoint with the caption, for the same reason: there is no
+    // halfway between `$#,##0` and `0.0%`.
+    format: t < 0.5 ? from.format : to.format,
+  }
+}
+
+function lerpOptionalRange(
+  from: Range | undefined,
+  to: Range | undefined,
+  t: number
+): Range | undefined {
+  if (!from || !to) return t < 0.5 ? from : to
+  return [lerpNumber(from[0], to[0], t), lerpNumber(from[1], to[1], t)]
+}
+
+function lerpOptionalTicks(
+  from: number[] | undefined,
+  to: number[] | undefined,
+  t: number
+): number[] | undefined {
+  if (!from || !to) return t < 0.5 ? from : to
+  const n = Math.max(from.length, to.length)
+  const out: number[] = []
+  for (let i = 0; i < n; i++) {
+    out.push(lerpNumber(from[i] ?? to[i], to[i] ?? from[i], t))
+  }
+  return out
+}
+
+/**
+ * The low-level colour tokens the default themes are built from — a dark plot
+ * panel with warm-grey axis furniture.
+ */
+export const CHART_PALETTE = {
+  /** Fill of the plot panel behind the marks. */
+  plotFill: "#15130e",
+  /** Colour of the plot's thick border. */
+  borderColor: "#4a4036",
+  /** Colour of the faint grid lines spanning the plot. */
+  gridColor: "#2c2820",
+  /** Colour of the numeric axis markers, axis captions, and legend labels. */
+  markerColor: "#8a7f70",
+  /** Colour of a spotlit region's dashed rules and its wash. */
+  regionColor: "#d99a3a",
+} as const
+
+/** The out-of-the-box series palette, cycled by series index. */
+export const DEFAULT_SERIES_COLORS = [
+  "#d9603b",
+  "#8194ad",
+  "#e0a93b",
+  "#5e9d6b",
+  "#9ec85a",
+] as const
+
+/**
+ * Opacity an *un*-spotlighted series fades to — its mark and its legend entry
+ * alike, so the two dim together.
+ */
+export const SPOTLIGHT_DIM = 0.2
+
+/** Clamp a number into `[0, 1]` — the range every reveal signal here runs in. */
+export function clampUnit(value: number): number {
+  return value < 0 ? 0 : value > 1 ? 1 : value
+}
+
+// ---- Row readers ---------------------------------------------------------
+
+/**
+ * Read a numeric field off a row, defaulting missing/non-numeric values to 0.
+ *
+ * A column left as strings silently plots as 0, which is why the CSV parser's
+ * numeric auto-coercion matters — a quoted or unit-suffixed column won't plot
+ * until it's coerced.
+ */
+export function num(row: DataRecord, field: string | undefined): number {
+  if (field === undefined) return 0
+  const v = row[field]
+  return typeof v === "number" ? v : 0
+}
+
+/**
+ * Read a field off a row as its caption — the counterpart to {@link num} for
+ * the columns a chart *names* things by rather than measures them by (a bar's
+ * category, a wedge's slice). A missing cell reads as empty rather than as the
+ * string `"undefined"`.
+ */
+export function text(row: DataRecord, field: string | undefined): string {
+  if (field === undefined || field === "") return ""
+  const v = row[field]
+  return v === undefined || v === null ? "" : String(v)
+}
+
+/**
+ * Every column that holds numbers across `data`, in header order, skipping the
+ * names in `exclude` (typically the category column).
+ *
+ * A column counts as numeric only if every non-empty cell in it is a number, so
+ * a stray text cell leaves the column out rather than plotting zeros. This is
+ * what lets a chart plot "every other column" without the author naming twenty
+ * fields.
+ */
+export function numericFields(
+  data: DataRecord[],
+  exclude: string[] = []
+): string[] {
+  if (data.length === 0) return []
+  const skip = new Set(exclude)
+  const seen = new Set<string>()
+  const order: string[] = []
+  for (const row of data)
+    for (const key of Object.keys(row))
+      if (!skip.has(key) && !seen.has(key)) {
+        seen.add(key)
+        order.push(key)
+      }
+
+  return order.filter((key) => {
+    let sawValue = false
+    for (const row of data) {
+      const v = row[key]
+      if (v === undefined || v === "") continue
+      if (typeof v !== "number") return false
+      sawValue = true
+    }
+    return sawValue
+  })
+}
+
+// ---- Theme branches ------------------------------------------------------
+
+/** One axis's (x or y) style vocabulary. */
+export interface AxisConfig {
+  /** Style of each marker along the axis. */
+  labelStyle: TextStyle
+  /** Style of the axis caption. */
+  titleStyle: TextStyle
+  /**
+   * This axis's direction of the plot's internal grid — weight+fill honoured,
+   * dash/cap/join ignored (grid lines are drawn as filled rects).
+   */
+  lineStyle: Stroke
+  /**
+   * Gap between the plot and the marker row. Only the side facing the plot is
+   * read — `.top` for a horizontal axis, `.right` for a vertical one.
+   */
+  tickPadding: Insets
+  /** Gap between the marker row and the caption, read the same side. */
+  titlePadding: Insets
+}
+
+/** A legend's per-series colour swatch — a rounded chip, not the caption. */
+export interface LegendMarkerConfig {
+  width: number
+  height: number
+  borderRadius: number
+  stroke: Stroke
+  shadow: Shadow
+}
+
+/** A legend's visual theme. */
+export interface LegendConfig {
+  padding: Insets
+  /** Caption style — only the swatch carries the series colour. */
+  textStyle: TextStyle
+  /** Gap between legend entries. */
+  itemGap: number
+  markerStyle: LegendMarkerConfig
+}
+
+/** The plot panel a cartesian chart draws its marks over. */
+export interface PlotAreaConfig {
+  stroke: Stroke
+  fill: Fill
+  shadow: Shadow
+}
+
+const AXIS_LABEL_STYLE: TextStyle = {
+  fontSize: 24,
+  fontWeight: 700,
+  textAlign: "center",
+  fill: CHART_PALETTE.markerColor,
+}
+const AXIS_TITLE_STYLE: TextStyle = {
+  fontSize: 30,
+  fontWeight: 600,
+  textAlign: "center",
+  fill: CHART_PALETTE.markerColor,
+}
+const AXIS_LINE_STYLE: Stroke = { weight: 2, fill: CHART_PALETTE.gridColor }
+
+/** The default styling of a horizontal (marker row beneath the plot) axis. */
+export const DEFAULT_X_AXIS: AxisConfig = {
+  labelStyle: AXIS_LABEL_STYLE,
+  titleStyle: AXIS_TITLE_STYLE,
+  lineStyle: AXIS_LINE_STYLE,
+  tickPadding: 20,
+  titlePadding: 4,
+}
+
+/** The default styling of a vertical (marker column beside the plot) axis. */
+export const DEFAULT_Y_AXIS: AxisConfig = {
+  labelStyle: { ...AXIS_LABEL_STYLE, fontWeight: 500, textAlign: "right" },
+  titleStyle: AXIS_TITLE_STYLE,
+  lineStyle: AXIS_LINE_STYLE,
+  tickPadding: 40,
+  titlePadding: 24,
+}
+
+/**
+ * The default plot panel: **unpainted**, framed. A chart reads against the
+ * stage rather than punching a panel into it, which is the look the family was
+ * designed at.
+ */
+export const DEFAULT_PLOT_AREA: PlotAreaConfig = {
+  fill: [],
+  stroke: { weight: 6, fill: CHART_PALETTE.borderColor },
+  shadow: [],
+}
+
+/** The default legend styling, shared by every chart that draws one. */
+export const DEFAULT_LEGEND: LegendConfig = {
+  padding: 0,
+  textStyle: {
+    fontSize: 30,
+    fontWeight: 600,
+    textAlign: "left",
+    fill: CHART_PALETTE.markerColor,
+  },
+  itemGap: 44,
+  markerStyle: {
+    width: 60,
+    height: 24,
+    borderRadius: 6,
+    stroke: [],
+    shadow: [],
+  },
+}
+
+/** The default per-series stroke palette — {@link DEFAULT_SERIES_COLORS}, drawn 4px. */
+export const DEFAULT_SERIES_STROKES: Stroke[] = DEFAULT_SERIES_COLORS.map(
+  (fill) => ({ weight: 4, fill })
+)
+
+/** The default per-series fill palette — the same colours, as solid paint. */
+export const DEFAULT_SERIES_FILLS: Fill[] = DEFAULT_SERIES_COLORS.map(
+  (fill) => fill
+)
+
+// ---- Theme branch resolvers ----------------------------------------------
+// Each chart type assembles its own theme out of these, so "the axis furniture"
+// means one thing across the family and each chart still declares only the
+// branches it actually draws.
+
+export function resolveAxisConfig(
+  axis: Partial<AxisConfig> | undefined,
+  previous: AxisConfig
+): AxisConfig {
+  return {
+    labelStyle: textOps.resolveStyle(axis?.labelStyle, previous.labelStyle),
+    titleStyle: textOps.resolveStyle(axis?.titleStyle, previous.titleStyle),
+    lineStyle: strokeOps.resolve(axis?.lineStyle ?? previous.lineStyle),
+    tickPadding: insetsOps.resolve(
+      axis?.tickPadding ?? previous.tickPadding,
+      previous.tickPadding as InsetsResolved
+    ),
+    titlePadding: insetsOps.resolve(
+      axis?.titlePadding ?? previous.titlePadding,
+      previous.titlePadding as InsetsResolved
+    ),
+  }
+}
+
+export function lerpAxisConfig(
+  from: AxisConfig,
+  to: AxisConfig,
+  t: number
+): AxisConfig {
+  return {
+    labelStyle: textOps.lerpStyle(from.labelStyle, to.labelStyle, t),
+    titleStyle: textOps.lerpStyle(from.titleStyle, to.titleStyle, t),
+    lineStyle: strokeOps.lerp(
+      from.lineStyle as StrokeResolved[],
+      to.lineStyle as StrokeResolved[],
+      t
+    ),
+    tickPadding: insetsOps.lerp(
+      from.tickPadding as InsetsResolved,
+      to.tickPadding as InsetsResolved,
+      t
+    ),
+    titlePadding: insetsOps.lerp(
+      from.titlePadding as InsetsResolved,
+      to.titlePadding as InsetsResolved,
+      t
+    ),
+  }
+}
+
+export function resolvePlotArea(
+  plotArea: Partial<PlotAreaConfig> | undefined,
+  previous: PlotAreaConfig
+): PlotAreaConfig {
+  return {
+    fill: fillOps.resolve(plotArea?.fill ?? previous.fill),
+    stroke: strokeOps.resolve(plotArea?.stroke ?? previous.stroke),
+    shadow: shadowOps.resolve(plotArea?.shadow ?? previous.shadow),
+  }
+}
+
+export function lerpPlotArea(
+  from: PlotAreaConfig,
+  to: PlotAreaConfig,
+  t: number
+): PlotAreaConfig {
+  return {
+    fill: fillOps.lerp(
+      from.fill as FillResolved[],
+      to.fill as FillResolved[],
+      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
+    ),
+  }
+}
+
+function resolveLegendMarkerConfig(
+  marker: Partial<LegendMarkerConfig> | undefined,
+  previous: LegendMarkerConfig
+): LegendMarkerConfig {
+  return {
+    width: marker?.width ?? previous.width,
+    height: marker?.height ?? previous.height,
+    borderRadius: marker?.borderRadius ?? previous.borderRadius,
+    stroke: strokeOps.resolve(marker?.stroke ?? previous.stroke),
+    shadow: shadowOps.resolve(marker?.shadow ?? previous.shadow),
+  }
+}
+
+function lerpLegendMarkerConfig(
+  from: LegendMarkerConfig,
+  to: LegendMarkerConfig,
+  t: number
+): LegendMarkerConfig {
+  return {
+    width: lerpNumber(from.width, to.width, t),
+    height: lerpNumber(from.height, to.height, t),
+    borderRadius: lerpNumber(from.borderRadius, to.borderRadius, 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
+    ),
+  }
+}
+
+/** A legend theme as the author may state it — every branch optional. */
+export type LegendTheme = Partial<Omit<LegendConfig, "markerStyle">> & {
+  markerStyle?: Partial<LegendMarkerConfig>
+}
+
+export function resolveLegendConfig(
+  legend: LegendTheme | undefined,
+  previous: LegendConfig
+): LegendConfig {
+  return {
+    padding: insetsOps.resolve(
+      legend?.padding ?? previous.padding,
+      previous.padding as InsetsResolved
+    ),
+    textStyle: textOps.resolveStyle(legend?.textStyle, previous.textStyle),
+    itemGap: legend?.itemGap ?? previous.itemGap,
+    markerStyle: resolveLegendMarkerConfig(
+      legend?.markerStyle,
+      previous.markerStyle
+    ),
+  }
+}
+
+export function lerpLegendConfig(
+  from: LegendConfig,
+  to: LegendConfig,
+  t: number
+): LegendConfig {
+  return {
+    padding: insetsOps.lerp(
+      from.padding as InsetsResolved,
+      to.padding as InsetsResolved,
+      t
+    ),
+    textStyle: textOps.lerpStyle(from.textStyle, to.textStyle, t),
+    itemGap: lerpNumber(from.itemGap, to.itemGap, t),
+    markerStyle: lerpLegendMarkerConfig(from.markerStyle, to.markerStyle, t),
+  }
+}
+
+/** A whole-palette override replaces the previous palette outright. */
+export function resolveSeriesStrokes(
+  styles: Stroke[] | undefined,
+  previous: Stroke[]
+): Stroke[] {
+  return (styles ?? previous).map((s) => strokeOps.resolve(s))
+}
+
+/** Pairwise by index; a palette that grows/shrinks holds the longer side's tail. */
+export function lerpSeriesStrokes(
+  from: Stroke[],
+  to: Stroke[],
+  t: number
+): Stroke[] {
+  const n = Math.max(from.length, to.length)
+  const out: Stroke[] = []
+  for (let i = 0; i < n; i++) {
+    const a = (from[i] ?? to[i]) as StrokeResolved[]
+    const b = (to[i] ?? from[i]) as StrokeResolved[]
+    out.push(strokeOps.lerp(a, b, t))
+  }
+  return out
+}
+
+/** The fill-palette twin of {@link resolveSeriesStrokes}, for filled marks. */
+export function resolveSeriesFills(
+  fills: Fill[] | undefined,
+  previous: Fill[]
+): Fill[] {
+  return (fills ?? previous).map((f) => fillOps.resolve(f))
+}
+
+/** The fill-palette twin of {@link lerpSeriesStrokes}. */
+export function lerpSeriesFills(from: Fill[], to: Fill[], t: number): Fill[] {
+  const n = Math.max(from.length, to.length)
+  const out: Fill[] = []
+  for (let i = 0; i < n; i++) {
+    const a = (from[i] ?? to[i]) as FillResolved[]
+    const b = (to[i] ?? from[i]) as FillResolved[]
+    out.push(fillOps.lerp(a, b, t))
+  }
+  return out
+}
+
+// ---- Per-series paint ----------------------------------------------------
+
+/**
+ * The effective stroke for series `index`: the palette's entry at
+ * `index % palette.length`, with the series' own `fill`, if set, overriding just
+ * the last (topmost) layer's colour.
+ */
+export function resolveSeriesStroke(
+  palette: Stroke[],
+  series: ChartSeries,
+  index: number
+): Stroke {
+  const entry: Stroke =
+    palette.length > 0
+      ? palette[index % palette.length]
+      : { weight: 4, fill: "white" }
+  if (series.fill == null) return entry
+  const layers = strokeOps.resolve(entry)
+  if (layers.length === 0) return { weight: 4, fill: series.fill }
+  const next = [...layers]
+  next[next.length - 1] = {
+    ...next[next.length - 1],
+    fill: fillOps.resolve(series.fill),
+  }
+  return next
+}
+
+/**
+ * The effective *colour* for series `index` — the same colour
+ * {@link resolveSeriesStroke} draws its line in — for contexts (a legend
+ * swatch) that only need the fill.
+ */
+export function resolveSeriesFill(
+  palette: Stroke[],
+  series: ChartSeries,
+  index: number
+): Fill {
+  const layers = strokeOps.resolve(resolveSeriesStroke(palette, series, index))
+  return layers[layers.length - 1]?.fill ?? "white"
+}
+
+/**
+ * The effective paint for mark `index` of a **filled** chart (a bar, a wedge):
+ * the series' own `fill` when it carries one, else the palette's entry for its
+ * index, cycled.
+ *
+ * The stroke twin above has to reach inside a stroke to swap one layer's colour;
+ * a filled mark has no such geometry wrapped around its paint, so an override is
+ * simply the whole answer.
+ */
+export function resolvePalettePaint(
+  palette: Fill[],
+  override: Fill | undefined,
+  index: number
+): Fill {
+  if (override != null) return override
+  if (palette.length === 0) return "white"
+  return palette[index % palette.length]
+}
+
+// ---- Scales and formatting -----------------------------------------------
+
+
+/** Format a marker value: integers plain, otherwise trimmed to one decimal. */
+export function formatMarker(value: number): string {
+  if (Number.isInteger(value)) return String(value)
+  return value.toFixed(1).replace(/\.0$/, "")
+}
+
+/** Format a fraction in `[0, 1]` as a percentage: integers plain, else one decimal. */
+export function formatPercent(fraction: number): string {
+  const pct = fraction * 100
+  if (Number.isInteger(pct)) return `${pct}%`
+  return `${pct.toFixed(1).replace(/\.0$/, "")}%`
+}
+
+/** `markerCount` evenly-spaced tick values across `[min, max]`, ends inclusive. */
+export function markerValues([min, max]: Range, markerCount: number): number[] {
+  const n = Math.max(2, Math.round(markerCount))
+  return Array.from({ length: n + 1 }, (_, i) => min + ((max - min) / n) * i)
+}
+
+// Lifted into the engine, because a graph and a diagram want them too — see
+// `@motionscript/core/component`. Re-exported so a chart, and anything that
+// copied one, still reaches them where it always did.
+export { niceStep, enterBudget } from "@motionscript/core/component"