@motionscript/charts 0.1.0 → 0.1.1-alpha.1

package/src/kit/cartesian.ts

@@ -1,81 +1,144 @@
-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.
- *
- * Two jobs, and the second is why it is real padding on the composition rather
- * than a number the point-mapping math imagines: a series peaking at the top of
- * the scale isn't flush to the top edge, **and** the top marker, which is
- * centred on that top grid line, has somewhere to be. Without it the marker's
- * upper half is drawn above the chart's own box.
- */
-export 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)
+}
 
-/** The parts of a cartesian chart's frame, as {@link cartesianFrame} arranges them. */
-export interface CartesianParts {
-  /** The value axis, left of the plot. */
-  readonly axis: Node2D
-  /** The plot panel: the box the grid and the marks share. */
+interface CartesianParts {
+  /** 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 beside the rows below the plot, so those rows start at
- * the plot's left edge rather than the chart's.
+ * 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
 }
 
-/** A cartesian frame's parts, as a command reaches them through its chart's children. */
-export interface CartesianViews {
-  readonly axis: ChildView
-  /** The plot panel's own children: the grid, the marks, the border. */
-  readonly plot: readonly ChildView[]
-  readonly below: readonly ChildView[]
+/** 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)
+    }
+  }
+  walk(children)
+  return out
+}
+
+/** A part's laid-out size; zero before it is built or laid out. */
+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
 }
 
 /**
- * The frame among a chart's children: 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 still, so it is found by shape.
+ * 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 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 }
+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)
   }
-  return null
+  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
 }
 
-/** A part's laid-out size, or nothing before it is built or laid out. */
-export function laidOutSize(node: Node2D | undefined): Size2D {
-  const bounds = node?.layoutBounds
-  return { width: bounds?.width ?? 0, height: bounds?.height ?? 0 }
+/** `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
 }

package/src/kit/chart-canvas.ts

@@ -3,119 +3,89 @@ import {
   Types,
   component2d,
   fillOps,
-  shadowOps,
   strokeOps,
   type Fill,
   type FillResolved,
   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 as _Node2D,
-  type Node2DProps,
-  type Shadow,
-  type ShadowResolved,
+  type Node2DProps as _Node2DProps,
+  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 })
 
-export interface ChartCanvasProps extends Node2DProps {
-  /** Fill of the plot panel behind the marks. */
-  fill: Fill
-  /** Drop shadow of the panel. Default none. */
-  shadow: Shadow
-  /** Stroke of the vertical grid lines (one per {@link xMarkers}). */
-  xGridStroke: Stroke
-  /** Stroke of the horizontal grid lines (one per {@link yMarkers}). */
-  yGridStroke: Stroke
-  /**
-   * Data-unit x positions to draw a vertical grid line at — one per horizontal
-   * axis marker, so a line lands under every marker regardless of spacing.
-   * Positions at (or past) an {@link xExtent} edge coincide with the border and
-   * are skipped. Pass an empty list for a chart whose horizontal axis is
-   * categorical and so has no numeric position to rule at.
-   */
-  xMarkers: number[]
-  /** Data-unit y positions to draw a horizontal grid line at. */
-  yMarkers: number[]
-  /** `[min, max]` of the horizontal scale — maps {@link xMarkers} into the panel. */
-  xExtent: Range
-  /** `[min, max]` of the vertical scale — maps {@link yMarkers} into the panel. */
-  yExtent: Range
+/** 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** of a cartesian chart: a filled panel with a grid of
- * faint lines spanning both directions across it, sized from its box and centred
- * on its origin.
- *
- * The thick frame is a **separate** {@link ChartBorder} node so it can be drawn
- * *over* the marks while this panel sits under them. Grid lines are placed from
- * the axis marker positions (in data units) mapped into the panel through
- * {@link ChartCanvasProps.xExtent}/`yExtent` — so each line lands under its
- * marker whether or not the markers are evenly 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),
+    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 are named 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))
 
-    // Plot panel, centred on the origin (node space is y-up, origin centre).
-    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
-    // Fraction of a marker across its extent; guard a zero-width extent.
-    const xFrac = (v: number) => (xMax <= xMin ? 0 : (v - xMin) / (xMax - xMin))
-    const yFrac = (v: number) => (yMax <= yMin ? 0 : (v - yMin) / (yMax - yMin))
-    // Skip markers landing on (or outside) the edges — they'd 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,10 +6,8 @@ import {
   Text,
   Types,
   component2d,
-  textOps,
   type Fill,
   type NodeOf,
-  type RectProps,
   // Named so the row's emitted type reaches the Rect surface it spreads through the sdk, not core.
   type Alignment as _Alignment,
   type CornerRadiusResolved as _CornerRadiusResolved,
@@ -29,6 +27,7 @@ import {
   type Vector2 as _Vector2,
 } from "@motionscript/sdk"
 
+import { boundText } from "./cartesian"
 import { fresh } from "./entries"
 import { frameEase } from "./motion"
 import {
@@ -38,54 +37,28 @@ import {
   type LegendConfig,
 } from "./shared"
 
-export interface ChartLegendProps extends RectProps {
-  /**
-   * One entry per series: legend `label`, its `enabled` default, and — through
-   * {@link ChartLegendProps.swatches} — the colour its chip is painted. A series
-   * that starts enabled (the default) is added to the row up front; one that
-   * starts `false` is hidden until a later `showSeries`.
-   */
-  series: ChartSeries[]
-  /**
-   * The swatch colour for each series, by index — resolved by the chart, whose
-   * business it is whether a series' colour comes out of a stroke palette (a
-   * line) or a fill palette (a bar). Shorter than the series list means the
-   * missing entries fall back to white.
-   */
-  swatches: Fill[]
-  /** Padding, caption style, gaps, and swatch geometry — see {@link LegendConfig}. */
-  legend: LegendConfig
-}
-
-/** A row's entries are a `Rect`'s: paint, the flow of its children, its corners. */
 const row = { ...Paint.state, ...Flow.state, ...Shapes.corners }
 
 /**
- * One legend entry. It hugs its caption and swatch; `shown` scales that width
- * from nothing to the whole of it.
- *
- * The width is taken from the content on every measure, at any reveal, so a frame
- * never depends on whether the entry was once seen fully shown. A collapse needs a
- * number to scale, and `"hug"` is not one until something measures it — this is
- * the something.
+ * 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)),
 })
 
-/**
- * How far each entry is shown, written whole (a document, a `set`) or one
- * entry at a time (a command, as `{ [index]: reveal }`), which leaves the others
- * as the frame left them — so two series moving at once each move their own.
- */
+/** Written whole, or one entry at a time as `{ [index]: reveal }`, which leaves the others as the frame left them so two series can move at once. */
 function revealOf(value: readonly number[] | Readonly<Record<number, number>>, previous?: number[]): number[] {
   if (Array.isArray(value)) return value as number[]
   const next = [...(previous ?? [])]
@@ -94,88 +67,68 @@ function revealOf(value: readonly number[] | Readonly<Record<number, number>>, p
 }
 
 /**
- * The legend of a chart: a **horizontal-flow row of entries**, one per series, laid out
- * left-to-right with the theme's `itemGap`. Each entry pairs the series label
- * with a rounded colour swatch; only the swatch carries the series colour, the
- * caption reads in the legend's neutral ink.
- *
- * `showSeries`/`hideSeries` flip a series on or off — showing one grows its
- * entry back in at its stable series position, hiding one shrinks it away. So
- * the row only ever shows the currently-enabled series, in series order, and
- * closes the gap when one leaves.
- *
- * This node *is* the row, so the parent places it (centred below the chart) and
- * it hugs its entries.
+ * 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: {
     ...row,
     series: fresh<ChartSeries[]>(() => []),
+    /** Swatch colour by series index, resolved by the chart; a missing entry is white. */
     swatches: fresh<Fill[]>(() => []),
     legend: Types.custom<LegendConfig>(DEFAULT_LEGEND),
     /**
-     * How far each entry is shown, `0`–`1`. Drives its width, opacity and gap
-     * together, so `0` is an entry that takes no room and `1` is one at its
-     * natural size.
-     *
-     * This replaces adding and removing the entry from the row: a command is
-     * asked what it looks like at a time, and "is this node a child" is not a
-     * value a time can produce. Collapsed-but-present is the same picture reached
-     * by a route that *is* a function of `t`.
+     * 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.
      */
     reveal: fresh<number[], number[] | Readonly<Record<number, number>>>(() => [], { resolve: revealOf }),
   },
-  // This node *is* the row, so the direction is its own answer. It has to be
-  // stated — a `Rect` given no flow lays its children out `freeform`, which
-  // stacks every entry on the same spot. The gap and padding are the theme's.
+  // The flow must be stated: a `Rect` with none lays children out `freeform`, stacking every entry on one spot.
   defaults: {
     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)),
   },
-  // One entry per series, in series order, every one a child for good: order is
-  // fixed rather than depending on which siblings happen to be shown, so an entry
-  // always comes back where it belongs.
+  // 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",
-        // Bound to the reveal, so showing and hiding is a number moving rather
-        // than a child arriving and leaving. The width follows it in `measure`,
-        // and the flanking gap closes with the entry rather than snapping.
+        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 }),
         ],
       })
     )
   },
   commands: {
     ...Paint.commands,
-    /**
-     * Grow series `index`'s entry back in at its series-order position, the
-     * siblings sliding over to make room. A reveal tween rather than an animated
-     * `addChildAt`: the entry never left, so the whole thing is a function of `t`.
-     */
+    /** Grow series `index`'s entry back in at its position, the siblings sliding over. */
     showSeries: {
       args: { index: Types.number(0, { min: 0, step: 1 }) },
       // An index that is not a series takes its slot and moves nothing.
@@ -183,20 +136,14 @@ export const ChartLegend = component2d({
         ? timeline.animate(revealFrame(state, timeline.args.index, 1, frameEase(timeline)))
         : timeline.wait(timeline.duration)),
     },
-    /** Shrink series `index`'s entry away, the gap closing behind it — the mirror of `showSeries`. */
+    /** The mirror of `showSeries`. */
     hideSeries: {
       args: { index: Types.number(0, { min: 0, step: 1 }) },
       run: (timeline, state) => (timeline.args.index in state.series
         ? timeline.animate(revealFrame(state, timeline.args.index, 0, frameEase(timeline)))
         : timeline.wait(timeline.duration)),
     },
-    /**
-     * Dim every entry but series `index` to {@link SPOTLIGHT_DIM} and bring that
-     * one back to full — the legend half of a chart's `spotlightSeries`. Entries
-     * stay in place; only their opacity moves, so the row doesn't reflow. Only
-     * the entries shown when it is built are touched: a hidden series' entry is
-     * left as `hideSeries` left it.
-     */
+    /** Dim every entry but `index` to {@link SPOTLIGHT_DIM}, in place. A hidden series' entry is left as `hideSeries` left it. */
     spotlightSeries: {
       args: { index: Types.number(0, { min: 0, step: 1 }) },
       run: (timeline, state, children) =>
@@ -212,18 +159,10 @@ export const ChartLegend = component2d({
   render: (ctx, state) => Paint.draw(ctx, state, Shapes.rect(ctx.size, state)),
 })
 
-/**
- * One entry's reveal ramping to `target` from where the command finds it — so a
- * hide that follows a show starts where the show left it.
- */
+/** One entry's reveal ramping to `target` from where the command finds it, so a hide after a show starts where the show left it. */
 function revealFrame(state: { readonly reveal: readonly number[] }, index: number, target: number, ease: (t: number) => number) {
   const from = state.reveal[index] ?? 0
   return (t: number) => ({ reveal: { [index]: from + (target - from) * ease(t) } })
 }
 
-/** Whether series `index` is showing at all on `legend`. */
-export function legendShows(legend: { readonly reveal: readonly number[] }, index: number): boolean {
-  return (legend.reveal[index] ?? 0) > 0
-}
-
 export type ChartLegend = NodeOf<typeof ChartLegend>

package/src/kit/entries.ts

@@ -1,4 +1,4 @@
-import { Types, type Element, type Node2D, type Type } from "@motionscript/sdk"
+import { Types, type Element, type EntryOptions, type Node2D, type Type } from "@motionscript/sdk"
 
 /**
  * An entry made fresh for every node: each node gets its own array or box
@@ -18,3 +18,6 @@ export function fresh<T, In = T>(make: () => T, options?: { readonly resolve?: (
 export function asParts(nodes: readonly Node2D[]): readonly Element[] {
   return nodes as unknown as readonly Element[]
 }
+
+/** The argument every per-series command takes: an index into `series`, offered by name. */
+export const SERIES_ARG = Types.custom<number, number, EntryOptions & { readonly min: number; readonly step: number }>(0, { kind: "series", min: 0, step: 1 })