@motionscript/charts 0.1.0 → 0.1.1-alpha.1

package/src/kit/style.ts

@@ -0,0 +1,257 @@
+/**
+ * The chart family's style: one `style` entry per chart, built from the groups
+ * below, so a look saved off one chart lays onto any other (a field the other
+ * chart does not draw is dropped). A chart spreads the shared groups and adds a
+ * `marks` group of its own.
+ */
+
+import {
+  Types,
+  type Fill,
+  type StrokeResolved,
+  type Stroke as _Stroke,
+  type StyleInput,
+  type TextStyle,
+  // Named so the emitted style types reach these through the sdk, not core.
+  type FillResolved as _FillResolved,
+  type Type as _Type,
+} from "@motionscript/sdk"
+
+import type { AxisConfig, ChartSeries, LegendConfig } from "./shared"
+
+/** The style family every chart shares; a host keys saved styles by it. */
+export const CHART_STYLE_FAMILY = "chart"
+
+/** The out-of-the-box series colours, cycled by series (or row) index. */
+export const CHART_PALETTE_DEFAULT = ["#4f8cff", "#2fbf8f", "#f5a524", "#e5547a", "#9b6cf0"] as const
+
+export const CHART_COLORS = {
+  /** A colour per series (a pie's or radial's per row), cycled. */
+  palette: Types.palette(CHART_PALETTE_DEFAULT),
+  /** Values, legend captions, centre text. */
+  foreground: Types.fill("#f4f4f5"),
+  /** Axis markers and captions, spoke labels. */
+  muted: Types.fill("#a1a1aa"),
+  /** Behind the plot; none by default, so the chart reads against the stage. */
+  background: Types.fill([]),
+}
+
+export const CHART_TEXT = {
+  /** Empty: the scene's default face. */
+  fontFamily: Types.font(""),
+  /** Marker and legend size at 1080p; titles and values scale from it. */
+  fontSize: Types.number(28, { min: 8, max: 160, step: 1, unit: "px" }),
+  fontWeight: Types.number(500, { min: 100, max: 900, step: 100 }),
+}
+
+export const CARTESIAN_GRID = {
+  /** The lines along the value ticks of a column chart (one per tick); empty draws none. */
+  horizontalGrid: Types.stroke({ weight: 2, fill: "white/15" }),
+  /** The lines under the category markers; empty draws none. */
+  verticalGrid: Types.stroke([]),
+  /** The baseline and the value-axis rule; empty draws none. */
+  axisStroke: Types.stroke([]),
+  /** Read as the chart is built: whether the category (x) axis row is drawn. */
+  showXAxis: Types.boolean(true, { animatable: false }),
+  /** Read as the chart is built: whether the value (y) axis column is drawn. */
+  showYAxis: Types.boolean(true, { animatable: false }),
+}
+
+export type LegendPosition = "bottom" | "top" | "right" | "none"
+export type LegendSwatch = "square" | "circle" | "line"
+
+export const CHART_LEGEND = {
+  /** Read as the chart is built: where the legend sits, or `none`. */
+  legend: Types.oneOf(["bottom", "top", "right", "none"] as const, { animatable: false }),
+  swatch: Types.oneOf(["square", "circle", "line"] as const),
+}
+
+/** The type fields, and the two text colours: what every text helper reads. */
+export interface ChartTextStyle {
+  readonly foreground: Fill
+  readonly muted: Fill
+  readonly fontFamily: string
+  readonly fontSize: number
+  readonly fontWeight: number
+}
+
+/** The fields every chart's style resolves, whichever groups it spreads. */
+export interface ChartStyleBase extends ChartTextStyle {
+  readonly palette: readonly Fill[]
+  readonly background: Fill
+  readonly legend: LegendPosition
+  readonly swatch: LegendSwatch
+}
+
+/** The cartesian grid fields, for the line and bar charts. */
+export interface CartesianStyle extends ChartStyleBase {
+  readonly horizontalGrid: StrokeResolved[]
+  readonly verticalGrid: StrokeResolved[]
+  readonly axisStroke: StrokeResolved[]
+  readonly showXAxis: boolean
+  readonly showYAxis: boolean
+}
+
+/** The rule and track fields a preset restates so its rules read on its background (a chart keeps those it draws). */
+const _PRESET_RULES = {
+  horizontalGrid: CARTESIAN_GRID.horizontalGrid,
+  gridStroke: Types.stroke([]),
+  spokeStroke: Types.stroke([]),
+  track: Types.fill([]),
+}
+
+/** A preset's fields: any chart's, so one preset dresses every chart. */
+export type ChartStylePreset = StyleInput<typeof CHART_COLORS & typeof CHART_TEXT & typeof _PRESET_RULES>
+
+/** Ready-made looks, each stating every colour so applying one replaces the last. */
+export const CHART_STYLE_PRESETS = {
+  midnight: {
+    palette: [...CHART_PALETTE_DEFAULT],
+    foreground: "#f4f4f5",
+    muted: "#a1a1aa",
+    horizontalGrid: { weight: 2, fill: "white/15" },
+    gridStroke: { weight: 2, fill: "white/15" },
+    spokeStroke: { weight: 2, fill: "white/15" },
+    track: "white/10",
+    background: [],
+  },
+  paper: {
+    palette: ["#2563eb", "#059669", "#d97706", "#db2777", "#7c3aed"],
+    foreground: "#1c1917",
+    muted: "#57534e",
+    horizontalGrid: { weight: 2, fill: "#1c1917/12" },
+    gridStroke: { weight: 2, fill: "#1c1917/12" },
+    spokeStroke: { weight: 2, fill: "#1c1917/12" },
+    track: "#1c1917/12",
+    background: "#fafaf9",
+  },
+  ember: {
+    palette: ["#d9603b", "#8194ad", "#e0a93b", "#5e9d6b", "#9ec85a"],
+    foreground: "#e9e1d4",
+    muted: "#8a7f70",
+    horizontalGrid: { weight: 2, fill: "#2c2820" },
+    gridStroke: { weight: 2, fill: "#2c2820" },
+    spokeStroke: { weight: 2, fill: "#2c2820" },
+    track: "#2c2820",
+    background: "#15130e",
+  },
+  neon: {
+    palette: ["#22d3ee", "#a3e635", "#f472b6", "#facc15", "#818cf8"],
+    foreground: "#ffffff",
+    muted: "#94a3b8",
+    horizontalGrid: { weight: 2, fill: "white/10" },
+    gridStroke: { weight: 2, fill: "white/10" },
+    spokeStroke: { weight: 2, fill: "white/10" },
+    track: "white/10",
+    background: [],
+  },
+  ocean: {
+    palette: ["#0ea5e9", "#14b8a6", "#6366f1", "#38bdf8", "#2dd4bf"],
+    foreground: "#e0f2fe",
+    muted: "#7dd3fc",
+    horizontalGrid: { weight: 2, fill: "#7dd3fc/20" },
+    gridStroke: { weight: 2, fill: "#7dd3fc/20" },
+    spokeStroke: { weight: 2, fill: "#7dd3fc/20" },
+    track: "#7dd3fc/20",
+    background: "#082f49",
+  },
+  sunset: {
+    palette: ["#f97316", "#ef4444", "#ec4899", "#f59e0b", "#a855f7"],
+    foreground: "#fff7ed",
+    muted: "#fdba74",
+    horizontalGrid: { weight: 2, fill: "#fdba74/20" },
+    gridStroke: { weight: 2, fill: "#fdba74/20" },
+    spokeStroke: { weight: 2, fill: "#fdba74/20" },
+    track: "#fdba74/20",
+    background: [],
+  },
+  pastel: {
+    palette: ["#a5b4fc", "#f9a8d4", "#86efac", "#fde68a", "#7dd3fc"],
+    foreground: "#f8fafc",
+    muted: "#cbd5e1",
+    horizontalGrid: { weight: 2, fill: "white/12" },
+    gridStroke: { weight: 2, fill: "white/12" },
+    spokeStroke: { weight: 2, fill: "white/12" },
+    track: "white/12",
+    background: [],
+  },
+  mono: {
+    palette: ["#fafafa", "#a3a3a3", "#737373", "#d4d4d4", "#525252"],
+    foreground: "#fafafa",
+    muted: "#a3a3a3",
+    horizontalGrid: { weight: 2, fill: "white/12" },
+    gridStroke: { weight: 2, fill: "white/12" },
+    spokeStroke: { weight: 2, fill: "white/12" },
+    track: "white/12",
+    background: [],
+  },
+} satisfies Record<string, ChartStylePreset>
+
+/** Series `index`'s colour: its own `fill`, else the palette's, cycled. */
+export function paletteFill(style: Pick<ChartStyleBase, "palette">, index: number, own?: Fill): Fill {
+  if (own != null) return own
+  const palette = style.palette
+  return palette.length > 0 ? palette[index % palette.length] : "white"
+}
+
+/** {@link paletteFill} for a series. */
+export function seriesFill(style: Pick<ChartStyleBase, "palette">, series: ChartSeries, index: number): Fill {
+  return paletteFill(style, index, series.fill)
+}
+
+function face(style: Pick<ChartTextStyle, "fontFamily">): Pick<TextStyle, "fontFamily"> {
+  return style.fontFamily ? { fontFamily: style.fontFamily } : {}
+}
+
+/** Axis markers, spoke labels: muted, at the base size. */
+export function markerText(style: ChartTextStyle, textAlign: TextStyle["textAlign"] = "center"): TextStyle {
+  return { ...face(style), fontSize: style.fontSize, fontWeight: style.fontWeight, textAlign, fill: style.muted }
+}
+
+/** Axis captions: muted, a step larger and heavier than the markers. */
+export function titleText(style: ChartTextStyle): TextStyle {
+  return {
+    ...face(style),
+    fontSize: Math.round(style.fontSize * 1.1),
+    fontWeight: Math.min(900, style.fontWeight + 100),
+    textAlign: "center",
+    fill: style.muted,
+  }
+}
+
+/** Values on marks and legend captions: the foreground, at the base size. */
+export function valueText(style: ChartTextStyle, textAlign: TextStyle["textAlign"] = "center"): TextStyle {
+  return { ...face(style), fontSize: style.fontSize, fontWeight: Math.min(900, style.fontWeight + 100), textAlign, fill: style.foreground }
+}
+
+/**
+ * The kit axis parts' config from a style. `x` is the axis under the plot;
+ * its grid lines are vertical (one per x marker), the `y` axis's horizontal.
+ */
+export function axisConfigOf(style: Pick<CartesianStyle, "verticalGrid" | "horizontalGrid"> & ChartTextStyle, axis: "x" | "y"): AxisConfig {
+  const gap = Math.round(style.fontSize * 0.6)
+  return {
+    labelStyle: markerText(style, axis === "x" ? "center" : "right"),
+    titleStyle: titleText(style),
+    lineStyle: axis === "x" ? style.verticalGrid : style.horizontalGrid,
+    tickPadding: axis === "x" ? { top: gap } : { right: gap },
+    titlePadding: axis === "x" ? { top: Math.round(gap / 2) } : { right: gap },
+  }
+}
+
+/** The kit legend's config: captions in the foreground, the swatch shaped by `swatch`. */
+export function legendConfigOf(style: ChartTextStyle & Pick<ChartStyleBase, "swatch">): LegendConfig {
+  const size = Math.max(8, Math.round(style.fontSize * 0.6))
+  const marker =
+    style.swatch === "line"
+      ? { width: Math.round(size * 2), height: Math.max(3, Math.round(size / 4)), borderRadius: size }
+      : style.swatch === "circle"
+        ? { width: size, height: size, borderRadius: size / 2 }
+        : { width: size, height: size, borderRadius: Math.round(size / 4) }
+  return {
+    padding: 0,
+    textStyle: { ...face(style), fontSize: style.fontSize, fontWeight: style.fontWeight, textAlign: "left", fill: style.foreground },
+    itemGap: Math.round(style.fontSize * 1.4),
+    markerStyle: { ...marker, stroke: [], shadow: [] },
+  }
+}

package/src/kit/vertical-axis.ts

@@ -5,166 +5,133 @@ import {
   Types,
   component2d,
   insetsOps,
-  textOps,
   type NodeOf,
+  // Named so this component's emitted type reaches `Node2D` and its props through the sdk, not core.
   type Node2D,
-  type Node2DProps,
+  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_Y_AXIS,
-  enterBudget,
   formatMarker,
   type AxisConfig,
   type Range,
 } from "./shared"
 
-export interface VerticalAxisProps extends Node2DProps {
-  /** `[min, max]` of the vertical scale the markers are positioned within. */
-  range: Range
-  /**
-   * Tick values (in data units) to draw up the axis, each placed by its fraction
-   * across {@link VerticalAxisProps.range}. Need not be evenly spaced or include
-   * the ends.
-   */
-  markers: number[]
-  /**
-   * How each marker is captioned, one per entry of `markers` and in its order.
-   * Empty (the default), or short, captions a marker with its bare numeric
-   * reading; a chart with a number format on this axis writes them through it.
-   */
-  captions: string[]
-  /** Marker/caption text style, grid stroke, and gutters — see {@link AxisConfig}. */
-  axis: AxisConfig
-  /**
-   * Rotated caption drawn in the gutter to the left of the marker column. Empty
-   * string (the default) hides it — no caption node is built and no label gutter
-   * is reserved.
-   */
-  label: string
-}
-
-/** How far a marker starts to the right of its slot when it enters, in px. */
 const SLIDE = 24
 
-/** How a tick value is captioned — see {@link VerticalAxisProps.captions}. */
-export type MarkerLabel = (value: number) => string
-
 /** What a marker's caption reads: the one listed for its value, else its bare reading. */
 export function markerCaption(s: { readonly markers: readonly number[]; readonly captions: readonly string[] }, value: number): string {
   const index = s.markers.indexOf(value)
   return (index >= 0 ? s.captions[index] : undefined) ?? formatMarker(value)
 }
 
+/** The gap between an axis's markers and the plot, and between the markers and the caption, read off its config. */
+export function axisPads(axis: AxisConfig, side: "top" | "right"): { tick: number; title: number } {
+  return { tick: insetsOps.resolve(axis.tickPadding)[side], title: insetsOps.resolve(axis.titlePadding)[side] }
+}
+
+/**
+ * A column of right-aligned captions beside the plot: `place(i)` is caption
+ * `i`'s centre height in the column (y-up), whose height it is handed. The
+ * value axis and a horizontal bar chart's category axis are both this column.
+ */
+export function captionColumn(spec: {
+  readonly count: number
+  readonly axis: () => AxisConfig
+  readonly text: (i: number) => string
+  readonly place: (i: number, height: number) => number
+  readonly arrivals: () => Readonly<Record<string, Arrival>>
+  readonly opacity?: (i: number) => number
+  readonly label: string
+}): Node2D {
+  const pads = () => axisPads(spec.axis(), "right")
+  const markers = Array.from({ length: spec.count }, (_, i) => {
+    const column = () => (marker.parent as Node2D | null)?.layoutBounds ?? { width: 0, height: 0 }
+    const marker: Node2D = new Text({
+      ...boundText(() => spec.axis().labelStyle),
+      text: () => spec.text(i),
+      // Right-aligned against the tick padding: freeform children sit on the content box's centre.
+      x: () => (column().width - pads().tick) / 2 - marker.layoutBounds.width / 2 + arrivalOf(spec.arrivals(), i).shift,
+      y: () => spec.place(i, column().height),
+      opacity: () => arrivalOf(spec.arrivals(), i).opacity * (spec.opacity?.(i) ?? 1),
+    })
+    return marker
+  })
+  const children: Node2D[] = []
+  if (spec.label !== "") {
+    // Node2D space is y-up and rotation is clockwise, so -90° reads bottom-to-top.
+    children.push(
+      new RotatedBox({
+        angle: -90,
+        width: "hug",
+        height: "hug",
+        children: new Text({
+          ...boundText(() => spec.axis().titleStyle),
+          text: spec.label,
+          opacity: () => arrivalOf(spec.arrivals(), "label").opacity,
+          x: () => arrivalOf(spec.arrivals(), "label").shift,
+        }),
+      }) as unknown as Node2D
+    )
+  }
+  children.push(new Rect({ height: "fill", width: "hug", padding: () => ({ right: pads().tick }), children: markers }) as unknown as Node2D)
+  return new Rect({ flow: "horizontal", gap: () => pads().title, height: "fill", children }) as unknown as Node2D
+}
+
 /**
- * The numeric vertical axis shared by the cartesian charts: a **column of
- * {@link Text} nodes**, one per marker value, running top-to-bottom (highest
- * value at the top). Pure layout — no `Graphics` — so the markers are real text
- * nodes the scene can measure, restyle, or animate individually.
- *
- * Each marker is positioned so its centre lands exactly on its value's fraction
- * across `range` within the axis's filled height, so unevenly-spaced markers
- * land where their values fall. Both the caption and the position are *bound*,
- * not snapshotted: a chart that rescales its axes (see `LineChart.zoomTo`)
- * tweens `range`/`markers` live. Only the marker **count** is fixed at
- * construction.
- *
- * `enter` staggers them in **bottom-to-top**: each marker starts pushed a
- * little to the right and transparent, then fades and slides left into place.
- * The resting state is the landed one, so a chart that is never told to enter
- * still reads as a finished chart.
+ * The numeric vertical axis the cartesian charts share: a column of {@link Text}
+ * markers, highest at the top, each centred on its value's fraction across
+ * `range` and right-aligned against the plot. Caption and position are bound, so
+ * a rescale tweens live; only the marker count is fixed at construction. The
+ * resting state is landed.
  */
 export const VerticalAxis = component2d({
   key: "verticalAxis",
   state: {
     range: fresh<Range>(() => [0, 1]),
+    /** Tick values in data units, each placed by its fraction across `range`; need not be even or include the ends. */
     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_Y_AXIS),
+    /** Rotated caption in the gutter left of the markers; empty builds no caption node and reserves no gutter. */
     label: "",
     arrivals: arrivalsEntry(),
   },
-  // A plain node filled its parent; one made of its markers would hug them.
+  // A node made of markers would otherwise hug them.
   defaults: { width: "fill", height: "fill" },
   children: (state) => {
-    // Composed from plain entries (range/markers/label), so it's built once here.
-    const tickPad = insetsOps.resolve(state.axis.tickPadding).right
-    const titlePad = insetsOps.resolve(state.axis.titlePadding).right
-
-    const row: Node2D[] = []
-    // The row's parent is the axis: its box is what the markers are placed in.
-    const box = () => (row[0]?.parent as Node2D | null | undefined)?.layoutBounds ?? { width: 0, height: 0 }
-    /** The live tick values, top → bottom (highest first) — re-read every frame. */
     const sorted = () => [...state.markers].sort((a, b) => b - a)
-    /** Tick `i`'s fraction across the live `range`, 0 at the bottom edge. */
     const fracAt = (value: number | undefined) => {
       if (value === undefined) return 0
       const [min, max] = state.range
       return max <= min ? 0 : (value - min) / (max - min)
     }
-
-    // One text node per marker, ordered top → bottom. A slot with no value (the
-    // live list is shorter than the column built for it) renders as empty text
-    // rather than repeating its neighbour.
-    const markers = state.markers.map((_, i) => {
-      const marker: Node2D = new Text({
-        ...textOps.styleProps(state.axis.labelStyle),
-        text: () => {
+    // A slot with no value (the live list is shorter than the column built) renders empty, not its neighbour.
+    return asParts([
+      captionColumn({
+        count: state.markers.length,
+        axis: () => state.axis,
+        text: (i) => {
           const value = sorted()[i]
           return value === undefined ? "" : markerCaption(state, value)
         },
-        y: () => {
-          // Node2D space is y-up, so the fraction runs from the bottom.
-          const height = box().height
-          const centred = (fracAt(sorted()[i]) - 0.5) * height
-          // Held inside the axis's top edge — the backstop for a chart whose
-          // headroom is smaller than its marker text is tall, which a theme with
-          // much larger markers can arrange. Only the top, because what lies
-          // below the axis is the chart's own horizontal axis and legend.
-          const limit = height / 2 - marker.layoutBounds.height / 2
-          return Math.min(centred, limit)
-        },
-        opacity: () => arrivalOf(state.arrivals, i).opacity,
-        x: () => arrivalOf(state.arrivals, i).shift,
-      })
-      return marker
-    })
-
-    const children: Node2D[] = []
-    if (state.label !== "") {
-      // Node2D space is y-up and rotation is clockwise, so -90° reads bottom-to-top.
-      children.push(
-        new RotatedBox({
-          angle: -90,
-          width: "hug",
-          height: "hug",
-          children: new Text({
-            ...textOps.styleProps(state.axis.titleStyle),
-            text: state.label,
-            opacity: () => arrivalOf(state.arrivals, "label").opacity,
-            x: () => arrivalOf(state.arrivals, "label").shift,
-          }),
-        })
-      )
-    }
-    children.push(new Rect({ height: "fill", width: "hug", padding: { right: tickPad }, children: markers }))
-    row.push(new Rect({ flow: "horizontal", gap: titlePad, children }))
-    return asParts(row)
+        place: (i, height) => (fracAt(sorted()[i]) - 0.5) * height,
+        arrivals: () => state.arrivals,
+        label: state.label,
+      }),
+    ])
   },
   commands: {
     /**
-     * Stagger the markers in bottom to top, then slide the caption in from the
-     * right after them. Its first frame arms them all: shifted right by `slide`
-     * and transparent.
-     *
-     * The timeline's duration is the **whole** entrance, not one marker's slide:
-     * the stagger and the caption are carved out of it rather than added on top.
-     * See {@link enterBudget} for why that distinction matters here.
-     *
-     * `stagger` is seconds between successive markers (derived when omitted);
-     * `slide` is the starting rightward offset in px.
+     * Stagger markers in bottom to top, then the caption. The duration is the
+     * whole entrance ({@link enterBudget}). `stagger` is seconds between markers
+     * (derived when omitted); `slide` is the starting rightward offset in px.
      */
     enter: {
       args: {
@@ -181,9 +148,8 @@ export const VerticalAxis = component2d({
         if (count === 0) return arm
         const { step, per, caption } = enterBudget(timeline.duration, count, captioned, stagger)
         const ease = frameEase(timeline)
-        // Bottom marker leads: the column is top → bottom, so walk it in reverse.
+        // The bottom marker leads, so walk the top-to-bottom column in reverse.
         const markers = state.markers.map((_, i) => ({ at: (count - 1 - i) * step, duration: per, piece: arrival(timeline, i, from, ease) }))
-        // Once every marker has landed, the caption slides in from the right.
         const label = captioned ? [{ at: (count - 1) * step + per, duration: caption, piece: arrival(timeline, "label", from, ease) }] : []
         return timeline.together([arm, beats(timeline, [...markers, ...label])])
       },