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

package/src/bar-chart/shared.ts

@@ -1,91 +1,66 @@
-import {
-  fillOps,
-  lerpNumber,
-  shadowOps,
-  strokeOps,
-  textOps,
-  type DataRecord,
-  type Fill,
-  type Shadow,
-  type ShadowResolved,
-  type Stroke,
-  type StrokeResolved,
-  type TextStyle,
-} from "@motionscript/sdk"
-import { niceStep } from "@motionscript/sdk/component"
+import { Types, fillOps, type DataRecord, type Fill } from "@motionscript/sdk"
 
-import {
-  CHART_PALETTE,
-  DEFAULT_LEGEND,
-  DEFAULT_PLOT_AREA,
-  DEFAULT_SERIES_FILLS,
-  DEFAULT_X_AXIS,
-  DEFAULT_Y_AXIS,
-  SPOTLIGHT_DIM,
-  lerpAxisConfig,
-  lerpLegendConfig,
-  lerpPlotArea,
-  lerpSeriesFills,
-  num,
-  resolveAxisConfig,
-  resolveLegendConfig,
-  resolvePlotArea,
-  resolveSeriesFills,
-  text,
-  type AxisConfig,
-  type ChartSeries,
-  type LegendConfig,
-  type LegendTheme,
-  type PlotAreaConfig,
-  type Range,
-} from "../kit/shared"
+import { niceRange, num, text, type ChartSeries, type Range } from "../kit/shared"
 
 /** One bar per row, beside its siblings in the category slot or stacked on them: {@link ChartSeries} under the name for what it draws here. */
 export type BarSeries = ChartSeries
 
+/** How the series share a category: side by side, stacked, or stacked as shares of 100. */
+export type BarStack = "none" | "stacked" | "percent"
+
+/** Which way the bars grow: up from a category row, or right from a category column. */
+export type BarOrientation = "vertical" | "horizontal"
+
 /**
- * One bar's span in data units. A span rather than a height because both modes
- * fit it, and a negative value just runs the other way with no special case.
+ * One bar's span in data units. A span rather than a height because every mode
+ * fits it, and a negative value just runs the other way with no special case.
  */
 export interface BarSpan {
-  /** Where the base sits: 0 when grouped, the running total below when stacked. */
+  /** Where the base sits: 0 apart, the running total below (or above, for a negative) when stacked. */
   from: number
   to: number
-  /** `to - from`, kept for the figure printed on the bar. */
+  /** `to - from`. */
   value: number
+  /** Whether it ends its stack on its side of zero, so its far end is rounded. */
+  outer: boolean
 }
 
 /**
- * One row's spans, in series order. Stacking is a running sum in listed order,
- * so series 0 sits on the baseline. A zero value still yields a degenerate span,
- * keeping the list index-aligned with the series.
- */
-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 series ending a row's stack, which gets the rounded cap; `-1` when the row
- * is all zero. It is the last non-zero series, so a zero one does not take the
- * cap and leave the segment below square.
+ * One row's spans, in series order. Stacking keeps a running sum on each side
+ * of zero, so a negative value stacks downward from the baseline rather than
+ * eating into the positives. In `percent` each value is its share of the row's
+ * total magnitude. A zero value still yields a degenerate span, keeping the list
+ * index-aligned with the series. `weights` scale each series' contribution.
  */
-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
+export function barSpans(row: DataRecord, series: readonly BarSeries[], stack: BarStack, weights: readonly number[] = []): BarSpan[] {
+  const weight = (i: number) => Math.max(0, weights[i] ?? 1)
+  if (stack !== "stacked" && stack !== "percent") {
+    return series.map((s) => {
+      const value = num(row, s.field)
+      return { from: 0, to: value, value, outer: true }
+    })
   }
-  return last
+  const values = series.map((s, i) => num(row, s.field) * weight(i))
+  const total = values.reduce((sum, v) => sum + Math.abs(v), 0)
+  const scaled = stack === "percent" ? values.map((v) => (total > 0 ? (v / total) * 100 : 0)) : values
+  let lastUp = -1
+  let lastDown = -1
+  scaled.forEach((v, i) => {
+    if (v > 0) lastUp = i
+    else if (v < 0) lastDown = i
+  })
+  let up = 0
+  let down = 0
+  return scaled.map((value, i) => {
+    if (value < 0) {
+      const from = down
+      down += value
+      return { from, to: down, value, outer: i === lastDown }
+    }
+    const from = up
+    up += value
+    return { from, to: up, value, outer: i === lastUp }
+  })
 }
 
 export function barCategories(data: DataRecord[], field: string): string[] {
@@ -94,18 +69,14 @@ export function barCategories(data: DataRecord[], field: string): string[] {
 
 /**
  * The `[min, max]` of everything drawn, zero always included: a scale starting
- * at 40 draws a column three times its neighbour for a 10% difference. A cropped
+ * at 40 draws a bar three times its neighbour for a 10% difference. A cropped
  * axis takes an explicit range.
  */
-export function barValueExtent(
-  data: DataRecord[],
-  series: BarSeries[],
-  stacked: boolean
-): Range {
+export function barValueExtent(data: DataRecord[], series: readonly BarSeries[], stack: BarStack, weights?: readonly number[]): Range {
   let lo = 0
   let hi = 0
   for (const row of data) {
-    for (const span of barSpans(row, series, stacked)) {
+    for (const span of barSpans(row, series, stack, weights)) {
       lo = Math.min(lo, span.from, span.to)
       hi = Math.max(hi, span.from, span.to)
     }
@@ -113,174 +84,43 @@ export function barValueExtent(
   return lo < hi ? [lo, hi] : [0, 1]
 }
 
-/** The explicit `range`, else the data's extent nudged to tidy bounds; `divisions` (one fewer than the marker count) makes the drawn ticks land on them. */
+/** The explicit `range`, else the data's extent nudged to tidy bounds (a percent stack reads to 100); `divisions` (one fewer than the marker count) makes the drawn ticks land on them. */
 export function resolveBarScale(
   data: DataRecord[],
-  series: BarSeries[],
-  stacked: boolean,
+  series: readonly BarSeries[],
+  stack: BarStack,
   range: Range | undefined,
-  divisions: number
+  divisions: number,
+  weights?: readonly 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]
-}
-
-/** How the columns are drawn and the slot divided. */
-export interface BarStyleConfig {
-  /** Radius in px of a column's far-end corners; an interior stacked segment stays square. */
-  cornerRadius: number
-  /** Fraction of the category slot the bars fill, `[0, 1]`; the rest separates groups. */
-  slotFill: number
-  /** Gap in px between grouped bars within a slot; ignored when stacked. */
-  groupGap: number
-  stroke: Stroke
-  shadow: Shadow
+  const [lo, hi] = barValueExtent(data, series, stack, weights)
+  if (stack === "percent") return [lo < 0 ? -100 : 0, hi > 0 ? 100 : 0]
+  return niceRange([lo, hi], divisions)
 }
 
-/** A {@link BarChart}'s full, resolved visual theme. */
-export interface BarChartConfig {
-  /** Cycled by series index; a series' own `fill` replaces its entry outright. */
-  seriesFills: Fill[]
-  bar: BarStyleConfig
-  /** The category axis. */
-  xAxis: AxisConfig
-  /** The value axis. */
-  yAxis: AxisConfig
-  plotArea: PlotAreaConfig
-  legend: LegendConfig
-  /** The figure printed on each column. */
-  valueStyle: TextStyle
-  /** How far everything outside a spotlit series or category fades. */
-  spotlight: { dimOpacity: number }
+/** Black or white, whichever reads on `fill`: a figure printed inside a bar. */
+export function inkOn(fill: Fill): string {
+  const layers = fillOps.resolve(fill)
+  const top = layers[layers.length - 1]
+  if (top?.type !== "solid") return "white"
+  const [r, g, b] = top.color
+  const lift = (c: number) => (c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4)
+  const luminance = 0.2126 * lift(r) + 0.7152 * lift(g) + 0.0722 * lift(b)
+  return luminance > 0.4 ? "#0a0a0a" : "white"
 }
 
-/** The author's partial theme, deep-merged onto {@link DEFAULT_BAR_CHART_THEME}. */
-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"]>
-}
-
-export const DEFAULT_BAR_CHART_THEME: BarChartConfig = {
-  seriesFills: DEFAULT_SERIES_FILLS,
-  bar: {
-    cornerRadius: 6,
-    slotFill: 0.72,
-    groupGap: 6,
-    stroke: [],
-    shadow: [],
-  },
-  // Captions rather than numeric markers: less weight than the line chart's ticks.
-  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
-    ),
-  }
-}
-
-/** The `theme` entry's resolve: merges a partial {@link BarChartTheme} onto `previous` (first resolution: the default). */
-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,
-    },
-  }
-}
-
-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
-      ),
-    },
-  }
+/** A bar chart's own look: how round and how wide the bars are. */
+export const BAR_MARKS = {
+  /** Radius of each bar's far corners; a stacked segment inside the stack stays square. */
+  barRadius: Types.number(10, { min: 0, max: 64, step: 1, unit: "px" }),
+  /** How much of its category slot a bar group fills, the rest spacing the groups. */
+  barWidth: Types.number(0.7, { min: 0.05, max: 1, step: 0.05 }),
+  /** Space between the bars of one group, side by side. */
+  barGap: Types.number(6, { min: 0, max: 40, step: 1, unit: "px" }),
 }
 
-/** Series `index`'s own `fill`, 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]
+export const BAR_LABELS = {
+  /** Read as the chart is built: each bar's value past its end, inside it, or none. */
+  values: Types.oneOf(["none", "end", "inside"] as const, { animatable: false }),
 }

package/src/engine.ts

@@ -1,16 +1,19 @@
 /**
- * The chart kit: what the three charts share, and what a copied chart does not
+ * The chart kit: what the five charts share, and what a copied chart does not
  * copy. A chart finds its parts by component identity (`VerticalAxis.is`), so a
  * second copy of `VerticalAxis` would be a second component that the chart never
  * finds, with no error. Copies import the kit from `@motionscript/charts`.
  */
 export * from "./kit/shared"
+export * from "./kit/style"
 export * from "./kit/cartesian"
-export * from "./kit/chart-border"
 export * from "./kit/chart-canvas"
+export * from "./kit/horizontal-axis"
 export * from "./kit/chart-legend"
 export * from "./kit/entries"
 export * from "./kit/motion"
 export * from "./kit/paints"
+export * from "./kit/pie-legend"
+export * from "./kit/polar"
 export * from "./kit/vertical-axis"
 export * from "@motionscript/sdk/component"

package/src/index.ts

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

package/src/kit/cartesian.ts

@@ -1,62 +1,96 @@
-import { Rect, type ChildView, type Node2D, type Size2D } from "@motionscript/sdk"
+import {
+  Rect,
+  RotatedBox,
+  Text,
+  textOps,
+  type ChildView,
+  type Fill,
+  type FillResolved,
+  type Insets,
+  type Node2D,
+  type Size2D,
+  type TextStyle,
+} from "@motionscript/sdk"
 
-import { VerticalAxis } from "./vertical-axis"
+import type { CartesianStyle, LegendPosition } from "./style"
 
-/**
- * Headroom above the plot, in px. Real padding on the composition, so the top
- * marker, centred on the top grid line, does not draw its upper half above the
- * chart's own box.
- */
-const TOP_HEADROOM = 24
+/** Space between the frame's rows and columns: the plot and the legend, the axes and the legend. */
+export function frameGap(style: Pick<CartesianStyle, "fontSize">): number {
+  return Math.round(style.fontSize * 0.9)
+}
+
+/** Room above the plot for the top value marker, which is centred on the top grid line. */
+export function headroom(style: Pick<CartesianStyle, "fontSize">): number {
+  return Math.ceil(style.fontSize * 0.7)
+}
+
+/** How far an end marker of a horizontal value axis may hang past the plot: half a short caption. */
+export function overhang(style: Pick<CartesianStyle, "fontSize">): number {
+  return Math.ceil(style.fontSize * 1.1)
+}
 
 interface CartesianParts {
-  readonly axis: Node2D
+  /** The axis beside the plot, on its left. */
+  readonly left?: Node2D
+  /** An invisible twin of `left` under the plot, so the row there starts at the plot's left edge. */
+  readonly ghost?: Node2D
   /** 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 axis under the plot. */
+  readonly bottom?: Node2D
+  readonly legend?: Node2D
+  readonly legendAt: LegendPosition
+  readonly gap: () => number
+  readonly padding: () => Insets
 }
 
-/** The frame the line and bar charts share: the value axis beside the plot, and under them the gutter, so the rows below start at the plot's left edge. */
+/**
+ * The frame the line and bar charts share. A legend above or below is centred
+ * on the whole chart; one on the right is a column beside the plot. An axis the
+ * style turns off is simply not here, and the plot takes its room.
+ */
 export function cartesianFrame(parts: CartesianParts): Node2D {
+  const top = new Rect({ flow: "horizontal", width: "fill", height: "fill", children: [...(parts.left ? [parts.left] : []), parts.plot] })
+  const rows: Node2D[] = [top as unknown as Node2D]
+  if (parts.bottom) {
+    rows.push(new Rect({ flow: "horizontal", width: "fill", height: "hug", children: [...(parts.ghost ? [parts.ghost] : []), parts.bottom] }) as unknown as Node2D)
+  }
+  const body = new Rect({ flow: "vertical", width: "fill", height: "fill", children: rows })
+  const legend = parts.legend && parts.legendAt !== "none" ? parts.legend : undefined
+  const main = new Rect({
+    flow: "horizontal",
+    width: "fill",
+    height: "fill",
+    align: "center",
+    gap: parts.gap,
+    children: [body, ...(legend && parts.legendAt === "right" ? [legend] : [])],
+  })
+  const across = (node: Node2D) => new Rect({ flow: "horizontal", width: "fill", height: "hug", align: "center", children: [node] })
   return new Rect({
     flow: "vertical",
     width: "fill",
     height: "fill",
-    padding: { top: TOP_HEADROOM },
+    gap: parts.gap,
+    padding: parts.padding,
     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] })],
-      }),
+      ...(legend && parts.legendAt === "top" ? [across(legend)] : []),
+      main,
+      ...(legend && parts.legendAt === "bottom" ? [across(legend)] : []),
     ],
   }) as unknown as Node2D
 }
 
-interface CartesianViews {
-  readonly axis: ChildView
-  /** The plot panel's own children: grid, marks, border. */
-  readonly plot: readonly ChildView[]
-  readonly below: readonly ChildView[]
-}
-
-/** 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, 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 }
+/** Every view under `children`, depth first in build order: the axis beside the plot comes before its twin, which holds no parts. */
+export function chartViews(children: readonly ChildView[]): ChildView[] {
+  const out: ChildView[] = []
+  const walk = (views: readonly ChildView[]) => {
+    for (const view of views) {
+      out.push(view)
+      walk(view.children)
+    }
   }
-  return null
+  walk(children)
+  return out
 }
 
 /** A part's laid-out size; zero before it is built or laid out. */
@@ -64,3 +98,47 @@ export function laidOutSize(node: Node2D | undefined): Size2D {
   const bounds = node?.layoutBounds
   return { width: bounds?.width ?? 0, height: bounds?.height ?? 0 }
 }
+
+/**
+ * A text style as props bound to `read`, so a style tween reaches text built
+ * once. Only the keys set at build are bound: an unset family stays unset, so
+ * the host's default face still applies.
+ */
+export function boundText(read: () => TextStyle): Record<string, unknown> {
+  const keys = Object.keys(textOps.styleProps(read())) as (keyof TextStyle)[]
+  const props: Record<string, unknown> = {}
+  for (const key of keys) props[key] = () => read()[key]
+  return props
+}
+
+interface GhostSpec {
+  readonly captions: () => readonly string[]
+  /** How many captions the real axis built. */
+  readonly count: number
+  readonly text: () => TextStyle
+  readonly title: string
+  readonly titleText: () => TextStyle
+  readonly tickPad: () => number
+  readonly titlePad: () => number
+}
+
+/**
+ * An invisible column as wide as a vertical axis built from the same captions:
+ * the widest caption plus the tick padding, and the rotated title before it. A
+ * plain tree, so a command looking for the axis never finds this instead.
+ */
+export function columnGhost(spec: GhostSpec): Node2D {
+  const captions = Array.from({ length: spec.count }, (_, i) => new Text({ ...boundText(spec.text), text: () => spec.captions()[i] ?? "" }))
+  const children: Node2D[] = []
+  if (spec.title !== "") {
+    children.push(new RotatedBox({ angle: -90, width: "hug", height: "hug", children: new Text({ ...boundText(spec.titleText), text: spec.title }) }) as unknown as Node2D)
+  }
+  children.push(new Rect({ flow: "vertical", width: "hug", height: "hug", padding: () => ({ right: spec.tickPad() }), children: captions }) as unknown as Node2D)
+  return new Rect({ opacity: 0, flow: "horizontal", gap: spec.titlePad, width: "hug", height: 0, children }) as unknown as Node2D
+}
+
+/** `fill` with every layer's opacity scaled by `k`. */
+export function fade(fill: Fill, k: number): Fill {
+  const layers = (Array.isArray(fill) ? fill : [fill]) as FillResolved[]
+  return layers.map((layer) => (typeof layer === "object" && layer !== null ? { ...layer, opacity: ((layer as { opacity?: number }).opacity ?? 1) * k } : layer)) as Fill
+}