@pixerate/editor 0.165.0 → 0.166.0

package/dist/chart/index.d.cts

@@ -2,6 +2,7 @@ export * from './types.cjs';
 export * from './spec.cjs';
 export * from './tree.cjs';
 export * from './links.cjs';
+export * from './race.cjs';
 export * from './scale.cjs';
 export * from './numfmt.cjs';
 export * from './color.cjs';

package/dist/chart/index.d.ts

@@ -2,6 +2,7 @@ export * from './types.js';
 export * from './spec.js';
 export * from './tree.js';
 export * from './links.js';
+export * from './race.js';
 export * from './scale.js';
 export * from './numfmt.js';
 export * from './color.js';

package/dist/chart/index.js

@@ -4,6 +4,7 @@ import {
   HEIGHT,
   LINK_INDEX,
   LINK_PROPS,
+  RACE_TIME,
   REFERENCE_BAND_PATCH,
   REFERENCE_BAND_PROPS,
   REFERENCE_INDEX,
@@ -16,7 +17,7 @@ import {
   TRENDLINE_PROPS,
   VALUE,
   WIDTH
-} from "../chunk-FEU2XVQH.js";
+} from "../chunk-5UNQDC3Q.js";
 import {
   CHART_OOXML_CONTENT_TYPE,
   CHART_OOXML_NS,
@@ -24,7 +25,7 @@ import {
   chartFormatToCode,
   chartFromOoxml,
   chartToOoxml
-} from "../chunk-CRFSQWKQ.js";
+} from "../chunk-XNU45TYA.js";
 import {
   CHART_COLOR_SCHEMES,
   CHART_LAYOUT_PRESETS,
@@ -46,7 +47,7 @@ import {
   monochromeChartPalette,
   sparklineToSvg,
   summarizeChart
-} from "../chunk-FRBRLKNQ.js";
+} from "../chunk-YUFTVNLX.js";
 import "../chunk-KGRZMHZB.js";
 import {
   CHART_DATE_STEPS,
@@ -59,6 +60,9 @@ import {
   chartHistogram,
   chartMovingAverage,
   chartQuantile,
+  chartRaceMoment,
+  chartRaceRanking,
+  chartRaceValueAt,
   chartScaleFromPixel,
   chartScaleToPixel,
   chartSerialToDate,
@@ -87,7 +91,7 @@ import {
   suggestChartReferences,
   summarizeChartSeries,
   trendNumberText
-} from "../chunk-V5GSY3NC.js";
+} from "../chunk-ITANXMZD.js";
 import {
   CHART_AXIS_KINDS,
   CHART_AXIS_SCALES,
@@ -181,7 +185,7 @@ import {
   shadeChartColor,
   simulateChartVision,
   uniqueChartSeriesId
-} from "../chunk-2ZRN43IN.js";
+} from "../chunk-FR432ROA.js";
 import "../chunk-O6OGNDND.js";
 import "../chunk-II2WIF5Z.js";
 import {
@@ -396,6 +400,7 @@ function recommendForShape(shape) {
     add("area", "Area", "Shows change over time with volume.");
     add("bar", "Column", "Compares each period.");
     if (shape.series > 1) add("area", "Stacked area", "Shows how the parts add up over time.", "stacked");
+    if (shape.series >= 5 && shape.points >= 3) add("barrace", "Bar race", "Many series over time: an animated ranking shows who leads when.");
     return out;
   }
   if (shape.series === 1) {
@@ -430,6 +435,7 @@ function recommendForShape(shape) {
     add("bar", "Stacked column", "Shows how the series add up.", "stacked");
     add("line", "Line", "Shows the series in order.");
     if (shape.points >= 3 && shape.series <= 6) add("radar", "Radar", "Compares several measures across the series.");
+    if (shape.nonNegative && shape.series >= 5 && shape.points >= 3) add("barrace", "Bar race", "Many series across ordered categories (such as years): an animated ranking shows who leads when.");
     if (shape.nonNegative && shape.series >= 3 && shape.series <= 7) add("likert", "Likert", "Survey answers per question (columns from most negative to most positive): shows agreement against disagreement.");
   }
   return out;
@@ -475,6 +481,12 @@ function createChartCommands(controller, options = {}) {
     if (index < 0 || index >= categories.length || !Number.isInteger(index)) fail(`There is no category ${JSON.stringify(ref)}; expected an index from 0 to ${categories.length - 1} or one of the labels.`);
     return index;
   };
+  const raceFrame = (time) => {
+    const cats = controller.getSpec().categories;
+    const frame = typeof time === "number" ? time : cats.indexOf(time);
+    if (!(Number.isFinite(frame) && frame >= 0 && frame <= cats.length - 1)) fail(`There is no time point ${JSON.stringify(time)}; expected an index from 0 to ${Math.max(0, cats.length - 1)} or a category label.`);
+    return frame;
+  };
   const object = (properties, required) => ({ type: "object", properties, ...required ? { required } : {}, additionalProperties: false });
   return [
     {
@@ -887,6 +899,57 @@ function createChartCommands(controller, options = {}) {
         return { links: controller.getSpec().links };
       }
     },
+    {
+      ...base,
+      id: `${prefix}raceRanking`,
+      label: "Bar Race Ranking",
+      readOnly: true,
+      keywords: ["chart", "race", "ranking", "leader", "time"],
+      description: "Returns the top names of a bar race at a moment (default: the one shown).",
+      params: object({ time: RACE_TIME }),
+      run: (_ctx, params = {}) => {
+        const spec = controller.getSpec();
+        const frame = params?.time !== void 0 ? raceFrame(params.time) : controller.getState().raceFrame ?? spec.categories.length - 1;
+        return { frame, ranking: chartRaceRanking(spec, frame).slice(0, spec.raceTopN).map((e) => ({ rank: e.rank + 1, series: e.seriesId, name: e.name, value: e.value })) };
+      }
+    },
+    {
+      ...base,
+      id: `${prefix}setRaceFrame`,
+      label: "Show Bar Race Moment\u2026",
+      keywords: ["chart", "race", "frame", "time", "scrub"],
+      description: "Shows the bar race at a time point (null for the last) and stops playback. View state, not an undo step.",
+      params: object({ time: { ...RACE_TIME, type: ["string", "number", "null"], description: `${RACE_TIME.description} null shows the last time point.` } }, ["time"]),
+      run: (_ctx, params) => {
+        const frame = params.time === null ? null : raceFrame(params.time);
+        check(controller.setRaceFrame(frame));
+        return { frame };
+      }
+    },
+    {
+      ...base,
+      id: `${prefix}playRace`,
+      label: "Play Bar Race",
+      keywords: ["chart", "race", "play", "animate"],
+      description: "Plays the bar race from the moment shown, one time point every msPerStep ms.",
+      params: object({ msPerStep: { type: "number", minimum: 50, maximum: 1e4, description: "Milliseconds per time point (default 1000)." } }),
+      run: (_ctx, params = {}) => {
+        check(controller.playRace({ msPerStep: params?.msPerStep }));
+        return { playing: true };
+      }
+    },
+    {
+      ...base,
+      id: `${prefix}pauseRace`,
+      label: "Pause Bar Race",
+      keywords: ["chart", "race", "pause", "stop"],
+      description: "Pauses bar race playback where it is.",
+      enabled: () => controller.getState().racePlaying || "The race is not playing",
+      run: () => {
+        controller.pauseRace();
+        return { frame: controller.getState().raceFrame };
+      }
+    },
     {
       ...base,
       id: `${prefix}applyPreset`,
@@ -1484,6 +1547,10 @@ function planChartToolPlayback(tool, args) {
       return click(control("series.callout"));
     case "highlight_chart":
       return click(control("highlight"));
+    case "set_chart_race_frame":
+      return click(control("raceFrame"));
+    case "play_chart_race":
+      return click({ kind: "action", id: "race-play" });
     case "render_chart":
       return [{ type: "target", ref: { kind: "action", id: "download-png" } }];
     case "undo_chart":
@@ -1548,6 +1615,22 @@ function createChartToolProvider(controller, options = {}) {
     const depth = chartTreeDepth(spec().tree);
     return [[...Array.from({ length: depth }, (_, k) => k === 0 ? "Group" : k === depth - 1 ? "Item" : `Level ${k + 1}`), "Value"], ...rows.map((r) => [...r.path, ...Array(depth - r.path.length).fill(""), r.value])];
   };
+  const raceFrameOf = (time) => {
+    const cats = spec().categories;
+    const frame = typeof time === "number" ? time : cats.indexOf(time);
+    if (!(Number.isFinite(frame) && frame >= 0 && frame <= cats.length - 1))
+      fail2(`There is no time point ${JSON.stringify(time)}; expected an index from 0 to ${Math.max(0, cats.length - 1)} or one of ${cats.slice(0, 20).map((c) => JSON.stringify(c)).join(", ")}.`);
+    return frame;
+  };
+  const raceAt = (frame) => {
+    const s = spec();
+    const at = frame ?? s.categories.length - 1;
+    return {
+      frame: at,
+      time: s.categories[Math.round(at)] ?? null,
+      ranking: chartRaceRanking(s, at).slice(0, s.raceTopN).map((e) => ({ rank: e.rank + 1, series: e.seriesId, name: e.name, value: e.value }))
+    };
+  };
   const linksSummary = () => ({ links: spec().links, nodes: spec().sankeyNodes.map((name, i) => ({ name, value: chartSankeyNodeValues(spec().links, spec().sankeyNodes)[i] })) });
   const treeSummary = () => ({ tree: spec().tree, groups: spec().tree.map((n) => ({ name: n.name, total: chartTreeTotal(n) })), depth: chartTreeDepth(spec().tree) });
   const Parser = () => options.DOMParser ?? globalThis.DOMParser;
@@ -1579,14 +1662,16 @@ function createChartToolProvider(controller, options = {}) {
       properties: {
         width: WIDTH,
         height: HEIGHT,
-        format: { type: "string", enum: ["svg", "png"], description: "svg (default): the SVG document as text. png: an image to look at (only when the host can rasterize; costs image tokens)." }
+        format: { type: "string", enum: ["svg", "png"], description: "svg (default): the SVG document as text. png: an image to look at (only when the host can rasterize; costs image tokens)." },
+        time: { ...RACE_TIME, description: `Bar race only: the moment to draw (default: the one shown). ${RACE_TIME.description}` }
       },
       additionalProperties: false
     },
     annotations: { title: "Render the chart", ...READ },
-    handler: async ({ width = size.width, height = size.height, format = "svg" }) => {
+    handler: async ({ width = size.width, height = size.height, format = "svg", time }) => {
       const json = controller.toJSON();
-      const scene = layoutChart(json, { width, height, selection: null });
+      const raceFrame = time !== void 0 ? raceFrameOf(time) : controller.getState().raceFrame;
+      const scene = layoutChart(json, { width, height, selection: null, raceFrame });
       const svg = chartSceneToSvg(scene, { ariaLabel: json.title || void 0, description: describeChart(json) });
       const warnings = scene.warnings;
       if (format === "png") {
@@ -1659,6 +1744,14 @@ function createChartToolProvider(controller, options = {}) {
       return { trendline: line, coefficients: fit.coefficients, r2: fit.r2, equation: fit.equation, points: fit.points };
     }
   };
+  const raceRanking = {
+    name: "get_chart_race_ranking",
+    title: "Read a bar race ranking",
+    description: "Returns who leads a bar race at a moment without changing what is shown: the top raceTopN names with their rank, series id and value (eased between time points). Defaults to the moment shown. Works for any chart, reading categories as time points and series as names.",
+    inputSchema: { type: "object", properties: { time: RACE_TIME }, additionalProperties: false },
+    annotations: { title: "Read a bar race ranking", ...READ },
+    handler: ({ time }) => raceAt(time !== void 0 ? raceFrameOf(time) : controller.getState().raceFrame)
+  };
   const listPresets = {
     name: "list_chart_presets",
     title: "List chart presets",
@@ -2150,6 +2243,30 @@ function createChartToolProvider(controller, options = {}) {
       return { links: spec().links };
     }
   };
+  const setRaceFrame = {
+    name: "set_chart_race_frame",
+    title: "Show a bar race moment",
+    description: "Shows the bar race at a time point (or between two), and stops playback. This is view state like the selection: it is not an undo step and is not saved in the chart. Returns the moment and the ranking shown.",
+    inputSchema: { type: "object", properties: { time: { ...RACE_TIME, type: ["string", "number", "null"], description: `${RACE_TIME.description} null shows the last time point.` } }, required: ["time"], additionalProperties: false },
+    annotations: { title: "Show a bar race moment", ...WRITE_IDEMPOTENT },
+    handler: ({ time }) => {
+      const frame = time === null ? null : raceFrameOf(time);
+      resolve(controller.setRaceFrame(frame));
+      return raceAt(frame);
+    }
+  };
+  const playRace = {
+    name: "play_chart_race",
+    title: "Play the bar race",
+    description: "Starts playing the bar race for the user from the moment shown (from the start when it is at the end), one time point every msPerStep ms, and returns at once. set_chart_race_frame stops it. Nothing in the chart changes.",
+    inputSchema: { type: "object", properties: { msPerStep: { type: "number", minimum: 50, maximum: 1e4, description: "Milliseconds per time point (default 1000)." } }, additionalProperties: false },
+    annotations: { title: "Play the bar race", ...WRITE },
+    handler: ({ msPerStep }) => {
+      resolve(controller.playRace({ msPerStep }));
+      const n = spec().categories.length;
+      return { playing: true, from: controller.getState().raceFrame ?? 0, durationMs: Math.round((n - 1 - (controller.getState().raceFrame ?? 0)) * (msPerStep ?? 1e3)) };
+    }
+  };
   const applyPreset = {
     name: "apply_chart_preset",
     title: "Apply a chart style",
@@ -2315,7 +2432,7 @@ function createChartToolProvider(controller, options = {}) {
       return { redone, ...redone ? { label } : {} };
     }
   };
-  const reads = [getChart, renderChart, checkColors, recommend, getTrendline, listPresets, exportMermaid, exportOoxml];
+  const reads = [getChart, renderChart, checkColors, recommend, getTrendline, raceRanking, listPresets, exportMermaid, exportOoxml];
   const writes = [
     updateChart,
     setData,
@@ -2347,6 +2464,8 @@ function createChartToolProvider(controller, options = {}) {
     addLink,
     updateLink,
     removeLink,
+    setRaceFrame,
+    playRace,
     applyPreset,
     transpose,
     select,
@@ -2359,7 +2478,7 @@ function createChartToolProvider(controller, options = {}) {
     id: options.id ?? "chart",
     namespace: options.namespace,
     title: "Chart editor",
-    description: "One chart: its spec, data and values, series and categories, trendlines, reference lines and bands, callouts, highlight, grouped data, flows and presets, CSV, Mermaid and OOXML import, rendering and colour checks.",
+    description: "One chart: its spec, data and values, series and categories, trendlines, reference lines and bands, callouts, highlight, grouped data, flows, bar race playback and presets, CSV, Mermaid and OOXML import, rendering and colour checks.",
     skill: "pixerate-chart",
     tools: () => {
       if (readOnlyReason()) return reads;
@@ -3112,6 +3231,9 @@ export {
   chartPointRef,
   chartPresetPatch,
   chartQuantile,
+  chartRaceMoment,
+  chartRaceRanking,
+  chartRaceValueAt,
   chartRasterSize,
   chartRgbToHex,
   chartRgbToOklab,

package/dist/chart/layout-families.d.cts

@@ -45,3 +45,10 @@ export declare function layoutSunburst(ctx: LayoutCtx, area: ChartRect, series:
  * in the order of the nodes at their other end, so they cross as little as the order allows.
  */
 export declare function layoutSankey(ctx: LayoutCtx, area: ChartRect, series: ChartSeries | undefined): FamilyResult;
+/**
+ * Bar race: the top `raceTopN` names at one moment (`frame`, a fractional category index;
+ * default the last time point) as ranked horizontal bars. Values ease between time points and
+ * places slide from one ranking to the next, so drawing frame after frame (or blending scenes,
+ * which match bars by series) animates the race. The time point is written large in a corner.
+ */
+export declare function layoutBarRace(ctx: LayoutCtx, area: ChartRect, frame: number | null | undefined): FamilyResult;

package/dist/chart/layout-families.d.ts

@@ -45,3 +45,10 @@ export declare function layoutSunburst(ctx: LayoutCtx, area: ChartRect, series:
  * in the order of the nodes at their other end, so they cross as little as the order allows.
  */
 export declare function layoutSankey(ctx: LayoutCtx, area: ChartRect, series: ChartSeries | undefined): FamilyResult;
+/**
+ * Bar race: the top `raceTopN` names at one moment (`frame`, a fractional category index;
+ * default the last time point) as ranked horizontal bars. Values ease between time points and
+ * places slide from one ranking to the next, so drawing frame after frame (or blending scenes,
+ * which match bars by series) animates the race. The time point is written large in a corner.
+ */
+export declare function layoutBarRace(ctx: LayoutCtx, area: ChartRect, frame: number | null | undefined): FamilyResult;

package/dist/chart/layout-shared.d.cts

@@ -34,6 +34,11 @@ export interface ChartLayoutOptions {
         seriesId: string;
         index: number;
     } | null;
+    /**
+     * Bar race: the moment to draw, as a category index that may be fractional (2.5 is halfway
+     * between the third and fourth time points). Default: the last time point.
+     */
+    raceFrame?: number | null;
 }
 /** A DOM-free text width estimate (average glyph ≈ 0.56 em, bold ≈ 0.6 em). */
 export declare const estimateChartTextWidth: ChartTextMeasure;

package/dist/chart/layout-shared.d.ts

@@ -34,6 +34,11 @@ export interface ChartLayoutOptions {
         seriesId: string;
         index: number;
     } | null;
+    /**
+     * Bar race: the moment to draw, as a category index that may be fractional (2.5 is halfway
+     * between the third and fourth time points). Default: the last time point.
+     */
+    raceFrame?: number | null;
 }
 /** A DOM-free text width estimate (average glyph ≈ 0.56 em, bold ≈ 0.6 em). */
 export declare const estimateChartTextWidth: ChartTextMeasure;

package/dist/chart/race.d.cts

@@ -0,0 +1,26 @@
+import type { ChartSeries, ChartSpec } from './types.cjs';
+/** A series' value at time point `index`: its own, else the last value before it (0 before the first). */
+export declare function chartRaceValueAt(series: Pick<ChartSeries, 'values'>, index: number): number;
+/** The moment `frame` stands for: the time points either side and how far between them (0–1). */
+export declare function chartRaceMoment(count: number, frame: number | null | undefined): {
+    from: number;
+    to: number;
+    t: number;
+    at: number;
+};
+export interface ChartRaceEntry {
+    seriesId: string;
+    name: string;
+    /** The value at the moment (between time points, eased from one to the next). */
+    value: number;
+    /** 0-based place at the moment, fractional while two names swap. */
+    position: number;
+    /** 0-based place at the nearest time point. */
+    rank: number;
+}
+/**
+ * Every visible series at a moment, best first: its value between the two time points and its
+ * position, which slides from its rank at one time point to its rank at the next so bars swap
+ * smoothly. Ties keep the series order.
+ */
+export declare function chartRaceRanking(spec: Pick<ChartSpec, 'series' | 'categories'>, frame: number | null | undefined): ChartRaceEntry[];

package/dist/chart/race.d.ts

@@ -0,0 +1,26 @@
+import type { ChartSeries, ChartSpec } from './types.js';
+/** A series' value at time point `index`: its own, else the last value before it (0 before the first). */
+export declare function chartRaceValueAt(series: Pick<ChartSeries, 'values'>, index: number): number;
+/** The moment `frame` stands for: the time points either side and how far between them (0–1). */
+export declare function chartRaceMoment(count: number, frame: number | null | undefined): {
+    from: number;
+    to: number;
+    t: number;
+    at: number;
+};
+export interface ChartRaceEntry {
+    seriesId: string;
+    name: string;
+    /** The value at the moment (between time points, eased from one to the next). */
+    value: number;
+    /** 0-based place at the moment, fractional while two names swap. */
+    position: number;
+    /** 0-based place at the nearest time point. */
+    rank: number;
+}
+/**
+ * Every visible series at a moment, best first: its value between the two time points and its
+ * position, which slides from its rank at one time point to its rank at the next so bars swap
+ * smoothly. Ties keep the series order.
+ */
+export declare function chartRaceRanking(spec: Pick<ChartSpec, 'series' | 'categories'>, frame: number | null | undefined): ChartRaceEntry[];

package/dist/chart/schemas.d.cts

@@ -22,6 +22,8 @@ export declare const TREE_DEFS: {
 export declare const TREE_PATH: JsonSchema;
 /** One Sankey flow's fields; source, target and value are required when adding. */
 export declare const LINK_PROPS: Record<string, JsonSchema>;
+/** A moment of a bar race: a time point by label, or a category index (fractional between time points). */
+export declare const RACE_TIME: JsonSchema;
 export declare const LINK_INDEX: JsonSchema;
 export declare const ERROR_BARS: (what: string) => JsonSchema;
 export declare const SERIES_PROPS: Record<string, JsonSchema>;

package/dist/chart/schemas.d.ts

@@ -22,6 +22,8 @@ export declare const TREE_DEFS: {
 export declare const TREE_PATH: JsonSchema;
 /** One Sankey flow's fields; source, target and value are required when adding. */
 export declare const LINK_PROPS: Record<string, JsonSchema>;
+/** A moment of a bar race: a time point by label, or a category index (fractional between time points). */
+export declare const RACE_TIME: JsonSchema;
 export declare const LINK_INDEX: JsonSchema;
 export declare const ERROR_BARS: (what: string) => JsonSchema;
 export declare const SERIES_PROPS: Record<string, JsonSchema>;

package/dist/chart/spec.d.cts

@@ -19,7 +19,7 @@ export declare const CHART_NUMBER_STYLES: readonly NonNullable<ChartNumberFormat
 /** Labels for pickers, shared by the React and Svelte components. */
 export declare const CHART_TYPE_LABELS: Readonly<Record<ChartType, string>>;
 /** How a chart type is laid out. */
-export type ChartFamily = 'cartesian' | 'xy' | 'pie' | 'radar' | 'waterfall' | 'histogram' | 'box' | 'funnel' | 'treemap' | 'slope' | 'likert' | 'parliament' | 'sunburst' | 'sankey';
+export type ChartFamily = 'cartesian' | 'xy' | 'pie' | 'radar' | 'waterfall' | 'histogram' | 'box' | 'funnel' | 'treemap' | 'slope' | 'likert' | 'parliament' | 'sunburst' | 'sankey' | 'barrace';
 /** A colour-blind-friendly categorical palette (Okabe–Ito order, tuned for light and dark backgrounds). */
 export declare const DEFAULT_CHART_PALETTE: readonly string[];
 export declare const DEFAULT_CHART_THEME: ChartTheme;

package/dist/chart/spec.d.ts

@@ -19,7 +19,7 @@ export declare const CHART_NUMBER_STYLES: readonly NonNullable<ChartNumberFormat
 /** Labels for pickers, shared by the React and Svelte components. */
 export declare const CHART_TYPE_LABELS: Readonly<Record<ChartType, string>>;
 /** How a chart type is laid out. */
-export type ChartFamily = 'cartesian' | 'xy' | 'pie' | 'radar' | 'waterfall' | 'histogram' | 'box' | 'funnel' | 'treemap' | 'slope' | 'likert' | 'parliament' | 'sunburst' | 'sankey';
+export type ChartFamily = 'cartesian' | 'xy' | 'pie' | 'radar' | 'waterfall' | 'histogram' | 'box' | 'funnel' | 'treemap' | 'slope' | 'likert' | 'parliament' | 'sunburst' | 'sankey' | 'barrace';
 /** A colour-blind-friendly categorical palette (Okabe–Ito order, tuned for light and dark backgrounds). */
 export declare const DEFAULT_CHART_PALETTE: readonly string[];
 export declare const DEFAULT_CHART_THEME: ChartTheme;

package/dist/chart/types.d.cts

@@ -17,8 +17,10 @@
  * - `sunburst` draws `tree` as rings from the centre out (or, without a tree, the first series
  *   as one ring); a `treemap` with a `tree` nests each group's rectangles inside it.
  * - `sankey` draws `links` as flows between columns of nodes.
+ * - `barrace` reads each category as a time point and each series as a name, and draws the
+ *   top `raceTopN` names at one moment as ranked horizontal bars (an animated ranking).
  */
-export type ChartType = 'bar' | 'line' | 'area' | 'scatter' | 'bubble' | 'pie' | 'donut' | 'radar' | 'waterfall' | 'histogram' | 'box' | 'funnel' | 'treemap' | 'slope' | 'likert' | 'parliament' | 'sunburst' | 'sankey';
+export type ChartType = 'bar' | 'line' | 'area' | 'scatter' | 'bubble' | 'pie' | 'donut' | 'radar' | 'waterfall' | 'histogram' | 'box' | 'funnel' | 'treemap' | 'slope' | 'likert' | 'parliament' | 'sunburst' | 'sankey' | 'barrace';
 /** How a series is drawn in a cartesian chart. */
 export type ChartSeriesType = 'bar' | 'line' | 'area' | 'scatter';
 /** One data value; `null` is a gap (missing value). */
@@ -299,6 +301,8 @@ export interface ChartSpec {
     sankeyNodes: string[];
     /** Sankey: what colours each flow. */
     sankeyLinkColor: ChartSankeyLinkColor;
+    /** Bar race: how many bars each moment shows, 1–30. */
+    raceTopN: number;
 }
 /** What a click selects. */
 export type ChartSelection = {
@@ -354,7 +358,7 @@ export interface ChartRect {
     height: number;
 }
 /** What a mark is, for styling and tests. */
-export type ChartMarkRole = 'background' | 'title' | 'subtitle' | 'grid' | 'axis' | 'tick' | 'tick-label' | 'axis-title' | 'bar' | 'line' | 'area' | 'point' | 'slice' | 'cell' | 'box' | 'whisker' | 'outlier' | 'connector' | 'trendline' | 'trendline-label' | 'error-bar' | 'data-label' | 'legend-swatch' | 'legend-label' | 'drag-readout' | 'reference-line' | 'reference-band' | 'reference-label' | 'callout' | 'node' | 'link' | 'note' | 'selection' | 'empty';
+export type ChartMarkRole = 'background' | 'title' | 'subtitle' | 'grid' | 'axis' | 'tick' | 'tick-label' | 'axis-title' | 'bar' | 'line' | 'area' | 'point' | 'slice' | 'cell' | 'box' | 'whisker' | 'outlier' | 'connector' | 'trendline' | 'trendline-label' | 'error-bar' | 'data-label' | 'legend-swatch' | 'legend-label' | 'drag-readout' | 'reference-line' | 'reference-band' | 'reference-label' | 'callout' | 'node' | 'race-time' | 'link' | 'note' | 'selection' | 'empty';
 interface ChartMarkBase {
     /** Unique within the scene (a stable key for frameworks). */
     key: string;

package/dist/chart/types.d.ts

@@ -17,8 +17,10 @@
  * - `sunburst` draws `tree` as rings from the centre out (or, without a tree, the first series
  *   as one ring); a `treemap` with a `tree` nests each group's rectangles inside it.
  * - `sankey` draws `links` as flows between columns of nodes.
+ * - `barrace` reads each category as a time point and each series as a name, and draws the
+ *   top `raceTopN` names at one moment as ranked horizontal bars (an animated ranking).
  */
-export type ChartType = 'bar' | 'line' | 'area' | 'scatter' | 'bubble' | 'pie' | 'donut' | 'radar' | 'waterfall' | 'histogram' | 'box' | 'funnel' | 'treemap' | 'slope' | 'likert' | 'parliament' | 'sunburst' | 'sankey';
+export type ChartType = 'bar' | 'line' | 'area' | 'scatter' | 'bubble' | 'pie' | 'donut' | 'radar' | 'waterfall' | 'histogram' | 'box' | 'funnel' | 'treemap' | 'slope' | 'likert' | 'parliament' | 'sunburst' | 'sankey' | 'barrace';
 /** How a series is drawn in a cartesian chart. */
 export type ChartSeriesType = 'bar' | 'line' | 'area' | 'scatter';
 /** One data value; `null` is a gap (missing value). */
@@ -299,6 +301,8 @@ export interface ChartSpec {
     sankeyNodes: string[];
     /** Sankey: what colours each flow. */
     sankeyLinkColor: ChartSankeyLinkColor;
+    /** Bar race: how many bars each moment shows, 1–30. */
+    raceTopN: number;
 }
 /** What a click selects. */
 export type ChartSelection = {
@@ -354,7 +358,7 @@ export interface ChartRect {
     height: number;
 }
 /** What a mark is, for styling and tests. */
-export type ChartMarkRole = 'background' | 'title' | 'subtitle' | 'grid' | 'axis' | 'tick' | 'tick-label' | 'axis-title' | 'bar' | 'line' | 'area' | 'point' | 'slice' | 'cell' | 'box' | 'whisker' | 'outlier' | 'connector' | 'trendline' | 'trendline-label' | 'error-bar' | 'data-label' | 'legend-swatch' | 'legend-label' | 'drag-readout' | 'reference-line' | 'reference-band' | 'reference-label' | 'callout' | 'node' | 'link' | 'note' | 'selection' | 'empty';
+export type ChartMarkRole = 'background' | 'title' | 'subtitle' | 'grid' | 'axis' | 'tick' | 'tick-label' | 'axis-title' | 'bar' | 'line' | 'area' | 'point' | 'slice' | 'cell' | 'box' | 'whisker' | 'outlier' | 'connector' | 'trendline' | 'trendline-label' | 'error-bar' | 'data-label' | 'legend-swatch' | 'legend-label' | 'drag-readout' | 'reference-line' | 'reference-band' | 'reference-label' | 'callout' | 'node' | 'race-time' | 'link' | 'note' | 'selection' | 'empty';
 interface ChartMarkBase {
     /** Unique within the scene (a stable key for frameworks). */
     key: string;

package/dist/{chunk-FEU2XVQH.js → chunk-5UNQDC3Q.js}

@@ -18,7 +18,7 @@ import {
   CHART_STACKINGS,
   CHART_TRENDLINE_TYPES,
   CHART_TYPES
-} from "./chunk-2ZRN43IN.js";
+} from "./chunk-FR432ROA.js";
 
 // src/chart/schemas.ts
 var VALUE = { type: ["number", "string", "null"], description: 'A number, numeric text ("1,200", "12%", "$40", "(3)") or null for a gap.' };
@@ -119,6 +119,7 @@ var LINK_PROPS = {
   value: { type: "number", exclusiveMinimum: 0, description: "How much flows, above 0 (its width)." },
   color: { type: "string", description: "CSS colour (default: by sankeyLinkColor)." }
 };
+var RACE_TIME = { type: ["string", "number"], description: 'Time point label (a category, e.g. "2023") or index from 0; an index may be fractional, 2.5 being halfway between the third and fourth time points.' };
 var LINK_INDEX = { type: "integer", minimum: 0, description: "Flow index (0 = first), as get_chart lists them in spec.links." };
 var ERROR_BARS = (what) => ({
   type: ["object", "null"],
@@ -157,7 +158,7 @@ var SERIES_PROPS = {
   xErrorBars: ERROR_BARS("Error bars along the x axis (scatter and bubble charts with numeric x values; amounts in x units).")
 };
 var CHART_UPDATE_PROPERTIES = {
-  type: { type: "string", enum: [...CHART_TYPES], description: "Chart type. slope joins each category from the first series (before) to the second (after); likert reads each category as a question and the series as answers from most negative to most positive; parliament draws the first series as seats; sunburst draws the grouped data (set_chart_tree) as rings, and a treemap with grouped data nests its groups; sankey draws the flows (set_chart_links)." },
+  type: { type: "string", enum: [...CHART_TYPES], description: "Chart type. slope joins each category from the first series (before) to the second (after); likert reads each category as a question and the series as answers from most negative to most positive; parliament draws the first series as seats; sunburst draws the grouped data (set_chart_tree) as rings, and a treemap with grouped data nests its groups; sankey draws the flows (set_chart_links); barrace reads categories as time points and series as names, and animates their ranking." },
   title: { type: "string", description: 'Title ("" for none).' },
   subtitle: { type: "string", description: 'Subtitle ("" for none).' },
   xAxis: AXIS("Category axis (or numeric x axis of scatter / bubble charts)."),
@@ -195,6 +196,7 @@ var CHART_UPDATE_PROPERTIES = {
   parliamentLabel: { type: "string", description: 'Parliament: caption under the seat total ("" writes "seats").' },
   sunburstLabel: { type: "string", description: 'Sunburst: caption under the total in the centre ("" for none).' },
   sankeyLinkColor: { type: "string", enum: [...CHART_SANKEY_LINK_COLORS], description: "Sankey: colour each flow by its source node (default), its target node, or grey." },
+  raceTopN: { type: "integer", minimum: 1, maximum: 30, description: "Bar race: how many bars each moment shows (default 10)." },
   sankeyNodes: { type: "array", items: { type: "string" }, description: "Sankey: node names in the order to stack them within their columns (reorder to untangle crossing flows); nodes left out follow in the order the flows name them." }
 };
 
@@ -213,6 +215,7 @@ export {
   TREE_DEFS,
   TREE_PATH,
   LINK_PROPS,
+  RACE_TIME,
   LINK_INDEX,
   SERIES_PROPS,
   CHART_UPDATE_PROPERTIES