@pixerate/editor 0.163.0 → 0.165.0

package/dist/chart/links.d.cts

@@ -0,0 +1,34 @@
+import type { ChartIssue, ChartLink } from './types.cjs';
+/** Most flows a chart may have. */
+export declare const MAX_CHART_LINKS = 2000;
+/**
+ * Checks flows: each has a source and a target (different names) and a value above 0, a pair
+ * appears once, and flows only go forwards (a flow that would close a loop is dropped, since a
+ * Sankey diagram cannot draw one). Problems are reported with the flow's index.
+ */
+export declare function normalizeChartLinks(value: unknown, issues?: ChartIssue[], path?: string): ChartLink[];
+/**
+ * The nodes of a set of flows, in `order` first (names no flow uses are reported and dropped),
+ * then any others as the flows first name them.
+ */
+export declare function chartSankeyNodes(links: readonly ChartLink[], order?: readonly string[], issues?: ChartIssue[]): string[];
+/** How much flows through each node: the larger of what comes in and what goes out. */
+export declare function chartSankeyNodeValues(links: readonly ChartLink[], nodes: readonly string[]): number[];
+/**
+ * Reads flows from a table of source, target and value columns. With `header` (default
+ * `auto`: when the first row's third cell is not a number) the first row is skipped.
+ */
+export declare function chartLinksFromTable(rows: ReadonlyArray<ReadonlyArray<unknown>>, options?: {
+    header?: boolean | 'auto';
+}): {
+    source: unknown;
+    target: unknown;
+    value: unknown;
+}[];
+/** Flows with one field of flow `index` set to `text` (for the data grids; `setLinks` checks the result). */
+export declare function setChartLinkField(links: readonly ChartLink[], index: number, field: 'source' | 'target' | 'value', text: string): Record<string, unknown>[];
+/**
+ * Flows with a new one at the end: from the last flow's target (or "Start") to a new node
+ * named "Step n", carrying the last flow's value (or 1).
+ */
+export declare function addChartLink(links: readonly ChartLink[]): ChartLink[];

package/dist/chart/links.d.ts

@@ -0,0 +1,34 @@
+import type { ChartIssue, ChartLink } from './types.js';
+/** Most flows a chart may have. */
+export declare const MAX_CHART_LINKS = 2000;
+/**
+ * Checks flows: each has a source and a target (different names) and a value above 0, a pair
+ * appears once, and flows only go forwards (a flow that would close a loop is dropped, since a
+ * Sankey diagram cannot draw one). Problems are reported with the flow's index.
+ */
+export declare function normalizeChartLinks(value: unknown, issues?: ChartIssue[], path?: string): ChartLink[];
+/**
+ * The nodes of a set of flows, in `order` first (names no flow uses are reported and dropped),
+ * then any others as the flows first name them.
+ */
+export declare function chartSankeyNodes(links: readonly ChartLink[], order?: readonly string[], issues?: ChartIssue[]): string[];
+/** How much flows through each node: the larger of what comes in and what goes out. */
+export declare function chartSankeyNodeValues(links: readonly ChartLink[], nodes: readonly string[]): number[];
+/**
+ * Reads flows from a table of source, target and value columns. With `header` (default
+ * `auto`: when the first row's third cell is not a number) the first row is skipped.
+ */
+export declare function chartLinksFromTable(rows: ReadonlyArray<ReadonlyArray<unknown>>, options?: {
+    header?: boolean | 'auto';
+}): {
+    source: unknown;
+    target: unknown;
+    value: unknown;
+}[];
+/** Flows with one field of flow `index` set to `text` (for the data grids; `setLinks` checks the result). */
+export declare function setChartLinkField(links: readonly ChartLink[], index: number, field: 'source' | 'target' | 'value', text: string): Record<string, unknown>[];
+/**
+ * Flows with a new one at the end: from the last flow's target (or "Start") to a new node
+ * named "Step n", carrying the last flow's value (or 1).
+ */
+export declare function addChartLink(links: readonly ChartLink[]): ChartLink[];

package/dist/chart/mermaid.d.cts

@@ -1,7 +1,7 @@
 import type { ChartIssue, ChartSpec } from './types.cjs';
 /** The comment line that carries what Mermaid cannot express. Every Mermaid tool ignores `%%` comments. */
 export declare const CHART_MERMAID_META_PREFIX = "%% @pixerate ";
-export type ChartMermaidFamily = 'xychart' | 'pie' | 'radar';
+export type ChartMermaidFamily = 'xychart' | 'pie' | 'radar' | 'sankey' | 'treemap';
 export interface ChartMermaidOptions {
     /** Write the `%% @pixerate {…}` line so the chart round-trips exactly (default `true`). */
     meta?: boolean;
@@ -9,12 +9,15 @@ export interface ChartMermaidOptions {
     indent?: string;
 }
 /** The Mermaid family a chart is written as. */
-export declare function chartMermaidFamily(spec: Pick<ChartSpec, 'type' | 'series'>): ChartMermaidFamily;
+export declare function chartMermaidFamily(spec: Pick<ChartSpec, 'type' | 'series'> & {
+    links?: ChartSpec['links'];
+}): ChartMermaidFamily;
 /**
  * Writes a chart as Mermaid: `xychart-beta` for bar, line, area and scatter charts (areas and
  * scatters drawn as lines; slopes and Likert charts as lines and bars), `pie` for pies, donuts,
- * funnels, treemaps and parliaments, `radar-beta` for
- * radars. Anything Mermaid cannot hold (stacking, colours, formats, gaps, trendlines, other
+ * funnels and parliaments, `radar-beta` for radars, `sankey-beta` for Sankey diagrams with
+ * flows, and `treemap-beta` for treemaps and sunbursts (their groups, or one item per category).
+ * Sankey titles go in frontmatter, which `sankey-beta` needs. Anything Mermaid cannot hold (stacking, colours, formats, gaps, trendlines, other
  * chart types) goes into one `%% @pixerate {…}` comment so `chartFromMermaid` gets the chart
  * back exactly, while any Mermaid renderer still draws the basic chart.
  */
@@ -34,7 +37,7 @@ export interface ChartMermaidResult {
     hasMeta: boolean;
 }
 /**
- * Reads Mermaid `xychart-beta`, `pie` or `radar-beta` text as a chart. Never throws: lines it
+ * Reads Mermaid `xychart-beta`, `pie`, `radar-beta`, `sankey-beta` or `treemap-beta` text as a chart. Never throws: lines it
  * cannot read are reported with their line numbers and skipped, and the result always draws.
  * A `%% @pixerate {…}` line written by `chartToMermaid` restores everything Mermaid cannot hold.
  */
@@ -47,6 +50,6 @@ export interface FoundChartMermaid {
 }
 /**
  * Finds Mermaid charts in Markdown or chat text: fenced ```mermaid blocks (and unlabelled
- * fences) whose header is xychart-beta, pie or radar-beta, else the whole text when it is one.
+ * fences) whose header is xychart-beta, pie, radar-beta, sankey-beta or treemap-beta, else the whole text when it is one.
  */
 export declare function findMermaidCharts(text: string): FoundChartMermaid[];

package/dist/chart/mermaid.d.ts

@@ -1,7 +1,7 @@
 import type { ChartIssue, ChartSpec } from './types.js';
 /** The comment line that carries what Mermaid cannot express. Every Mermaid tool ignores `%%` comments. */
 export declare const CHART_MERMAID_META_PREFIX = "%% @pixerate ";
-export type ChartMermaidFamily = 'xychart' | 'pie' | 'radar';
+export type ChartMermaidFamily = 'xychart' | 'pie' | 'radar' | 'sankey' | 'treemap';
 export interface ChartMermaidOptions {
     /** Write the `%% @pixerate {…}` line so the chart round-trips exactly (default `true`). */
     meta?: boolean;
@@ -9,12 +9,15 @@ export interface ChartMermaidOptions {
     indent?: string;
 }
 /** The Mermaid family a chart is written as. */
-export declare function chartMermaidFamily(spec: Pick<ChartSpec, 'type' | 'series'>): ChartMermaidFamily;
+export declare function chartMermaidFamily(spec: Pick<ChartSpec, 'type' | 'series'> & {
+    links?: ChartSpec['links'];
+}): ChartMermaidFamily;
 /**
  * Writes a chart as Mermaid: `xychart-beta` for bar, line, area and scatter charts (areas and
  * scatters drawn as lines; slopes and Likert charts as lines and bars), `pie` for pies, donuts,
- * funnels, treemaps and parliaments, `radar-beta` for
- * radars. Anything Mermaid cannot hold (stacking, colours, formats, gaps, trendlines, other
+ * funnels and parliaments, `radar-beta` for radars, `sankey-beta` for Sankey diagrams with
+ * flows, and `treemap-beta` for treemaps and sunbursts (their groups, or one item per category).
+ * Sankey titles go in frontmatter, which `sankey-beta` needs. Anything Mermaid cannot hold (stacking, colours, formats, gaps, trendlines, other
  * chart types) goes into one `%% @pixerate {…}` comment so `chartFromMermaid` gets the chart
  * back exactly, while any Mermaid renderer still draws the basic chart.
  */
@@ -34,7 +37,7 @@ export interface ChartMermaidResult {
     hasMeta: boolean;
 }
 /**
- * Reads Mermaid `xychart-beta`, `pie` or `radar-beta` text as a chart. Never throws: lines it
+ * Reads Mermaid `xychart-beta`, `pie`, `radar-beta`, `sankey-beta` or `treemap-beta` text as a chart. Never throws: lines it
  * cannot read are reported with their line numbers and skipped, and the result always draws.
  * A `%% @pixerate {…}` line written by `chartToMermaid` restores everything Mermaid cannot hold.
  */
@@ -47,6 +50,6 @@ export interface FoundChartMermaid {
 }
 /**
  * Finds Mermaid charts in Markdown or chat text: fenced ```mermaid blocks (and unlabelled
- * fences) whose header is xychart-beta, pie or radar-beta, else the whole text when it is one.
+ * fences) whose header is xychart-beta, pie, radar-beta, sankey-beta or treemap-beta, else the whole text when it is one.
  */
 export declare function findMermaidCharts(text: string): FoundChartMermaid[];

package/dist/chart/schemas.d.cts

@@ -20,6 +20,9 @@ export declare const TREE_DEFS: {
     chartTreeNode: JsonSchema;
 };
 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>;
+export declare const LINK_INDEX: JsonSchema;
 export declare const ERROR_BARS: (what: string) => JsonSchema;
 export declare const SERIES_PROPS: Record<string, JsonSchema>;
 export declare const CHART_UPDATE_PROPERTIES: Record<string, JsonSchema>;

package/dist/chart/schemas.d.ts

@@ -20,6 +20,9 @@ export declare const TREE_DEFS: {
     chartTreeNode: JsonSchema;
 };
 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>;
+export declare const LINK_INDEX: JsonSchema;
 export declare const ERROR_BARS: (what: string) => JsonSchema;
 export declare const SERIES_PROPS: Record<string, JsonSchema>;
 export declare const CHART_UPDATE_PROPERTIES: Record<string, JsonSchema>;

package/dist/chart/spec.d.cts

@@ -1,4 +1,4 @@
-import type { ChartAxis, ChartCurve, ChartErrorBars, ChartIssue, ChartLabelPosition, ChartLegendPosition, ChartLikertNeutral, ChartLikertSort, ChartMarker, ChartNumberFormat, ChartOrientation, ChartRadarGraticule, ChartReferenceAxis, ChartReferenceBand, ChartReferenceLine, ChartSeries, ChartSeriesType, ChartSpec, ChartStacking, ChartTheme, ChartTrendline, ChartTrendlineType, ChartType, ChartValue } from './types.cjs';
+import type { ChartAxis, ChartCurve, ChartErrorBars, ChartIssue, ChartLabelPosition, ChartLegendPosition, ChartLikertNeutral, ChartLikertSort, ChartMarker, ChartNumberFormat, ChartOrientation, ChartRadarGraticule, ChartReferenceAxis, ChartReferenceBand, ChartReferenceLine, ChartSankeyLinkColor, ChartSeries, ChartSeriesType, ChartSpec, ChartStacking, ChartTheme, ChartTrendline, ChartTrendlineType, ChartType, ChartValue } from './types.cjs';
 export declare const CHART_TYPES: readonly ChartType[];
 export declare const CHART_MARKERS: readonly ChartMarker[];
 export declare const CHART_TRENDLINE_TYPES: readonly ChartTrendlineType[];
@@ -11,6 +11,7 @@ export declare const CHART_CURVES: readonly ChartCurve[];
 export declare const CHART_RADAR_GRATICULES: readonly ChartRadarGraticule[];
 export declare const CHART_LIKERT_NEUTRALS: readonly ChartLikertNeutral[];
 export declare const CHART_LIKERT_SORTS: readonly ChartLikertSort[];
+export declare const CHART_SANKEY_LINK_COLORS: readonly ChartSankeyLinkColor[];
 export declare const CHART_REFERENCE_AXES: readonly ChartReferenceAxis[];
 export declare const CHART_ORIENTATIONS: readonly ChartOrientation[];
 export declare const CHART_LEGEND_POSITIONS: readonly ChartLegendPosition[];
@@ -18,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';
+export type ChartFamily = 'cartesian' | 'xy' | 'pie' | 'radar' | 'waterfall' | 'histogram' | 'box' | 'funnel' | 'treemap' | 'slope' | 'likert' | 'parliament' | 'sunburst' | 'sankey';
 /** 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

@@ -1,4 +1,4 @@
-import type { ChartAxis, ChartCurve, ChartErrorBars, ChartIssue, ChartLabelPosition, ChartLegendPosition, ChartLikertNeutral, ChartLikertSort, ChartMarker, ChartNumberFormat, ChartOrientation, ChartRadarGraticule, ChartReferenceAxis, ChartReferenceBand, ChartReferenceLine, ChartSeries, ChartSeriesType, ChartSpec, ChartStacking, ChartTheme, ChartTrendline, ChartTrendlineType, ChartType, ChartValue } from './types.js';
+import type { ChartAxis, ChartCurve, ChartErrorBars, ChartIssue, ChartLabelPosition, ChartLegendPosition, ChartLikertNeutral, ChartLikertSort, ChartMarker, ChartNumberFormat, ChartOrientation, ChartRadarGraticule, ChartReferenceAxis, ChartReferenceBand, ChartReferenceLine, ChartSankeyLinkColor, ChartSeries, ChartSeriesType, ChartSpec, ChartStacking, ChartTheme, ChartTrendline, ChartTrendlineType, ChartType, ChartValue } from './types.js';
 export declare const CHART_TYPES: readonly ChartType[];
 export declare const CHART_MARKERS: readonly ChartMarker[];
 export declare const CHART_TRENDLINE_TYPES: readonly ChartTrendlineType[];
@@ -11,6 +11,7 @@ export declare const CHART_CURVES: readonly ChartCurve[];
 export declare const CHART_RADAR_GRATICULES: readonly ChartRadarGraticule[];
 export declare const CHART_LIKERT_NEUTRALS: readonly ChartLikertNeutral[];
 export declare const CHART_LIKERT_SORTS: readonly ChartLikertSort[];
+export declare const CHART_SANKEY_LINK_COLORS: readonly ChartSankeyLinkColor[];
 export declare const CHART_REFERENCE_AXES: readonly ChartReferenceAxis[];
 export declare const CHART_ORIENTATIONS: readonly ChartOrientation[];
 export declare const CHART_LEGEND_POSITIONS: readonly ChartLegendPosition[];
@@ -18,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';
+export type ChartFamily = 'cartesian' | 'xy' | 'pie' | 'radar' | 'waterfall' | 'histogram' | 'box' | 'funnel' | 'treemap' | 'slope' | 'likert' | 'parliament' | 'sunburst' | 'sankey';
 /** 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/style.d.cts

@@ -0,0 +1,33 @@
+/**
+ * House style for charts: the `chart.json` profile (palette, allowed colour schemes and
+ * layouts, theme, defaults for new charts), its checks, and `check_chart_style`.
+ */
+import type { AgentToolProvider } from '../tools/registry.cjs';
+import type { StyleDomain, StyleResolver } from '../tools/style.cjs';
+import type { ChartSpec } from './types.cjs';
+import type { ChartController } from './controller.cjs';
+/** A chart's `chart.json` house-style profile, after `$token` references are resolved. */
+export interface ChartStyleProfile {
+    /** Series colours in order: the house palette. */
+    palette?: string[];
+    /** `CHART_COLOR_SCHEMES` ids allowed besides the palette. */
+    colorSchemes?: string[];
+    /** `CHART_LAYOUT_PRESETS` ids allowed. */
+    layouts?: string[];
+    /** Colours and type to draw charts with (the `theme` option of the chart renderers). */
+    theme?: Partial<Record<'background' | 'surface' | 'text' | 'mutedText' | 'grid' | 'axis' | 'positive' | 'negative' | 'fontFamily', string> & Record<'fontSize' | 'titleSize', number>>;
+    /** Spec values new charts start from. */
+    defaults?: Partial<Pick<ChartSpec, 'dataLabels' | 'points' | 'curve' | 'stacking' | 'orientation' | 'labelPosition'>>;
+}
+/** The chart house-style domain: register it with `createStyleResolver({ domains })`. */
+export declare const chartStyleDomain: StyleDomain<ChartSpec>;
+/** The spec patch that starts a chart in the house style: the palette and the defaults. */
+export declare function chartStylePatch(profile: Readonly<Record<string, unknown>>): Partial<ChartSpec>;
+export interface ChartStyleToolProviderOptions {
+    /** Provider id (unique per registry). Default `chart-style`. */
+    id?: string;
+    /** Tool-name prefix; defaults to `chart`, so `check_chart_style` joins the chart toolset. */
+    namespace?: string;
+}
+/** `check_chart_style`: runs the chart house-style checks against a chart. */
+export declare function createChartStyleToolProvider(controller: ChartController, styles: StyleResolver, options?: ChartStyleToolProviderOptions): AgentToolProvider;

package/dist/chart/style.d.ts

@@ -0,0 +1,33 @@
+/**
+ * House style for charts: the `chart.json` profile (palette, allowed colour schemes and
+ * layouts, theme, defaults for new charts), its checks, and `check_chart_style`.
+ */
+import type { AgentToolProvider } from '../tools/registry.js';
+import type { StyleDomain, StyleResolver } from '../tools/style.js';
+import type { ChartSpec } from './types.js';
+import type { ChartController } from './controller.js';
+/** A chart's `chart.json` house-style profile, after `$token` references are resolved. */
+export interface ChartStyleProfile {
+    /** Series colours in order: the house palette. */
+    palette?: string[];
+    /** `CHART_COLOR_SCHEMES` ids allowed besides the palette. */
+    colorSchemes?: string[];
+    /** `CHART_LAYOUT_PRESETS` ids allowed. */
+    layouts?: string[];
+    /** Colours and type to draw charts with (the `theme` option of the chart renderers). */
+    theme?: Partial<Record<'background' | 'surface' | 'text' | 'mutedText' | 'grid' | 'axis' | 'positive' | 'negative' | 'fontFamily', string> & Record<'fontSize' | 'titleSize', number>>;
+    /** Spec values new charts start from. */
+    defaults?: Partial<Pick<ChartSpec, 'dataLabels' | 'points' | 'curve' | 'stacking' | 'orientation' | 'labelPosition'>>;
+}
+/** The chart house-style domain: register it with `createStyleResolver({ domains })`. */
+export declare const chartStyleDomain: StyleDomain<ChartSpec>;
+/** The spec patch that starts a chart in the house style: the palette and the defaults. */
+export declare function chartStylePatch(profile: Readonly<Record<string, unknown>>): Partial<ChartSpec>;
+export interface ChartStyleToolProviderOptions {
+    /** Provider id (unique per registry). Default `chart-style`. */
+    id?: string;
+    /** Tool-name prefix; defaults to `chart`, so `check_chart_style` joins the chart toolset. */
+    namespace?: string;
+}
+/** `check_chart_style`: runs the chart house-style checks against a chart. */
+export declare function createChartStyleToolProvider(controller: ChartController, styles: StyleResolver, options?: ChartStyleToolProviderOptions): AgentToolProvider;

package/dist/chart/types.d.cts

@@ -16,8 +16,9 @@
  * - `parliament` draws the first series as seats in a hemicycle, one colour per category.
  * - `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.
  */
-export type ChartType = 'bar' | 'line' | 'area' | 'scatter' | 'bubble' | 'pie' | 'donut' | 'radar' | 'waterfall' | 'histogram' | 'box' | 'funnel' | 'treemap' | 'slope' | 'likert' | 'parliament' | 'sunburst';
+export type ChartType = 'bar' | 'line' | 'area' | 'scatter' | 'bubble' | 'pie' | 'donut' | 'radar' | 'waterfall' | 'histogram' | 'box' | 'funnel' | 'treemap' | 'slope' | 'likert' | 'parliament' | 'sunburst' | 'sankey';
 /** 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). */
@@ -122,6 +123,17 @@ export interface ChartTreeNode {
     /** CSS colour (default: the palette colour of its top-level group, lighter further in). */
     color?: string;
 }
+/** One flow of a Sankey diagram, from one named node to another. */
+export interface ChartLink {
+    source: string;
+    target: string;
+    /** Above 0. */
+    value: number;
+    /** CSS colour (default: by `sankeyLinkColor`). */
+    color?: string;
+}
+/** What colours each flow of a Sankey diagram: its source node, its target node, or grey. */
+export type ChartSankeyLinkColor = 'source' | 'target' | 'gray';
 /** Which axis a reference line or band is measured on: the value axis, the secondary value axis, or the numeric x axis of a scatter or bubble chart. */
 export type ChartReferenceAxis = 'y' | 'y2' | 'x';
 /** A line across the plot at one value: a target, a floor, an average. */
@@ -277,6 +289,16 @@ export interface ChartSpec {
     tree: ChartTreeNode[];
     /** Sunburst: the caption under the total in the centre ("" for none). */
     sunburstLabel: string;
+    /**
+     * Flows between named nodes (Sankey diagrams). When set they are the chart's data: the
+     * categories are the nodes (in `sankeyNodes` order) and the first series holds how much flows
+     * through each (the larger of in and out), so other types draw those amounts.
+     */
+    links: ChartLink[];
+    /** Sankey: the order nodes are listed and stacked in (default: as the links first name them). */
+    sankeyNodes: string[];
+    /** Sankey: what colours each flow. */
+    sankeyLinkColor: ChartSankeyLinkColor;
 }
 /** What a click selects. */
 export type ChartSelection = {
@@ -332,7 +354,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' | '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' | 'link' | 'note' | 'selection' | 'empty';
 interface ChartMarkBase {
     /** Unique within the scene (a stable key for frameworks). */
     key: string;

package/dist/chart/types.d.ts

@@ -16,8 +16,9 @@
  * - `parliament` draws the first series as seats in a hemicycle, one colour per category.
  * - `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.
  */
-export type ChartType = 'bar' | 'line' | 'area' | 'scatter' | 'bubble' | 'pie' | 'donut' | 'radar' | 'waterfall' | 'histogram' | 'box' | 'funnel' | 'treemap' | 'slope' | 'likert' | 'parliament' | 'sunburst';
+export type ChartType = 'bar' | 'line' | 'area' | 'scatter' | 'bubble' | 'pie' | 'donut' | 'radar' | 'waterfall' | 'histogram' | 'box' | 'funnel' | 'treemap' | 'slope' | 'likert' | 'parliament' | 'sunburst' | 'sankey';
 /** 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). */
@@ -122,6 +123,17 @@ export interface ChartTreeNode {
     /** CSS colour (default: the palette colour of its top-level group, lighter further in). */
     color?: string;
 }
+/** One flow of a Sankey diagram, from one named node to another. */
+export interface ChartLink {
+    source: string;
+    target: string;
+    /** Above 0. */
+    value: number;
+    /** CSS colour (default: by `sankeyLinkColor`). */
+    color?: string;
+}
+/** What colours each flow of a Sankey diagram: its source node, its target node, or grey. */
+export type ChartSankeyLinkColor = 'source' | 'target' | 'gray';
 /** Which axis a reference line or band is measured on: the value axis, the secondary value axis, or the numeric x axis of a scatter or bubble chart. */
 export type ChartReferenceAxis = 'y' | 'y2' | 'x';
 /** A line across the plot at one value: a target, a floor, an average. */
@@ -277,6 +289,16 @@ export interface ChartSpec {
     tree: ChartTreeNode[];
     /** Sunburst: the caption under the total in the centre ("" for none). */
     sunburstLabel: string;
+    /**
+     * Flows between named nodes (Sankey diagrams). When set they are the chart's data: the
+     * categories are the nodes (in `sankeyNodes` order) and the first series holds how much flows
+     * through each (the larger of in and out), so other types draw those amounts.
+     */
+    links: ChartLink[];
+    /** Sankey: the order nodes are listed and stacked in (default: as the links first name them). */
+    sankeyNodes: string[];
+    /** Sankey: what colours each flow. */
+    sankeyLinkColor: ChartSankeyLinkColor;
 }
 /** What a click selects. */
 export type ChartSelection = {
@@ -332,7 +354,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' | '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' | 'link' | 'note' | 'selection' | 'empty';
 interface ChartMarkBase {
     /** Unique within the scene (a stable key for frameworks). */
     key: string;

package/dist/{chunk-TALQONZ5.js → chunk-2J5VLJHC.js}

@@ -7,7 +7,7 @@ import {
 import {
   CHART_OOXML_NS,
   chartFromOoxml
-} from "./chunk-POR54B55.js";
+} from "./chunk-CRFSQWKQ.js";
 import {
   compareDocuments
 } from "./chunk-V5OOP74P.js";
@@ -34,10 +34,10 @@ import {
   searchDocument,
   sliceContainsTable,
   syncInitialContent
-} from "./chunk-OXERWBKE.js";
+} from "./chunk-X5W645RI.js";
 import {
   chartDataToTable
-} from "./chunk-3NEZJCBY.js";
+} from "./chunk-2ZRN43IN.js";
 import {
   PIXERATE_DOCUMENT_MIME,
   getClipboardData,