@pixerate/editor 0.166.0 → 0.167.0

package/dist/chart/index.d.cts

@@ -3,6 +3,7 @@ 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

@@ -3,6 +3,7 @@ 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

@@ -17,7 +17,7 @@ import {
   TRENDLINE_PROPS,
   VALUE,
   WIDTH
-} from "../chunk-5UNQDC3Q.js";
+} from "../chunk-34UCPHYO.js";
 import {
   CHART_OOXML_CONTENT_TYPE,
   CHART_OOXML_NS,
@@ -25,7 +25,7 @@ import {
   chartFormatToCode,
   chartFromOoxml,
   chartToOoxml
-} from "../chunk-XNU45TYA.js";
+} from "../chunk-OLCHKGGO.js";
 import {
   CHART_COLOR_SCHEMES,
   CHART_LAYOUT_PRESETS,
@@ -47,7 +47,7 @@ import {
   monochromeChartPalette,
   sparklineToSvg,
   summarizeChart
-} from "../chunk-YUFTVNLX.js";
+} from "../chunk-N3ACT6VJ.js";
 import "../chunk-KGRZMHZB.js";
 import {
   CHART_DATE_STEPS,
@@ -58,6 +58,9 @@ import {
   chartDateLabels,
   chartDateToSerial,
   chartHistogram,
+  chartMapBreaks,
+  chartMapClass,
+  chartMapRamp,
   chartMovingAverage,
   chartQuantile,
   chartRaceMoment,
@@ -79,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-ITANXMZD.js";
+} from "../chunk-M52UCHVZ.js";
 import {
   CHART_AXIS_KINDS,
   CHART_AXIS_SCALES,
@@ -185,7 +192,7 @@ import {
   shadeChartColor,
   simulateChartVision,
   uniqueChartSeriesId
-} from "../chunk-FR432ROA.js";
+} from "../chunk-ORZF4JOO.js";
 import "../chunk-O6OGNDND.js";
 import "../chunk-II2WIF5Z.js";
 import {
@@ -899,6 +906,22 @@ 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`,
@@ -1752,6 +1775,27 @@ function createChartToolProvider(controller, options = {}) {
     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",
@@ -2432,7 +2476,7 @@ function createChartToolProvider(controller, options = {}) {
       return { redone, ...redone ? { label } : {} };
     }
   };
-  const reads = [getChart, renderChart, checkColors, recommend, getTrendline, raceRanking, listPresets, exportMermaid, exportOoxml];
+  const reads = [getChart, renderChart, checkColors, recommend, getTrendline, raceRanking, mapRegions, listPresets, exportMermaid, exportOoxml];
   const writes = [
     updateChart,
     setData,
@@ -3224,6 +3268,9 @@ export {
   chartLikertColor,
   chartLinksFromTable,
   chartLuminance,
+  chartMapBreaks,
+  chartMapClass,
+  chartMapRamp,
   chartMermaidFamily,
   chartMovingAverage,
   chartPointAnchor,
@@ -3306,13 +3353,16 @@ export {
   formatChartDate,
   formatChartNumber,
   formatChartValueWithCode,
+  getChartMap,
   handleChartKey,
   isCartesianChart,
   isXyChart,
   layoutChart,
   layoutSparkline,
   linearMap,
+  listChartMaps,
   locateChartPoint,
+  matchChartMapRegions,
   monochromeChartPalette,
   niceLogScale,
   niceScale,
@@ -3337,6 +3387,7 @@ export {
   realChartClock,
   recommendChartTypes,
   recommendForShape,
+  registerChartMap,
   removeChartTreeRow,
   resolveChartSvgPaints,
   sameChartSelection,

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

@@ -52,3 +52,11 @@ export declare function layoutSankey(ctx: LayoutCtx, area: ChartRect, series: Ch
  * 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

@@ -52,3 +52,11 @@ export declare function layoutSankey(ctx: LayoutCtx, area: ChartRect, series: Ch
  * 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/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/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' | 'barrace';
+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' | 'barrace';
+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/types.d.cts

@@ -19,8 +19,10 @@
  * - `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).
+ * - `choropleth` shades the regions of a registered map (`map`) by the first series, each
+ *   category naming a region by id (ISO alpha-3 for countries) or name.
  */
-export type ChartType = 'bar' | 'line' | 'area' | 'scatter' | 'bubble' | 'pie' | 'donut' | 'radar' | 'waterfall' | 'histogram' | 'box' | 'funnel' | 'treemap' | 'slope' | 'likert' | 'parliament' | 'sunburst' | 'sankey' | 'barrace';
+export type ChartType = 'bar' | 'line' | 'area' | 'scatter' | 'bubble' | 'pie' | 'donut' | 'radar' | 'waterfall' | 'histogram' | 'box' | 'funnel' | 'treemap' | 'slope' | 'likert' | 'parliament' | 'sunburst' | 'sankey' | 'barrace' | 'choropleth';
 /** 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). */
@@ -303,6 +305,12 @@ export interface ChartSpec {
     sankeyLinkColor: ChartSankeyLinkColor;
     /** Bar race: how many bars each moment shows, 1–30. */
     raceTopN: number;
+    /** Choropleth: the registered map to draw (see `registerChartMap`; `@pixerate/editor/chart-maps` has `europe`). */
+    map: string;
+    /** Choropleth: number of equal colour classes between the smallest and largest value, 2–9. */
+    mapSteps: number;
+    /** Choropleth: class breaks in ascending order, instead of `mapSteps` ([] for none). */
+    mapThresholds: number[];
 }
 /** What a click selects. */
 export type ChartSelection = {
@@ -358,7 +366,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' | 'race-time' | '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' | 'region' | 'map-land' | 'link' | 'note' | 'selection' | 'empty';
 interface ChartMarkBase {
     /** Unique within the scene (a stable key for frameworks). */
     key: string;

package/dist/chart/types.d.ts

@@ -19,8 +19,10 @@
  * - `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).
+ * - `choropleth` shades the regions of a registered map (`map`) by the first series, each
+ *   category naming a region by id (ISO alpha-3 for countries) or name.
  */
-export type ChartType = 'bar' | 'line' | 'area' | 'scatter' | 'bubble' | 'pie' | 'donut' | 'radar' | 'waterfall' | 'histogram' | 'box' | 'funnel' | 'treemap' | 'slope' | 'likert' | 'parliament' | 'sunburst' | 'sankey' | 'barrace';
+export type ChartType = 'bar' | 'line' | 'area' | 'scatter' | 'bubble' | 'pie' | 'donut' | 'radar' | 'waterfall' | 'histogram' | 'box' | 'funnel' | 'treemap' | 'slope' | 'likert' | 'parliament' | 'sunburst' | 'sankey' | 'barrace' | 'choropleth';
 /** 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). */
@@ -303,6 +305,12 @@ export interface ChartSpec {
     sankeyLinkColor: ChartSankeyLinkColor;
     /** Bar race: how many bars each moment shows, 1–30. */
     raceTopN: number;
+    /** Choropleth: the registered map to draw (see `registerChartMap`; `@pixerate/editor/chart-maps` has `europe`). */
+    map: string;
+    /** Choropleth: number of equal colour classes between the smallest and largest value, 2–9. */
+    mapSteps: number;
+    /** Choropleth: class breaks in ascending order, instead of `mapSteps` ([] for none). */
+    mapThresholds: number[];
 }
 /** What a click selects. */
 export type ChartSelection = {
@@ -358,7 +366,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' | 'race-time' | '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' | 'region' | 'map-land' | 'link' | 'note' | 'selection' | 'empty';
 interface ChartMarkBase {
     /** Unique within the scene (a stable key for frameworks). */
     key: string;

package/dist/chart-maps/europe.d.cts

@@ -0,0 +1,7 @@
+import type { ChartMapGeometry } from '../chart/maps.cjs';
+/**
+ * Europe, from Iceland to the Caucasus and from Cyprus to the North Cape, in Lambert azimuthal
+ * equal-area (centred on 10°E 52°N) within a 1000 × 873 box. Regions are countries keyed by
+ * ISO 3166-1 alpha-3 code (Kosovo: XKX). Register it with `registerChartMap(EUROPE_CHART_MAP)`.
+ */
+export declare const EUROPE_CHART_MAP: ChartMapGeometry;

package/dist/chart-maps/europe.d.ts

@@ -0,0 +1,7 @@
+import type { ChartMapGeometry } from '../chart/maps.js';
+/**
+ * Europe, from Iceland to the Caucasus and from Cyprus to the North Cape, in Lambert azimuthal
+ * equal-area (centred on 10°E 52°N) within a 1000 × 873 box. Regions are countries keyed by
+ * ISO 3166-1 alpha-3 code (Kosovo: XKX). Register it with `registerChartMap(EUROPE_CHART_MAP)`.
+ */
+export declare const EUROPE_CHART_MAP: ChartMapGeometry;