@motionscript/charts 0.1.0 → 0.1.1-alpha.1

package/src/pie-chart/shared.ts

@@ -1,166 +1,73 @@
-/**
- * Types and pure helpers specific to the {@link PieChart} family: how rows
- * become slices, how slices become arcs on a ring, where the labels around it
- * end up, and the theme all of that is drawn from.
- *
- * The one chart in the family that draws **one mark per row** rather than one
- * per column, which is why almost nothing about its geometry is shared: there is
- * no scale, no axis and no baseline, only a circle divided by share. What it
- * *does* share — the legend, the theme leaf resolvers, the palette, the
- * percentage format — comes from `../kit/shared.ts`.
- *
- * Kept renderer-agnostic (no `Node` imports) so a host's inspector mapping
- * can build a partial {@link PieChartTheme} without
- * pulling the node classes in.
- */
-
-import {
-  lerpNumber,
-  shadowOps,
-  strokeOps,
-  textOps,
-  type DataRecord,
-  type Fill,
-  type Shadow,
-  type ShadowResolved,
-  type Stroke,
-  type StrokeResolved,
-  type TextStyle,
-  type Vector2,
-} from "@motionscript/sdk"
+import { Types, type Fill, type TextStyle, type Stroke, type FillResolved as _FillResolved } from "@motionscript/sdk"
 
 import {
-  CHART_PALETTE,
-  DEFAULT_LEGEND,
-  DEFAULT_SERIES_FILLS,
-  lerpLegendConfig,
-  lerpSeriesFills,
-  num,
-  resolveLegendConfig,
-  resolveSeriesFills,
-  text,
-  type LegendConfig,
-  type LegendTheme,
-} from "../kit/shared"
+  CHART_COLORS,
+  CHART_LEGEND,
+  CHART_TEXT,
+  legendConfigOf,
+  type ChartStyleBase,
+} from "../kit/style"
+import { num, text, type LegendConfig } from "../kit/shared"
+import { DEG, PIE_SPOTLIGHT_DIM, ringPoint, selectionFade, type CenterConfig, type PieSlice } from "../kit/polar"
 
-/**
- * One **resolved** slice of a {@link PieChart}: its caption, its magnitude, and
- * the paint its wedge and legend swatch take.
- *
- * This is what the ring and the legend consume, not what a scene authors: the
- * chart takes tabular `data` plus two field names and resolves it into these, so
- * the parts stay unaware of where a slice's caption, magnitude and paint came
- * from.
- */
-export interface PieSlice {
-  /** Legend caption and label text for this slice. */
-  category: string
-  /** This slice's magnitude. Its wedge covers `value / (sum of all values)`. */
-  value: number
-  /** Wedge and swatch paint. */
-  fill: Fill
-}
+export { DEG, PIE_SPOTLIGHT_DIM, ringPoint, selectionFade, type CenterConfig, type PieSlice }
 
 /**
- * Resolve tabular rows into slices: one per row, captioned by the `category`
- * column, sized by the `value` column, painted from `palette` by row order
- * (cycling when the palette is shorter than the data).
- *
- * Paint comes from the palette rather than from the rows because a pie draws one
- * mark per *row* — unlike the line and bar charts, where a colour belongs to a
- * series (a whole column) and rides on the series entry instead. Keeping it out
- * of the rows is what lets a pie be fed straight from a CSV of plain numbers.
+ * One slice per row, painted from `palette` by row order (cycling). Paint comes
+ * from the palette, not the rows, because a pie's mark is a row where a line's
+ * colour belongs to a column; that lets a pie be fed a CSV of plain numbers.
  */
-export function resolvePieSlices(
-  data: DataRecord[],
-  category: string,
-  value: string,
-  palette: Fill[]
-): PieSlice[] {
+export function resolvePieSlices(data: readonly Record<string, unknown>[], category: string, value: string, palette: readonly Fill[]): PieSlice[] {
   return data.map((row, i) => ({
-    category: text(row, category),
-    value: num(row, value),
-    fill:
-      palette.length > 0 ? palette[i % palette.length] : ("white" as Fill),
+    category: text(row as never, category),
+    value: num(row as never, value),
+    fill: palette.length > 0 ? palette[i % palette.length] : ("white" as Fill),
   }))
 }
 
 /** What a {@link PieChart}'s labels say. */
 export type PieLabelMode =
-  /**
-   * The category and its percentage, two lines. Their order flips with the
-   * placement: a **leader** label reads category over percentage, an **inside**
-   * label reads the percentage big over a small category caption — inside a
-   * wedge the reader already knows which slice they're on, so the magnitude is
-   * the thing being read.
-   */
+  /** Two lines, whose order flips with placement: an outside label reads category over percentage, an inside label reads the percentage big over a small category. */
   | "both"
-  /** The category only. */
   | "category"
-  /** The percentage only — the pick when a legend already names the categories. */
   | "percent"
-  /** No labels and no leader lines at all. */
+  /** No labels and no leader lines. */
   | "none"
 
-/**
- * Where a slice's label sits.
- *
- * `"inside"` drops the leader line entirely and centres the label in the wedge's
- * own band, which costs no gutter — so the ring draws bigger — and costs the eye
- * no round trip. `"leader"` is the classic treatment, and what a sliver too
- * narrow to hold text needs.
- */
-export type PieLabelPlacement = "inside" | "leader" | "none"
+/** `"inside"` centres the label in the wedge's band with no leader or gutter, so the ring draws bigger; `"outside"` sets it on a leader, which a sliver too narrow for text needs. */
+export type PieLabelPlacement = "inside" | "outside" | "none"
 
-/** Degrees → radians. */
-export const DEG = Math.PI / 180
 
 /** A slice's plotted value: negatives and non-finite values count as 0. */
 export function sliceValue(slice: PieSlice): number {
   return slice.value > 0 && Number.isFinite(slice.value) ? slice.value : 0
 }
 
-/** Sum of every slice's plotted value — the denominator every share is taken against. */
+/** Sum of every slice's plotted value, the denominator of every share. */
 export function sliceTotal(slices: PieSlice[]): number {
   let sum = 0
   for (const slice of slices) sum += sliceValue(slice)
   return sum
 }
 
-/**
- * The point at radius `r` and angle `a` on a ring centred on the origin, in the
- * node's centred, **y-up** space. Angles run **clockwise from 12 o'clock**:
- * `a = 0` points straight up (+y), and increasing `a` sweeps toward +x then −y.
- */
-export function ringPoint(r: number, a: number): Vector2 {
-  return { x: r * Math.sin(a), y: r * Math.cos(a) }
-}
-
 /** One slice's resolved angular span on the ring. */
 export interface PieArc {
   /** Index of the slice in the source list. */
   index: number
-  /** Start angle, radians clockwise from 12 o'clock. */
+  /** Radians clockwise from 12 o'clock. */
   a0: number
-  /** End angle, radians clockwise from 12 o'clock. */
   a1: number
-  /** Bisector angle — where this slice's label and pop-out point. */
+  /** Where the slice's label and pop-out point. */
   mid: number
-  /** This slice's share of the total, in `[0, 1]`. */
+  /** Share of the total, `[0, 1]`. */
   fraction: number
 }
 
 /**
- * Resolve slices into per-slice arcs: each covers exactly its share of the
- * circle, walking clockwise from `startDegrees` (0 = 12 o'clock), with the arcs
- * abutting. Zero/negative slices are skipped entirely; an all-zero list yields
- * no arcs.
- *
- * Arcs are the *undivided* shares — the gap between neighbours is not carved out
- * here, because a fixed angular gap reads as a wedge: wide at the rim, pinched
- * shut at the hole. It's applied when the wedge is drawn instead, as a
- * constant-width inset off both ends of every arc, so a slice still covers its
- * true percentage of the circle.
+ * One arc per positive slice, walking clockwise from `startDegrees` and abutting.
+ * Arcs are the undivided shares: a fixed angular gap would pinch shut at the
+ * hole, so the gap is applied when the wedge is drawn, as a constant-width inset
+ * off both ends.
  */
 export function pieArcs(slices: PieSlice[], startDegrees: number): PieArc[] {
   const total = sliceTotal(slices)
@@ -180,32 +87,21 @@ export function pieArcs(slices: PieSlice[], startDegrees: number): PieArc[] {
   return arcs
 }
 
-/** A label competing for vertical space in one of the two label columns. */
-export interface LabelSlot {
+interface LabelSlot {
   /** Where the label would sit if nothing else were in the way. */
   ideal: number
-  /** Where it ends up once the column has been de-conflicted. Written by {@link relaxLabels}. */
+  /** Written by {@link relaxLabels}. */
   y: number
 }
 
 /**
- * Spread one column of labels so no two overlap, keeping each as close to its
- * `ideal` y as possible and the whole column inside `[bottom, top]`.
- *
- * Two passes, the standard treatment. Walking top-to-bottom, each label takes
- * the highest slot at or below its ideal that still clears the label above it by
- * `minGap`; if that pushes the tail past `bottom`, a reverse pass lifts it back
- * up. When there are more labels than the column can hold, the reverse pass wins
- * and the crowding is shared evenly rather than dumped off the bottom edge.
- *
- * Mutates each slot's `y` and returns `slots` re-ordered top-to-bottom.
+ * Spread one column of labels so none overlap, each near its `ideal` y and all
+ * inside `[bottom, top]`. A top-down pass clears each label from the one above
+ * by `minGap`; a reverse pass lifts a tail pushed past `bottom`. When the column
+ * cannot hold them all, the reverse pass wins and the crowding is shared evenly.
+ * Mutates each `y` and returns `slots` ordered top to bottom.
  */
-export function relaxLabels<T extends LabelSlot>(
-  slots: T[],
-  minGap: number,
-  top: number,
-  bottom: number
-): T[] {
+export function relaxLabels<T extends LabelSlot>(slots: T[], minGap: number, top: number, bottom: number): T[] {
   slots.sort((a, b) => b.ideal - a.ideal)
 
   let ceiling = top
@@ -223,274 +119,91 @@ export function relaxLabels<T extends LabelSlot>(
   return slots
 }
 
-// ---- Theme ---------------------------------------------------------------
-
-/** The ring's geometry and paint — everything about the wedges but their colour. */
+/** The ring's geometry: everything about the wedges but their colour. */
 export interface RingConfig {
-  /**
-   * Width of the channel between adjacent slices, in px, held constant all the
-   * way across the band — the same clearance at the hole as at the rim. (An
-   * angular gap would splay open toward the rim instead.)
-   */
+  /** Channel between adjacent slices in px, constant across the band (an angular gap would splay open toward the rim). */
   gap: number
-  /**
-   * Radius of the hole punched through the middle. Below 1 it reads as a
-   * fraction of the ring's outer radius (`0.6` leaves a band 40% of the radius
-   * thick); 1 and up as an explicit pixel radius; `0` fills the middle in,
-   * drawing solid pie wedges.
-   */
+  /** Below 1 a fraction of the outer radius (`0.6` leaves a band 40% thick); 1 and up a pixel radius; `0` draws solid wedges. */
   holeRadius: number
-  /** Angle in degrees where the first slice begins, clockwise from 12 o'clock. */
+  /** Degrees clockwise from 12 o'clock where the first slice begins. */
   startAngle: number
-  /**
-   * How far out a selected slice's rim reaches, as a **multiple of the ring's
-   * outer radius**. Being relative, the emphasis scales with the chart instead
-   * of shrinking on a big one and swamping a small one. Clamped to `[1, 1.6]`.
-   */
+  /** How far a selected slice's rim reaches, as a multiple of the outer radius so the emphasis scales with the chart. Clamped to `[1, 1.6]`. */
   selectedGrow: number
-  /** Optional outline on every wedge. */
-  stroke: Stroke
-  /** Optional drop shadow on every wedge. */
-  shadow: Shadow
+  /** Rounding of each wedge corner, px. */
+  cornerRadius: number
 }
 
 /** How the ring's labels are set, and the leader lines that point at them. */
 export interface LabelConfig {
-  /** The category caption on a label. */
+  /** The category caption outside the ring. */
   textStyle: TextStyle
-  /** The percentage on a label. */
+  /** The percentage outside the ring. */
   percentStyle: TextStyle
-  /**
-   * Ink for a label set **inside** its wedge, both lines. Separate because an
-   * inside label sits on the wedge's own paint rather than on the background, so
-   * it usually wants the opposite end of the value range from everything else.
-   */
+  /** Both lines of a label inside its wedge; its fill is set per wedge, for contrast against the paint. */
   insideStyle: TextStyle
-  /** The leader line running from a wedge out to its label. */
+  /** Runs from a wedge out to its label. */
   leaderStroke: Stroke
 }
 
-/** The summary set in the ring's hole. */
-export interface CenterConfig {
-  labelStyle: TextStyle
-  captionStyle: TextStyle
-}
-
-/** A {@link PieChart}'s full, resolved visual theme. */
-export interface PieChartConfig {
-  /** Wedge and swatch paint, cycled by **row** index (`i % length`). */
-  sliceFills: Fill[]
-  ring: RingConfig
-  label: LabelConfig
-  center: CenterConfig
-  legend: LegendConfig
-  /** How far everything outside the selection fades while any slice is selected. */
-  spotlight: { dimOpacity: number }
-}
-
-/** Author-facing partial theme — every branch optional and deep-merged. */
-export type PieChartTheme = {
-  sliceFills?: Fill[]
-  ring?: Partial<RingConfig>
-  label?: Partial<LabelConfig>
-  center?: Partial<CenterConfig>
-  legend?: LegendTheme
-  spotlight?: Partial<PieChartConfig["spotlight"]>
-}
-
-const LABEL_TEXT_STYLE: TextStyle = {
-  fontSize: 26,
-  fontWeight: 600,
-  textAlign: "center",
-  fill: CHART_PALETTE.markerColor,
-}
-
-/**
- * Opacity the other slices fade to under a selection. Fainter than the line and
- * bar charts' `SPOTLIGHT_DIM`: a ring's slices touch, so at that a selected
- * slice barely separates from its neighbours.
- */
-export const PIE_SPOTLIGHT_DIM = 0.1
-
-/** The pie chart's out-of-the-box look. */
-export const DEFAULT_PIE_CHART_THEME: PieChartConfig = {
-  sliceFills: DEFAULT_SERIES_FILLS,
-  ring: {
-    gap: 6,
-    // A donut rather than a solid pie by default: the hole is the largest
-    // uninterrupted area the chart owns and the one place a conclusion can be
-    // set. `0` here would give that away before anyone had asked for it.
-    holeRadius: 0.6,
-    startAngle: 0,
-    selectedGrow: 1.08,
-    stroke: [],
-    shadow: [],
-  },
-  label: {
-    textStyle: LABEL_TEXT_STYLE,
-    percentStyle: { ...LABEL_TEXT_STYLE, fontWeight: 700 },
-    // Inside labels sit on the wedge's paint, which is a mid-tone from the
-    // palette — so they lead with the panel colour rather than the axis ink.
-    insideStyle: { ...LABEL_TEXT_STYLE, fontWeight: 800, fill: "#15130e" },
-    leaderStroke: { weight: 2, fill: CHART_PALETTE.markerColor },
+/** What a pie's `style` resolves to. */
+export interface PieStyle extends ChartStyleBase {
+  readonly innerRadius: number
+  readonly sliceGap: number
+  readonly sliceRadius: number
+  readonly labelPlacement: PieLabelPlacement
+}
+
+/** The groups of a pie's `style`: no grid, as nothing is ruled. */
+export const PIE_STYLE_GROUPS = {
+  colors: CHART_COLORS,
+  text: CHART_TEXT,
+  marks: {
+    /** Hole radius as a fraction of the outer radius: 0 is a pie, about 0.6 a donut. */
+    innerRadius: Types.number(0, { min: 0, max: 0.9, step: 0.05 }),
+    /** Channel between neighbouring wedges, px. */
+    sliceGap: Types.number(3, { min: 0, max: 40, step: 1, unit: "px" }),
+    /** Rounding of each wedge corner, px. */
+    sliceRadius: Types.number(4, { min: 0, max: 60, step: 1, unit: "px" }),
   },
-  center: {
-    labelStyle: {
-      fontSize: 46,
-      fontWeight: 800,
-      textAlign: "center",
-      fill: CHART_PALETTE.markerColor,
-    },
-    captionStyle: {
-      fontSize: 22,
-      fontWeight: 500,
-      textAlign: "center",
-      fill: CHART_PALETTE.markerColor,
-    },
+  labels: {
+    /** Read as the chart is built: inside the wedge, outside on a leader, or none. */
+    labelPlacement: Types.oneOf(["inside", "outside", "none"] as const, { animatable: false }),
   },
-  legend: DEFAULT_LEGEND,
-  spotlight: { dimOpacity: PIE_SPOTLIGHT_DIM },
-}
-
-function resolveRingConfig(
-  ring: Partial<RingConfig> | undefined,
-  previous: RingConfig
-): RingConfig {
-  return {
-    gap: ring?.gap ?? previous.gap,
-    holeRadius: ring?.holeRadius ?? previous.holeRadius,
-    startAngle: ring?.startAngle ?? previous.startAngle,
-    selectedGrow: ring?.selectedGrow ?? previous.selectedGrow,
-    stroke: strokeOps.resolve(ring?.stroke ?? previous.stroke),
-    shadow: shadowOps.resolve(ring?.shadow ?? previous.shadow),
-  }
+  legend: CHART_LEGEND,
 }
 
-function lerpRingConfig(
-  from: RingConfig,
-  to: RingConfig,
-  t: number
-): RingConfig {
-  return {
-    gap: lerpNumber(from.gap, to.gap, t),
-    holeRadius: lerpNumber(from.holeRadius, to.holeRadius, t),
-    startAngle: lerpNumber(from.startAngle, to.startAngle, t),
-    selectedGrow: lerpNumber(from.selectedGrow, to.selectedGrow, 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
-    ),
-  }
+export function legendOf(style: PieStyle): LegendConfig {
+  return legendConfigOf(style)
 }
 
-function resolveLabelConfig(
-  label: Partial<LabelConfig> | undefined,
-  previous: LabelConfig
-): LabelConfig {
-  return {
-    textStyle: textOps.resolveStyle(label?.textStyle, previous.textStyle),
-    percentStyle: textOps.resolveStyle(
-      label?.percentStyle,
-      previous.percentStyle
-    ),
-    insideStyle: textOps.resolveStyle(label?.insideStyle, previous.insideStyle),
-    leaderStroke: strokeOps.resolve(
-      label?.leaderStroke ?? previous.leaderStroke
-    ),
-  }
+function face(style: PieStyle): Pick<TextStyle, "fontFamily"> {
+  return style.fontFamily ? { fontFamily: style.fontFamily } : {}
 }
 
-function lerpLabelConfig(
-  from: LabelConfig,
-  to: LabelConfig,
-  t: number
-): LabelConfig {
-  return {
-    textStyle: textOps.lerpStyle(from.textStyle, to.textStyle, t),
-    percentStyle: textOps.lerpStyle(from.percentStyle, to.percentStyle, t),
-    insideStyle: textOps.lerpStyle(from.insideStyle, to.insideStyle, t),
-    leaderStroke: strokeOps.lerp(
-      from.leaderStroke as StrokeResolved[],
-      to.leaderStroke as StrokeResolved[],
-      t
-    ),
-  }
+export function ringConfigOf(style: PieStyle): RingConfig {
+  return { gap: style.sliceGap, holeRadius: style.innerRadius, startAngle: 0, selectedGrow: 1.08, cornerRadius: style.sliceRadius }
 }
 
-function resolveCenterConfig(
-  center: Partial<CenterConfig> | undefined,
-  previous: CenterConfig
-): CenterConfig {
+export function labelConfigOf(style: PieStyle): LabelConfig {
+  const base: TextStyle = { ...face(style), fontSize: style.fontSize, fontWeight: style.fontWeight, textAlign: "center", fill: style.muted }
+  const bold = Math.min(900, style.fontWeight + 200)
   return {
-    labelStyle: textOps.resolveStyle(center?.labelStyle, previous.labelStyle),
-    captionStyle: textOps.resolveStyle(
-      center?.captionStyle,
-      previous.captionStyle
-    ),
+    textStyle: base,
+    percentStyle: { ...base, fontWeight: bold, fill: style.foreground },
+    insideStyle: { ...base, fontSize: Math.round(style.fontSize * 1.9), fontWeight: bold, fill: "#111113" },
+    leaderStroke: { weight: 2, fill: style.muted },
   }
 }
 
-function lerpCenterConfig(
-  from: CenterConfig,
-  to: CenterConfig,
-  t: number
-): CenterConfig {
+export function centerConfigOf(style: PieStyle): CenterConfig {
   return {
-    labelStyle: textOps.lerpStyle(from.labelStyle, to.labelStyle, t),
-    captionStyle: textOps.lerpStyle(from.captionStyle, to.captionStyle, t),
-  }
-}
-
-/**
- * {@link PieChart}'s `theme` property mapper: merges the author's partial
- * {@link PieChartTheme} onto `previous` (falling back to
- * {@link DEFAULT_PIE_CHART_THEME} on first resolution), fully resolving every
- * leaf so the tween below always has resolved data to interpolate.
- */
-export function resolvePieChartTheme(
-  theme: PieChartTheme | undefined,
-  previous?: PieChartConfig
-): PieChartConfig {
-  const base = previous ?? DEFAULT_PIE_CHART_THEME
-  return {
-    sliceFills: resolveSeriesFills(theme?.sliceFills, base.sliceFills),
-    ring: resolveRingConfig(theme?.ring, base.ring),
-    label: resolveLabelConfig(theme?.label, base.label),
-    center: resolveCenterConfig(theme?.center, base.center),
-    legend: resolveLegendConfig(theme?.legend, base.legend),
-    spotlight: {
-      dimOpacity: theme?.spotlight?.dimOpacity ?? base.spotlight.dimOpacity,
-    },
-  }
-}
-
-/** {@link PieChart}'s `theme` property tween — leaf by leaf. */
-export function lerpPieChartTheme(
-  from: PieChartConfig,
-  to: PieChartConfig,
-  t: number
-): PieChartConfig {
-  return {
-    // A palette is a list of independent paints rather than one value, so it
-    // interpolates pairwise by index; one that grows or shrinks holds the longer
-    // side's tail, exactly as the cartesian charts' palettes do.
-    sliceFills: lerpSeriesFills(from.sliceFills, to.sliceFills, t),
-    ring: lerpRingConfig(from.ring, to.ring, t),
-    label: lerpLabelConfig(from.label, to.label, t),
-    center: lerpCenterConfig(from.center, to.center, t),
-    legend: lerpLegendConfig(from.legend, to.legend, t),
-    spotlight: {
-      dimOpacity: lerpNumber(
-        from.spotlight.dimOpacity,
-        to.spotlight.dimOpacity,
-        t
-      ),
+    labelStyle: {
+      ...face(style),
+      fontSize: Math.round(style.fontSize * 1.8),
+      fontWeight: Math.min(900, style.fontWeight + 300),
+      textAlign: "center",
+      fill: style.foreground,
     },
+    captionStyle: { ...face(style), fontSize: Math.round(style.fontSize * 0.8), fontWeight: style.fontWeight, textAlign: "center", fill: style.muted },
   }
 }

package/src/radar-chart/index.ts

@@ -0,0 +1,4 @@
+export { RadarChart, radarFractions, radarScale, type RadarValues } from "./radar-chart"
+export { RadarGrid } from "./radar-grid"
+export { RadarSeries, seriesVertices } from "./radar-series"
+export { RADAR_GRID, RADAR_MARKS, fitRadius, niceCeil, spokeDirection } from "./shared"