@opendata-ai/openchart-engine 6.7.1 → 6.9.0

package/src/sankey/compile-sankey.ts

@@ -28,6 +28,7 @@ import type {
 } from '@opendata-ai/openchart-core';
 import {
   adaptTheme,
+  buildD3Formatter,
   computeChrome,
   estimateTextWidth,
   formatNumber,
@@ -47,7 +48,8 @@ const SWATCH_SIZE = 12;
 const SWATCH_GAP = 6;
 const ENTRY_GAP = 16;
 const LABEL_GAP = 6;
-const LINK_OPACITY = 0.35;
+const LINK_OPACITY_LIGHT = 0.5;
+const LINK_OPACITY_DARK = 0.75;
 const NODE_CORNER_RADIUS = 2;
 
 // ---------------------------------------------------------------------------
@@ -129,18 +131,28 @@ function getLinkColors(
 
 /**
  * Determine label position for a node based on its column depth.
- * Leftmost column: label to the right.
- * Rightmost column: label to the left.
- * Middle columns: label to the right (default).
+ * Default ('auto'): leftmost/middle columns label right, rightmost column labels left.
+ * 'right': all labels to the right.  'left': all labels to the left.
  */
 function computeNodeLabel(
   node: ComputedNode,
   maxDepth: number,
   theme: ResolvedTheme,
   nodeWidth: number,
+  nodeLabelAlign: 'auto' | 'left' | 'right' = 'auto',
 ): SankeyNodeMark['label'] {
   const depth = node.depth ?? 0;
-  const isRightmost = depth === maxDepth;
+
+  // Determine which side to place the label
+  let placeLeft: boolean;
+  if (nodeLabelAlign === 'left') {
+    placeLeft = true;
+  } else if (nodeLabelAlign === 'right') {
+    placeLeft = false;
+  } else {
+    // 'auto': rightmost column goes left, everything else goes right
+    placeLeft = depth === maxDepth;
+  }
 
   const style: TextStyle = {
     fontFamily: theme.fonts.family,
@@ -156,8 +168,7 @@ function computeNodeLabel(
   const y1 = node.y1 ?? 0;
   const midY = (y0 + y1) / 2;
 
-  if (isRightmost) {
-    // Label to the left of the node
+  if (placeLeft) {
     return {
       text: node.label ?? node.id,
       x: x0 - LABEL_GAP,
@@ -167,7 +178,6 @@ function computeNodeLabel(
     };
   }
 
-  // Label to the right of the node (leftmost and middle columns)
   return {
     text: node.label ?? node.id,
     x: x1 + LABEL_GAP,
@@ -205,9 +215,18 @@ export function compileSankey(spec: unknown, options: CompileOptions): SankeyLay
   const mergedThemeConfig = options.theme
     ? { ...sankeySpec.theme, ...options.theme }
     : sankeySpec.theme;
-  let theme: ResolvedTheme = resolveTheme(mergedThemeConfig);
+  const lightTheme: ResolvedTheme = resolveTheme(mergedThemeConfig);
+  let theme: ResolvedTheme = lightTheme;
   if (options.darkMode) {
     theme = adaptTheme(theme);
+    // Sankey nodes and link gradients need vivid colors that stand out on dark
+    // backgrounds. The adapted palette preserves contrast ratios designed for
+    // text, but those contrast-matched colors are too dark for filled shapes.
+    // Use the original light-theme categorical palette for node/link colors.
+    theme = {
+      ...theme,
+      colors: { ...theme.colors, categorical: lightTheme.colors.categorical },
+    };
   }
 
   // 3. Compute chrome
@@ -282,19 +301,64 @@ export function compileSankey(spec: unknown, options: CompileOptions): SankeyLay
     return emptyLayout(area, chrome, theme, options);
   }
 
-  // 6. Run d3-sankey layout
-  const { nodes, links } = computeSankeyLayout(
+  // 6. Run d3-sankey layout (may re-run once if labels overflow)
+  const labelFontSize = theme.fonts.sizes.small;
+  const labelFontWeight = theme.fonts.weights.normal;
+  const nodeWidth = sankeySpec.nodeWidth ?? 12;
+
+  let layoutArea: Rect = { ...area };
+  let { nodes, links } = computeSankeyLayout(
     sankeySpec.data,
     sourceField,
     targetField,
     valueField,
-    area,
+    layoutArea,
     sankeySpec.nodeWidth,
     sankeySpec.nodePadding,
     sankeySpec.nodeAlign,
     sankeySpec.iterations,
   );
 
+  // 6b. Check if any right-side node labels overflow the right edge.
+  const nodeLabelAlign = sankeySpec.nodeLabelAlign ?? 'auto';
+  const maxDepthFirst = nodes.reduce((max, n) => Math.max(max, n.depth ?? 0), 0);
+  const rightEdge = area.x + area.width;
+  let maxOverflow = 0;
+  for (const node of nodes) {
+    const depth = node.depth ?? 0;
+    // Skip nodes whose labels go left (they can't overflow the right edge)
+    const labelsLeft =
+      nodeLabelAlign === 'left' || (nodeLabelAlign === 'auto' && depth === maxDepthFirst);
+    if (labelsLeft) continue;
+    const labelX = (node.x1 ?? nodeWidth) + LABEL_GAP;
+    const labelText = node.label ?? node.id;
+    const labelWidth = estimateTextWidth(labelText, labelFontSize, labelFontWeight);
+    const overflow = labelX + labelWidth - rightEdge;
+    if (overflow > maxOverflow) maxOverflow = overflow;
+  }
+
+  // Re-run layout with tighter width if labels would clip
+  if (maxOverflow > 0) {
+    const margin = Math.ceil(maxOverflow) + 4; // small extra buffer
+    layoutArea = {
+      x: area.x,
+      y: area.y,
+      width: Math.max(area.width - margin, 40),
+      height: area.height,
+    };
+    ({ nodes, links } = computeSankeyLayout(
+      sankeySpec.data,
+      sourceField,
+      targetField,
+      valueField,
+      layoutArea,
+      sankeySpec.nodeWidth,
+      sankeySpec.nodePadding,
+      sankeySpec.nodeAlign,
+      sankeySpec.iterations,
+    ));
+  }
+
   // 7. Build node color map
   const nodeColorMap = buildNodeColorMap(
     nodes,
@@ -321,14 +385,14 @@ export function compileSankey(spec: unknown, options: CompileOptions): SankeyLay
       height: (node.y1 ?? 0) - (node.y0 ?? 0),
       fill,
       cornerRadius: NODE_CORNER_RADIUS,
-      label: computeNodeLabel(node, maxDepth, theme, sankeySpec.nodeWidth),
+      label: computeNodeLabel(node, maxDepth, theme, sankeySpec.nodeWidth, nodeLabelAlign),
       nodeId: node.id,
       value: node.value ?? 0,
       depth,
       data: { id: node.id, label: node.label },
       aria: {
         role: 'img',
-        label: `${node.label}: ${formatNumber(node.value ?? 0)}`,
+        label: `${node.label}: ${formatFlowValue(node.value ?? 0, sankeySpec.valueFormat)}`,
       },
       animationIndex: 0, // Reassigned below after sorting by depth
     };
@@ -354,7 +418,8 @@ export function compileSankey(spec: unknown, options: CompileOptions): SankeyLay
       path: generateLinkPath(link),
       sourceColor: colors.sourceColor,
       targetColor: colors.targetColor,
-      fillOpacity: LINK_OPACITY,
+      fillOpacity:
+        sankeySpec.linkOpacity ?? (options.darkMode ? LINK_OPACITY_DARK : LINK_OPACITY_LIGHT),
       sourceId: sourceNode.id,
       targetId: targetNode.id,
       width: link.width ?? 0,
@@ -362,7 +427,7 @@ export function compileSankey(spec: unknown, options: CompileOptions): SankeyLay
       data: (link as unknown as { data: Record<string, unknown> }).data ?? {},
       aria: {
         role: 'img',
-        label: `${sourceNode.label} to ${targetNode.label}: ${formatNumber(link.value)}`,
+        label: `${sourceNode.label} to ${targetNode.label}: ${formatFlowValue(link.value, sankeySpec.valueFormat)}`,
       },
       // Links animate after nodes
       animationIndex: nodeMarks.length + i,
@@ -381,7 +446,7 @@ export function compileSankey(spec: unknown, options: CompileOptions): SankeyLay
   );
 
   // 13. Build tooltip descriptors
-  const tooltipDescriptors = buildTooltipDescriptors(nodeMarks, linkMarks);
+  const tooltipDescriptors = buildTooltipDescriptors(nodeMarks, linkMarks, sankeySpec.valueFormat);
 
   // 14. Build a11y metadata
   const a11y = {
@@ -510,9 +575,18 @@ function buildSankeyLegend(
 // Tooltip builder
 // ---------------------------------------------------------------------------
 
+function formatFlowValue(value: number, valueFormat?: string): string {
+  if (valueFormat) {
+    const fmt = buildD3Formatter(valueFormat);
+    if (fmt) return fmt(value);
+  }
+  return formatNumber(value);
+}
+
 function buildTooltipDescriptors(
   nodes: SankeyNodeMark[],
   links: SankeyLinkMark[],
+  valueFormat?: string,
 ): Map<string, TooltipContent> {
   const descriptors = new Map<string, TooltipContent>();
 
@@ -521,7 +595,7 @@ function buildTooltipDescriptors(
     const fields: TooltipField[] = [
       {
         label: 'Total flow',
-        value: formatNumber(node.value),
+        value: formatFlowValue(node.value, valueFormat),
       },
     ];
     descriptors.set(`node-${node.nodeId}`, {
@@ -531,14 +605,15 @@ function buildTooltipDescriptors(
   }
 
   // Link tooltips: keyed by "link-{sourceId}-{targetId}" to match renderer data-mark-id
-  for (const link of links) {
+  for (let i = 0; i < links.length; i++) {
+    const link = links[i];
     const fields: TooltipField[] = [
       {
         label: 'Flow',
-        value: formatNumber(link.value),
+        value: formatFlowValue(link.value, valueFormat),
       },
     ];
-    descriptors.set(`link-${link.sourceId}-${link.targetId}`, {
+    descriptors.set(`link-${link.sourceId}-${link.targetId}-${i}`, {
       title: `${link.sourceId} \u2192 ${link.targetId}`,
       fields,
     });

package/src/sankey/types.ts

@@ -28,9 +28,12 @@ export interface NormalizedSankeySpec {
   nodeAlign: SankeyNodeAlign;
   iterations: number;
   linkStyle: SankeyLinkColor;
+  nodeLabelAlign: 'auto' | 'left' | 'right';
   chrome: NormalizedChrome;
   legend?: LegendConfig;
   theme: ThemeConfig;
   darkMode: DarkMode;
   animation?: AnimationSpec;
+  valueFormat?: string;
+  linkOpacity?: number;
 }

package/src/tables/__tests__/format-cells.test.ts

@@ -106,6 +106,18 @@ describe('formatCell', () => {
     const result = formatCell('not a number', col);
     expect(result.formattedValue).toBe('not a number');
   });
+
+  it('supports literal suffix format .0f%', () => {
+    const col: ColumnConfig = { key: 'x', format: '.0f%' };
+    const result = formatCell(32.5, col);
+    expect(result.formattedValue).toBe('33%');
+  });
+
+  it('supports literal suffix format $,.2~fT', () => {
+    const col: ColumnConfig = { key: 'x', format: '$,.2~fT' };
+    const result = formatCell(3.75, col);
+    expect(result.formattedValue).toBe('$3.75T');
+  });
 });
 
 describe('formatValueForSearch', () => {
@@ -123,4 +135,9 @@ describe('formatValueForSearch', () => {
     const col: ColumnConfig = { key: 'x' };
     expect(formatValueForSearch('hello', col)).toBe('hello');
   });
+
+  it('supports literal suffix format in search', () => {
+    const col: ColumnConfig = { key: 'x', format: '.0f%' };
+    expect(formatValueForSearch(32.5, col)).toBe('33%');
+  });
 });

package/src/tables/format-cells.ts

@@ -7,8 +7,7 @@
  */
 
 import type { CellStyle, ColumnConfig, TableCellBase } from '@opendata-ai/openchart-core';
-import { formatDate, formatNumber } from '@opendata-ai/openchart-core';
-import { format as d3Format } from 'd3-format';
+import { buildD3Formatter, formatDate, formatNumber } from '@opendata-ai/openchart-core';
 
 /**
  * Check if a value is numeric (finite number or parseable numeric string).
@@ -49,15 +48,13 @@ export function formatCell(value: unknown, column: ColumnConfig): TableCellBase
 
   // If column has a d3-format string and value is numeric
   if (column.format && isNumericValue(value)) {
-    try {
-      const formatter = d3Format(column.format);
+    const formatter = buildD3Formatter(column.format);
+    if (formatter) {
       return {
         value,
         formattedValue: formatter(value),
         style,
       };
-    } catch {
-      // Fall through to auto-format if format string is invalid
     }
   }
 
@@ -95,10 +92,9 @@ export function formatValueForSearch(value: unknown, column: ColumnConfig): stri
   if (value == null) return '';
 
   if (column.format && isNumericValue(value)) {
-    try {
-      return d3Format(column.format)(value);
-    } catch {
-      // Fall through
+    const formatter = buildD3Formatter(column.format);
+    if (formatter) {
+      return formatter(value);
     }
   }