@motionscript/charts 0.1.0 → 0.1.1-alpha.1

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

@@ -3,7 +3,23 @@ import { Types, easeOut, type EasingFunction, type Piece, type Timeline } from "
 const identity: EasingFunction = (t) => t
 
 /** Any component's timeline: these helpers only build pieces, which every timeline builds alike. */
-type AnyTimeline = Timeline<any, any>
+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
+
+/** How a cartesian `enter` splits its duration: axes arriving, marks drawing, legend coming up. Sums to 1. */
+export const ENTER_SHARE = { axes: 0.35, marks: 0.5, legend: 0.15 } as const
 
 /**
  * The ease a part's own frames apply to `t`: none when its command was given
@@ -49,7 +65,7 @@ export interface Arrival {
 /** Each piece's arrival, by key. An unlisted piece has landed. */
 export type Arrivals = Readonly<Record<string, Arrival>>
 
-export const LANDED: Arrival = { opacity: 1, shift: 0 }
+const LANDED: Arrival = { opacity: 1, shift: 0 }
 
 /**
  * A part's private record of its pieces' arrivals. A write merges into it, so

package/src/{pie-chart → kit}/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,
@@ -29,45 +29,18 @@ 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,
-  clampUnit,
-  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[]
-}
+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"
 
-/** 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,22 +64,19 @@ 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
+    const marker = () => state.legend.markerStyle
     return state.slices.map((_, index) =>
       Rect({
         width: "hug",
         height: "hug",
         flow: "freeform",
-        opacity: () => clampUnit(state.dims[index] ?? 1),
+        opacity: () => clamp(state.dims[index] ?? 1, 0, 1),
         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",
@@ -113,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 ?? "",
               }),
             ],
@@ -132,28 +104,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)

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))
+}
+