@motionscript/charts 0.1.0 → 0.1.1-alpha.0

package/src/pie-chart/index.ts

@@ -1,18 +1,7 @@
-/**
- * The pie chart: the one in the family that draws a mark per **row** rather
- * than per column.
- *
- * So it shares the legend and the theme machinery with its siblings and none of
- * the cartesian geometry. Set the theme's `ring.holeRadius` to 0 for a solid
- * pie; it defaults to a donut, because the hole is the only place a chart has
- * to put its conclusion.
- */
 export { PieChart, isSliceSelected } from "./pie-chart"
-export type { PieChartProps, PieChartValues } from "./pie-chart"
+export type { PieChartValues } from "./pie-chart"
 export { PieRing } from "./pie-ring"
-export type { PieRingProps } from "./pie-ring"
 export { PieLegend } from "./pie-legend"
-export type { PieLegendProps } from "./pie-legend"
 export {
   DEFAULT_PIE_CHART_THEME,
   lerpPieChartTheme,

package/src/pie-chart/pie-chart.ts

@@ -1,20 +1,19 @@
 import {
   Rect,
   Types,
+  clamp,
   component2d,
   easeOut,
   type ChildView,
   type DataRecord,
   type NodeOf,
-  // Named so this component's emitted type reaches `Node2D` through the sdk, not core.
+  // Named so this component's emitted type reaches `Node2D` and its props through the sdk, not core.
   type Node2D,
-  type Node2DProps,
-  type Timeline,
+  type Node2DProps as _Node2DProps,
 } from "@motionscript/sdk"
 
 import { asParts, fresh } from "../kit/entries"
-import { beats, type Beat } from "../kit/motion"
-import { clampUnit } from "../kit/shared"
+import { beats, type AnyTimeline, type Beat } from "../kit/motion"
 import { PieLegend } from "./pie-legend"
 import { PieRing } from "./pie-ring"
 import {
@@ -22,6 +21,7 @@ import {
   lerpPieChartTheme,
   resolvePieChartTheme,
   resolvePieSlices,
+  selectionFade,
   type PieChartConfig,
   type PieChartTheme,
   type PieLabelMode,
@@ -29,40 +29,6 @@ import {
   type PieSlice,
 } from "./shared"
 
-export interface PieChartProps extends Node2DProps {
-  /** One row per slice — a plain record of field name to value. */
-  data: DataRecord[]
-  /** Key into each row for its slice caption, used on the labels and the legend. */
-  categoryField: string
-  /** Key into each row for its slice magnitude — the wedge's share of the ring. */
-  valueField: string
-  /**
-   * The chart's visual theme — slice palette, ring geometry, label and centre
-   * type, legend. Every branch is optional and deep-merged onto
-   * {@link DEFAULT_PIE_CHART_THEME}.
-   */
-  theme?: PieChartTheme
-  /** What the ring's labels say. */
-  labelMode?: PieLabelMode
-  /** Where they sit: inside their wedge, outside on a leader, or nowhere. */
-  labelPlacement?: PieLabelPlacement
-  /** Whether the legend column beside the ring is drawn at all. */
-  showLegend?: boolean
-  /** Gap between the ring and the legend, in px. */
-  gap?: number
-  /** Text set in the ring's hole — see `revealCenter`. */
-  centerLabel?: string
-  /** Smaller second line under {@link centerLabel}. */
-  centerCaption?: string
-  /**
-   * Whether the hole's summary is drawn at rest. `true` (the default) is the
-   * plain answer; a scene that wants the conclusion to land on a later beat sets
-   * this `false` and runs `revealCenter` when it gets there.
-   */
-  showCenter?: boolean
-}
-
-/** What the selection reads: the rows, how they are cut, and the pops the commands move. */
 export interface PieChartValues {
   readonly data: DataRecord[]
   readonly categoryField: string
@@ -71,57 +37,42 @@ export interface PieChartValues {
   readonly pops: number[]
 }
 
-/**
- * How `enter` divides its duration: the wedges sweeping in, then the labels and
- * the legend arriving together. Shares of the whole, so they sum to 1.
- */
+/** How `enter` divides its duration: wedges sweeping in, then labels and legend together. Sums to 1. */
 const SWEEP_SHARE = 0.65
 const LABEL_SHARE = 0.35
 
 const SLICE_ARG = Types.number(0, { min: 0, step: 1 })
 
-/** The slices the ring and the legend draw, resolved from the rows and the palette. */
 function slicesOf(s: PieChartValues): PieSlice[] {
   return resolvePieSlices(s.data, s.categoryField, s.valueField, s.theme.sliceFills)
 }
 
-/** How far slice `index` is pushed out, in `[0, 1]`. */
 function popAt(s: PieChartValues, index: number): number {
-  return clampUnit(s.pops[index] ?? 0)
+  return clamp(s.pops[index] ?? 0, 0, 1)
 }
 
-/** Whether slice `index` is grown out past the ring's rim: past half way, so a slice mid-swell is not yet counted. */
+/** Whether slice `index` is past half way out, so a slice mid-swell is not yet counted. */
 export function isSliceSelected(s: PieChartValues, index: number): boolean {
   return popAt(s, index) > 0.5
 }
 
-/**
- * How far each slice is dimmed by the selection, one entry per slice: 1 while
- * nothing is out, and for the selected slice itself; falling toward the theme's
- * `dimOpacity` for the rest in proportion to how far the selection has grown.
- */
+/** Per-slice opacity: 1 while nothing is out and for the selected slice, falling toward `dimOpacity` for the rest as the selection grows. */
 function sliceDims(s: PieChartValues): number[] {
   let focus = 0
   for (let i = 0; i < s.data.length; i++) focus = Math.max(focus, popAt(s, i))
   const dim = s.theme.spotlight.dimOpacity
-  if (focus <= 0) return s.data.map(() => 1)
-  return s.data.map((_, i) => 1 - (1 - clampUnit(dim)) * focus * (1 - popAt(s, i)))
+  return s.data.map((_, i) => selectionFade(focus, dim, popAt(s, i)))
 }
 
-type AnyTimeline = Timeline<any, any>
-
-/**
- * Every slice's pop eased from where it is to what `pop` asks for. A move that
- * changes nothing still takes its slot, writing nothing.
- */
+/** Every slice's pop eased to what `pop` asks for. A move that changes nothing still takes its slot. */
 function popping(timeline: AnyTimeline, s: PieChartValues, pop: (index: number) => number) {
   const from = s.data.map((_, i) => popAt(s, i))
-  const targets = s.data.map((_, i) => clampUnit(pop(i)))
+  const targets = s.data.map((_, i) => clamp(pop(i), 0, 1))
   if (from.every((value, i) => value === targets[i])) return timeline.wait(timeline.duration)
   return timeline.animate((t) => ({ pops: from.map((value, i) => value + (targets[i] - value) * t) }))
 }
 
-/** The ring and the legend, found through the chart's children: the last row of them is the one it built. */
+/** The ring and legend among the children; the last row is the one the chart built. */
 function partsOf(children: readonly ChildView[]) {
   for (let i = children.length - 1; i >= 0; i--) {
     const row = children[i]
@@ -132,57 +83,48 @@ function partsOf(children: readonly ChildView[]) {
 }
 
 /**
- * A pie or donut chart, composed from two parts laid out by a horizontal-flow
- * {@link Rect} — the ring filling whatever the hugging legend leaves, both
- * centred:
- *
- * - {@link PieRing} — the wedges, each sized by its share of the total, with its
- *   label inside its own band or pinned outside on a leader line, and the
- *   summary in the hole.
- * - {@link PieLegend} — a column of swatch-and-caption rows naming each slice.
- *
- * **One mark per row, not per column**: a pie's palette is indexed by row and
- * there is nothing to hide, since dropping a slice would re-cut every other
- * wedge. `selectSlice` and its siblings are what a pie has instead — a slice
- * swells out of the ring and everything else dims behind it.
+ * A pie or donut chart: a {@link PieRing} filling what the hugging {@link PieLegend}
+ * leaves. One mark per row, not per column, and nothing to hide, since dropping
+ * a slice would re-cut every other wedge; `selectSlice` and its siblings swell
+ * a slice and dim the rest instead.
  *
- * **Resting state is the finished chart**; `enter` arms every part on its first
- * frame. The one exception is the hole's summary, which a scene can hold back
- * with `showCenter: false`, because it is usually the chart's *conclusion*.
+ * Resting state is the finished chart, except the hole's summary, which
+ * `showCenter: false` holds back for `revealCenter`.
  */
 export const PieChart = component2d({
   key: "pieChart",
   state: {
     data: fresh<DataRecord[]>(() => []),
+    /** Slice caption, used on the labels and the legend. */
     categoryField: "",
+    /** Slice magnitude: the wedge's share of the ring. */
     valueField: "",
     theme: Types.custom<PieChartTheme, PieChartConfig>(DEFAULT_PIE_CHART_THEME, { resolve: resolvePieChartTheme, lerp: lerpPieChartTheme }),
+    /** What the ring's labels say. */
     labelMode: Types.custom<PieLabelMode>("percent"),
+    /** Where they sit: inside their wedge, outside on a leader, or nowhere. */
     labelPlacement: Types.custom<PieLabelPlacement>("leader"),
+    /** Gap between the ring and the legend, in px. */
     gap: 40,
+    /** Text set in the ring's hole. */
     centerLabel: "",
+    /** Smaller second line under `centerLabel`. */
     centerCaption: "",
-    /**
-     * How far each slice is pushed out of the ring, `0`–`1` per index. Held here
-     * rather than on the ring because two parts read it: the wedges grow out by
-     * it, and the legend entries dim by it. Seeded flush, one to a row.
-     */
+    /** How far each slice is pushed out, `0`-`1` per index. Here, not on the ring, because the wedges and the legend both read it. */
     pops: fresh<number[]>(() => []),
     /** Read as the chart is built: the legend is a part the chart builds or doesn't. */
     showLegend: Types.boolean(true, { animatable: false }),
-    /** Read as the chart is built: whether the hole's summary is drawn at rest. */
+    /** Read as the chart is built: whether the hole's summary is drawn at rest. A scene that wants it to land later sets `false` and runs `revealCenter`. */
     showCenter: Types.boolean(true, { animatable: false }),
   },
   defaults: {
-    // Its parts fill it; a node made of them would hug them.
+    // A node made of parts that fill would otherwise hug them.
     width: "fill",
     height: "fill",
     pops: (state) => slicesOf(state).map(() => 0),
   },
   allowedChildren: [],
-  // The slice *structure* (one label and one legend row per row) is read once;
-  // the slices themselves, their paint and the selection are bound, so a theme
-  // tween re-paints and a `set` of `data` re-cuts the wedges.
+  // The structure (a label and legend row per row) is read once; slices, paint and selection are bound, so a theme tween re-paints and a `set` of `data` re-cuts.
   children: (state) => {
     const theme = () => state.theme
     const slices = () => slicesOf(state)
@@ -209,8 +151,7 @@ export const PieChart = component2d({
           slices,
           legend: () => theme().legend,
           dims: () => sliceDims(state),
-          // The column's spacing is the theme's as the chart was built, like the
-          // entries' type and chips.
+          // Spacing is fixed as built.
           gap: state.theme.legend.itemGap / 3,
           padding: state.theme.legend.padding,
         }) as unknown as Node2D
@@ -220,15 +161,10 @@ export const PieChart = component2d({
     return asParts([row as unknown as Node2D])
   },
   commands: {
-    /**
-     * Animate the whole chart in: the wedges sweep in clockwise from the theme's
-     * `startAngle`, then the labels fade up and the legend staggers in together.
-     * Its first frame arms the wedges, the labels and the legend; the hole's
-     * summary keeps its own signal. `duration` is the **whole** entrance.
-     */
+    /** Wedges sweep in clockwise from `startAngle`, then labels fade up and the legend staggers in. `duration` is the whole entrance; the hole's summary keeps its own signal. */
     enter: {
       args: {},
-      // Held from the chart's arrival, so it never shows finished ahead of its draw.
+      // Held from arrival, so it never shows finished ahead of its draw.
       entrance: true,
       easing: easeOut(),
       run: (timeline, _state, children) => {
@@ -247,11 +183,7 @@ export const PieChart = component2d({
         ])
       },
     },
-    /**
-     * Fade the hole's summary up. Held out of `enter` on purpose: what sits in a
-     * donut's hole is usually the chart's conclusion, so the scene lands it on
-     * its own beat. Pair it with `showCenter: false`.
-     */
+    /** Fade the hole's summary up. Not part of `enter`: it is usually the conclusion, which a scene lands on its own beat. */
     revealCenter: {
       args: {},
       easing: easeOut(),

package/src/pie-chart/pie-legend.ts

@@ -5,10 +5,10 @@ import {
   Shapes,
   Text,
   Types,
+  clamp,
   component2d,
   textOps,
   type NodeOf,
-  type RectProps,
   // Named so the column's emitted type reaches the Rect surface it spreads through the sdk, not core.
   type Alignment as _Alignment,
   type CornerRadiusResolved as _CornerRadiusResolved,
@@ -31,43 +31,16 @@ import {
 
 import { fresh } from "../kit/entries"
 import { armed, arrival, arrivalOf, arrivalsEntry, beats, frameEase, type Arrival } from "../kit/motion"
-import {
-  DEFAULT_LEGEND,
-  clampUnit,
-  type LegendConfig,
-} from "../kit/shared"
+import { DEFAULT_LEGEND, type LegendConfig } from "../kit/shared"
 import type { PieSlice } from "./shared"
 
-export interface PieLegendProps extends RectProps {
-  /** One entry per slice, in ring order. */
-  slices: PieSlice[]
-  /** Padding, caption style, gaps, and swatch geometry — see {@link LegendConfig}. */
-  legend: LegendConfig
-  /**
-   * Per-slice opacity multiplier, by index — the same signal that dims the ring,
-   * so an entry fades in step with the wedge it names. Missing entries read as 1.
-   */
-  dims: number[]
-}
-
-/** How far an entry starts to the right of its slot when it enters, in px. */
 const SLIDE = 16
 
 /**
- * The legend of a {@link PieChart}: a **vertical-flow column** of entries, one per
- * slice, each pairing the slice's caption with its colour swatch.
- *
- * A column rather than the cartesian charts' row, because it sits *beside* the
- * ring rather than beneath the plot — a pie is as tall as it is wide, so the
- * space it leaves over is a vertical strip. It is otherwise the same entry: the
- * swatch carries the colour, the caption reads in the legend's neutral ink, and
- * both take the shared {@link LegendConfig}.
- *
- * There is no show/hide here. A pie's marks are its *rows*, and a row that
- * shouldn't be in the chart shouldn't be in the table — removing one would
- * silently re-cut every other wedge's share, which is a different chart rather
- * than the same chart with something hidden. Selection is what a pie has
- * instead, and it arrives through {@link PieLegendProps.dims}.
+ * The legend of a {@link PieChart}: a column (it sits beside the ring, in the
+ * vertical strip it leaves) of caption-and-swatch entries, one per slice. No
+ * show/hide: removing a row would re-cut every other wedge's share. Selection
+ * arrives through `dims`.
  */
 export const PieLegend = component2d({
   key: "pieLegend",
@@ -75,13 +48,14 @@ export const PieLegend = component2d({
     ...Paint.state,
     ...Flow.state,
     ...Shapes.corners,
+    /** One entry per slice, in ring order. */
     slices: fresh<PieSlice[]>(() => []),
     legend: Types.custom<LegendConfig>(DEFAULT_LEGEND),
+    /** Per-slice opacity multiplier, the signal that dims the ring, so an entry fades in step with its wedge. Missing reads as 1. */
     dims: fresh<number[]>(() => []),
     arrivals: arrivalsEntry(),
   },
-  // A column, for the reason `ChartLegend` gives for its row: a `Rect` given no
-  // flow lays its children out `freeform`, every caption on top of the last.
+  // The flow must be stated: a `Rect` with none lays children out `freeform`, every caption on top of the last.
   defaults: {
     flow: "vertical",
     align: "centerLeft",
@@ -90,10 +64,7 @@ export const PieLegend = component2d({
     gap: (state) => state.legend.itemGap / 3,
     padding: (state) => state.legend.padding,
   },
-  // One entry per slice, ordered top → bottom. The selection dim rides a wrapper
-  // rather than the entry itself, so the entrance can animate the entry's own
-  // opacity without the two fighting over one value — opacity multiplies down
-  // the tree, which is exactly the composition wanted here.
+  // The selection dim rides a wrapper, so the entrance animates the entry's own opacity without the two fighting over one value.
   children: (state) => {
     const marker = state.legend.markerStyle
     return state.slices.map((_, index) =>
@@ -101,7 +72,7 @@ export const PieLegend = component2d({
         width: "hug",
         height: "hug",
         flow: "freeform",
-        opacity: () => clampUnit(state.dims[index] ?? 1),
+        opacity: () => clamp(state.dims[index] ?? 1, 0, 1),
         children: [
           Rect({
             flow: "horizontal",
@@ -132,28 +103,16 @@ export const PieLegend = component2d({
   },
   commands: {
     ...Paint.commands,
-    /**
-     * Every entry at its pre-entrance state, shifted right and transparent: what
-     * a chart shows ahead of this legend's own beat in its entrance, since
-     * `enter` arms the entries only on its first frame.
-     */
+    /** Every entry shifted right and transparent: what a chart shows ahead of this legend's beat, since `enter` arms only on its first frame. */
     arm: (timeline, state) =>
       timeline.animate(() => ({ arrivals: armed([...state.slices.keys()], { opacity: 0, shift: SLIDE }) })),
-    /**
-     * Slide + fade every entry in from the right, staggered top-to-bottom. Its
-     * first frame arms them all: shifted right and transparent.
-     *
-     * The timeline's duration is the **whole** entrance: the stagger is carved
-     * out of it rather than added on top, so the command takes exactly the time
-     * the timeline laid out for it.
-     */
+    /** Slide and fade entries in from the right, top to bottom. The duration is the whole entrance, the stagger carved out of it. */
     enter: (timeline, state) => {
       const count = state.slices.length
       if (count === 0) return timeline.wait(timeline.duration)
       const from: Arrival = { opacity: 0, shift: SLIDE }
       const arm = timeline.animate(() => ({ arrivals: armed([...state.slices.keys()], from) }))
-      // Each gap is a fifth of an entry's own move, the rhythm the axes use;
-      // solved for from the budget rather than added to it.
+      // Each gap is a fifth of an entry's move, the axes' rhythm, solved from the budget.
       const per = timeline.duration / (1 + Math.max(0, count - 1) / 5)
       const step = per / 5
       const ease = frameEase(timeline)