@opendata-ai/openchart-engine 8.0.0-rc.9 → 8.1.0

package/src/sankey/layout.ts

@@ -1,184 +0,0 @@
-/**
- * d3-sankey layout wrapper.
- *
- * Extracts unique nodes from tabular data rows, configures the d3-sankey
- * generator, and returns computed node/link positions. Clones input data
- * before passing to d3-sankey since it mutates objects in place.
- */
-
-import type { Rect, SankeyNodeAlign } from '@opendata-ai/openchart-core';
-import type { SankeyExtraProperties, SankeyGraph, SankeyLink, SankeyNode } from 'd3-sankey';
-import { sankey, sankeyCenter, sankeyJustify, sankeyLeft, sankeyRight } from 'd3-sankey';
-
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-
-/** Extra properties carried on our sankey nodes. */
-interface NodeExtra extends SankeyExtraProperties {
-  id: string;
-  label: string;
-}
-
-/** Extra properties carried on our sankey links. */
-interface LinkExtra extends SankeyExtraProperties {
-  /** Original data row for this link. */
-  data: Record<string, unknown>;
-}
-
-export type ComputedNode = SankeyNode<NodeExtra, LinkExtra>;
-export type ComputedLink = SankeyLink<NodeExtra, LinkExtra>;
-
-export interface SankeyLayoutResult {
-  nodes: ComputedNode[];
-  links: ComputedLink[];
-}
-
-// ---------------------------------------------------------------------------
-// Alignment resolver
-// ---------------------------------------------------------------------------
-
-const ALIGN_MAP: Record<SankeyNodeAlign, typeof sankeyJustify> = {
-  justify: sankeyJustify,
-  left: sankeyLeft,
-  right: sankeyRight,
-  center: sankeyCenter,
-};
-
-// ---------------------------------------------------------------------------
-// Public API
-// ---------------------------------------------------------------------------
-
-/**
- * Run the d3-sankey layout algorithm on tabular flow data.
- *
- * @param data - Array of data rows (each row is a source-target-value flow).
- * @param sourceField - Field name for the source node.
- * @param targetField - Field name for the target node.
- * @param valueField - Field name for the flow value.
- * @param area - Drawing area rect (after chrome subtracted).
- * @param nodeWidth - Width of node rectangles in px.
- * @param nodePadding - Vertical padding between nodes in px.
- * @param nodeAlign - Node alignment strategy.
- * @param iterations - Number of layout relaxation iterations.
- * @returns Computed node and link positions.
- */
-export function computeSankeyLayout(
-  data: Record<string, unknown>[],
-  sourceField: string,
-  targetField: string,
-  valueField: string,
-  area: Rect,
-  nodeWidth: number,
-  nodePadding: number,
-  nodeAlign: SankeyNodeAlign,
-  iterations: number,
-  nodeSort?: string[],
-): SankeyLayoutResult {
-  // Extract unique node IDs from source and target columns
-  const nodeSet = new Set<string>();
-  for (const row of data) {
-    nodeSet.add(String(row[sourceField]));
-    nodeSet.add(String(row[targetField]));
-  }
-
-  // Build node and link arrays (cloned so d3-sankey mutations don't affect input)
-  const nodes: Array<{ id: string; label: string }> = [...nodeSet].map((id) => ({
-    id,
-    label: id,
-  }));
-
-  const links: Array<{
-    source: string;
-    target: string;
-    value: number;
-    data: Record<string, unknown>;
-  }> = data.map((row) => ({
-    source: String(row[sourceField]),
-    target: String(row[targetField]),
-    value: Number(row[valueField]) || 0,
-    data: { ...row },
-  }));
-
-  // Configure and run d3-sankey
-  const alignFn = ALIGN_MAP[nodeAlign] ?? sankeyJustify;
-
-  const generator = sankey<SankeyGraph<NodeExtra, LinkExtra>, NodeExtra, LinkExtra>()
-    .nodeId((d) => d.id)
-    .nodeAlign(alignFn as unknown as (node: SankeyNode<NodeExtra, LinkExtra>, n: number) => number)
-    .nodeWidth(nodeWidth)
-    .nodePadding(nodePadding)
-    .extent([
-      [area.x, area.y],
-      [area.x + area.width, area.y + area.height],
-    ])
-    .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>>,
-  });
-
-  return {
-    nodes: graph.nodes,
-    links: graph.links,
-  };
-}
-
-/**
- * Generate a filled ribbon SVG path for a sankey link.
- *
- * d3-sankey's sankeyLinkHorizontal() only produces a stroke centerline.
- * This generates a closed area path with two cubic bezier edges (top and
- * bottom) forming a ribbon whose width is proportional to flow value.
- *
- * The link object from d3-sankey provides:
- *   - y0: center y at source side
- *   - y1: center y at target side
- *   - width: thickness of the ribbon
- *   - source.x1: right edge of source node
- *   - target.x0: left edge of target node
- */
-export function generateLinkPath(link: ComputedLink): string {
-  const source = link.source as ComputedNode;
-  const target = link.target as ComputedNode;
-
-  const x0 = source.x1 ?? 0;
-  const x1 = target.x0 ?? 0;
-  const y0 = link.y0 ?? 0;
-  const y1 = link.y1 ?? 0;
-  const halfWidth0 = (link.width ?? 0) / 2;
-  const halfWidth1 = halfWidth0;
-
-  // Control point x at the horizontal midpoint for smooth S-curves
-  const mx = (x0 + x1) / 2;
-
-  // Top edge: left-to-right
-  const topY0 = y0 - halfWidth0;
-  const topY1 = y1 - halfWidth1;
-
-  // Bottom edge: right-to-left
-  const botY0 = y0 + halfWidth0;
-  const botY1 = y1 + halfWidth1;
-
-  return [
-    `M${x0},${topY0}`,
-    `C${mx},${topY0} ${mx},${topY1} ${x1},${topY1}`,
-    `L${x1},${botY1}`,
-    `C${mx},${botY1} ${mx},${botY0} ${x0},${botY0}`,
-    'Z',
-  ].join(' ');
-}

package/src/sankey/types.ts

@@ -1,41 +0,0 @@
-/**
- * Internal normalized sankey spec type used by the compilation pipeline.
- *
- * This mirrors NormalizedChartSpec/NormalizedGraphSpec: all optional fields
- * have been filled with sensible defaults. It's an engine implementation
- * detail, not a public contract.
- */
-
-import type {
-  AnimationSpec,
-  DarkMode,
-  LegendConfig,
-  SankeyEncoding,
-  SankeyLinkColor,
-  SankeyNodeAlign,
-  ThemeConfig,
-} from '@opendata-ai/openchart-core';
-
-import type { NormalizedChrome } from '../compiler/types';
-
-/** A SankeySpec with all optional fields filled with defaults. */
-export interface NormalizedSankeySpec {
-  type: 'sankey';
-  data: Record<string, unknown>[];
-  encoding: SankeyEncoding;
-  nodeWidth: number;
-  nodePadding: number;
-  nodeAlign: SankeyNodeAlign;
-  iterations: number;
-  linkStyle: SankeyLinkColor;
-  nodeLabelAlign: 'auto' | 'left' | 'right';
-  nodeSort?: string[];
-  chrome: NormalizedChrome;
-  legend?: LegendConfig;
-  theme: ThemeConfig;
-  darkMode: DarkMode;
-  watermark: boolean;
-  animation?: AnimationSpec;
-  valueFormat?: string;
-  linkOpacity?: number;
-}

package/src/tables/__tests__/bar-column.test.ts

@@ -1,147 +0,0 @@
-import type { BarColumnConfig } from '@opendata-ai/openchart-core';
-import { resolveTheme } from '@opendata-ai/openchart-core';
-import { describe, expect, it } from 'vitest';
-import { computeBarCell, computeColumnMax, computeColumnMin } from '../bar-column';
-
-const theme = resolveTheme();
-
-describe('computeBarCell', () => {
-  it('computes correct percentage for mid-range value', () => {
-    const config: BarColumnConfig = {};
-    const result = computeBarCell(50, config, 100, 0, theme, false);
-    expect(result.barPercent).toBeCloseTo(0.5);
-    expect(result.barOffset).toBe(0);
-    expect(result.isNegative).toBe(false);
-  });
-
-  it('computes 100% for max value', () => {
-    const config: BarColumnConfig = {};
-    const result = computeBarCell(100, config, 100, 0, theme, false);
-    expect(result.barPercent).toBeCloseTo(1);
-  });
-
-  it('computes 0% for zero value', () => {
-    const config: BarColumnConfig = {};
-    const result = computeBarCell(0, config, 100, 0, theme, false);
-    expect(result.barPercent).toBeCloseTo(0);
-  });
-
-  it('uses config maxValue when provided', () => {
-    const config: BarColumnConfig = { maxValue: 200 };
-    const result = computeBarCell(100, config, 50, 0, theme, false);
-    // Should use config maxValue (200), not columnMax (50)
-    expect(result.barPercent).toBeCloseTo(0.5);
-  });
-
-  it('clamps negative values to 0 when column has no negatives', () => {
-    const config: BarColumnConfig = {};
-    // columnMin=0 means no negative values in the column
-    const result = computeBarCell(-10, config, 100, 0, theme, false);
-    expect(result.barPercent).toBe(0);
-  });
-
-  it('clamps values above max to 1', () => {
-    const config: BarColumnConfig = {};
-    const result = computeBarCell(150, config, 100, 0, theme, false);
-    expect(result.barPercent).toBe(1);
-  });
-
-  it('uses custom color from config', () => {
-    const config: BarColumnConfig = { color: '#ff0000' };
-    const result = computeBarCell(50, config, 100, 0, theme, false);
-    expect(result.barColor).toBe('#ff0000');
-  });
-
-  it('defaults to first categorical palette color', () => {
-    const config: BarColumnConfig = {};
-    const result = computeBarCell(50, config, 100, 0, theme, false);
-    expect(result.barColor).toBe(theme.colors.categorical[0]);
-  });
-
-  it('handles NaN value', () => {
-    const config: BarColumnConfig = {};
-    const result = computeBarCell(NaN, config, 100, 0, theme, false);
-    expect(result.barPercent).toBe(0);
-  });
-
-  it('handles Infinity value', () => {
-    const config: BarColumnConfig = {};
-    const result = computeBarCell(Infinity, config, 100, 0, theme, false);
-    expect(result.barPercent).toBe(0);
-  });
-
-  it('handles zero columnMax', () => {
-    const config: BarColumnConfig = {};
-    const result = computeBarCell(50, config, 0, 0, theme, false);
-    expect(result.barPercent).toBe(0);
-  });
-
-  // Negative value support
-  it('renders negative value as bidirectional bar', () => {
-    const config: BarColumnConfig = {};
-    // Column range: -20 to 80, totalRange = 100, zeroPos = 0.2
-    const result = computeBarCell(-10, config, 80, -20, theme, false);
-    expect(result.isNegative).toBe(true);
-    expect(result.barPercent).toBeCloseTo(0.1); // 10/100
-    expect(result.barOffset).toBeCloseTo(0.1); // zeroPos(0.2) - barPercent(0.1)
-  });
-
-  it('renders positive value with offset when column has negatives', () => {
-    const config: BarColumnConfig = {};
-    // Column range: -20 to 80, totalRange = 100, zeroPos = 0.2
-    const result = computeBarCell(40, config, 80, -20, theme, false);
-    expect(result.isNegative).toBe(false);
-    expect(result.barPercent).toBeCloseTo(0.4); // 40/100
-    expect(result.barOffset).toBeCloseTo(0.2); // zeroPos
-  });
-
-  it('uses red color for negative bars by default', () => {
-    const config: BarColumnConfig = {};
-    const result = computeBarCell(-10, config, 80, -20, theme, false);
-    expect(result.isNegative).toBe(true);
-    expect(result.barColor).toBe('#c44e52');
-  });
-
-  it('uses custom color for negative bars when config.color is set', () => {
-    const config: BarColumnConfig = { color: '#ff0000' };
-    const result = computeBarCell(-10, config, 80, -20, theme, false);
-    expect(result.barColor).toBe('#ff0000');
-  });
-});
-
-describe('computeColumnMax', () => {
-  it('finds the max numeric value in a column', () => {
-    const data = [{ value: 10 }, { value: 50 }, { value: 30 }];
-    expect(computeColumnMax(data, 'value')).toBe(50);
-  });
-
-  it('ignores non-numeric values', () => {
-    const data = [{ value: 10 }, { value: 'hello' }, { value: null }, { value: 30 }];
-    expect(computeColumnMax(data, 'value')).toBe(30);
-  });
-
-  it('returns 0 for empty data', () => {
-    expect(computeColumnMax([], 'value')).toBe(0);
-  });
-
-  it('returns 0 when all values are non-numeric', () => {
-    const data = [{ value: 'a' }, { value: 'b' }];
-    expect(computeColumnMax(data, 'value')).toBe(0);
-  });
-});
-
-describe('computeColumnMin', () => {
-  it('finds the min numeric value in a column', () => {
-    const data = [{ value: 10 }, { value: -5 }, { value: 30 }];
-    expect(computeColumnMin(data, 'value')).toBe(-5);
-  });
-
-  it('returns 0 for all-positive data', () => {
-    const data = [{ value: 10 }, { value: 20 }];
-    expect(computeColumnMin(data, 'value')).toBe(0);
-  });
-
-  it('returns 0 for empty data', () => {
-    expect(computeColumnMin([], 'value')).toBe(0);
-  });
-});

package/src/tables/__tests__/category-colors.test.ts

@@ -1,230 +0,0 @@
-import type { ColumnConfig, ResolvedTheme } from '@opendata-ai/openchart-core';
-import { adaptTheme, contrastRatio, resolveTheme } from '@opendata-ai/openchart-core';
-import { describe, expect, it } from 'vitest';
-import { computeCategoryColors } from '../category-colors';
-
-function getTheme(dark = false): ResolvedTheme {
-  const theme = resolveTheme();
-  return dark ? adaptTheme(theme) : theme;
-}
-
-describe('computeCategoryColors', () => {
-  const data = [
-    { status: 'active' },
-    { status: 'inactive' },
-    { status: 'active' },
-    { status: 'pending' },
-  ];
-
-  it('applies explicit color mapping correctly', () => {
-    const col: ColumnConfig = {
-      key: 'status',
-      categoryColors: {
-        active: '#00ff00',
-        inactive: '#ff0000',
-      },
-    };
-    const theme = getTheme();
-    const colors = computeCategoryColors(data, col, theme, false);
-
-    expect(colors.size).toBe(3);
-    // "active" rows (indices 0, 2) should have green background
-    expect(colors.get(0)!.backgroundColor).toBe('#00ff00');
-    expect(colors.get(2)!.backgroundColor).toBe('#00ff00');
-    // "inactive" row (index 1) should have red background
-    expect(colors.get(1)!.backgroundColor).toBe('#ff0000');
-    // "pending" (index 3) is not in the explicit map, should be skipped
-    expect(colors.has(3)).toBe(false);
-  });
-
-  it('unmapped values are skipped by default', () => {
-    const col: ColumnConfig = {
-      key: 'status',
-      categoryColors: {
-        active: '#00ff00',
-      },
-    };
-    const theme = getTheme();
-    const colors = computeCategoryColors(data, col, theme, false);
-
-    // Only "active" rows (indices 0, 2) should be colored
-    expect(colors.size).toBe(2);
-    expect(colors.get(0)!.backgroundColor).toBe('#00ff00');
-    expect(colors.get(2)!.backgroundColor).toBe('#00ff00');
-    // Unmapped values should not have entries
-    expect(colors.has(1)).toBe(false); // inactive
-    expect(colors.has(3)).toBe(false); // pending
-  });
-
-  it('autoAssign: true assigns palette colors to unmapped values', () => {
-    const col: ColumnConfig = {
-      key: 'status',
-      categoryColors: {
-        active: '#00ff00',
-      },
-      autoAssign: true,
-    };
-    const theme = getTheme();
-    const colors = computeCategoryColors(data, col, theme, false);
-
-    // All 4 rows should be colored
-    expect(colors.size).toBe(4);
-    // "inactive" and "pending" should get palette colors (not the explicit green)
-    const inactiveBg = colors.get(1)!.backgroundColor!;
-    const pendingBg = colors.get(3)!.backgroundColor!;
-    expect(inactiveBg).toBeTruthy();
-    expect(pendingBg).toBeTruthy();
-    expect(inactiveBg).not.toBe('#00ff00');
-  });
-
-  it('same category value gets consistent colors', () => {
-    const col: ColumnConfig = {
-      key: 'status',
-      categoryColors: { active: '#00ff00' },
-    };
-    const theme = getTheme();
-    const colors = computeCategoryColors(data, col, theme, false);
-
-    // Both "active" rows should have the same color
-    expect(colors.get(0)!.backgroundColor).toBe(colors.get(2)!.backgroundColor);
-  });
-
-  it('text contrast meets AA (at least 3:1)', () => {
-    const col: ColumnConfig = {
-      key: 'status',
-      categoryColors: {
-        active: '#00ff00',
-        inactive: '#ff0000',
-        pending: '#0000ff',
-      },
-    };
-    const theme = getTheme();
-    const colors = computeCategoryColors(data, col, theme, false);
-
-    for (const [, style] of colors) {
-      const bg = style.backgroundColor!;
-      const fg = style.color!;
-      const ratio = contrastRatio(fg, bg);
-      // accessibleTextColor picks black or white; both should exceed 3:1
-      expect(ratio).toBeGreaterThanOrEqual(3);
-    }
-  });
-
-  it('dark mode preserves explicit user-provided colors', () => {
-    const col: ColumnConfig = {
-      key: 'status',
-      categoryColors: {
-        active: '#00ff00',
-        inactive: '#ff0000',
-      },
-    };
-    const darkTheme = getTheme(true);
-    const colors = computeCategoryColors(data, col, darkTheme, true);
-
-    // Explicit colors should NOT be adapted for dark mode
-    expect(colors.get(0)!.backgroundColor).toBe('#00ff00');
-    expect(colors.get(1)!.backgroundColor).toBe('#ff0000');
-  });
-
-  it('dark mode adapts auto-assigned palette colors but not explicit ones', () => {
-    // Use a bright yellow that will definitely get adapted in dark mode
-    const col: ColumnConfig = {
-      key: 'status',
-      categoryColors: {
-        active: '#ffff00',
-      },
-      autoAssign: true,
-    };
-    const darkTheme = getTheme(true);
-    const darkColors = computeCategoryColors(data, col, darkTheme, true);
-
-    // Explicit color should be preserved as-is (not adapted)
-    expect(darkColors.get(0)!.backgroundColor).toBe('#ffff00');
-
-    // Auto-assigned palette colors should still be present (adaptation may or
-    // may not visually change them, but the code path runs adaptColorForDarkMode)
-    expect(darkColors.has(1)).toBe(true); // inactive
-    expect(darkColors.has(3)).toBe(true); // pending
-  });
-
-  it('autoAssign: true gives same value consistent color across rows', () => {
-    const col: ColumnConfig = {
-      key: 'status',
-      categoryColors: {},
-      autoAssign: true,
-    };
-    const theme = getTheme();
-    const colors = computeCategoryColors(data, col, theme, false);
-
-    // Both "active" rows should get the same auto-assigned color
-    expect(colors.get(0)!.backgroundColor).toBe(colors.get(2)!.backgroundColor);
-  });
-
-  it('dark mode text contrast still meets AA', () => {
-    const col: ColumnConfig = {
-      key: 'status',
-      categoryColors: {
-        active: '#00ff00',
-        inactive: '#ff0000',
-      },
-    };
-    const theme = getTheme(true);
-    const colors = computeCategoryColors(data, col, theme, true);
-
-    for (const [, style] of colors) {
-      const bg = style.backgroundColor!;
-      const fg = style.color!;
-      const ratio = contrastRatio(fg, bg);
-      expect(ratio).toBeGreaterThanOrEqual(3);
-    }
-  });
-
-  it('returns empty map when no categoryColors config', () => {
-    const col: ColumnConfig = { key: 'status' };
-    const theme = getTheme();
-    const colors = computeCategoryColors(data, col, theme, false);
-    expect(colors.size).toBe(0);
-  });
-
-  it('skips transparent and none category colors', () => {
-    const dataWithSpecial = [
-      { status: 'active' },
-      { status: 'inactive' },
-      { status: 'pending' },
-      { status: 'disabled' },
-    ];
-    const col: ColumnConfig = {
-      key: 'status',
-      categoryColors: {
-        active: '#00ff00',
-        inactive: 'transparent',
-        pending: 'none',
-        disabled: '#cccccc',
-      },
-    };
-    const theme = getTheme();
-    const colors = computeCategoryColors(dataWithSpecial, col, theme, false);
-
-    // transparent and none rows should be skipped
-    expect(colors.has(1)).toBe(false); // inactive = transparent
-    expect(colors.has(2)).toBe(false); // pending = none
-    // explicit colors should still be present
-    expect(colors.get(0)!.backgroundColor).toBe('#00ff00');
-    expect(colors.get(3)!.backgroundColor).toBe('#cccccc');
-    expect(colors.size).toBe(2);
-  });
-
-  it('skips null values', () => {
-    const dataWithNull = [{ status: 'active' }, { status: null }, { status: 'inactive' }];
-    const col: ColumnConfig = {
-      key: 'status',
-      categoryColors: { active: '#00ff00', inactive: '#ff0000' },
-    };
-    const theme = getTheme();
-    const colors = computeCategoryColors(dataWithNull, col, theme, false);
-
-    // null row (index 1) should not be included
-    expect(colors.has(1)).toBe(false);
-    expect(colors.size).toBe(2);
-  });
-});