@motionscript/charts 0.1.0 → 0.1.1-alpha.0

package/src/bar-chart/chart-bars.ts

@@ -2,6 +2,7 @@ import {
   Graphics2D,
   Text,
   Types,
+  clamp,
   component2d,
   fillOps,
   shadowOps,
@@ -10,9 +11,9 @@ import {
   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 Node2DProps as _Node2DProps,
   type Shadow,
   type ShadowResolved,
   type Stroke,
@@ -23,35 +24,28 @@ import {
 import { fresh } from "../kit/entries"
 import { frameEase } from "../kit/motion"
 import { loadPaints } from "../kit/paints"
-import { clampUnit, formatMarker } from "../kit/shared"
+import { formatMarker } from "../kit/shared"
 import { DEFAULT_BAR_CHART_THEME } from "./shared"
 
 /**
- * One drawn column, already mapped into the plot's **centred pixel space**
- * (origin at the plot centre, y-up) by the parent {@link BarChart}.
- *
- * `from`/`to` are the two ends of the column rather than a base and a height,
- * for the same reason {@link BarSpan} is a span: it is the one shape that fits a
- * grouped bar, a stacked segment and a negative value without a special case.
+ * One drawn column in the plot's centred pixel space (origin at the centre,
+ * y-up), mapped by the parent {@link BarChart}. `from`/`to` are the two ends
+ * rather than a base and a height, like {@link BarSpan}: one shape fits grouped,
+ * stacked and negative.
  */
 export interface BarGeometry {
-  /** Centre x of the column. */
+  /** Centre x. */
   x: number
-  /** Column width in px. */
   width: number
-  /** Pixel y of the column's base — the baseline when grouped, the running stack top when stacked. */
+  /** Pixel y of the base: the baseline when grouped, the running stack top when stacked. */
   from: number
-  /** Pixel y of its far end, at full {@link ChartBarsProps.growth}. */
+  /** Pixel y of the far end at full growth. */
   to: number
-  /** Whether the far end takes the theme's corner radius (the stack's cap). */
+  /** Whether the far end takes the corner radius (the stack's cap). */
   round: boolean
-  /** The value this column plots, for the figure printed on it. */
+  /** The value plotted, for the printed figure. */
   value: number
-  /**
-   * The figure printed on it, written as the chart's value axis writes its
-   * ticks, so the two cannot disagree. Absent, the bare marker reading of
-   * {@link value}.
-   */
+  /** The printed figure, written as the value axis writes its ticks; absent, the bare marker reading of `value`. */
   caption?: string
 }
 
@@ -62,49 +56,6 @@ const VALUE_FIT = 1.6
 /** Fallback type size when the theme's value style leaves it unset or autofit. */
 const VALUE_SIZE = 24
 
-export interface ChartBarsProps extends Node2DProps {
-  /** This series' columns, one per row of the chart's data. */
-  bars: BarGeometry[]
-  /** Pixel y of value 0 — where every column grows *from*. */
-  baseline: number
-  /** Column paint — this series' own, or the theme palette's entry for its index. */
-  fill: Fill
-  /** Optional outline on every column. */
-  barStroke: Stroke
-  /** Optional drop shadow on every column. */
-  barShadow: Shadow
-  /** Radius of the far-end corners, in px. */
-  cornerRadius: number
-  /**
-   * Rise of every column in `[0, 1]`, measured **about the baseline**: 0
-   * collapses them all onto it, 1 draws them at full length.
-   *
-   * Scaling about the baseline rather than about each column's own base is what
-   * keeps a stack flush mid-animation — every segment's base and end travel by
-   * the same factor, so the segments stay stacked instead of the upper ones
-   * floating above the still-growing lower ones. It also means a negative
-   * column grows *down* out of the same signal.
-   */
-  growth: number
-  /**
-   * Per-column opacity multiplier, by row index — how the chart's category
-   * spotlight reaches a single column without touching the series it belongs
-   * to. Missing entries read as 1.
-   */
-  dims: number[]
-  /** Whether the figure each column plots is printed on it. */
-  showValues: boolean
-  /** Type style for those figures. */
-  valueStyle: TextStyle
-  /**
-   * Whether this series draws at all — the wholesale switch behind
-   * `BarChart.showSeries`/`hideSeries`, alongside the slot weight that animates
-   * the reflow. Off skips the columns *and* their figures.
-   */
-  enabled: boolean
-}
-
-/** What the column geometry reads. */
 interface Columns {
   readonly bars: readonly BarGeometry[]
   readonly baseline: number
@@ -115,51 +66,37 @@ interface Columns {
 }
 
 /**
- * How far column `i` is dimmed — the chart's category spotlight, and the series
- * switch on top of it.
- *
- * The captions read this rather than being hidden by `render`'s guard: they are
- * real child nodes, so a `return` in the draw would leave them on screen over a
- * series that isn't there.
+ * Column `i`'s dimming: the category spotlight, then the series switch. Captions
+ * read this because they are child nodes, which a `render` guard would leave on
+ * screen over a series that is not there.
  */
 function dimAt(s: Columns, index: number): number {
   if (!s.enabled) return 0
-  return clampUnit(s.dims[index] ?? 1)
+  return clamp(s.dims[index] ?? 1, 0, 1)
 }
 
-/** The two ends of column `i` at the current growth. */
 function endsAt(s: Columns, index: number): { base: number; end: number } | null {
   const bar = s.bars[index]
   if (!bar) return null
-  const g = clampUnit(s.growth)
+  const g = clamp(s.growth, 0, 1)
   return { base: s.baseline + (bar.from - s.baseline) * g, end: s.baseline + (bar.to - s.baseline) * g }
 }
 
-/** The type size the figures are set at, guarding the autofit/unset cases. */
 function valueSize(s: Columns): number {
   const size = s.valueStyle.fontSize
   return typeof size === "number" ? size : VALUE_SIZE
 }
 
-/** Whether column `i`'s figure sits inside the column (a stacked segment) or past its end. */
 function insideAt(s: Columns, index: number): boolean {
   const bar = s.bars[index]
   return bar !== undefined && Math.abs(bar.from - s.baseline) > 0.5
 }
 
-/**
- * The figure printed on column `i`, or `""` where there is no room for it.
- *
- * Blanking the text rather than dropping the node keeps the caption list
- * index-aligned with the columns, so a chart that rescales into more room simply
- * starts printing again.
- */
+/** Column `i`'s figure, or `""` where there is no room. Blanking rather than dropping the node keeps captions index-aligned, so a rescale into more room prints again. */
 function captionAt(s: Columns, index: number): string {
   const bar = s.bars[index]
   if (!bar || bar.value === 0) return ""
-  // An interior segment prints inside itself, so it has to be tall enough to
-  // hold a line of type; a grouped column prints in the headroom above its end,
-  // where the only constraint is the plot's own top.
+  // An interior segment prints inside itself and must hold a line of type; a grouped column prints past its end.
   if (insideAt(s, index)) {
     const ends = endsAt(s, index)
     if (!ends) return ""
@@ -168,53 +105,51 @@ function captionAt(s: Columns, index: number): string {
   return bar.caption ?? formatMarker(bar.value)
 }
 
-/** Where column `i`'s figure sits, in the node's centred y-up space. */
 function captionY(s: Columns, index: number): number {
   const ends = endsAt(s, index)
   if (!ends) return 0
   if (insideAt(s, index)) return (ends.base + ends.end) / 2
-  // Text is centred on its `y`, so clear the column's end by the gap plus half a
-  // line — on whichever side of the baseline the column actually reached.
+  // Text is centred on `y`: clear the end by the gap plus half a line, on the side the column reached.
   const direction = ends.end >= ends.base ? 1 : -1
   return ends.end + direction * (VALUE_GAP + valueSize(s) / 2)
 }
 
 /**
- * One **series** of a {@link BarChart}, drawn as one command list: its column in
- * every category, plus the figures printed on them.
- *
- * A node per series rather than a node per bar, deliberately — it is the same
- * unit `ChartLine` is, which is what lets `showSeries`/`hideSeries`/
- * `spotlightSeries` mean exactly the same thing on a bar chart as on a line
- * chart: enable the node, or tween its opacity. The columns' *positions* come
- * from the parent (it owns the slot arithmetic both modes share), so this part
- * only has to know how to draw a span and grow it.
+ * One series of a {@link BarChart}: its column in every category plus the
+ * printed figures. A node per series, like `ChartLine`, so `showSeries` and
+ * `spotlightSeries` mean the same on both: enable the node or tween its opacity.
+ * Positions come from the parent, which owns the slot arithmetic.
  *
- * The figures are real {@link Text} children rather than glyphs in the command
- * list, so they take the theme's type style, are measured by the layout engine,
- * and ride the node's own opacity — which is why hiding the series takes its
- * figures with it for free.
+ * The figures are {@link Text} children, so they take the theme's type style,
+ * are measured by layout, and hide with the series.
  */
 export const ChartBars = component2d({
   key: "chartBars",
   state: {
     bars: fresh<BarGeometry[]>(() => []),
+    /** Pixel y of value 0, where every column grows from. */
     baseline: 0,
     fill: Types.custom<Fill, FillResolved[]>([], { resolve: fillOps.resolve, lerp: fillOps.lerp }),
     barStroke: Types.custom<Stroke, StrokeResolved[]>(DEFAULT_BAR_CHART_THEME.bar.stroke, { resolve: strokeOps.resolve, lerp: strokeOps.lerp }),
     barShadow: Types.custom<Shadow, ShadowResolved[]>(DEFAULT_BAR_CHART_THEME.bar.shadow, { resolve: shadowOps.resolve, lerp: shadowOps.lerp }),
     cornerRadius: DEFAULT_BAR_CHART_THEME.bar.cornerRadius,
+    /**
+     * Rise of every column in `[0, 1]` about the baseline, not each column's own
+     * base: every segment travels by the same factor, so a stack stays flush
+     * mid-animation and a negative column grows down.
+     */
     growth: 1,
+    /** Per-column opacity by row index, how the category spotlight reaches one column. Missing reads as 1. */
     dims: fresh<number[]>(() => []),
     showValues: false,
     valueStyle: Types.custom<TextStyle>(DEFAULT_BAR_CHART_THEME.valueStyle),
+    /** The wholesale switch behind `showSeries`/`hideSeries`; off skips the columns and their figures. */
     enabled: true,
   },
-  // A plain node filled its parent; one made of its figures would hug them.
+  // A node made of its figures would otherwise hug them.
   defaults: { width: "fill", height: "fill" },
-  // One caption per column, built once (the row count is fixed at construction,
-  // like an axis's marker count) and bound to the live geometry so it travels
-  // with its column as the chart grows, rescales or reflows.
+  // One caption per column, built once (the row count is fixed at construction)
+  // and bound to the live geometry so it travels with its column.
   children: (state) => {
     if (!state.showValues) return []
     return state.bars.map((_, i) =>
@@ -227,18 +162,11 @@ export const ChartBars = component2d({
       })
     )
   },
-  // The column stroke and shadow are named past the conventional slots, so they are named here.
+  // The stroke and shadow sit past the conventional slots, so they are named here.
   load: (loader, state) =>
     loadPaints(loader, { fills: [state.fill], shadows: [state.barShadow], strokes: [state.barStroke] }),
   commands: {
-    /**
-     * Raise every column from the baseline by tweening `growth` `0 → 1`.
-     *
-     * The mirror of `ChartLine.enter`: same contract that the resting state is
-     * the finished one, so the chart arms this back to 0 before animating rather
-     * than the node hiding itself at construction. No priming to 0 first: the
-     * value at `t` is a function of `t`, so a repeat call re-raises by definition.
-     */
+    /** Raise every column from the baseline (`growth` 0 to 1). The resting state is the finished one; the chart arms it back to 0. */
     enter: (timeline) => {
       const ease = frameEase(timeline)
       return timeline.animate((t) => ({ growth: ease(t) }))
@@ -254,19 +182,14 @@ export const ChartBars = component2d({
         if (height <= 0) continue
 
         const radius = bar.round ? Math.min(state.cornerRadius, height) : 0
-        // A column per `Graphics2D` rather than one list for the series: the
-        // category spotlight dims individual columns, and opacity is a property
-        // of the command list rather than of a shape within it.
+        // One `Graphics2D` per column: opacity belongs to the command list, and the spotlight dims single columns.
         const g = new Graphics2D()
         const rect = g.rect({
           x: bar.x,
           y: (ends.base + ends.end) / 2,
           width: bar.width,
           height,
-          // Corner keys are visual (the renderer keeps them in y-up author space),
-          // so a column reaching *up* rounds its `top*` corners and one reaching
-          // down its `bottom*` ones. Only the far end rounds, which is what makes
-          // a stack read as a single capped column.
+          // Corner keys are visual (y-up): a column reaching up rounds `top*`, one reaching down `bottom*`. Only the far end rounds.
           cornerRadius:
             radius > 0
               ? ends.end >= ends.base

package/src/bar-chart/index.ts

@@ -1,16 +1,8 @@
-/**
- * The bar chart: grouped or stacked columns off a category axis.
- *
- * Shares the plot panel, the value axis and the legend with the line chart —
- * which is what lets a scene swap one for the other without re-theming — and
- * brings its own category axis, since a band scale is not a continuous one.
- */
 export { BarChart, barChartDomain } from "./bar-chart"
-export type { BarChartDomain, BarChartProps, BarChartValues } from "./bar-chart"
+export type { BarChartDomain, BarChartValues } from "./bar-chart"
 export { ChartBars } from "./chart-bars"
-export type { BarGeometry, ChartBarsProps } from "./chart-bars"
+export type { BarGeometry } from "./chart-bars"
 export { CategoryAxis } from "./category-axis"
-export type { CategoryAxisProps } from "./category-axis"
 export {
   DEFAULT_BAR_CHART_THEME,
   barCategories,

package/src/bar-chart/shared.ts

@@ -1,17 +1,3 @@
-/**
- * Types and pure helpers specific to the {@link BarChart} family: how a row's
- * values become the spans its columns cover, how the value axis is scaled around
- * them, and the theme the bars add to the shared chart vocabulary.
- *
- * Everything a line or a pie chart would want too — what a series is, the axis
- * domain model, the theme leaf resolvers, the legend and plot-panel branches —
- * lives in `../kit/shared.ts` and is imported here.
- *
- * Kept renderer-agnostic (no `Node` imports) so a host's inspector mapping
- * can build a partial {@link BarChartTheme} without
- * pulling the components in.
- */
-
 import {
   fillOps,
   lerpNumber,
@@ -26,6 +12,7 @@ import {
   type StrokeResolved,
   type TextStyle,
 } from "@motionscript/sdk"
+import { niceStep } from "@motionscript/sdk/component"
 
 import {
   CHART_PALETTE,
@@ -39,7 +26,6 @@ import {
   lerpLegendConfig,
   lerpPlotArea,
   lerpSeriesFills,
-  niceStep,
   num,
   resolveAxisConfig,
   resolveLegendConfig,
@@ -54,41 +40,25 @@ import {
   type Range,
 } from "../kit/shared"
 
-/**
- * One series in a {@link BarChart}: a column of the table drawn as one bar per
- * row — side by side with its siblings within each category's slot, or stacked
- * on top of them.
- *
- * The family-wide {@link ChartSeries} under a name that says what it draws here.
- */
+/** One bar per row, beside its siblings in the category slot or stacked on them: {@link ChartSeries} under the name for what it draws here. */
 export type BarSeries = ChartSeries
 
 /**
- * One drawn bar's span in **data units**: the value its base sits at and the
- * value its far end reaches.
- *
- * A span rather than a height because that is the one shape both modes fit. A
- * grouped bar runs from zero to its value; a stacked segment runs from the
- * running total below it to that total plus its own value. Negative values fall
- * out of the same arithmetic — the span simply runs the other way — so a chart
- * with a loss in it needs no special case, only a baseline that isn't the floor.
+ * One bar's span in data units. A span rather than a height because both modes
+ * fit it, and a negative value just runs the other way with no special case.
  */
 export interface BarSpan {
-  /** Value the bar's base sits at — 0 when grouped, the running total when stacked. */
+  /** Where the base sits: 0 when grouped, the running total below when stacked. */
   from: number
-  /** Value its far end reaches. */
   to: number
-  /** The value this bar plots — `to - from`, kept for the figure printed on it. */
+  /** `to - from`, kept for the figure printed on the bar. */
   value: number
 }
 
 /**
- * The spans one row's bars cover, one per series, in series order.
- *
- * Stacking is a running sum in the order the series are listed, which is also
- * the order they're drawn: series 0 sits on the baseline and each later one
- * rides on what's below it. A zero-valued series still yields a (degenerate)
- * span so the returned list stays index-aligned with the series list.
+ * One row's spans, in series order. Stacking is a running sum in listed order,
+ * so series 0 sits on the baseline. A zero value still yields a degenerate span,
+ * keeping the list index-aligned with the series.
  */
 export function barSpans(
   row: DataRecord,
@@ -106,13 +76,9 @@ export function barSpans(
 }
 
 /**
- * The index of the series whose segment ends a row's stack — the one that gets
- * the rounded cap, so a stack reads as one capped column rather than a pile of
- * separate boxes. `-1` when every value in the row is zero.
- *
- * Read off the *last non-zero* series rather than the last one listed, so a
- * series that happens to be 0 in this row doesn't take the cap and leave the
- * segment below it square.
+ * The series ending a row's stack, which gets the rounded cap; `-1` when the row
+ * is all zero. It is the last non-zero series, so a zero one does not take the
+ * cap and leave the segment below square.
  */
 export function stackCapIndex(row: DataRecord, series: BarSeries[]): number {
   let last = -1
@@ -122,18 +88,14 @@ export function stackCapIndex(row: DataRecord, series: BarSeries[]): number {
   return last
 }
 
-/** The captions beneath the baseline: one per row, read off the category column. */
 export function barCategories(data: DataRecord[], field: string): string[] {
   return data.map((row) => text(row, field))
 }
 
 /**
- * The `[min, max]` of everything the chart draws, **zero always included**.
- *
- * Zero is in the range whatever the data says, because a bar chart's baseline is
- * zero: a scale starting at 40 draws a column three times its neighbour for a
- * 10% difference, which is the classic way to lie with one. A chart that really
- * does want a cropped axis says so with an explicit range.
+ * The `[min, max]` of everything drawn, zero always included: a scale starting
+ * at 40 draws a column three times its neighbour for a 10% difference. A cropped
+ * axis takes an explicit range.
  */
 export function barValueExtent(
   data: DataRecord[],
@@ -151,14 +113,7 @@ export function barValueExtent(
   return lo < hi ? [lo, hi] : [0, 1]
 }
 
-/**
- * Effective value scale: the explicit `range`, else the data's extent nudged out
- * to tidy step bounds so the markers read as round numbers.
- *
- * `divisions` is how many segments the auto-range is stepped into (one fewer
- * than the marker count), so the ticks the axis draws land on the bounds this
- * picks.
- */
+/** The explicit `range`, else the data's extent nudged to tidy bounds; `divisions` (one fewer than the marker count) makes the drawn ticks land on them. */
 export function resolveBarScale(
   data: DataRecord[],
   series: BarSeries[],
@@ -173,50 +128,36 @@ export function resolveBarScale(
   return [Math.floor(lo / step) * step, Math.ceil(hi / step) * step]
 }
 
-// ---- Theme ---------------------------------------------------------------
-
-/** How the columns themselves are drawn and how the slot is divided up. */
+/** How the columns are drawn and the slot divided. */
 export interface BarStyleConfig {
-  /**
-   * Radius of a column's far-end corners, in px. Only the outer end rounds — an
-   * interior stacked segment stays square, so the stack reads as one column.
-   */
+  /** Radius in px of a column's far-end corners; an interior stacked segment stays square. */
   cornerRadius: number
-  /**
-   * Fraction of its category's slot the bars fill, `[0, 1]`. The remainder is
-   * the channel between one category and the next, which is what makes a bar
-   * chart read as groups rather than as a solid block.
-   */
+  /** Fraction of the category slot the bars fill, `[0, 1]`; the rest separates groups. */
   slotFill: number
-  /** Gap between the grouped bars *within* one slot, in px. Ignored when stacked. */
+  /** Gap in px between grouped bars within a slot; ignored when stacked. */
   groupGap: number
-  /** Optional outline on every column. */
   stroke: Stroke
-  /** Optional drop shadow on every column. */
   shadow: Shadow
 }
 
 /** A {@link BarChart}'s full, resolved visual theme. */
 export interface BarChartConfig {
-  /**
-   * Default per-series bar paint, cycled by series index (`i % length`). A
-   * series' own `fill`, when set, replaces its entry outright.
-   */
+  /** Cycled by series index; a series' own `fill` replaces its entry outright. */
   seriesFills: Fill[]
   bar: BarStyleConfig
-  /** The category axis beneath the baseline. */
+  /** The category axis. */
   xAxis: AxisConfig
-  /** The numeric value axis up the left. */
+  /** The value axis. */
   yAxis: AxisConfig
   plotArea: PlotAreaConfig
   legend: LegendConfig
-  /** The figure printed on each column, when the chart prints them. */
+  /** The figure printed on each column. */
   valueStyle: TextStyle
-  /** How far everything *outside* a spotlit series or category fades. */
+  /** How far everything outside a spotlit series or category fades. */
   spotlight: { dimOpacity: number }
 }
 
-/** Author-facing partial theme — every branch optional and deep-merged. */
+/** The author's partial theme, deep-merged onto {@link DEFAULT_BAR_CHART_THEME}. */
 export type BarChartTheme = {
   seriesFills?: Fill[]
   bar?: Partial<BarStyleConfig>
@@ -228,7 +169,6 @@ export type BarChartTheme = {
   spotlight?: Partial<BarChartConfig["spotlight"]>
 }
 
-/** The bar chart's out-of-the-box look. */
 export const DEFAULT_BAR_CHART_THEME: BarChartConfig = {
   seriesFills: DEFAULT_SERIES_FILLS,
   bar: {
@@ -238,9 +178,7 @@ export const DEFAULT_BAR_CHART_THEME: BarChartConfig = {
     stroke: [],
     shadow: [],
   },
-  // A category axis names its slots, so its captions are set like a caption
-  // rather than like a numeric marker: same size, less weight than the line
-  // chart's ticks, and centred on the slot.
+  // Captions rather than numeric markers: less weight than the line chart's ticks.
   xAxis: {
     ...DEFAULT_X_AXIS,
     labelStyle: { ...DEFAULT_X_AXIS.labelStyle, fontWeight: 600 },
@@ -293,12 +231,7 @@ function lerpBarStyle(
   }
 }
 
-/**
- * {@link BarChart}'s `theme` entry's resolve: merges the author's partial
- * {@link BarChartTheme} onto `previous` (falling back to
- * {@link DEFAULT_BAR_CHART_THEME} on first resolution), fully resolving every
- * leaf so the tween below always has resolved data to interpolate.
- */
+/** The `theme` entry's resolve: merges a partial {@link BarChartTheme} onto `previous` (first resolution: the default). */
 export function resolveBarChartTheme(
   theme: BarChartTheme | undefined,
   previous?: BarChartConfig
@@ -318,7 +251,6 @@ export function resolveBarChartTheme(
   }
 }
 
-/** {@link BarChart}'s `theme` entry's lerp — leaf by leaf. */
 export function lerpBarChartTheme(
   from: BarChartConfig,
   to: BarChartConfig,
@@ -342,7 +274,7 @@ export function lerpBarChartTheme(
   }
 }
 
-/** The paint series `index` is drawn in: its own override, else the palette's entry. */
+/** Series `index`'s own `fill`, else the palette's entry. */
 export function resolveBarFill(
   palette: Fill[],
   series: BarSeries,

package/src/engine.ts

@@ -1,20 +1,8 @@
 /**
- * The chart **kit**: everything the three charts share, and the one thing a
- * copied chart does not copy.
- *
- * A copy of the line chart takes `line-chart/*` into your project and rewrites its
- * reach for these to `@motionscript/charts`, so the plot panel, the value
- * axis, the legend and the number formatting stay a real dependency. That is
- * not a size decision — it is the only arrangement that works.
- *
- * A chart identifies its own parts by component identity (`VerticalAxis.is`).
- * Copy `VerticalAxis` alongside your fork and there are now two of it — two
- * components answering one name, and whichever one your chart did not get is
- * a part it never finds, with no error. Keeping the kit external makes that
- * impossible rather than unlikely.
- *
- * It also means a fix to the axis reaches a forked chart without a re-add,
- * which is the half of the bargain you get back for it.
+ * The chart kit: what the three charts share, and what a copied chart does not
+ * copy. A chart finds its parts by component identity (`VerticalAxis.is`), so a
+ * second copy of `VerticalAxis` would be a second component that the chart never
+ * finds, with no error. Copies import the kit from `@motionscript/charts`.
  */
 export * from "./kit/shared"
 export * from "./kit/cartesian"

package/src/kit/cartesian.ts

@@ -3,21 +3,15 @@ import { Rect, type ChildView, type Node2D, type Size2D } from "@motionscript/sd
 import { VerticalAxis } from "./vertical-axis"
 
 /**
- * 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.
+ * Headroom above the plot, in px. Real padding on the composition, so the top
+ * marker, centred on the top grid line, does not draw its upper half above the
+ * chart's own box.
  */
-export const TOP_HEADROOM = 24
+const TOP_HEADROOM = 24
 
-/** The parts of a cartesian chart's frame, as {@link cartesianFrame} arranges them. */
-export interface CartesianParts {
-  /** The value axis, left of the plot. */
+interface CartesianParts {
   readonly axis: Node2D
-  /** The plot panel: the box the grid and the marks share. */
+  /** 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
@@ -25,11 +19,7 @@ export interface CartesianParts {
   readonly below: readonly Node2D[]
 }
 
-/**
- * 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: the value axis beside the plot, and under them the gutter, so the rows below start at the plot's left edge. */
 export function cartesianFrame(parts: CartesianParts): Node2D {
   return new Rect({
     flow: "vertical",
@@ -47,19 +37,14 @@ export function cartesianFrame(parts: CartesianParts): Node2D {
   }) as unknown as Node2D
 }
 
-/** A cartesian frame's parts, as a command reaches them through its chart's children. */
-export interface CartesianViews {
+interface CartesianViews {
   readonly axis: ChildView
-  /** The plot panel's own children: the grid, the marks, the border. */
+  /** The plot panel's own children: grid, marks, border. */
   readonly plot: readonly ChildView[]
   readonly below: readonly ChildView[]
 }
 
-/**
- * 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.
- */
+/** 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, so it is found by shape. */
 export function cartesianViews(children: readonly ChildView[]): CartesianViews | null {
   for (let i = children.length - 1; i >= 0; i--) {
     const frame = children[i]
@@ -74,7 +59,7 @@ export function cartesianViews(children: readonly ChildView[]): CartesianViews |
   return null
 }
 
-/** A part's laid-out size, or nothing before it is built or laid 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 }