@opendata-ai/openchart-engine 6.19.3 → 6.20.0

package/src/sankey/__tests__/node-label-wrap.test.ts

@@ -0,0 +1,114 @@
+/**
+ * Characterization test for sankey node-label wrapping at narrow widths.
+ *
+ * Part of refactor/v7-cohesion step 1. The sankey engine computes a label's
+ * `maxWidth` based on available horizontal space from the label anchor to the
+ * container edge (see computeNodeLabel in compile-sankey.ts around line 137).
+ * When the container is narrow and node labels are long, the computed
+ * `maxWidth` falls below the estimated text width — the adapter then wraps the
+ * label into multiple lines via its own wrapText routine.
+ *
+ * Step 3 of the v7 plan extracts `wrapText` to core while keeping the sankey
+ * path heuristic-only. This test guards the engine's responsibility: produce a
+ * label `maxWidth` that forces wrapping on long-label narrow-width sankeys.
+ */
+
+import { estimateTextWidth, wrapText } from '@opendata-ai/openchart-core';
+import { describe, expect, it } from 'vitest';
+import { compileSankey } from '../../compile';
+
+describe('sankey node-label wrapping', () => {
+  it('produces at least one node whose label maxWidth forces wrapping at narrow widths', () => {
+    const spec = {
+      type: 'sankey' as const,
+      data: [
+        {
+          from: 'Renewable Energy Sources International',
+          to: 'Grid Transmission Network',
+          amount: 100,
+        },
+        { from: 'Grid Transmission Network', to: 'Residential Consumption Households', amount: 60 },
+        { from: 'Grid Transmission Network', to: 'Commercial Industrial Facilities', amount: 40 },
+      ],
+      encoding: {
+        source: { field: 'from', type: 'nominal' as const },
+        target: { field: 'to', type: 'nominal' as const },
+        value: { field: 'amount', type: 'quantitative' as const },
+      },
+    };
+
+    // 360px wide total is cramped for the labels above across 3 columns,
+    // forcing per-label maxWidth to be well below the longest text width.
+    const layout = compileSankey(spec, { width: 360, height: 300 });
+
+    // Every node should have a finite maxWidth set (a proxy for "engine
+    // participated in wrap geometry") when overflow-compression kicked in.
+    const withMaxWidth = layout.nodes.filter(
+      (n) => typeof n.label.maxWidth === 'number' && (n.label.maxWidth as number) >= 0,
+    );
+    expect(withMaxWidth.length).toBe(layout.nodes.length);
+
+    // At least one node label requires wrapping: its natural text width
+    // exceeds the engine-assigned maxWidth at the same font size/weight.
+    const wrapsRequired = withMaxWidth.filter((n) => {
+      const tw = estimateTextWidth(
+        n.label.text,
+        n.label.style.fontSize,
+        n.label.style.fontWeight ?? 400,
+      );
+      return tw > (n.label.maxWidth as number);
+    });
+    expect(wrapsRequired.length).toBeGreaterThanOrEqual(1);
+  });
+
+  it('does not force wrapping at generous widths for the same long-label spec', () => {
+    // Control: the same spec at a comfortable width does not require wrapping.
+    const spec = {
+      type: 'sankey' as const,
+      data: [
+        {
+          from: 'Renewable Energy Sources International',
+          to: 'Grid Transmission Network',
+          amount: 100,
+        },
+        { from: 'Grid Transmission Network', to: 'Residential Consumption Households', amount: 60 },
+      ],
+      encoding: {
+        source: { field: 'from', type: 'nominal' as const },
+        target: { field: 'to', type: 'nominal' as const },
+        value: { field: 'amount', type: 'quantitative' as const },
+      },
+    };
+
+    const layout = compileSankey(spec, { width: 1600, height: 300 });
+
+    const wrapsRequired = layout.nodes.filter((n) => {
+      if (typeof n.label.maxWidth !== 'number') return false;
+      const tw = estimateTextWidth(
+        n.label.text,
+        n.label.style.fontSize,
+        n.label.style.fontWeight ?? 400,
+      );
+      return tw > (n.label.maxWidth as number);
+    });
+    expect(wrapsRequired.length).toBe(0);
+  });
+
+  // ---------------------------------------------------------------------------
+  // Pinned behavior (refactor/v7-cohesion code review item 1):
+  // The shared wrapText in core/src/layout/text-wrap.ts splits on `\n` before
+  // word-wrapping. The previous sankey-local wrapText did not. Pin the new
+  // behavior so anyone relying on `\n` in node labels sees the multi-line break.
+  // ---------------------------------------------------------------------------
+  it('honors explicit `\\n` in node labels by producing multi-line wrap output', () => {
+    const lines = wrapText('First line\nSecond line', 12, 400, 1000);
+
+    expect(lines).toEqual(['First line', 'Second line']);
+  });
+
+  it('preserves blank lines between consecutive `\\n` characters', () => {
+    const lines = wrapText('A\n\nB', 12, 400, 1000);
+
+    expect(lines).toEqual(['A', '', 'B']);
+  });
+});

package/src/sankey/__tests__/node-sort.test.ts

@@ -0,0 +1,45 @@
+/**
+ * Characterization test for sankey explicit `nodeSort`.
+ *
+ * Part of refactor/v7-cohesion step 1. Pins the `nodeSort` handling in
+ * `packages/engine/src/sankey/layout.ts` around line 120, where an explicit
+ * ordered-ID array is translated into a d3-sankey `nodeSort` comparator so
+ * nodes stack top-to-bottom within each column following the user's order
+ * rather than d3-sankey's default (data-insertion / value-based) ordering.
+ */
+
+import { describe, expect, it } from 'vitest';
+import { computeSankeyLayout } from '../layout';
+
+describe('sankey explicit nodeSort', () => {
+  it('orders nodes within a column according to the nodeSort array', () => {
+    // A, B, C all live in column 0 and flow into D in column 1.
+    // Data-insertion order is A, B, C (the default d3-sankey order varies
+    // with value anyway). Explicit nodeSort forces C, A, B top-to-bottom.
+    const data = [
+      { source: 'A', target: 'D', value: 10 },
+      { source: 'B', target: 'D', value: 20 },
+      { source: 'C', target: 'D', value: 15 },
+    ];
+
+    const { nodes } = computeSankeyLayout(
+      data,
+      'source',
+      'target',
+      'value',
+      { x: 0, y: 0, width: 600, height: 400 },
+      12,
+      16,
+      'justify',
+      6,
+      ['C', 'A', 'B'],
+    );
+
+    // Collect column-0 nodes, sort them by vertical position, and read back IDs.
+    const col0 = nodes.filter((n) => n.depth === 0);
+    expect(col0.map((n) => n.id).sort()).toEqual(['A', 'B', 'C']);
+
+    const ordered = [...col0].sort((a, b) => (a.y0 ?? 0) - (b.y0 ?? 0)).map((n) => n.id);
+    expect(ordered).toEqual(['C', 'A', 'B']);
+  });
+});

package/src/sankey/compile-sankey.ts

@@ -37,6 +37,7 @@ import {
 
 import { resolveAnimation } from '../compiler/animation';
 import { compile as compileSpec } from '../compiler/index';
+import { ENTRY_GAP, measureLegendWrap, SWATCH_GAP, SWATCH_SIZE } from '../legend/wrap';
 import { type ComputedNode, computeSankeyLayout, generateLinkPath } from './layout';
 import type { NormalizedSankeySpec } from './types';
 
@@ -44,9 +45,6 @@ import type { NormalizedSankeySpec } from './types';
 // Constants
 // ---------------------------------------------------------------------------
 
-const SWATCH_SIZE = 12;
-const SWATCH_GAP = 6;
-const ENTRY_GAP = 16;
 const LABEL_GAP = 6;
 const LINK_OPACITY_LIGHT = 0.5;
 const LINK_OPACITY_DARK = 0.75;
@@ -570,23 +568,10 @@ function buildSankeyLegend(
     const ROW_HEIGHT = SWATCH_SIZE + 4;
     const availableWidth = area.width;
 
-    // Compute row count by simulating horizontal wrapping
-    let rowCount = 1;
-    let rowX = 0;
-    for (const entry of entries) {
-      const labelWidth = estimateTextWidth(entry.label, labelStyle.fontSize, labelStyle.fontWeight);
-      const entryWidth = SWATCH_SIZE + SWATCH_GAP + labelWidth + ENTRY_GAP;
-      if (rowX > 0 && rowX + entryWidth > availableWidth) {
-        rowCount++;
-        rowX = entryWidth;
-      } else {
-        rowX += entryWidth;
-      }
-    }
-
-    // Cap at 2 rows max
-    rowCount = Math.min(rowCount, 2);
-    const legendHeight = rowCount * ROW_HEIGHT;
+    // Compute row count via shared wrap geometry, then cap at 2 rows.
+    const { rowCount } = measureLegendWrap(entries, availableWidth, labelStyle);
+    const cappedRowCount = Math.min(rowCount, 2);
+    const legendHeight = cappedRowCount * ROW_HEIGHT;
 
     bounds = {
       x: area.x,