@motionscript/charts 0.1.0 → 0.1.1-alpha.1

package/src/line-chart/x-scale.ts

@@ -1,29 +1,11 @@
 /**
- * What a line chart's x column *means* — the one question that has to be
- * answered before a row can be given a position along the bottom of the plot.
+ * What a line chart's x column means: a number (plotted as is), an instant
+ * (`Jan`, `2026-W12`; plotted by time, so a gap in the data reads as a gap), or
+ * anything else (the row's position, evenly spaced).
  *
- * A y column is always a magnitude. An x column is one of three things, and
- * which one is a property of the data rather than something the author states:
- *
- * - **numeric** — `0, 5, 10` — plot the number.
- * - **time** — `Jan`, `2026-03`, `2026-W12`, `2026-03-14` — plot the instant,
- *   so samples a month apart sit a month apart and a gap in the data reads as a
- *   gap.
- * - **ordinal** — anything else — plot the row's position, evenly spaced.
- *
- * Before this, every x column went through `num()`, which reads a non-numeric
- * cell as `0`. A `Month` column of `Jan…Dec` therefore stacked all twelve
- * points on one x and drew a vertical line — no error, no empty chart, just a
- * wrong picture. That is the failure this module exists to remove: every column
- * now plots as *something*, and the something is the reading a person would
- * give it.
- *
- * The captions come back off the rows rather than out of a formatter. A tick on
- * a time or ordinal scale is chosen *from the data* (see {@link XScale.ticks}),
- * so the label it wants is the cell the author wrote — `Jan`, not `1970-01-01`,
- * and `2026-W12`, not the Monday it resolves to. Only a tick that is not a
- * sample — an author-set range, or a `zoomTo` mid-flight — needs formatting,
- * and that is the one case {@link formatInstant} covers.
+ * A tick on a time or ordinal scale is a sample, so its caption is the cell the
+ * author wrote; only a tick that is not (an author-set range, a `zoomTo`
+ * mid-flight) is formatted, by {@link formatInstant}.
  */
 
 import type { DataRecord } from "@motionscript/sdk"
@@ -40,26 +22,18 @@ import { formatNumber } from "@motionscript/sdk/component"
 /** How an x column's cells become positions along the axis. */
 export type XScaleKind = "numeric" | "time" | "ordinal"
 
-/**
- * An x column resolved into positions, captions and ticks.
- *
- * The three kinds differ in all three answers, so they are three closures built
- * once per (data, column) rather than a kind tag every caller switches on.
- */
+/** An x column resolved into positions, captions and ticks: three closures built once per (data, column), not a tag callers switch on. */
 export interface XScale {
   kind: XScaleKind
   /** Position of row `index` along the axis, in this scale's own units. */
   at(index: number): number
-  /** `[min, max]` across the rows — the scale when no range is set. */
+  /** `[min, max]` across the rows: the scale when no range is set. */
   extent: Range
-  /** The caption for a tick at `value`. */
   label(value: number): string
   /** `divisions + 1` tick values spanning `range`, ends included. */
   ticks(range: Range, divisions: number): number[]
 }
 
-// ---- Time parsing --------------------------------------------------------
-
 const DAY = 86_400_000
 
 const MONTHS = [
@@ -77,29 +51,15 @@ const MONTHS = [
   "december",
 ]
 
-/**
- * The year a cell that names no year is dated into.
- *
- * Any year would place `Jan…Dec` in the right order at the right spacing; a
- * leap year is the one that also spaces February correctly against a column
- * that *does* carry years, so the two read alike.
- */
+/** The year a cell naming none is dated into; a leap year, so February spaces the same as in a column that carries years. */
 const NOMINAL_YEAR = 2024
 
-/**
- * Month index for any unambiguous abbreviation of a month name — `jan`, `sept`,
- * `january` — or -1.
- *
- * Three letters minimum, and then a prefix match, which is what lets `sept`
- * through without letting `janitor` through: a longer word has to still *be*
- * the month.
- */
+/** Month index for `jan`, `sept` or `january`, else -1: three letters minimum, then a prefix match, so `sept` passes and `janitor` does not. */
 function monthIndex(word: string): number {
   if (word.length < 3) return -1
   return MONTHS.findIndex((month) => month.startsWith(word))
 }
 
-/** The Monday of ISO week `week` in `year`, as an epoch timestamp. */
 function isoWeekStart(year: number, week: number): number {
   // ISO week 1 is the week containing 4 January, and weeks start on Monday.
   const jan4 = Date.UTC(year, 0, 4)
@@ -108,14 +68,10 @@ function isoWeekStart(year: number, week: number): number {
 }
 
 /**
- * One cell read as an instant, or `null` when it isn't one.
- *
- * Deliberately **not** `Date.parse`. That accepts `"5"`, `"Q3"` and a good deal
- * else besides, differs between engines on anything non-ISO, and reads a bare
- * `2026-03-14` as UTC but `2026/03/14` as local — three ways for a column to be
- * silently misread as time. Every form below is matched explicitly, and an
- * ambiguous all-numeric date (`03/04/2026` — March or April, depending on where
- * the author lives) is deliberately not one of them.
+ * One cell read as an instant, or `null`. Not `Date.parse`, which accepts `"5"`
+ * and `"Q3"`, differs between engines off ISO, and reads `2026-03-14` as UTC but
+ * `2026/03/14` as local. Every form is matched explicitly, and an ambiguous
+ * all-numeric date (`03/04/2026`) is not one of them.
  */
 export function parseInstant(raw: unknown): number | null {
   if (typeof raw !== "string") return null
@@ -169,14 +125,7 @@ export function parseInstant(raw: unknown): number | null {
   return null
 }
 
-/**
- * An instant captioned at the coarsest granularity the axis's own span can tell
- * apart — a decade of samples reads as years, a year of them as months.
- *
- * Only reached for a tick that is *not* one of the rows (an author-set range, a
- * `zoomTo` part-way through). A tick that is a sample is captioned with the
- * cell the author wrote; see the note at the top of this file.
- */
+/** An instant captioned at the coarsest granularity the span tells apart: a decade reads as years, a year as months. */
 export function formatInstant(value: number, span: number): string {
   const date = new Date(value)
   const year = date.getUTCFullYear()
@@ -187,16 +136,7 @@ export function formatInstant(value: number, span: number): string {
   return `${label} ${date.getUTCDate()}`
 }
 
-// ---- Column reading ------------------------------------------------------
-
-/**
- * Whether every non-empty cell of `field` holds a number.
- *
- * The same rule `numericFields` applies, asked of one column: a single text
- * cell in an otherwise numeric column takes the whole column off the numeric
- * scale, because plotting that row at 0 is the failure this module is here to
- * stop.
- */
+/** `numericFields`' rule for one column: a single text cell takes it off the numeric scale rather than plot that row at 0. */
 function isNumericColumn(data: DataRecord[], field: string): boolean {
   let sawValue = false
   for (const row of data) {
@@ -209,13 +149,9 @@ function isNumericColumn(data: DataRecord[], field: string): boolean {
 }
 
 /**
- * Every non-empty cell of `field` parsed as an instant, or `null` if any one of
- * them isn't one — in which case the column isn't a time column at all.
- *
- * A blank cell keeps its slot, so the returned list stays index-aligned with
- * the rows, and takes the nearest known instant: a hole in an x column is a row
- * whose date the file didn't say, and stacking it on the epoch would drag the
- * whole scale back fifty years to make room for it.
+ * Every non-empty cell as an instant, or `null` if any is not one. A blank cell
+ * keeps its slot and takes the nearest known instant: stacking it on the epoch
+ * would drag the whole scale back fifty years.
  */
 function instantColumn(data: DataRecord[], field: string): number[] | null {
   const parsed: (number | null)[] = []
@@ -249,24 +185,16 @@ function extentOf(values: number[]): Range {
   return lo <= hi ? [lo, hi] : [0, 1]
 }
 
+/** Up to this many samples in view, every one is a tick. */
+export const EVERY_SAMPLE = 12
+
 /**
- * Ticks spanning `range`, each one **a sample** — a row the author can point at
- * in their file — placed as near as it can be to where an evenly spaced tick
- * would have gone.
- *
- * Two things have to hold at once, and picking either alone gets it wrong.
- * Ticks must be *samples*, because a caption between two of them has nothing to
- * say (two-thirds of the way through March is not a month, and on a category
- * column it is not anything at all). And they must be *spread*, because the
- * labels sit side by side in a row: taking every nth sample instead puts five
- * dates in the two weeks a burst of rows happens to cover and prints them on
- * top of each other, which is what a column with a gap in it does.
- *
- * Walking the targets rather than the samples is what satisfies both. A run of
- * rows too close together to caption collapses to one tick — consecutive
- * targets pick the same sample and the duplicate is dropped — so a chart asked
- * for five ticks across a gappy column draws four honest ones instead of five
- * overlapping.
+ * Ticks spanning `range`, each a sample, nearest to where an evenly spaced tick
+ * would go. They must be samples (a caption between two has nothing to say) and
+ * spread (every nth sample would print five dates on top of each other across a
+ * burst of rows), so this walks the evenly spaced targets, not the samples.
+ * Targets that pick the same sample collapse to one tick, so a gappy column
+ * draws fewer honest ticks rather than overlapping ones.
  */
 function sampledTicks(
   positions: number[],
@@ -276,6 +204,8 @@ function sampledTicks(
   const inside = positions.filter((v) => v >= min && v <= max)
   const unique = [...new Set(inside)].sort((a, b) => a - b)
   if (unique.length === 0) return markerValues([min, max], divisions)
+  // Few and even enough to caption every one: a month left out reads as missing data.
+  if (unique.length <= EVERY_SAMPLE && evenlySpaced(unique)) return unique
 
   const nearest = (target: number) =>
     unique.reduce((best, v) =>
@@ -290,10 +220,15 @@ function sampledTicks(
   return out
 }
 
-/**
- * The caption a tick carries on a sample-based scale: the cell of the row it
- * came from, or `fallback` when the tick isn't a sample after all.
- */
+/** Whether no two neighbouring samples sit much closer than the average gap: months do, a burst of days between weeks of nothing does not. */
+function evenlySpaced(sorted: readonly number[]): boolean {
+  if (sorted.length < 3) return true
+  const mean = (sorted[sorted.length - 1] - sorted[0]) / (sorted.length - 1)
+  for (let i = 1; i < sorted.length; i++) if (sorted[i] - sorted[i - 1] < mean * 0.75) return false
+  return true
+}
+
+/** The cell of the row a tick came from, or `fallback` when it is not a sample. */
 function labelBySample(
   positions: number[],
   captions: string[],
@@ -304,16 +239,10 @@ function labelBySample(
   return i >= 0 ? captions[i] : fallback(value)
 }
 
-/** Scales already resolved, by data array, then by field and pattern. */
+/** Resolved scales by data array, then by field and pattern. */
 const scales = new WeakMap<DataRecord[], Map<string, XScale>>()
 
-/**
- * How `field` positions the rows: the number it holds, the instant it names, or
- * failing both, the row's own place in the file.
- *
- * Kept per `data` array: a chart's bound props ask a dozen times a frame, and
- * parsing every row's instant each time was most of a frame.
- */
+/** Kept per `data` array: bound props ask a dozen times a frame, and parsing every row's instant each time was most of a frame. */
 export function resolveXScale(
   data: DataRecord[],
   field: string,
@@ -330,11 +259,7 @@ export function resolveXScale(
 function xScaleOf(
   data: DataRecord[],
   field: string,
-  /**
-   * The number-format pattern for a *numeric* column. Ignored by the other two
-   * kinds, and correctly so: a tick on those is captioned with the cell the
-   * author wrote, and `Jan` has no decimal places.
-   */
+  /** Number-format pattern for a numeric column only; ticks on the other kinds are the author's cells. */
   pattern?: string
 ): XScale {
   if (field !== "" && isNumericColumn(data, field)) {
@@ -345,8 +270,7 @@ function xScaleOf(
       extent: extentOf(positions),
       label: (value) =>
         pattern === undefined ? formatMarker(value) : formatNumber(value, pattern),
-      // Round numbers, evenly spaced — a continuous axis is read by its scale
-      // rather than by which samples happen to be on it.
+      // A continuous axis is read by its scale, not by which samples are on it.
       ticks: markerValues,
     }
   }
@@ -373,8 +297,7 @@ function xScaleOf(
   return {
     kind: "ordinal",
     at: (i) => i,
-    // `[0, n-1]` rather than the tidy `[0, n]`: the first and last rows sit on
-    // the plot's edges, which is where a reader looks for them.
+    // `[0, n-1]`, not `[0, n]`: the first and last rows sit on the plot's edges.
     extent: positions.length > 0 ? [0, positions.length - 1] : [0, 1],
     label: (value) => captions[Math.round(value)] ?? "",
     ticks: (range, divisions) => sampledTicks(positions, range, divisions),

package/src/nodes.ts

@@ -1,18 +1,14 @@
 import { LineChart } from "./line-chart";
 import { BarChart } from "./bar-chart";
 import { PieChart } from "./pie-chart";
+import { RadarChart } from "./radar-chart";
+import { RadialChart } from "./radial-chart";
 
-/**
- * Every node type this package publishes.
- *
- * A host registers these by handing the array to an engine —
- * `new Engine(platform, { nodes: NODES })` — which reads each component's key.
- * Defining a component only *declares* that key: nothing is registered by
- * importing a module, so a registry holds exactly what its owner asked for.
- *
- * Listing the component **values** is also what survives bundling: this package
- * declares `sideEffects: false`, and a document names a node type by string, so
- * an import kept only for its side effect is exactly what gets shaken out.
- */
 // Typed by name, so the declaration names each component rather than spelling out its type through core.
-export const NODES: (typeof LineChart | typeof BarChart | typeof PieChart)[] = [LineChart, BarChart, PieChart];
+export const NODES: (typeof LineChart | typeof BarChart | typeof PieChart | typeof RadarChart | typeof RadialChart)[] = [
+  LineChart,
+  BarChart,
+  PieChart,
+  RadarChart,
+  RadialChart,
+];

package/src/pie-chart/index.ts

@@ -1,37 +1,5 @@
-/**
- * The pie chart: the one in the family that draws a mark per **row** rather
- * than per column.
- *
- * So it shares the legend and the theme machinery with its siblings and none of
- * the cartesian geometry. Set the theme's `ring.holeRadius` to 0 for a solid
- * pie; it defaults to a donut, because the hole is the only place a chart has
- * to put its conclusion.
- */
 export { PieChart, isSliceSelected } from "./pie-chart"
-export type { PieChartProps, PieChartValues } from "./pie-chart"
+export type { PieChartValues } from "./pie-chart"
 export { PieRing } from "./pie-ring"
-export type { PieRingProps } from "./pie-ring"
-export { PieLegend } from "./pie-legend"
-export type { PieLegendProps } from "./pie-legend"
-export {
-  DEFAULT_PIE_CHART_THEME,
-  lerpPieChartTheme,
-  pieArcs,
-  relaxLabels,
-  resolvePieChartTheme,
-  resolvePieSlices,
-  ringPoint,
-  sliceTotal,
-  sliceValue,
-} from "./shared"
-export type {
-  CenterConfig,
-  LabelConfig,
-  PieArc,
-  PieChartConfig,
-  PieChartTheme,
-  PieLabelMode,
-  PieLabelPlacement,
-  PieSlice,
-  RingConfig,
-} from "./shared"
+export { PIE_STYLE_GROUPS, pieArcs, relaxLabels, resolvePieSlices, sliceTotal, sliceValue } from "./shared"
+export type { LabelConfig, PieArc, PieLabelMode, PieLabelPlacement, PieStyle, RingConfig } from "./shared"