@opendata-ai/openchart-engine 8.0.0-rc.8 → 8.0.0

package/src/legend/wrap.ts

@@ -1,117 +0,0 @@
-/**
- * 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 { COMPACT_WIDTH, 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;
-/** Tighter inter-entry gap for narrow viewports where every pixel matters. */
-export const ENTRY_GAP_COMPACT = 10;
-
-/** Default gap between legend bounds and chart area. Zero on narrow viewports. */
-export const LEGEND_GAP = 8;
-
-/**
- * Minimum gap between the chrome/metrics block above and a top legend.
- * Without it the legend sits flush against the subtitle (compact widths)
- * or the metric bar (all widths) once the inline-tick overhang is placed
- * below the legend where it belongs.
- */
-export const TOP_LEGEND_GAP_ABOVE = 6;
-
-/** Gap between legend and chart area, responsive to container width. */
-export function legendGap(width: number): number {
-  return width < COMPACT_WIDTH ? 0 : LEGEND_GAP;
-}
-
-// ---------------------------------------------------------------------------
-// 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[];
-  /** Per-entry placement: wrap row and x offset within that row. */
-  placements: Array<{ row: number; xOffset: 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,
-  entryGap: number = ENTRY_GAP,
-  measure?: (text: string, fontSize: number, fontWeight: number) => number,
-): LegendWrapResult {
-  if (entries.length === 0) {
-    return { rowCount: 0, fittingCount: 0, rowWidths: [], placements: [] };
-  }
-
-  const measureWidth = measure ?? estimateTextWidth;
-
-  let rowCount = 1;
-  let rowWidth = 0;
-  const rowWidths: number[] = [];
-  const placements: Array<{ row: number; xOffset: number }> = [];
-  let fittingCount = entries.length;
-  let fittingCountLocked = false;
-
-  for (let i = 0; i < entries.length; i++) {
-    const labelWidth = measureWidth(entries[i].label, labelStyle.fontSize, labelStyle.fontWeight);
-    const entryWidth = SWATCH_SIZE + SWATCH_GAP + labelWidth + entryGap;
-
-    if (rowWidth + entryWidth > maxWidth && rowWidth > 0) {
-      rowWidths.push(rowWidth);
-      rowCount++;
-      placements.push({ row: rowCount - 1, xOffset: 0 });
-      rowWidth = entryWidth;
-      if (!fittingCountLocked && maxRows != null && rowCount > maxRows) {
-        fittingCount = i;
-        fittingCountLocked = true;
-      }
-    } else {
-      placements.push({ row: rowCount - 1, xOffset: rowWidth });
-      rowWidth += entryWidth;
-    }
-  }
-
-  // Flush the final row width so rowWidths has one entry per row.
-  rowWidths.push(rowWidth);
-
-  return { rowCount, fittingCount, rowWidths, placements };
-}

package/src/sankey/__tests__/compile-sankey.test.ts

@@ -1,458 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import { compileSankey } from '../../compile';
-
-// ---------------------------------------------------------------------------
-// Shared fixtures
-// ---------------------------------------------------------------------------
-
-const basicSpec = {
-  type: 'sankey' as const,
-  data: [
-    { from: 'A', to: 'C', amount: 10 },
-    { from: 'B', to: 'C', amount: 20 },
-    { from: 'C', to: 'D', amount: 15 },
-    { from: 'C', to: 'E', amount: 15 },
-  ],
-  encoding: {
-    source: { field: 'from', type: 'nominal' as const },
-    target: { field: 'to', type: 'nominal' as const },
-    value: { field: 'amount', type: 'quantitative' as const },
-  },
-};
-
-const defaultOptions = { width: 600, height: 400 };
-
-// ---------------------------------------------------------------------------
-// Tests
-// ---------------------------------------------------------------------------
-
-describe('compileSankey', () => {
-  it('compiles a basic sankey and returns correct node/link counts', () => {
-    const result = compileSankey(basicSpec, defaultOptions);
-
-    // A, B, C, D, E = 5 nodes
-    expect(result.nodes).toHaveLength(5);
-    // A->C, B->C, C->D, C->E = 4 links
-    expect(result.links).toHaveLength(4);
-  });
-
-  it('infers nodes from unique source/target values in data', () => {
-    const result = compileSankey(basicSpec, defaultOptions);
-
-    const nodeIds = result.nodes.map((n) => n.nodeId).sort();
-    expect(nodeIds).toEqual(['A', 'B', 'C', 'D', 'E']);
-  });
-
-  it('node positions are valid (x >= 0, y >= 0, width > 0, height > 0)', () => {
-    const result = compileSankey(basicSpec, defaultOptions);
-
-    for (const node of result.nodes) {
-      expect(node.x).toBeGreaterThanOrEqual(0);
-      expect(node.y).toBeGreaterThanOrEqual(0);
-      expect(node.width).toBeGreaterThan(0);
-      expect(node.height).toBeGreaterThan(0);
-    }
-  });
-
-  it('link paths are valid SVG path strings starting with M', () => {
-    const result = compileSankey(basicSpec, defaultOptions);
-
-    for (const link of result.links) {
-      expect(link.path).toBeTruthy();
-      expect(link.path[0]).toBe('M');
-    }
-  });
-
-  it('nodes get default colors from theme categorical palette', () => {
-    const result = compileSankey(basicSpec, defaultOptions);
-
-    for (const node of result.nodes) {
-      expect(node.fill).toBeTruthy();
-      // Should be a color string (hex, rgb, etc.)
-      expect(typeof node.fill).toBe('string');
-    }
-
-    // With 5 nodes and no color encoding, each node gets a different palette slot
-    const fills = new Set(result.nodes.map((n) => n.fill));
-    expect(fills.size).toBe(5);
-  });
-
-  it('color encoding groups nodes by category value', () => {
-    const spec = {
-      ...basicSpec,
-      encoding: {
-        ...basicSpec.encoding,
-        color: { field: 'from', type: 'nominal' as const },
-      },
-    };
-    const result = compileSankey(spec, defaultOptions);
-
-    // Nodes that share the same color field value should share the same color.
-    // "from" field: A has "A", B has "B", C is a target (gets the color of
-    // the first row where it appears as source or target).
-    const nodeA = result.nodes.find((n) => n.nodeId === 'A')!;
-    const nodeB = result.nodes.find((n) => n.nodeId === 'B')!;
-    // A and B have different "from" categories, so different colors
-    expect(nodeA.fill).not.toBe(nodeB.fill);
-  });
-
-  describe('linkStyle', () => {
-    it('gradient: sourceColor and targetColor differ (match connected nodes)', () => {
-      const spec = { ...basicSpec, linkStyle: 'gradient' as const };
-      const result = compileSankey(spec, defaultOptions);
-
-      // Link from A->C: source and target have different colors
-      const acLink = result.links.find((l) => l.sourceId === 'A' && l.targetId === 'C')!;
-      const nodeA = result.nodes.find((n) => n.nodeId === 'A')!;
-      const nodeC = result.nodes.find((n) => n.nodeId === 'C')!;
-      expect(acLink.sourceColor).toBe(nodeA.fill);
-      expect(acLink.targetColor).toBe(nodeC.fill);
-    });
-
-    it('source: both colors equal source node fill', () => {
-      const spec = { ...basicSpec, linkStyle: 'source' as const };
-      const result = compileSankey(spec, defaultOptions);
-
-      const acLink = result.links.find((l) => l.sourceId === 'A' && l.targetId === 'C')!;
-      const nodeA = result.nodes.find((n) => n.nodeId === 'A')!;
-      expect(acLink.sourceColor).toBe(nodeA.fill);
-      expect(acLink.targetColor).toBe(nodeA.fill);
-    });
-
-    it('target: both colors equal target node fill', () => {
-      const spec = { ...basicSpec, linkStyle: 'target' as const };
-      const result = compileSankey(spec, defaultOptions);
-
-      const acLink = result.links.find((l) => l.sourceId === 'A' && l.targetId === 'C')!;
-      const nodeC = result.nodes.find((n) => n.nodeId === 'C')!;
-      expect(acLink.sourceColor).toBe(nodeC.fill);
-      expect(acLink.targetColor).toBe(nodeC.fill);
-    });
-
-    it('neutral: both colors are the same muted value', () => {
-      const spec = { ...basicSpec, linkStyle: 'neutral' as const };
-      const result = compileSankey(spec, defaultOptions);
-
-      for (const link of result.links) {
-        expect(link.sourceColor).toBe(link.targetColor);
-      }
-
-      // All neutral links share the same color
-      const colors = new Set(result.links.map((l) => l.sourceColor));
-      expect(colors.size).toBe(1);
-    });
-  });
-
-  describe('chrome', () => {
-    it('resolves title and subtitle in output', () => {
-      const spec = {
-        ...basicSpec,
-        chrome: {
-          title: 'Energy Flow',
-          subtitle: 'US energy sources to end uses',
-        },
-      };
-      const result = compileSankey(spec, defaultOptions);
-
-      expect(result.chrome.title).toBeDefined();
-      expect(result.chrome.title!.text).toBe('Energy Flow');
-      expect(result.chrome.subtitle).toBeDefined();
-      expect(result.chrome.subtitle!.text).toBe('US energy sources to end uses');
-    });
-  });
-
-  describe('legend', () => {
-    it('entries match unique node colors when color encoding is set', () => {
-      const spec = {
-        ...basicSpec,
-        encoding: {
-          ...basicSpec.encoding,
-          color: { field: 'from', type: 'nominal' as const },
-        },
-      };
-      const result = compileSankey(spec, defaultOptions);
-
-      // Legend should have entries for the unique color categories
-      expect(result.legend.entries.length).toBeGreaterThan(0);
-      for (const entry of result.legend.entries) {
-        expect(entry.label).toBeTruthy();
-        expect(entry.color).toBeTruthy();
-      }
-    });
-
-    it('has no legend entries when no color encoding is set', () => {
-      const result = compileSankey(basicSpec, defaultOptions);
-
-      // Without color encoding, no legend needed
-      expect(result.legend.entries).toHaveLength(0);
-    });
-  });
-
-  describe('tooltip descriptors', () => {
-    it('contains entries for nodes keyed as node-{id}', () => {
-      const result = compileSankey(basicSpec, defaultOptions);
-
-      expect(result.tooltipDescriptors.has('node-A')).toBe(true);
-      expect(result.tooltipDescriptors.has('node-B')).toBe(true);
-      expect(result.tooltipDescriptors.has('node-C')).toBe(true);
-      expect(result.tooltipDescriptors.has('node-D')).toBe(true);
-      expect(result.tooltipDescriptors.has('node-E')).toBe(true);
-    });
-
-    it('contains entries for links keyed as link-{source}-{target}-{index}', () => {
-      const result = compileSankey(basicSpec, defaultOptions);
-
-      // Keys include index suffix for uniqueness with duplicate source-target pairs
-      const linkKeys = [...result.tooltipDescriptors.keys()].filter((k) => k.startsWith('link-'));
-      expect(linkKeys.length).toBe(4);
-      // Each key should have a numeric suffix
-      for (const key of linkKeys) {
-        expect(key).toMatch(/link-.+-\d+$/);
-      }
-    });
-
-    it('node tooltip has title and flow field', () => {
-      const result = compileSankey(basicSpec, defaultOptions);
-
-      const tooltip = result.tooltipDescriptors.get('node-A')!;
-      expect(tooltip.title).toBeTruthy();
-      expect(tooltip.fields.length).toBeGreaterThan(0);
-      expect(tooltip.fields.some((f) => f.label === 'Total flow')).toBe(true);
-    });
-
-    it('link tooltip has title and flow field', () => {
-      const result = compileSankey(basicSpec, defaultOptions);
-
-      // Get the first link tooltip (keyed with index suffix)
-      const linkKey = [...result.tooltipDescriptors.keys()].find((k) => k.startsWith('link-'));
-      expect(linkKey).toBeTruthy();
-      const tooltip = result.tooltipDescriptors.get(linkKey!)!;
-      expect(tooltip.title).toContain('\u2192'); // arrow character
-      expect(tooltip.fields.some((f) => f.label === 'Flow')).toBe(true);
-    });
-  });
-
-  describe('animation', () => {
-    it('node animation indices increase left-to-right by column depth', () => {
-      const result = compileSankey(basicSpec, defaultOptions);
-
-      // Group nodes by depth
-      const byDepth = new Map<number, number[]>();
-      for (const node of result.nodes) {
-        const indices = byDepth.get(node.depth) ?? [];
-        indices.push(node.animationIndex);
-        byDepth.set(node.depth, indices);
-      }
-
-      // All indices in a shallower column should be less than all indices
-      // in a deeper column
-      const depths = [...byDepth.keys()].sort((a, b) => a - b);
-      for (let i = 0; i < depths.length - 1; i++) {
-        const currentMax = Math.max(...byDepth.get(depths[i])!);
-        const nextMin = Math.min(...byDepth.get(depths[i + 1])!);
-        expect(currentMax).toBeLessThan(nextMin);
-      }
-    });
-
-    it('link animation indices come after all node indices', () => {
-      const spec = { ...basicSpec, animation: true };
-      const result = compileSankey(spec, defaultOptions);
-
-      const maxNodeIndex = Math.max(...result.nodes.map((n) => n.animationIndex));
-      const minLinkIndex = Math.min(...result.links.map((l) => l.animationIndex));
-      expect(minLinkIndex).toBeGreaterThan(maxNodeIndex);
-    });
-  });
-
-  describe('a11y', () => {
-    it('generates descriptive alt text', () => {
-      const result = compileSankey(basicSpec, defaultOptions);
-
-      expect(result.a11y.altText).toContain('5 nodes');
-      expect(result.a11y.altText).toContain('4 links');
-    });
-
-    it('has a data table fallback', () => {
-      const result = compileSankey(basicSpec, defaultOptions);
-
-      expect(result.a11y.dataTableFallback.length).toBeGreaterThan(0);
-    });
-  });
-
-  describe('dimensions', () => {
-    it('reflects the compile options', () => {
-      const result = compileSankey(basicSpec, defaultOptions);
-
-      expect(result.dimensions.width).toBe(600);
-      expect(result.dimensions.height).toBe(400);
-    });
-  });
-
-  describe('dark mode', () => {
-    it('applies dark mode theme when option is set', () => {
-      const result = compileSankey(basicSpec, { ...defaultOptions, darkMode: true });
-
-      expect(result.theme.isDark).toBe(true);
-    });
-  });
-
-  describe('validation', () => {
-    it('throws when data is empty', () => {
-      const spec = {
-        ...basicSpec,
-        data: [],
-      };
-
-      expect(() => compileSankey(spec, defaultOptions)).toThrow();
-    });
-
-    it('throws when source encoding is missing', () => {
-      const spec = {
-        ...basicSpec,
-        encoding: {
-          target: { field: 'to', type: 'nominal' as const },
-          value: { field: 'amount', type: 'quantitative' as const },
-        },
-      };
-
-      expect(() => compileSankey(spec, defaultOptions)).toThrow();
-    });
-
-    it('throws when target encoding is missing', () => {
-      const spec = {
-        ...basicSpec,
-        encoding: {
-          source: { field: 'from', type: 'nominal' as const },
-          value: { field: 'amount', type: 'quantitative' as const },
-        },
-      };
-
-      expect(() => compileSankey(spec, defaultOptions)).toThrow();
-    });
-
-    it('throws when value encoding is missing', () => {
-      const spec = {
-        ...basicSpec,
-        encoding: {
-          source: { field: 'from', type: 'nominal' as const },
-          target: { field: 'to', type: 'nominal' as const },
-        },
-      };
-
-      expect(() => compileSankey(spec, defaultOptions)).toThrow();
-    });
-
-    it('throws for non-sankey specs', () => {
-      const chartSpec = {
-        mark: 'bar' as const,
-        data: [{ x: 1, y: 2 }],
-        encoding: {
-          x: { field: 'x', type: 'quantitative' as const },
-          y: { field: 'y', type: 'quantitative' as const },
-        },
-      };
-
-      expect(() => compileSankey(chartSpec, defaultOptions)).toThrow(/non-sankey spec/);
-    });
-  });
-
-  describe('special characters in node names', () => {
-    it('compiles with spaces and $ in node names', () => {
-      const spec = {
-        type: 'sankey' as const,
-        data: [
-          { from: 'Income $104k', to: 'Essential costs', amount: 50 },
-          { from: 'Income $104k', to: 'Taxes & fees', amount: 20 },
-          { from: 'Essential costs', to: 'Housing #1', amount: 30 },
-          { from: 'Essential costs', to: 'Food (groceries)', amount: 20 },
-        ],
-        encoding: {
-          source: { field: 'from', type: 'nominal' as const },
-          target: { field: 'to', type: 'nominal' as const },
-          value: { field: 'amount', type: 'quantitative' as const },
-        },
-      };
-
-      const result = compileSankey(spec, defaultOptions);
-      expect(result.nodes.length).toBe(5);
-      expect(result.links.length).toBe(4);
-      // Node IDs should preserve the original names
-      expect(result.nodes.some((n) => n.nodeId === 'Income $104k')).toBe(true);
-      expect(result.nodes.some((n) => n.nodeId === 'Taxes & fees')).toBe(true);
-    });
-  });
-
-  describe('dark mode colors', () => {
-    it('preserves vivid categorical colors in dark mode', () => {
-      const spec = {
-        ...basicSpec,
-        theme: { colors: ['#38bdf8', '#f87171', '#4ade80'] },
-      };
-
-      const lightResult = compileSankey(spec, defaultOptions);
-      const darkResult = compileSankey(spec, { ...defaultOptions, darkMode: true });
-
-      // Dark mode should use the same vivid node colors, not dark-adapted ones
-      const lightColors = lightResult.nodes.map((n) => n.fill);
-      const darkColors = darkResult.nodes.map((n) => n.fill);
-      expect(darkColors).toEqual(lightColors);
-    });
-
-    it('uses higher link opacity in dark mode', () => {
-      const lightResult = compileSankey(basicSpec, defaultOptions);
-      const darkResult = compileSankey(basicSpec, { ...defaultOptions, darkMode: true });
-
-      const lightOpacity = lightResult.links[0].fillOpacity;
-      const darkOpacity = darkResult.links[0].fillOpacity;
-      expect(darkOpacity).toBeGreaterThan(lightOpacity);
-    });
-  });
-
-  describe('valueFormat', () => {
-    it('formats tooltip values when valueFormat is set', () => {
-      const spec = { ...basicSpec, valueFormat: '.0f%' };
-      const result = compileSankey(spec, defaultOptions);
-
-      // Check that node tooltips use the format
-      const nodeTooltip = result.tooltipDescriptors.get('node-C');
-      expect(nodeTooltip?.fields[0].value).toContain('%');
-    });
-
-    it('uses default formatting when valueFormat is undefined', () => {
-      const result = compileSankey(basicSpec, defaultOptions);
-
-      const nodeTooltip = result.tooltipDescriptors.get('node-C');
-      expect(nodeTooltip?.fields[0].value).not.toContain('%');
-    });
-
-    it('falls back to default on invalid format string', () => {
-      const spec = { ...basicSpec, valueFormat: 'not-a-format' };
-      // Should not throw
-      const result = compileSankey(spec, defaultOptions);
-      expect(result.nodes.length).toBeGreaterThan(0);
-    });
-  });
-
-  describe('linkOpacity', () => {
-    it('uses custom linkOpacity when specified', () => {
-      const spec = { ...basicSpec, linkOpacity: 0.9 };
-      const result = compileSankey(spec, defaultOptions);
-
-      expect(result.links[0].fillOpacity).toBe(0.9);
-    });
-
-    it('uses default opacity when linkOpacity is not set', () => {
-      const result = compileSankey(basicSpec, defaultOptions);
-      // Light mode default
-      expect(result.links[0].fillOpacity).toBe(0.5);
-    });
-  });
-
-  describe('dimensions', () => {
-    it('dimensions match the provided container size', () => {
-      const result = compileSankey(basicSpec, { width: 600, height: 800 });
-      expect(result.dimensions.width).toBe(600);
-      expect(result.dimensions.height).toBe(800);
-    });
-  });
-});