@opendata-ai/openchart-engine 6.17.0 → 6.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opendata-ai/openchart-engine",
-  "version": "6.17.0",
+  "version": "6.18.0",
   "description": "Headless compiler for openchart: spec validation, data compilation, scales, and layout",
   "license": "Apache-2.0",
   "author": "Riley Hilliard",
@@ -45,7 +45,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@opendata-ai/openchart-core": "6.17.0",
+    "@opendata-ai/openchart-core": "6.18.0",
     "d3-array": "^3.2.0",
     "d3-format": "^3.1.2",
     "d3-interpolate": "^3.0.0",

package/src/compiler/normalize.ts

@@ -249,6 +249,7 @@ function normalizeSankeySpec(spec: SankeySpec, _warnings: string[]): NormalizedS
     iterations: spec.iterations ?? 6,
     linkStyle: spec.linkStyle ?? 'gradient',
     nodeLabelAlign: spec.nodeLabelAlign ?? 'auto',
+    nodeSort: spec.nodeSort,
     chrome: normalizeChrome(spec.chrome),
     legend: spec.legend,
     theme: spec.theme ?? {},

package/src/sankey/compile-sankey.ts

@@ -324,6 +324,7 @@ export function compileSankey(spec: unknown, options: CompileOptions): SankeyLay
     sankeySpec.nodePadding,
     sankeySpec.nodeAlign,
     sankeySpec.iterations,
+    sankeySpec.nodeSort,
   );
 
   // 6b. Check if any right-side node labels overflow the right edge.
@@ -363,6 +364,7 @@ export function compileSankey(spec: unknown, options: CompileOptions): SankeyLay
       sankeySpec.nodePadding,
       sankeySpec.nodeAlign,
       sankeySpec.iterations,
+      sankeySpec.nodeSort,
     ));
   }
 

package/src/sankey/layout.ts

@@ -73,6 +73,7 @@ export function computeSankeyLayout(
   nodePadding: number,
   nodeAlign: SankeyNodeAlign,
   iterations: number,
+  nodeSort?: string[],
 ): SankeyLayoutResult {
   // Extract unique node IDs from source and target columns
   const nodeSet = new Set<string>();
@@ -113,6 +114,19 @@ export function computeSankeyLayout(
     ])
     .iterations(iterations);
 
+  // Apply explicit node ordering when provided.
+  // Builds a comparator from the ordered ID array so d3-sankey places nodes
+  // top-to-bottom within each column according to the spec's nodeSort.
+  if (nodeSort && nodeSort.length > 0) {
+    const orderMap = new Map(nodeSort.map((id, i) => [id, i]));
+    const fallback = nodeSort.length;
+    generator.nodeSort(
+      (a: SankeyNode<NodeExtra, LinkExtra>, b: SankeyNode<NodeExtra, LinkExtra>) =>
+        (orderMap.get((a as unknown as NodeExtra).id) ?? fallback) -
+        (orderMap.get((b as unknown as NodeExtra).id) ?? fallback),
+    );
+  }
+
   const graph = generator({
     nodes: nodes as unknown as Array<SankeyNode<NodeExtra, LinkExtra>>,
     links: links as unknown as Array<SankeyLink<NodeExtra, LinkExtra>>,

package/src/sankey/types.ts

@@ -29,6 +29,7 @@ export interface NormalizedSankeySpec {
   iterations: number;
   linkStyle: SankeyLinkColor;
   nodeLabelAlign: 'auto' | 'left' | 'right';
+  nodeSort?: string[];
   chrome: NormalizedChrome;
   legend?: LegendConfig;
   theme: ThemeConfig;