@motionscript/charts 0.1.0 → 0.1.1-alpha.1

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # @motionscript/charts
 
+## 0.1.1-alpha.1
+
+### Patch Changes
+
+- 1810e8a: **Breaking:** the charts are rebuilt around one `style` entry, and the kit gains a radar and a radial chart.
+
+  - **One look entry.** Every chart's `theme` (and its `DEFAULT_*_THEME`, `resolve*Theme`, `lerp*Theme`) is gone, along with `showLegend` and the bar chart's `showValues`. Each chart has `style: Types.style("chart", …)` instead, with fields grouped as colours (`palette`, `foreground`, `muted`, `background`), text (`fontFamily`, `fontSize`, `fontWeight`), grid (`horizontalGrid`, `verticalGrid` and `axisStroke` on a line or bar chart, `gridStroke` and `spokeStroke` on a radar, all strokes, so weight, colour, dash and caps come with them and an empty one draws nothing), marks, labels and legend (`legend`: bottom, top, right or none; `swatch`: square, circle or line). A chart takes only the fields it draws, and one style dresses any chart. `CHART_STYLE_PRESETS` (midnight, paper, ember, neon, ocean, sunset, pastel, mono) are partial looks to spread in; `to({ style })` tweens a restyle.
+  - **Line and area are one chart.** `lineChart` draws curves `smooth` (monotone, never overshooting), `linear` or `step`, optional dots, and `style.area` of `none`, `solid` or `gradient` under each line. `stack` is `none`, `stacked` or `percent`. Up to twelve categorical or dated samples each get a tick.
+  - **Bars.** `barChart` takes `orientation` (`vertical` or `horizontal`) and `stack` (`none`, `stacked` or `percent`; replaces `stacked`). Negative values grow from zero, only a stack's outer end is rounded, and `style.values` puts figures at the `end` of a bar or `inside` it.
+  - **Pie.** `style.innerRadius` makes a donut; `sliceGap`, `sliceRadius` and `labelPlacement` (`inside`, `outside`, `none`) are style fields.
+  - **New: `radarChart`.** One spoke per row, one polygon per series, a `polygon` or `circle` grid, with `enter` and the series commands.
+  - **A line is a stroke, an area is a fill.** A radial's `track` is a fill (empty for none). There is no grid width, dash, axis-line, spoke or track switch, and no `gridColor`. A series' `label` is optional: the legend shows `label || field`.
+  - **New: `radialChart`.** One ring per row, swept by `value / max` over `style.sweep` degrees from `style.startAngle`, with tracks, round caps, ring labels, a centre summary, `enter`, `selectRing`, `clearSelection` and `revealCenter`.
+  - **The kit** draws no plot border by default, puts each legend swatch before its caption, and moves `HorizontalAxis`, the polar helpers (`kit/polar`) and `PieLegend` behind the kit barrel, so a copied chart reaches only the kit. Removed from `./kit`: `ChartBorder`, `CHART_PALETTE`, `DEFAULT_PLOT_AREA`, `PlotAreaConfig`, `DEFAULT_SERIES_COLORS` (use `CHART_PALETTE_DEFAULT`), `DEFAULT_SERIES_STROKES`, `DEFAULT_SERIES_FILLS`, `LegendTheme`, and the theme helpers `resolveAxisConfig`, `lerpAxisConfig`, `resolvePlotArea`, `lerpPlotArea`, `resolveLegendConfig`, `lerpLegendConfig`, `resolveSeriesStrokes`, `lerpSeriesStrokes`, `resolveSeriesFills`, `lerpSeriesFills`, `resolveSeriesStroke` and `resolveSeriesFill` (a chart's colours come from `seriesFill`/`paletteFill` over its style).
+
+  The renderer's path and paint cache keys no longer collide for shapes mirrored through the origin, which drew two symmetric grid rules as one.
+
+  Migration: nothing converts a stored chart. A document row's `theme`, `showLegend`, `showValues` and `stacked` are dropped on open and the chart draws in the default style; a host with stored charts rewrites them: `theme` → a `style` partial (series colours to `palette`, text colours to `foreground`/`muted`), `showLegend: false` → `style.legend: "none"`, `showValues: true` → `style.values: "end"`, `stacked: true` → `stack: "stacked"`, `gridColor`/`gridWidth`/`gridDashed` → `horizontalGrid`/`verticalGrid` (or `gridStroke` on a radar), `grid: "vertical"` → `verticalGrid` on and `horizontalGrid: []`, `axisLine` → `axisStroke`, `spokes: false` → `spokeStroke: []`, a radial's `track: false` → `track: []`, and a pie's `labelPlacement` → `style.labelPlacement` (`leader` is now `outside`).
+
+## 0.1.1-alpha.0
+
+### Patch Changes
+
+- e279864: **Breaking:** the component kits drop exports nothing used.
+
+  - **math:** the hand-mirrored `*Props` interfaces of 24 components (`AngleMarkProps`, `CurlyBraceProps`, `EmphasisMarkProps`, `CurveAreaProps`, `DropLinesProps`, `PlotPointProps`, `RiemannSumProps`, `TangentLineProps`, `VectorArrowProps`, `PointsPlotProps`, `StreamLinesProps`, `TracedPathProps`, `VectorFieldProps`, `NetworkGraphProps`, `SampleSpaceProps`, `NumberLineProps`, `NumberPlaneProps`, `PolarPlaneProps`, `LatexMatrixProps`, `Axes3dProps`, `CurvePlot3dProps`, `PlotPoint3dProps`, `SurfacePlot3dProps`, `VectorArrow3dProps`), `FILL_PAINT`, `STROKE_PAINT`, `OUTLINE_TRIM` and `spaceOf` from `./kit`, and `LatexPathResult.commands`.
+  - **charts:** `LineChartProps`, `BarChartProps`, `PieChartProps`, `PieRingProps`, `PieLegendProps`, `ChartBarsProps`, `CategoryAxisProps`, `ChartBorderProps`, `ChartCanvasProps`, `ChartLegendProps`, `VerticalAxisProps`, and from `./kit` `axisTweenTarget`, `resolvePalettePaint`, `legendShows`, `MarkerLabel`, `clampUnit` (use the SDK's `clamp`). `niceStep` and `enterBudget` stay reachable from `@motionscript/sdk/component`.
+  - **audio:** `FullWaveformProps`, `LiveWaveformProps`, and `clamp01` from `./kit`.
+  - **patterns:** `DotGridPatternProps`, `GridPatternProps`, `LineGridPatternProps`.
+  - **code:** `DEFAULT_THEMES`, `splitTokensAt`, `LINE_ALIGN_CELLS`, `EDIT_ALIGN_CELLS`, and `phasesFor` (use `defaultCodePhases`). `ensureHighlighter`, `loadCodeLanguage`, `initSyntaxHighlighter` and `canHighlight` lose their ignored theme argument.
+  - **grids:** the `findNode2D` and `frameIn` re-exports (import them from `@motionscript/sdk`), `ArrangementKind`, `PathGridShape`, `RectangularGridProps`, `RadialGridProps`, `PathGridProps`, `SphereGridProps`.
+  - **geography:** `GeoBorderProps`.
+
+  Migration: no stored document is affected; only TypeScript imports change. Code that imported a removed `*Props` interface states the props it passes inline, and code that used a removed helper uses the replacement named beside it above.
+
+- Updated dependencies [e279864]
+  - @motionscript/sdk@0.1.1-alpha.0
+
 ## 0.1.0
 
 ## 0.1.0-alpha.10

package/README.md

@@ -1,14 +1,15 @@
 # @motionscript/charts
 
-Animated data charts for [Motion Script](https://motionscript.dev): a line chart,
-a bar chart and a pie chart, built from one shared kit (plot panel, value axis,
-legend, number formatting, theme resolution). Written against
+Animated data charts for [Motion Script](https://motionscript.dev): a line chart
+(which is also the area chart), a bar chart, a pie chart, a radar chart and a
+radial chart, built from one shared kit (plot panel, value axis, legend, number
+formatting) and dressed by one `style` entry. Written against
 [`@motionscript/sdk`](https://github.com/motionscript-dev/motionscript/tree/main/packages/sdk), which it takes as a peer dependency.
 
 ```ts
 import { NODES } from '@motionscript/charts';
 
-export const nodes = NODES; // [LineChart, BarChart, PieChart]
+export const nodes = NODES; // [LineChart, BarChart, PieChart, RadarChart, RadialChart]
 ```
 
 Importing registers nothing; the host hands `NODES` to the engine (see
@@ -24,36 +25,98 @@ npm install @motionscript/charts @motionscript/sdk
 
 | Path | Source | What |
 |---|---|---|
-| `@motionscript/charts` | `src/index.ts` | the three chart barrels, `src/engine.ts` and `NODES` |
-| `@motionscript/charts/kit` | `src/engine.ts` | the shared kit (`src/kit/*`) and all of `@motionscript/sdk/component` |
-
-Each chart folder (`line-chart/`, `bar-chart/`, `pie-chart/`) has an `index.ts`
-barrel with the node, its parts, its theme (`DEFAULT_*_THEME`, `resolve*Theme`,
-`lerp*Theme`) and its pure helpers (`resolveXScale`, `barSpans`, `pieArcs`, ...).
-The charts and their parts (`ChartLine`, `ChartBars`, `PieRing`, `VerticalAxis`, ...)
-are components (`component2d`); only the charts are registered node types, so a
-document cannot name a part. A chart tells a host its key, entries and commands;
-where it is shelved and the box it is seeded at are the host's to keep. `lineChartDomains` and `barChartDomain` give the axes as drawn, and
-`isSliceSelected` whether a pie slice is out.
+| `@motionscript/charts` | `src/index.ts` | the five chart barrels, `src/engine.ts` and `NODES` |
+| `@motionscript/charts/kit` | `src/engine.ts` | the shared kit (`src/kit/*`, including `kit/style`, `kit/polar` and `PieLegend`) and all of `@motionscript/sdk/component` |
+
+Each chart folder (`line-chart/`, `bar-chart/`, `pie-chart/`, `radar-chart/`,
+`radial-chart/`) has an `index.ts` barrel with the node, its parts and its pure
+helpers (`resolveXScale`, `barSpans`, `pieArcs`, ...). The charts and their parts
+(`ChartLine`, `ChartBars`, `PieRing`, `VerticalAxis`, ...) are components
+(`component2d`); only the charts are registered node types, so a document cannot
+name a part. A chart tells a host its key, entries and commands; where it is
+shelved and the box it is seeded at are the host's to keep. `lineChartDomains` and
+`barChartDomain` give the axes as drawn, and `isSliceSelected` whether a pie slice
+is out.
+
+The style kit exports `CHART_STYLE_FAMILY` (`"chart"`), `CHART_STYLE_PRESETS`,
+`CHART_PALETTE_DEFAULT` and the shared field groups (`CHART_COLORS`,
+`CHART_TEXT`, `CARTESIAN_GRID`, `CHART_LEGEND`).
 
 ## Nodes
 
 | Key | Made for (w x h) | Data props | Commands |
 |---|---|---|---|
-| `lineChart` | 760 x 460 | `data`, `xField`, `series`, `xAxis`, `yAxis`, `region` | `enter`, `spotlightRegion`, `clearRegion`, `zoomTo`, `resetZoom`, `showSeries`/`hideSeries`/`spotlightSeries` |
-| `barChart` | 760 x 460 | `data`, `categoryField`, `series`, `valueAxis`, `stacked` | `enter`, `showSeries`/`hideSeries`/`spotlightSeries`, `spotlightCategory`, `clearCategory` |
-| `pieChart` | 680 x 480 | `data`, `categoryField`, `valueField` | `enter`, `revealCenter`, `selectSlice`/`deselectSlice`/`selectOnlySlice`/`clearSelection` |
+| `lineChart` | 760 x 460 | `data`, `xField`, `series`, `stack`, `xAxis`, `yAxis`, `region` | `enter`, `spotlightRegion`, `clearRegion`, `zoomTo`, `resetZoom`, `showSeries`/`hideSeries`/`spotlightSeries` |
+| `barChart` | 760 x 460 | `data`, `categoryField`, `series`, `orientation`, `stack`, `valueAxis`, `categoryAxis` | `enter`, `showSeries`/`hideSeries`/`spotlightSeries`, `spotlightCategory`, `clearCategory` |
+| `pieChart` | 680 x 480 | `data`, `categoryField`, `valueField`, `labelMode`, `centerLabel`, `centerCaption` | `enter`, `revealCenter`, `selectSlice`/`deselectSlice`/`selectOnlySlice`/`clearSelection` |
+| `radarChart` | 680 x 480 | `data`, `categoryField`, `series`, `min`, `max` | `enter`, `showSeries`/`hideSeries`/`spotlightSeries` |
+| `radialChart` | 560 x 560 | `data`, `categoryField`, `valueField`, `max`, `centerLabel`, `centerCaption` | `enter`, `revealCenter`, `selectRing`, `clearSelection` |
 
 Every command takes the duration its row (or call) gives, and eases out unless
-given an easing. Arguments: `seriesIndex`, `sliceIndex`, `categoryIndex` (each 0
-when left out), and for `spotlightRegion` and `zoomTo` a `region` of
-`{ x?: [min, max], y?: [min, max] }`.
+given an easing. Arguments: `seriesIndex`, `sliceIndex`, `categoryIndex`,
+`ringIndex` (each 0 when left out), and for `spotlightRegion` and `zoomTo` a
+`region` of `{ x?: [min, max], y?: [min, max] }`.
+
+`lineChart` draws a line or an area chart: `style.area` of `none`, `solid` or
+`gradient` fills under each line. `pieChart` draws a donut once `style.innerRadius`
+is above 0.
+
+## Styling
+
+Each chart has one look entry, `style`, and nothing else about colour or type:
+no `theme`, no `showLegend`. Its fields come in groups, written grouped and read
+flat (`state.style.fontSize`):
+
+| Group | Fields | On |
+|---|---|---|
+| colors | `palette`, `foreground`, `muted`, `background` | every chart |
+| text | `fontFamily`, `fontSize`, `fontWeight` | every chart |
+| grid | `horizontalGrid` (a 2px `white/15` stroke), `verticalGrid` (none), `axisStroke` (none), `showXAxis`, `showYAxis` | line, bar |
+| grid | `gridShape`, `gridLevels`, `gridStroke` (rings), `spokeStroke` (spokes), `spokeLabels` | radar |
+| marks | the chart's own: `strokeWidth`, `curve`, `dots`, `area`, `barRadius`, `innerRadius`, `sweep`, ... | every chart |
+| labels | `values` (line, bar), `labelPlacement` (pie), `ringLabels` (radial) | |
+
+A line is a stroke and an area is a fill: `horizontalGrid`, `verticalGrid`, `axisStroke`, `gridStroke`
+and `spokeStroke` are `Types.stroke` entries (weight, colour, dash and caps; empty draws
+nothing), and a radial's `track` is a `Types.fill` (empty draws no track). A series' `label`
+is optional; the legend shows `label || field`.
+| legend | `legend` (`bottom`, `top`, `right`, `none`), `swatch` (`square`, `circle`, `line`) | every chart |
+
+A chart takes only the fields it draws. A style is a partial laid over the chart's
+previous style, and a key the chart does not have is dropped, so one style dresses
+every chart in the family.
+
+`CHART_STYLE_PRESETS` (`midnight`, `paper`, `ember`, `neon`, `ocean`, `sunset`,
+`pastel`, `mono`) are colour-only partials. Spread one into a style and add to it:
+
+```ts
+import { CHART_STYLE_PRESETS } from '@motionscript/charts';
+
+const props = {
+  // ...data, series
+  style: { ...CHART_STYLE_PRESETS.paper, fontSize: 32, area: 'gradient' },
+};
+```
+
+Restyle with a `to` command, which tweens colours, sizes and weights and steps
+everything else at the midpoint:
+
+```ts
+{ id: 'restyle', type: 'to', targetId: 'chart', at: 3, duration: 1,
+  args: { style: CHART_STYLE_PRESETS.ember } }
+```
+
+Fields marked read-once below (`legend`, `showXAxis`, `showYAxis`, `values`,
+`labelPlacement`, `spokeLabels`) shape which parts are built; a `to` of them
+steps rather than tweens, and a document edit rebuilds the node.
 
 ## Rules worth knowing
 
 - **The kit stays an import.** A copy of `line-chart` takes only `line-chart/*` and
   rewrites its kit imports to `@motionscript/charts` (`registry.json`): a second
-  copy of `VerticalAxis` would render as nothing, with no error.
+  copy of `VerticalAxis` would render as nothing, with no error. The kit includes
+  `kit/polar` and `PieLegend`, which the pie, radar and radial charts reach for, so
+  a copy of any chart reaches only the kit.
 - **Resting state is the finished chart.** `enter` arms every part on its first
   frame: every piece of a component command is built run to its end, and a beat
   ahead of the playhead writes nothing, so the first frame writes what each later
@@ -63,14 +126,18 @@ when left out), and for `spotlightRegion` and `zoomTo` a `region` of
   duration and easing it moves with; called directly, a part's command takes the
   duration it is given, and a part's own frames ease out unless given an easing.
 - **Some props are read once, at construction**: the series list (count, labels,
-  `enabled`), `showLegend`, `showValues`, `showCenter`, axis captions, text styles and
-  paddings, the bar chart's category captions, the pie's label and legend-row counts,
-  `labelMode`, `labelPlacement`, `gap`, `centerLabel`, `centerCaption`. A `set` or `to`
-  of them changes nothing; a document edit re-instantiates the node, which does
-  refresh them. `data`, scales, ticks, theme paints, `region`, `stacked`, `weights`
+  `enabled`), `orientation`, `showCenter`, axis captions, the bar chart's category
+  captions, the pie's and radial's label and legend-row counts, `labelMode`, `gap`,
+  `centerLabel`, `centerCaption`, and the style fields `legend`, `showXAxis`,
+  `showYAxis`, `values`, `labelPlacement`, `spokeLabels`. A `set` or `to` of them
+  changes nothing; a document edit re-instantiates the node, which does refresh
+  them. `data`, scales, ticks, every other style field, `region`, `stack`, `weights`
   and `pops` are live.
 - **Non-finite cells plot as 0.** `num()` returns a cell only when it is a finite
   number, so a numeric string, `NaN`, `Infinity` and a missing cell all read 0.
+- **`horizontalGrid` and `verticalGrid` are literal.** They name the lines drawn, not an axis: a
+  horizontal bar chart that wants rules along its value axis sets `verticalGrid` and
+  `horizontalGrid: []`.
 - **x units on the line chart.** `xAxis.range`, `xAxis.ticks` and a region's `x`
   are in the x scale's own units: the number (numeric column), UTC epoch
   milliseconds (time column) or the row index (ordinal column), chosen from the
@@ -85,7 +152,10 @@ when left out), and for `spotlightRegion` and `zoomTo` a `region` of
   the chart settles against its data, so a rescale from an auto axis is continuous.
   A restated range without ticks spreads explicit ticks across it; one side of an
   auto axis restated alone leaves the other to the data.
-- **Pie angles** are radians clockwise from 12 o'clock; `startAngle` is degrees.
+- **Pie angles** are radians clockwise from 12 o'clock. A radial's `startAngle` and
+  `sweep` are degrees, `startAngle` clockwise from 12 o'clock.
+- **Centre text needs a hole.** A pie shows `centerLabel` and `centerCaption` only
+  with `style.innerRadius` above 0; a radial's hole is `style.innerRadius` too.
 
 ## Development