@opendata-ai/openchart-engine 8.0.0-rc.12 → 8.0.0-rc.3

package/src/sankey/compile-sankey.ts

@@ -0,0 +1,706 @@
+/**
+ * Sankey diagram compilation pipeline.
+ *
+ * Takes a raw sankey spec (unknown shape), validates, normalizes, resolves
+ * theme, computes chrome, runs d3-sankey layout, builds marks with colors
+ * and labels, and returns a SankeyLayout.
+ *
+ * Pipeline:
+ *   validate -> normalize -> resolve theme -> dark mode adapt ->
+ *   compute chrome -> compute drawing area -> d3-sankey layout ->
+ *   build node marks -> build link marks -> legend -> tooltips ->
+ *   a11y -> animation -> return SankeyLayout
+ */
+
+import type {
+  CompileOptions,
+  LegendEntry,
+  LegendLayout,
+  NumberFormatter,
+  Rect,
+  ResolvedAnimation,
+  ResolvedTheme,
+  SankeyLayout,
+  SankeyLinkMark,
+  SankeyNodeMark,
+  TextStyle,
+  TooltipContent,
+  TooltipField,
+} from '@opendata-ai/openchart-core';
+import {
+  adaptTheme,
+  computeChrome,
+  defaultNumberFormatter,
+  estimateTextWidth,
+  resolveTheme,
+} from '@opendata-ai/openchart-core';
+import { emitSpecWarnings, expandSpecSugar } from '../compile/spec-sugar';
+import { resolveAnimation } from '../compiler/animation';
+import { compile as compileSpec } from '../compiler/index';
+import { resolveFieldFormatter } from '../format/field-format';
+import { ENTRY_GAP, measureLegendWrap, SWATCH_GAP, SWATCH_SIZE } from '../legend/wrap';
+import { type ComputedNode, computeSankeyLayout, generateLinkPath } from './layout';
+import type { NormalizedSankeySpec } from './types';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const LABEL_GAP = 6;
+const LINK_OPACITY_LIGHT = 0.5;
+const LINK_OPACITY_DARK = 0.75;
+const NODE_CORNER_RADIUS = 2;
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Assign a color from the categorical palette, cycling through it. */
+function pickColor(palette: string[], index: number): string {
+  return palette[index % palette.length];
+}
+
+/**
+ * Build a color map for nodes.
+ * If encoding.color is specified, groups by that field's value.
+ * Otherwise, assigns by unique node ID cycling the palette.
+ * Accepts any array with `id` field (works with ComputedNode[] or plain objects).
+ */
+function buildNodeColorMap(
+  nodes: Array<{ id: string }>,
+  palette: string[],
+  colorField: string | undefined,
+  data: Record<string, unknown>[],
+  sourceField: string,
+  targetField: string,
+): Map<string, string> {
+  const colorMap = new Map<string, string>();
+
+  if (colorField) {
+    // Build a mapping from node ID to color category value
+    const nodeCategoryMap = new Map<string, string>();
+    for (const row of data) {
+      const src = String(row[sourceField]);
+      const tgt = String(row[targetField]);
+      const cat = String(row[colorField]);
+      if (!nodeCategoryMap.has(src)) nodeCategoryMap.set(src, cat);
+      if (!nodeCategoryMap.has(tgt)) nodeCategoryMap.set(tgt, cat);
+    }
+
+    // Assign colors by unique category
+    const categoryIndex = new Map<string, number>();
+    let nextIdx = 0;
+    for (const node of nodes) {
+      const category = nodeCategoryMap.get(node.id) ?? node.id;
+      if (!categoryIndex.has(category)) {
+        categoryIndex.set(category, nextIdx++);
+      }
+      colorMap.set(node.id, pickColor(palette, categoryIndex.get(category)!));
+    }
+  } else {
+    // Default: assign colors cycling through palette by node order
+    for (let i = 0; i < nodes.length; i++) {
+      colorMap.set(nodes[i].id, pickColor(palette, i));
+    }
+  }
+
+  return colorMap;
+}
+
+/**
+ * Get colors for a link based on the linkStyle strategy.
+ */
+function getLinkColors(
+  linkStyle: string,
+  sourceColor: string,
+  targetColor: string,
+  neutralColor: string,
+): { sourceColor: string; targetColor: string } {
+  switch (linkStyle) {
+    case 'source':
+      return { sourceColor, targetColor: sourceColor };
+    case 'target':
+      return { sourceColor: targetColor, targetColor };
+    case 'neutral':
+      return { sourceColor: neutralColor, targetColor: neutralColor };
+    default:
+      return { sourceColor, targetColor };
+  }
+}
+
+/**
+ * Determine label position for a node based on its column depth.
+ * 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',
+  containerWidth?: number,
+  padding?: number,
+): SankeyNodeMark['label'] {
+  const depth = node.depth ?? 0;
+
+  // 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,
+    fontSize: theme.fonts.sizes.small,
+    fontWeight: theme.fonts.weights.normal,
+    fill: theme.colors.text,
+    lineHeight: 1.3,
+  };
+
+  const x0 = node.x0 ?? 0;
+  const x1 = node.x1 ?? nodeWidth;
+  const y0 = node.y0 ?? 0;
+  const y1 = node.y1 ?? 0;
+  const midY = (y0 + y1) / 2;
+
+  // Compute maxWidth: space from label position to the container edge
+  const pad = padding ?? 0;
+  let maxWidth: number | undefined;
+  if (containerWidth !== undefined) {
+    if (placeLeft) {
+      // Label goes left from x0: available space is from left padding to x0
+      maxWidth = x0 - LABEL_GAP - pad;
+    } else {
+      // Label goes right from x1: available space is from x1 to right edge
+      maxWidth = containerWidth - pad - (x1 + LABEL_GAP);
+    }
+    if (maxWidth !== undefined && maxWidth < 0) maxWidth = 0;
+  }
+
+  if (placeLeft) {
+    return {
+      text: node.label ?? node.id,
+      x: x0 - LABEL_GAP,
+      y: midY,
+      style: { ...style, textAnchor: 'end', dominantBaseline: 'central' },
+      visible: true,
+      maxWidth,
+    };
+  }
+
+  return {
+    text: node.label ?? node.id,
+    x: x1 + LABEL_GAP,
+    y: midY,
+    style: { ...style, textAnchor: 'start', dominantBaseline: 'central' },
+    visible: true,
+    maxWidth,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Compile a sankey spec into a SankeyLayout.
+ *
+ * @param spec - Raw sankey spec (validated at runtime).
+ * @param options - Compile options (width, height, theme, darkMode).
+ * @returns SankeyLayout with all computed positions and visual properties.
+ * @throws Error if spec is invalid or not a sankey type.
+ */
+export function compileSankey(spec: unknown, options: CompileOptions): SankeyLayout {
+  // 1. Expand deprecated top-level sugar (valueFormat -> encoding.value.format)
+  // before validation, then validate + normalize via the shared compiler pipeline.
+  const sugarWarnings: string[] = [];
+  const expandedSpec =
+    spec && typeof spec === 'object' && !Array.isArray(spec)
+      ? expandSpecSugar(spec as Record<string, unknown>, sugarWarnings)
+      : spec;
+  const { spec: normalized, warnings } = compileSpec(expandedSpec);
+  emitSpecWarnings([...sugarWarnings, ...warnings], options.onWarn);
+
+  if (!('type' in normalized) || normalized.type !== 'sankey') {
+    throw new Error(
+      'compileSankey received a non-sankey spec. Use compileChart, compileTable, or compileGraph instead.',
+    );
+  }
+
+  const sankeySpec = normalized as NormalizedSankeySpec;
+
+  // Resolve format: encoding-level (v8 canonical) wins over deprecated top-level valueFormat
+  const resolvedValueFormat = sankeySpec.encoding.value.format ?? sankeySpec.valueFormat;
+
+  // Resolve watermark: explicit spec value wins, then options fallback, then default true.
+  const rawWatermark = (spec as Record<string, unknown>).watermark;
+  const watermark = rawWatermark !== undefined ? sankeySpec.watermark : (options.watermark ?? true);
+
+  // 2. Resolve theme
+  const mergedThemeConfig = options.theme
+    ? { ...sankeySpec.theme, ...options.theme }
+    : sankeySpec.theme;
+  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
+  const chrome = computeChrome(
+    {
+      title: sankeySpec.chrome.title,
+      subtitle: sankeySpec.chrome.subtitle,
+      source: sankeySpec.chrome.source,
+      byline: sankeySpec.chrome.byline,
+      footer: sankeySpec.chrome.footer,
+    },
+    theme,
+    options.width,
+    options.measureText,
+    'full',
+    undefined,
+    watermark,
+  );
+
+  // 4. Compute drawing area (total space minus chrome)
+  const padding = theme.spacing.padding;
+  const fullArea: Rect = {
+    x: padding,
+    y: padding + chrome.topHeight,
+    width: options.width - padding * 2,
+    height: options.height - chrome.topHeight - chrome.bottomHeight - padding * 2,
+  };
+
+  // Guard against negative dimensions
+  if (fullArea.width <= 0 || fullArea.height <= 0) {
+    return emptyLayout(fullArea, chrome, theme, options, watermark);
+  }
+
+  // 5. Extract encoding fields
+  const sourceField = sankeySpec.encoding.source.field;
+  const targetField = sankeySpec.encoding.target.field;
+  const valueField = sankeySpec.encoding.value.field;
+  const colorField = sankeySpec.encoding.color?.field;
+  const flowFmt = resolveFieldFormatter({
+    surfaceFormat: resolvedValueFormat,
+    values: sankeySpec.data.map((r) => r[valueField]),
+  });
+
+  // 5b. Pre-compute legend to reserve vertical space
+  //     We need the color map first, so build a temporary one from raw data
+  const tempNodeIds = new Set<string>();
+  for (const row of sankeySpec.data) {
+    tempNodeIds.add(String(row[sourceField]));
+    tempNodeIds.add(String(row[targetField]));
+  }
+  const tempColorMap = buildNodeColorMap(
+    [...tempNodeIds].map((id) => ({ id })),
+    theme.colors.categorical,
+    colorField,
+    sankeySpec.data,
+    sourceField,
+    targetField,
+  );
+  const legend = buildSankeyLegend(
+    tempColorMap,
+    colorField,
+    sankeySpec.data,
+    sourceField,
+    targetField,
+    theme,
+    fullArea,
+  );
+
+  // Reserve legend space by shrinking the drawing area
+  const legendGap = 'entries' in legend && legend.entries.length > 0 ? 4 : 0;
+  const area: Rect = {
+    x: fullArea.x,
+    y: fullArea.y + legend.bounds.height + legendGap,
+    width: fullArea.width,
+    height: fullArea.height - legend.bounds.height - legendGap,
+  };
+
+  if (area.height <= 0) {
+    return emptyLayout(area, chrome, theme, options, watermark);
+  }
+
+  // 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,
+    layoutArea,
+    sankeySpec.nodeWidth,
+    sankeySpec.nodePadding,
+    sankeySpec.nodeAlign,
+    sankeySpec.iterations,
+    sankeySpec.nodeSort,
+  );
+
+  // 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,
+      sankeySpec.nodeSort,
+    ));
+  }
+
+  // 7. Build node color map
+  const nodeColorMap = buildNodeColorMap(
+    nodes,
+    theme.colors.categorical,
+    colorField,
+    sankeySpec.data,
+    sourceField,
+    targetField,
+  );
+
+  // 8. Compute max depth for label positioning
+  const maxDepth = nodes.reduce((max, n) => Math.max(max, n.depth ?? 0), 0);
+
+  // 9. Build SankeyNodeMark[]
+  const nodeMarks: SankeyNodeMark[] = nodes.map((node) => {
+    const fill = nodeColorMap.get(node.id) ?? theme.colors.categorical[0];
+    const depth = node.depth ?? 0;
+
+    return {
+      type: 'sankeyNode' as const,
+      x: node.x0 ?? 0,
+      y: node.y0 ?? 0,
+      width: (node.x1 ?? 0) - (node.x0 ?? 0),
+      height: (node.y1 ?? 0) - (node.y0 ?? 0),
+      fill,
+      cornerRadius: NODE_CORNER_RADIUS,
+      label: computeNodeLabel(
+        node,
+        maxDepth,
+        theme,
+        sankeySpec.nodeWidth,
+        nodeLabelAlign,
+        options.width,
+        padding,
+      ),
+      nodeId: node.id,
+      value: node.value ?? 0,
+      depth,
+      data: { id: node.id, label: node.label },
+      aria: {
+        role: 'img',
+        label: `${node.label}: ${formatFlowValue(node.value ?? 0, flowFmt)}`,
+      },
+      animationIndex: 0, // Reassigned below after sorting by depth
+    };
+  });
+
+  // 10. Assign node animation indices by column (left-to-right, top-to-bottom within column)
+  nodeMarks.sort((a, b) => a.depth - b.depth || a.y - b.y);
+  for (let i = 0; i < nodeMarks.length; i++) {
+    nodeMarks[i].animationIndex = i;
+  }
+
+  // 11. Build SankeyLinkMark[]
+  const neutralColor = theme.colors.gridline;
+  const linkMarks: SankeyLinkMark[] = links.map((link, i) => {
+    const sourceNode = link.source as ComputedNode;
+    const targetNode = link.target as ComputedNode;
+    const srcColor = nodeColorMap.get(sourceNode.id) ?? theme.colors.categorical[0];
+    const tgtColor = nodeColorMap.get(targetNode.id) ?? theme.colors.categorical[0];
+    const colors = getLinkColors(sankeySpec.linkStyle, srcColor, tgtColor, neutralColor);
+
+    return {
+      type: 'sankeyLink' as const,
+      path: generateLinkPath(link),
+      sourceColor: colors.sourceColor,
+      targetColor: colors.targetColor,
+      fillOpacity:
+        sankeySpec.linkOpacity ?? (options.darkMode ? LINK_OPACITY_DARK : LINK_OPACITY_LIGHT),
+      sourceId: sourceNode.id,
+      targetId: targetNode.id,
+      width: link.width ?? 0,
+      value: link.value,
+      data: (link as unknown as { data: Record<string, unknown> }).data ?? {},
+      aria: {
+        role: 'img',
+        label: `${sourceNode.label} to ${targetNode.label}: ${formatFlowValue(link.value, flowFmt)}`,
+      },
+      // Links animate after nodes
+      animationIndex: nodeMarks.length + i,
+    };
+  });
+
+  // 12. Rebuild legend with final color map (temp map may differ in node order)
+  const finalLegend = buildSankeyLegend(
+    nodeColorMap,
+    colorField,
+    sankeySpec.data,
+    sourceField,
+    targetField,
+    theme,
+    fullArea,
+  );
+
+  // 13. Build tooltip descriptors
+  const tooltipDescriptors = buildTooltipDescriptors(nodeMarks, linkMarks, flowFmt);
+
+  // 14. Build a11y metadata
+  const a11y = {
+    altText: `Sankey diagram with ${nodeMarks.length} nodes and ${linkMarks.length} links`,
+    dataTableFallback: linkMarks.map((l) => [l.sourceId, l.targetId, String(l.value)]),
+    role: 'img',
+    keyboardNavigable: nodeMarks.length > 0,
+  };
+
+  // 15. Resolve animation
+  const resolvedAnimation: ResolvedAnimation | undefined = resolveAnimation(sankeySpec.animation);
+
+  return {
+    area,
+    chrome,
+    nodes: nodeMarks,
+    links: linkMarks,
+    legend: finalLegend,
+    tooltipDescriptors,
+    a11y,
+    theme,
+    dimensions: {
+      width: options.width,
+      height: options.height,
+    },
+    animation: resolvedAnimation,
+    watermark,
+    measureText: options.measureText,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Legend builder
+// ---------------------------------------------------------------------------
+
+function buildSankeyLegend(
+  nodeColorMap: Map<string, string>,
+  colorField: string | undefined,
+  data: Record<string, unknown>[],
+  sourceField: string,
+  targetField: string,
+  theme: ResolvedTheme,
+  area: Rect,
+): LegendLayout {
+  const labelStyle: TextStyle = {
+    fontFamily: theme.fonts.family,
+    fontSize: theme.fonts.sizes.small,
+    fontWeight: theme.fonts.weights.normal,
+    fill: theme.colors.text,
+    lineHeight: 1.3,
+  };
+
+  let entries: LegendEntry[];
+
+  if (colorField) {
+    // Group by color field value for legend entries
+    const categoryColors = new Map<string, string>();
+    const nodeCategoryMap = new Map<string, string>();
+    for (const row of data) {
+      const src = String(row[sourceField]);
+      const tgt = String(row[targetField]);
+      const cat = String(row[colorField]);
+      if (!nodeCategoryMap.has(src)) nodeCategoryMap.set(src, cat);
+      if (!nodeCategoryMap.has(tgt)) nodeCategoryMap.set(tgt, cat);
+    }
+    for (const [nodeId, category] of nodeCategoryMap) {
+      if (!categoryColors.has(category)) {
+        categoryColors.set(category, nodeColorMap.get(nodeId) ?? theme.colors.categorical[0]);
+      }
+    }
+
+    entries = [...categoryColors.entries()].map(([label, color]) => ({
+      label,
+      color,
+      shape: 'square' as const,
+      active: true,
+    }));
+  } else {
+    // No color encoding: no legend needed (nodes are individually colored)
+    entries = [];
+  }
+
+  // Compute bounds for horizontal top legend
+  let bounds = { x: 0, y: 0, width: 0, height: 0 };
+
+  if (entries.length > 0) {
+    const ROW_HEIGHT = SWATCH_SIZE + 4;
+    const availableWidth = area.width;
+
+    // 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,
+      y: area.y,
+      width: availableWidth,
+      height: legendHeight,
+    };
+  }
+
+  return {
+    position: 'top',
+    entries,
+    bounds,
+    labelStyle,
+    swatchSize: SWATCH_SIZE,
+    swatchGap: SWATCH_GAP,
+    entryGap: ENTRY_GAP,
+    swatchChipFill: theme.colors.annotationFill,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Tooltip builder
+// ---------------------------------------------------------------------------
+
+const defaultFmt = defaultNumberFormatter();
+
+function formatFlowValue(value: number, formatter?: NumberFormatter | null): string {
+  if (formatter) return formatter(value);
+  return defaultFmt(value);
+}
+
+function buildTooltipDescriptors(
+  nodes: SankeyNodeMark[],
+  links: SankeyLinkMark[],
+  formatter?: NumberFormatter | null,
+): Map<string, TooltipContent> {
+  const descriptors = new Map<string, TooltipContent>();
+
+  for (const node of nodes) {
+    const fields: TooltipField[] = [
+      {
+        label: 'Total flow',
+        value: formatFlowValue(node.value, formatter),
+      },
+    ];
+    descriptors.set(`node-${node.nodeId}`, {
+      title: node.label.text,
+      fields,
+    });
+  }
+
+  for (let i = 0; i < links.length; i++) {
+    const link = links[i];
+    const fields: TooltipField[] = [
+      {
+        label: 'Flow',
+        value: formatFlowValue(link.value, formatter),
+      },
+    ];
+    descriptors.set(`link-${link.sourceId}-${link.targetId}-${i}`, {
+      title: `${link.sourceId} \u2192 ${link.targetId}`,
+      fields,
+    });
+  }
+
+  return descriptors;
+}
+
+// ---------------------------------------------------------------------------
+// Empty layout fallback
+// ---------------------------------------------------------------------------
+
+function emptyLayout(
+  area: Rect,
+  chrome: ReturnType<typeof computeChrome>,
+  theme: ResolvedTheme,
+  options: CompileOptions,
+  watermark: boolean,
+): SankeyLayout {
+  return {
+    area,
+    chrome,
+    nodes: [],
+    links: [],
+    legend: {
+      position: 'top',
+      entries: [],
+      bounds: { x: 0, y: 0, width: 0, height: 0 },
+      labelStyle: {
+        fontFamily: theme.fonts.family,
+        fontSize: theme.fonts.sizes.small,
+        fontWeight: theme.fonts.weights.normal,
+        fill: theme.colors.text,
+        lineHeight: 1.3,
+      },
+      swatchSize: SWATCH_SIZE,
+      swatchGap: SWATCH_GAP,
+      entryGap: ENTRY_GAP,
+      swatchChipFill: theme.colors.annotationFill,
+    },
+    tooltipDescriptors: new Map(),
+    a11y: {
+      altText: 'Empty sankey diagram',
+      dataTableFallback: [],
+      role: 'img',
+      keyboardNavigable: false,
+    },
+    theme,
+    dimensions: {
+      width: options.width,
+      height: options.height,
+    },
+    watermark,
+  };
+}