@pixerate/editor 0.165.0 → 0.167.0

package/dist/chart/index.d.cts

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

package/dist/chart/index.d.ts

@@ -2,6 +2,8 @@ export * from './types.js';
 export * from './spec.js';
 export * from './tree.js';
 export * from './links.js';
+export * from './race.js';
+export * from './maps.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-34UCPHYO.js";
 import {
   CHART_OOXML_CONTENT_TYPE,
   CHART_OOXML_NS,
@@ -24,7 +25,7 @@ import {
   chartFormatToCode,
   chartFromOoxml,
   chartToOoxml
-} from "../chunk-CRFSQWKQ.js";
+} from "../chunk-OLCHKGGO.js";
 import {
   CHART_COLOR_SCHEMES,
   CHART_LAYOUT_PRESETS,
@@ -46,7 +47,7 @@ import {
   monochromeChartPalette,
   sparklineToSvg,
   summarizeChart
-} from "../chunk-FRBRLKNQ.js";
+} from "../chunk-N3ACT6VJ.js";
 import "../chunk-KGRZMHZB.js";
 import {
   CHART_DATE_STEPS,
@@ -57,8 +58,14 @@ import {
   chartDateLabels,
   chartDateToSerial,
   chartHistogram,
+  chartMapBreaks,
+  chartMapClass,
+  chartMapRamp,
   chartMovingAverage,
   chartQuantile,
+  chartRaceMoment,
+  chartRaceRanking,
+  chartRaceValueAt,
   chartScaleFromPixel,
   chartScaleToPixel,
   chartSerialToDate,
@@ -75,19 +82,23 @@ import {
   formatChartDate,
   formatChartNumber,
   formatChartValueWithCode,
+  getChartMap,
   layoutChart,
   linearMap,
+  listChartMaps,
+  matchChartMapRegions,
   niceLogScale,
   niceScale,
   niceStep,
   parseChartDate,
+  registerChartMap,
   sameChartSelection,
   snapChartValue,
   stepDecimals,
   suggestChartReferences,
   summarizeChartSeries,
   trendNumberText
-} from "../chunk-V5GSY3NC.js";
+} from "../chunk-M52UCHVZ.js";
 import {
   CHART_AXIS_KINDS,
   CHART_AXIS_SCALES,
@@ -181,7 +192,7 @@ import {
   shadeChartColor,
   simulateChartVision,
   uniqueChartSeriesId
-} from "../chunk-2ZRN43IN.js";
+} from "../chunk-ORZF4JOO.js";
 import "../chunk-O6OGNDND.js";
 import "../chunk-II2WIF5Z.js";
 import {
@@ -396,6 +407,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 +442,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 +488,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 +906,73 @@ function createChartCommands(controller, options = {}) {
         return { links: controller.getSpec().links };
       }
     },
+    {
+      ...base,
+      id: `${prefix}mapRegions`,
+      label: "Map Regions",
+      readOnly: true,
+      keywords: ["chart", "map", "choropleth", "regions", "countries", "codes"],
+      description: "Lists the regions of the chart's map (or another registered map) and which categories match none.",
+      params: object({ map: { type: "string", description: "Map id (default: the chart's map)." } }),
+      run: (_ctx, params = {}) => {
+        const id = params?.map ?? controller.getSpec().map;
+        const geometry = getChartMap(id);
+        if (!geometry) fail(`There is no map "${id}"; register it with registerChartMap.`);
+        const matches = matchChartMapRegions(geometry, controller.getSpec().categories);
+        return { regions: geometry.regions.map((r) => ({ id: r.id, name: r.name })), unmatched: controller.getSpec().categories.filter((_, i) => !matches[i]) };
+      }
+    },
+    {
+      ...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 +1570,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 +1638,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 +1685,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 +1767,35 @@ 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 mapRegions = {
+    name: "list_chart_map_regions",
+    title: "List map regions",
+    description: "Lists the maps a choropleth can draw and the regions of one (default: the chart's map), each with the id and name that categories may use, and how the chart's categories match them: matched (category \u2192 region id) and unmatched. Use it to pick category labels before set_chart_data, and to fix unmatched ones.",
+    inputSchema: { type: "object", properties: { map: { type: "string", description: "Map id (default: the chart's map)." } }, additionalProperties: false },
+    annotations: { title: "List map regions", ...READ },
+    handler: ({ map }) => {
+      const id = map ?? spec().map;
+      const maps = listChartMaps().map((m) => ({ id: m.id, name: m.name, regions: m.regions.length }));
+      const geometry = getChartMap(id);
+      if (!geometry) fail2(maps.length ? `There is no map "${id}"; the host has ${maps.map((m) => `"${m.id}"`).join(", ")}.` : `There is no map "${id}": the host has not registered any maps (EUROPE_CHART_MAP in @pixerate/editor/chart-maps).`);
+      const matches = matchChartMapRegions(geometry, spec().categories);
+      return {
+        maps,
+        map: id,
+        regions: geometry.regions.map((r) => ({ id: r.id, name: r.name })),
+        matched: spec().categories.flatMap((c, i) => matches[i] ? [{ category: c, region: matches[i].id }] : []),
+        unmatched: spec().categories.filter((_, i) => !matches[i])
+      };
+    }
+  };
   const listPresets = {
     name: "list_chart_presets",
     title: "List chart presets",
@@ -2150,6 +2287,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 +2476,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, mapRegions, listPresets, exportMermaid, exportOoxml];
   const writes = [
     updateChart,
     setData,
@@ -2347,6 +2508,8 @@ function createChartToolProvider(controller, options = {}) {
     addLink,
     updateLink,
     removeLink,
+    setRaceFrame,
+    playRace,
     applyPreset,
     transpose,
     select,
@@ -2359,7 +2522,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;
@@ -3105,6 +3268,9 @@ export {
   chartLikertColor,
   chartLinksFromTable,
   chartLuminance,
+  chartMapBreaks,
+  chartMapClass,
+  chartMapRamp,
   chartMermaidFamily,
   chartMovingAverage,
   chartPointAnchor,
@@ -3112,6 +3278,9 @@ export {
   chartPointRef,
   chartPresetPatch,
   chartQuantile,
+  chartRaceMoment,
+  chartRaceRanking,
+  chartRaceValueAt,
   chartRasterSize,
   chartRgbToHex,
   chartRgbToOklab,
@@ -3184,13 +3353,16 @@ export {
   formatChartDate,
   formatChartNumber,
   formatChartValueWithCode,
+  getChartMap,
   handleChartKey,
   isCartesianChart,
   isXyChart,
   layoutChart,
   layoutSparkline,
   linearMap,
+  listChartMaps,
   locateChartPoint,
+  matchChartMapRegions,
   monochromeChartPalette,
   niceLogScale,
   niceScale,
@@ -3215,6 +3387,7 @@ export {
   realChartClock,
   recommendChartTypes,
   recommendForShape,
+  registerChartMap,
   removeChartTreeRow,
   resolveChartSvgPaints,
   sameChartSelection,

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

@@ -45,3 +45,18 @@ 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;
+/**
+ * Choropleth: the regions of a registered map (`spec.map`) shaded by the first series, one class
+ * per `mapSteps` (or `mapThresholds`), light to dark. Each category names a region by id or name;
+ * regions without data are grey and neighbouring land is drawn behind. Regions too small to see
+ * get a marker at their centre. The class legend runs along the bottom. The map must be
+ * registered and match a category (`layoutChart` draws bars otherwise).
+ */
+export declare function layoutChoropleth(ctx: LayoutCtx, area: ChartRect, series: ChartSeries): FamilyResult;

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

@@ -45,3 +45,18 @@ 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;
+/**
+ * Choropleth: the regions of a registered map (`spec.map`) shaded by the first series, one class
+ * per `mapSteps` (or `mapThresholds`), light to dark. Each category names a region by id or name;
+ * regions without data are grey and neighbouring land is drawn behind. Regions too small to see
+ * get a marker at their centre. The class legend runs along the bottom. The map must be
+ * registered and match a category (`layoutChart` draws bars otherwise).
+ */
+export declare function layoutChoropleth(ctx: LayoutCtx, area: ChartRect, series: ChartSeries): 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/maps.d.cts

@@ -0,0 +1,43 @@
+/** One region of a map: an id (ISO 3166-1 alpha-3 for countries), a name and its outline. */
+export interface ChartMapRegion {
+    id: string;
+    name: string;
+    /** SVG path data in the map's box (absolute M / L / Z commands). */
+    d: string;
+    /** Where a label or a marker goes, in the map's box. */
+    center: [number, number];
+    /** Area in square box units (0 for a region too small to outline, drawn as a marker). */
+    area: number;
+}
+export interface ChartMapGeometry {
+    /** What `spec.map` names, e.g. `europe`. */
+    id: string;
+    name: string;
+    width: number;
+    height: number;
+    regions: ChartMapRegion[];
+    /** Land in the frame that is not a region (neighbouring countries), drawn as background. */
+    land?: string;
+    /** Credit to show with the map (Natural Earth asks for none, but welcomes it). */
+    attribution?: string;
+}
+/** Makes a map available to choropleth charts (`spec.map` = its id). Registering an id again replaces it. */
+export declare function registerChartMap(map: ChartMapGeometry): void;
+/** A registered map by id, or undefined. */
+export declare function getChartMap(id: string): ChartMapGeometry | undefined;
+/** Every registered map. */
+export declare function listChartMaps(): ChartMapGeometry[];
+/**
+ * The region each category names, matched by id (any case) or by name (ignoring case and
+ * accents), or null. Several categories may not name the same region: the first wins.
+ */
+export declare function matchChartMapRegions(map: ChartMapGeometry, categories: readonly string[]): (ChartMapRegion | null)[];
+/**
+ * Class breaks for a choropleth: `thresholds` when given (ascending), else `steps` equal
+ * intervals between the smallest and largest value. Returns the inner breaks (one fewer than the classes).
+ */
+export declare function chartMapBreaks(values: readonly number[], steps: number, thresholds: readonly number[]): number[];
+/** The class (0-based) a value falls in: the number of breaks at or below it. */
+export declare const chartMapClass: (value: number, breaks: readonly number[]) => number;
+/** A light-to-dark ramp of `count` shades of `base`, one per class. */
+export declare function chartMapRamp(base: string, count: number): string[];

package/dist/chart/maps.d.ts

@@ -0,0 +1,43 @@
+/** One region of a map: an id (ISO 3166-1 alpha-3 for countries), a name and its outline. */
+export interface ChartMapRegion {
+    id: string;
+    name: string;
+    /** SVG path data in the map's box (absolute M / L / Z commands). */
+    d: string;
+    /** Where a label or a marker goes, in the map's box. */
+    center: [number, number];
+    /** Area in square box units (0 for a region too small to outline, drawn as a marker). */
+    area: number;
+}
+export interface ChartMapGeometry {
+    /** What `spec.map` names, e.g. `europe`. */
+    id: string;
+    name: string;
+    width: number;
+    height: number;
+    regions: ChartMapRegion[];
+    /** Land in the frame that is not a region (neighbouring countries), drawn as background. */
+    land?: string;
+    /** Credit to show with the map (Natural Earth asks for none, but welcomes it). */
+    attribution?: string;
+}
+/** Makes a map available to choropleth charts (`spec.map` = its id). Registering an id again replaces it. */
+export declare function registerChartMap(map: ChartMapGeometry): void;
+/** A registered map by id, or undefined. */
+export declare function getChartMap(id: string): ChartMapGeometry | undefined;
+/** Every registered map. */
+export declare function listChartMaps(): ChartMapGeometry[];
+/**
+ * The region each category names, matched by id (any case) or by name (ignoring case and
+ * accents), or null. Several categories may not name the same region: the first wins.
+ */
+export declare function matchChartMapRegions(map: ChartMapGeometry, categories: readonly string[]): (ChartMapRegion | null)[];
+/**
+ * Class breaks for a choropleth: `thresholds` when given (ascending), else `steps` equal
+ * intervals between the smallest and largest value. Returns the inner breaks (one fewer than the classes).
+ */
+export declare function chartMapBreaks(values: readonly number[], steps: number, thresholds: readonly number[]): number[];
+/** The class (0-based) a value falls in: the number of breaks at or below it. */
+export declare const chartMapClass: (value: number, breaks: readonly number[]) => number;
+/** A light-to-dark ramp of `count` shades of `base`, one per class. */
+export declare function chartMapRamp(base: string, count: number): string[];

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' | 'choropleth';
 /** 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' | 'choropleth';
 /** 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;