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

package/src/kit/chart-canvas.ts

@@ -3,7 +3,6 @@ import {
   Types,
   component2d,
   fillOps,
-  shadowOps,
   strokeOps,
   type Fill,
   type FillResolved,
@@ -11,86 +10,82 @@ import {
   // Named so this component's emitted type reaches `Node2D` and its props through the sdk, not core.
   type Node2D as _Node2D,
   type Node2DProps as _Node2DProps,
-  type Shadow,
-  type ShadowResolved,
+  type RenderContext,
   type Stroke,
   type StrokeResolved,
+  type Vector2,
 } from "@motionscript/sdk"
 
 import { fresh } from "./entries"
 import { loadPaints } from "./paints"
-import {
-  DEFAULT_PLOT_AREA,
-  DEFAULT_X_AXIS,
-  DEFAULT_Y_AXIS,
-  type Range,
-} from "./shared"
+import type { Range } from "./shared"
+
+const strokeEntry = () => Types.custom<Stroke, StrokeResolved[]>([], { resolve: strokeOps.resolve, lerp: strokeOps.lerp })
+
+/** Where along a scale a fraction lands in a run of `length` px centred on 0. */
+function along(value: number, [min, max]: Range, length: number): number {
+  return (max <= min ? 0 : (value - min) / (max - min) - 0.5) * length
+}
 
-const strokeEntry = (initial: Stroke) =>
-  Types.custom<Stroke, StrokeResolved[]>(initial, { resolve: strokeOps.resolve, lerp: strokeOps.lerp })
+/** One rule per draw: stroking a union of open paths paints nothing, and a dashed rule keeps its own phase. */
+export function rule(ctx: RenderContext, from: Vector2, to: Vector2, stroke: StrokeResolved[], opacity = 1): void {
+  ctx.draw(new Graphics2D().line({ points: [from, to] }).stroke(stroke).opacity(opacity))
+}
 
 /**
- * The plot backdrop: a filled panel and a grid, sized from its box. The frame is
- * a separate {@link ChartBorder} drawn over the marks. Grid lines are placed from
- * the axis markers' data-unit positions mapped through the extents, so each lands
- * under its marker however the markers are spaced.
+ * The plot backdrop: the panel fill, the grid and the axis rules, sized from its
+ * box. Grid lines are placed from data-unit marker positions mapped through the
+ * extents, so each lands under its marker however the markers are spaced; a line
+ * on an edge is drawn just inside it.
  */
 export const ChartCanvas = component2d({
   key: "chartCanvas",
   state: {
-    fill: Types.custom<Fill, FillResolved[]>(DEFAULT_PLOT_AREA.fill, { resolve: fillOps.resolve, lerp: fillOps.lerp }),
-    shadow: Types.custom<Shadow, ShadowResolved[]>(DEFAULT_PLOT_AREA.shadow, { resolve: shadowOps.resolve, lerp: shadowOps.lerp }),
-    xGridStroke: strokeEntry(DEFAULT_X_AXIS.lineStyle),
-    yGridStroke: strokeEntry(DEFAULT_Y_AXIS.lineStyle),
-    /**
-     * Data-unit positions of the vertical grid lines, one per horizontal marker.
-     * Positions at or past an extent edge coincide with the border and are
-     * skipped. Empty for a categorical axis, which has no numeric position to rule at.
-     */
+    fill: Types.custom<Fill, FillResolved[]>([], { resolve: fillOps.resolve, lerp: fillOps.lerp }),
+    /** The vertical grid lines, one per `xMarkers` entry. */
+    xGridStroke: strokeEntry(),
+    /** The horizontal grid lines, one per `yMarkers` entry. */
+    yGridStroke: strokeEntry(),
     xMarkers: fresh<number[]>(() => []),
     yMarkers: fresh<number[]>(() => []),
     /** `[min, max]` of each scale, mapping the markers into the panel. */
     xExtent: fresh<Range>(() => [0, 1]),
     yExtent: fresh<Range>(() => [0, 1]),
+    /** The baseline and the value-axis rule. */
+    axisStroke: strokeEntry(),
+    /** Where the horizontal axis rule sits on the y scale, or `null` for none. */
+    xAxisAt: Types.custom<number | null>(null),
+    /** Where the vertical axis rule sits on the x scale, or `null` for none. */
+    yAxisAt: Types.custom<number | null>(null),
   },
-  // The grid strokes sit past the conventional slots, so they are named here.
-  load: (loader, state) =>
-    loadPaints(loader, { fills: [state.fill], shadows: [state.shadow], strokes: [state.xGridStroke, state.yGridStroke] }),
+  load: (loader, state) => loadPaints(loader, { fills: [state.fill], strokes: [state.xGridStroke, state.yGridStroke, state.axisStroke] }),
   render: (ctx, state) => {
     const { width: W, height: H } = ctx.size
     if (W <= 0 || H <= 0) return
+    if (state.fill.length > 0) ctx.draw(new Graphics2D().rect({ x: 0, y: 0, width: W, height: H }).fill(state.fill))
 
-    ctx.draw(new Graphics2D().rect({ x: 0, y: 0, width: W, height: H }).shadow(state.shadow).fill(state.fill))
-
-    const [xMin, xMax] = state.xExtent
-    const [yMin, yMax] = state.yExtent
-    // A zero-width extent maps to 0.
-    const xFrac = (v: number) => (xMax <= xMin ? 0 : (v - xMin) / (xMax - xMin))
-    const yFrac = (v: number) => (yMax <= yMin ? 0 : (v - yMin) / (yMax - yMin))
-    // Markers on or past the edges would sit under the border.
-    const interior = (f: number) => f > 1e-6 && f < 1 - 1e-6
-
-    const xStroke = state.xGridStroke[0]
-    if (xStroke) {
-      const xGrid = new Graphics2D()
-      for (const v of state.xMarkers) {
-        const f = xFrac(v)
-        if (!interior(f)) continue
-        xGrid.rect({ x: -W / 2 + f * W, y: 0, width: xStroke.weight, height: H })
+    const inside = (at: number, length: number, weight: number) => Math.max(-length / 2 + weight / 2, Math.min(length / 2 - weight / 2, at))
+    const verticals = (values: readonly number[], stroke: StrokeResolved[]) => {
+      const weight = stroke[0]?.weight ?? 0
+      if (weight <= 0) return
+      for (const v of values) {
+        const x = inside(along(v, state.xExtent, W), W, weight)
+        rule(ctx, { x, y: -H / 2 }, { x, y: H / 2 }, stroke)
       }
-      ctx.draw(xGrid.fill(xStroke.fill))
     }
-
-    const yStroke = state.yGridStroke[0]
-    if (yStroke) {
-      const yGrid = new Graphics2D()
-      for (const v of state.yMarkers) {
-        const f = yFrac(v)
-        if (!interior(f)) continue
-        yGrid.rect({ x: 0, y: -H / 2 + f * H, width: W, height: yStroke.weight })
+    const horizontals = (values: readonly number[], stroke: StrokeResolved[]) => {
+      const weight = stroke[0]?.weight ?? 0
+      if (weight <= 0) return
+      for (const v of values) {
+        const y = inside(along(v, state.yExtent, H), H, weight)
+        rule(ctx, { x: -W / 2, y }, { x: W / 2, y }, stroke)
       }
-      ctx.draw(yGrid.fill(yStroke.fill))
     }
+    const within = ([min, max]: Range) => (v: number) => v >= Math.min(min, max) - 1e-9 && v <= Math.max(min, max) + 1e-9
+    verticals(state.xMarkers.filter(within(state.xExtent)), state.xGridStroke)
+    horizontals(state.yMarkers.filter(within(state.yExtent)), state.yGridStroke)
+    if (state.xAxisAt !== null) horizontals([state.xAxisAt], state.axisStroke)
+    if (state.yAxisAt !== null) verticals([state.yAxisAt], state.axisStroke)
   },
 })
 

package/src/kit/chart-legend.ts

@@ -6,7 +6,6 @@ import {
   Text,
   Types,
   component2d,
-  textOps,
   type Fill,
   type NodeOf,
   // Named so the row's emitted type reaches the Rect surface it spreads through the sdk, not core.
@@ -28,6 +27,7 @@ import {
   type Vector2 as _Vector2,
 } from "@motionscript/sdk"
 
+import { boundText } from "./cartesian"
 import { fresh } from "./entries"
 import { frameEase } from "./motion"
 import {
@@ -40,18 +40,19 @@ import {
 const row = { ...Paint.state, ...Flow.state, ...Shapes.corners }
 
 /**
- * One legend entry, hugging its caption and swatch; `shown` scales that width
- * from nothing. The width is measured from the content at any reveal, so a frame
- * never depends on the entry once having been fully shown (`"hug"` is not a
- * number to scale until something measures it).
+ * One legend entry, hugging its swatch and caption; `shown` scales its length
+ * along the legend (`along`) from nothing. The length is measured from the
+ * content at any reveal, so a frame never depends on the entry once having been
+ * fully shown.
  */
 const LegendEntry = component2d({
   key: "legendEntry",
-  state: { ...row, shown: Types.number(1) },
+  state: { ...row, shown: Types.number(1), along: Types.oneOf(["horizontal", "vertical"] as const) },
   commands: { ...Paint.commands },
   measure: (measurer, state, children) => {
     const size = Flow.measure(measurer, state, children, Paint.inset(state))
-    return state.shown >= 1 ? size : { ...size, width: state.shown * size.width }
+    if (state.shown >= 1) return size
+    return state.along === "vertical" ? { ...size, height: state.shown * size.height } : { ...size, width: state.shown * size.width }
   },
   layout: (box, state, children) => Flow.layout(box, state, children, Paint.inset(state)),
   render: (ctx, state) => Paint.draw(ctx, state, Shapes.rect(ctx.size, state)),
@@ -65,7 +66,11 @@ function revealOf(value: readonly number[] | Readonly<Record<number, number>>, p
   return next
 }
 
-/** A chart's legend: a horizontal row with one entry per series, each a caption and a colour swatch. This node is the row, so the parent places it. */
+/**
+ * A chart's legend: one entry per series, a colour swatch then its caption, in
+ * a row (`flow: "horizontal"`) or a column (`"vertical"`, for a legend beside
+ * the plot). This node is the row, so the parent places it.
+ */
 export const ChartLegend = component2d({
   key: "chartLegend",
   state: {
@@ -75,7 +80,7 @@ export const ChartLegend = component2d({
     swatches: fresh<Fill[]>(() => []),
     legend: Types.custom<LegendConfig>(DEFAULT_LEGEND),
     /**
-     * How far each entry is shown, `0`-`1`, driving its width, opacity and gap
+     * How far each entry is shown, `0`-`1`, driving its length, opacity and gap
      * together. Entries are never added or removed: "is this node a child" is not
      * a function of time, while collapsed-but-present is.
      */
@@ -86,34 +91,37 @@ export const ChartLegend = component2d({
     flow: "horizontal",
     width: "hug",
     height: "hug",
-    gap: (state) => state.legend.itemGap,
+    gap: (state) => (state.flow === "vertical" ? Math.round(state.legend.itemGap * 0.4) : state.legend.itemGap),
     padding: (state) => state.legend.padding,
+    align: (state) => (state.flow === "vertical" ? "centerLeft" : "center"),
     reveal: (state) => state.series.map((s) => ((s.enabled ?? true) ? 1 : 0)),
   },
   // Every entry stays a child, so one always comes back where it belongs.
   children: (state) => {
-    const marker = state.legend.markerStyle
+    const marker = () => state.legend.markerStyle
+    const along = state.flow === "vertical" ? "vertical" : "horizontal"
     return state.series.map((series, index) =>
       LegendEntry({
         flow: "horizontal",
-        gap: 12,
+        gap: () => Math.round(((state.legend.textStyle.fontSize as number | undefined) ?? 24) * 0.45),
         align: "center",
         width: "hug",
         height: "hug",
-        // The width follows the reveal in `measure`, and the flanking gap closes with the entry.
+        along,
+        // The length follows the reveal in `measure`, and the flanking gap closes with the entry.
         opacity: () => state.reveal[index] ?? 0,
         gapScale: () => state.reveal[index] ?? 0,
         shown: () => state.reveal[index] ?? 0,
         children: [
-          Text({ ...textOps.styleProps(state.legend.textStyle), text: series.label }),
           Rect({
-            width: marker.width,
-            height: marker.height,
-            cornerRadius: marker.borderRadius,
-            fill: state.swatches[index] ?? "white",
-            stroke: marker.stroke,
-            shadow: marker.shadow,
+            width: () => marker().width,
+            height: () => marker().height,
+            cornerRadius: () => marker().borderRadius,
+            fill: () => state.swatches[index] ?? "white",
+            stroke: () => marker().stroke,
+            shadow: () => marker().shadow,
           }),
+          Text({ ...boundText(() => state.legend.textStyle), text: series.label || series.field }),
         ],
       })
     )

package/src/kit/horizontal-axis.ts

@@ -0,0 +1,114 @@
+import {
+  Rect,
+  Text,
+  Types,
+  component2d,
+  type NodeOf,
+  // Named so this component's emitted type reaches `Node2D` and its props through the sdk, not core.
+  type Node2D,
+  type Node2DProps as _Node2DProps,
+} from "@motionscript/sdk"
+import { enterBudget } from "@motionscript/sdk/component"
+
+import { boundText } from "./cartesian"
+import { asParts, fresh } from "./entries"
+import { armed, arrival, arrivalOf, arrivalsEntry, beats, frameEase, type Arrival } from "./motion"
+import { DEFAULT_X_AXIS, type AxisConfig, type Range } from "./shared"
+import { axisPads, markerCaption } from "./vertical-axis"
+
+const SLIDE = 24
+
+/**
+ * A row of {@link Text} markers under the plot, the mirror of `VerticalAxis`
+ * (bound text and positions, landed resting state). Markers are placed by value
+ * across the range, whatever they say: `2026-03` sits three months along, not
+ * three slots along, unlike a bar chart's category axis. An end marker may hang
+ * past the row by `overhang` px on either side, then is held inside it.
+ */
+export const HorizontalAxis = component2d({
+  key: "horizontalAxis",
+  state: {
+    range: fresh<Range>(() => [0, 1]),
+    /** Tick values in data units. */
+    markers: fresh<number[]>(() => []),
+    /** One caption per marker in its order; a missing one reads as the bare numeric value. */
+    captions: fresh<string[]>(() => []),
+    axis: Types.custom<AxisConfig>(DEFAULT_X_AXIS),
+    /** Caption centred beneath the markers; empty hides it. */
+    label: "",
+    /** How far past the row's left and right ends a marker may reach, in px. */
+    overhang: Types.custom<{ left: number; right: number }>({ left: 0, right: 0 }),
+    arrivals: arrivalsEntry(),
+  },
+  // A node made of markers would otherwise hug them.
+  defaults: { width: "fill", height: "fill" },
+  children: (state) => {
+    const pads = () => axisPads(state.axis, "top")
+    const sorted = () => [...state.markers].sort((a, b) => a - b)
+    const fracAt = (value: number | undefined) => {
+      if (value === undefined) return 0
+      const [min, max] = state.range
+      return max <= min ? 0 : (value - min) / (max - min)
+    }
+
+    const markers = state.markers.map((_, i) => {
+      const width = () => (marker.parent as Node2D | null)?.layoutBounds.width ?? 0
+      const marker: Node2D = new Text({
+        ...boundText(() => state.axis.labelStyle),
+        text: () => {
+          const value = sorted()[i]
+          return value === undefined ? "" : markerCaption(state, value)
+        },
+        x: () => {
+          const w = width()
+          const half = marker.layoutBounds.width / 2
+          const centred = (fracAt(sorted()[i]) - 0.5) * w
+          return Math.max(-w / 2 - state.overhang.left + half, Math.min(w / 2 + state.overhang.right - half, centred))
+        },
+        opacity: () => arrivalOf(state.arrivals, i).opacity,
+        y: () => arrivalOf(state.arrivals, i).shift,
+      })
+      return marker
+    })
+
+    const children: Node2D[] = [
+      new Rect({ width: "fill", height: "hug", padding: () => ({ top: pads().tick }), children: markers }) as unknown as Node2D,
+    ]
+    if (state.label !== "") {
+      children.push(
+        new Text({
+          ...boundText(() => state.axis.titleStyle),
+          text: state.label,
+          opacity: () => arrivalOf(state.arrivals, "label").opacity,
+          y: () => arrivalOf(state.arrivals, "label").shift,
+        }) as unknown as Node2D
+      )
+    }
+    return asParts([new Rect({ flow: "vertical", gap: () => pads().title, height: "hug", width: "fill", children }) as unknown as Node2D])
+  },
+  commands: {
+    /** Stagger markers in left to right, then the caption. The duration is the whole entrance ({@link enterBudget}). */
+    enter: {
+      args: {
+        stagger: Types.custom<number | undefined>(undefined),
+        slide: Types.number(SLIDE),
+      },
+      run: (timeline, state) => {
+        const { stagger, slide } = timeline.args
+        const count = state.markers.length
+        const captioned = state.label !== ""
+        const from: Arrival = { opacity: 0, shift: slide }
+        const keys = [...state.markers.keys(), ...(captioned ? ["label"] : [])]
+        const arm = timeline.animate(() => ({ arrivals: armed(keys, from) }))
+        if (count === 0) return arm
+        const { step, per, caption } = enterBudget(timeline.duration, count, captioned, stagger)
+        const ease = frameEase(timeline)
+        const markers = state.markers.map((_, i) => ({ at: i * step, duration: per, piece: arrival(timeline, i, from, ease) }))
+        const label = captioned ? [{ at: (count - 1) * step + per, duration: caption, piece: arrival(timeline, "label", from, ease) }] : []
+        return timeline.together([arm, beats(timeline, [...markers, ...label])])
+      },
+    },
+  },
+})
+
+export type HorizontalAxis = NodeOf<typeof HorizontalAxis>

package/src/kit/motion.ts

@@ -8,6 +8,13 @@ export type AnyTimeline = Timeline<any, any>
 /** How far a legend starts below its slot when `enter` brings it in, in px. */
 export const LEGEND_SLIDE = 20
 
+/** Where a legend waits before it comes up: below its place, above it, or to its right. */
+export function legendAway(at: string): { x?: number; y?: number } {
+  if (at === "top") return { y: LEGEND_SLIDE }
+  if (at === "right") return { x: LEGEND_SLIDE }
+  return { y: -LEGEND_SLIDE }
+}
+
 /** Marker count when an axis states no ticks. */
 export const DEFAULT_MARKERS = 5
 

package/src/{pie-chart → kit}/pie-legend.ts

@@ -29,10 +29,10 @@ import {
   type Vector2 as _Vector2,
 } from "@motionscript/sdk"
 
-import { fresh } from "../kit/entries"
-import { armed, arrival, arrivalOf, arrivalsEntry, beats, frameEase, type Arrival } from "../kit/motion"
-import { DEFAULT_LEGEND, type LegendConfig } from "../kit/shared"
-import type { PieSlice } from "./shared"
+import { fresh } from "./entries"
+import { armed, arrival, arrivalOf, arrivalsEntry, beats, frameEase, type Arrival } from "./motion"
+import { DEFAULT_LEGEND, type LegendConfig } from "./shared"
+import type { PieSlice } from "./polar"
 
 const SLIDE = 16
 
@@ -66,7 +66,7 @@ export const PieLegend = component2d({
   },
   // 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
+    const marker = () => state.legend.markerStyle
     return state.slices.map((_, index) =>
       Rect({
         width: "hug",
@@ -76,7 +76,7 @@ export const PieLegend = component2d({
         children: [
           Rect({
             flow: "horizontal",
-            gap: 12,
+            gap: () => Math.round(state.legend.textStyle.fontSize === undefined ? 12 : Number(state.legend.textStyle.fontSize) * 0.4),
             align: "center",
             width: "hug",
             height: "hug",
@@ -84,15 +84,16 @@ export const PieLegend = component2d({
             x: () => arrivalOf(state.arrivals, index).shift,
             children: [
               Rect({
-                width: marker.height,
-                height: marker.height,
-                cornerRadius: marker.borderRadius,
+                width: () => marker().width,
+                height: () => marker().height,
+                cornerRadius: () => marker().borderRadius,
                 fill: () => state.slices[index]?.fill ?? "white",
-                stroke: marker.stroke,
-                shadow: marker.shadow,
               }),
               Text({
                 ...textOps.styleProps(state.legend.textStyle),
+                fill: () => state.legend.textStyle.fill ?? "white",
+                fontSize: () => state.legend.textStyle.fontSize ?? 28,
+                fontWeight: () => state.legend.textStyle.fontWeight ?? 500,
                 text: () => state.slices[index]?.category ?? "",
               }),
             ],

package/src/kit/polar.ts

@@ -0,0 +1,54 @@
+/** What the polar charts (pie, radial) share: slices, ring geometry, the hole's summary and the selection fade. */
+
+import { clamp, fillOps, type Fill, type FillResolved, type TextStyle, type Vector2 } from "@motionscript/sdk"
+
+/** One resolved slice, which the ring and legend consume; the chart resolves it from `data` and two field names. */
+export interface PieSlice {
+  /** Label and legend caption. */
+  category: string
+  /** The wedge covers `value / (sum of all values)`. */
+  value: number
+  /** Wedge and swatch paint. */
+  fill: Fill
+}
+
+export const DEG = Math.PI / 180
+
+/**
+ * Opacity of a slice under the selection: 1 while nothing is out (`focus` is the
+ * most-grown pop) and for the selected slice itself, falling toward `dimOpacity`
+ * for the rest as the selection grows.
+ */
+export function selectionFade(focus: number, dimOpacity: number, pop: number): number {
+  if (focus <= 0) return 1
+  return 1 - (1 - clamp(dimOpacity, 0, 1)) * focus * (1 - pop)
+}
+
+/** The point at radius `r`, angle `a` on a ring about the origin in centred y-up space. Angles run clockwise from 12 o'clock. */
+export function ringPoint(r: number, a: number): Vector2 {
+  return { x: r * Math.sin(a), y: r * Math.cos(a) }
+}
+
+/** The summary set in the ring's hole. */
+export interface CenterConfig {
+  labelStyle: TextStyle
+  captionStyle: TextStyle
+}
+
+/** How far everything outside the selection fades while any slice is selected; fainter than a gapless chart's, as a ring's slices touch. */
+export const PIE_SPOTLIGHT_DIM = 0.15
+
+const resolvedFills = new WeakMap<object, FillResolved[]>()
+
+export function resolvedFill(fill: Fill): FillResolved[] {
+  if (typeof fill !== "object" || fill === null) return fillOps.resolve(fill)
+  let resolved = resolvedFills.get(fill)
+  if (resolved === undefined) resolvedFills.set(fill, resolved = fillOps.resolve(fill))
+  return resolved
+}
+
+/** Each slice's paint, resolved once per fill object. */
+export function ringFills(slices: readonly PieSlice[]): FillResolved[][] {
+  return slices.map((slice) => resolvedFill(slice.fill))
+}
+