@opendata-ai/openchart-engine 6.19.2 → 6.20.0

package/src/legend/wrap.ts

@@ -0,0 +1,94 @@
+/**
+ * Legend row-wrap geometry.
+ *
+ * Shared helper for measuring how legend entries flow across horizontal rows
+ * when wrapped at a max width. Both the main legend compute and the sankey
+ * legend compile use this to size their legends — the main legend uses
+ * `fittingCount` for truncation decisions, while sankey uses `rowCount` to
+ * reserve vertical height.
+ *
+ * The geometry matches the existing layout exactly: each entry occupies
+ * SWATCH_SIZE + SWATCH_GAP + labelWidth + ENTRY_GAP pixels, a new row is
+ * started when the accumulated row width plus the next entry would exceed
+ * maxWidth (and the current row is non-empty), and rowWidths captures the
+ * in-row accumulated width at the point of wrapping.
+ */
+
+import type { LegendEntry, TextStyle } from '@opendata-ai/openchart-core';
+import { estimateTextWidth } from '@opendata-ai/openchart-core';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+//
+// Single source of truth for legend row geometry. Both compute.ts and the
+// sankey compile site import these so the wrap math here can never drift from
+// the layout math at the call sites.
+
+export const SWATCH_SIZE = 12;
+export const SWATCH_GAP = 6;
+export const ENTRY_GAP = 16;
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export interface LegendWrapResult {
+  /** Total number of rows the entries occupy when wrapped at maxWidth. */
+  rowCount: number;
+  /** Entries that fit within maxRows (for truncation). Equals entries.length when maxRows is not set or all entries fit. */
+  fittingCount: number;
+  /** Width (in px) of each row — callers can use for alignment. */
+  rowWidths: number[];
+}
+
+/**
+ * Measure how legend entries wrap across rows at a given max width.
+ *
+ * @param entries - Legend entries to measure.
+ * @param maxWidth - Maximum width (in px) available for a single row.
+ * @param labelStyle - Text style used to estimate label widths.
+ * @param maxRows - Optional cap used only for the `fittingCount` truncation decision. When provided, `fittingCount` will be the index of the first entry that would spill onto a row beyond `maxRows`. `rowCount` is always the real row count regardless of this cap.
+ */
+export function measureLegendWrap(
+  entries: LegendEntry[],
+  maxWidth: number,
+  labelStyle: TextStyle,
+  maxRows?: number,
+): LegendWrapResult {
+  if (entries.length === 0) {
+    return { rowCount: 0, fittingCount: 0, rowWidths: [] };
+  }
+
+  let rowCount = 1;
+  let rowWidth = 0;
+  const rowWidths: number[] = [];
+  let fittingCount = entries.length;
+  let fittingCountLocked = false;
+
+  for (let i = 0; i < entries.length; i++) {
+    const labelWidth = estimateTextWidth(
+      entries[i].label,
+      labelStyle.fontSize,
+      labelStyle.fontWeight,
+    );
+    const entryWidth = SWATCH_SIZE + SWATCH_GAP + labelWidth + ENTRY_GAP;
+
+    if (rowWidth + entryWidth > maxWidth && rowWidth > 0) {
+      rowWidths.push(rowWidth);
+      rowCount++;
+      rowWidth = entryWidth;
+      if (!fittingCountLocked && maxRows != null && rowCount > maxRows) {
+        fittingCount = i;
+        fittingCountLocked = true;
+      }
+    } else {
+      rowWidth += entryWidth;
+    }
+  }
+
+  // Flush the final row width so rowWidths has one entry per row.
+  rowWidths.push(rowWidth);
+
+  return { rowCount, fittingCount, rowWidths };
+}

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,