@opendata-ai/openchart-engine 6.7.1 → 6.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opendata-ai/openchart-engine",
-  "version": "6.7.1",
+  "version": "6.8.0",
   "description": "Headless compiler for openchart: spec validation, data compilation, scales, and layout",
   "license": "Apache-2.0",
   "author": "Riley Hilliard",
@@ -45,7 +45,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@opendata-ai/openchart-core": "6.7.1",
+    "@opendata-ai/openchart-core": "6.8.0",
     "d3-array": "^3.2.0",
     "d3-format": "^3.1.2",
     "d3-interpolate": "^3.0.0",

package/src/__tests__/legend.test.ts

@@ -213,6 +213,36 @@ describe('computeLegend', () => {
     expect(legend.entries.every((e) => !e.overflow)).toBe(true);
   });
 
+  it('with maxRows: 3 and 8 long-named entries, shows more entries than default maxRows of 2', () => {
+    // Use long series names so entries overflow 2 rows but fit in 3
+    const longNameData = [
+      { date: '2020', value: 10, country: 'Home price to income ratio' },
+      { date: '2020', value: 10, country: 'Tuition to income ratio' },
+      { date: '2020', value: 10, country: 'Health premium to income' },
+      { date: '2020', value: 10, country: 'Childcare cost to income' },
+      { date: '2020', value: 10, country: 'Transportation expenses' },
+      { date: '2020', value: 10, country: 'Food and groceries cost' },
+      { date: '2020', value: 10, country: 'Utilities and services' },
+      { date: '2020', value: 10, country: 'Insurance and benefits' },
+    ];
+    const maxRowsSpec: NormalizedChartSpec = {
+      ...specWithColor,
+      data: longNameData,
+      legend: { maxRows: 3 },
+      hiddenSeries: [],
+      seriesStyles: {},
+    };
+    const defaultSpec: NormalizedChartSpec = {
+      ...specWithColor,
+      data: longNameData,
+    };
+    const legendDefault = computeLegend(defaultSpec, compactStrategy, theme, chartArea);
+    const legendMaxRows = computeLegend(maxRowsSpec, compactStrategy, theme, chartArea);
+    const defaultVisible = legendDefault.entries.filter((e) => !e.overflow).length;
+    const maxRowsVisible = legendMaxRows.entries.filter((e) => !e.overflow).length;
+    expect(maxRowsVisible).toBeGreaterThan(defaultVisible);
+  });
+
   it('uses correct swatch shape for chart type', () => {
     const lineLegend = computeLegend(specWithColor, fullStrategy, theme, chartArea);
     expect(lineLegend.entries[0].shape).toBe('line');

package/src/annotations/__tests__/compute.test.ts

@@ -552,6 +552,99 @@ describe('computeAnnotations', () => {
     });
   });
 
+  // -----------------------------------------------------------------
+  // Refline labelAnchor positioning
+  // -----------------------------------------------------------------
+
+  describe('refline labelAnchor positioning', () => {
+    it('horizontal refline: "left" places label at start.x with text-anchor start', () => {
+      const spec = makeSpec([{ type: 'refline', y: 20, label: 'Left label', labelAnchor: 'left' }]);
+      const scales = computeScales(spec, chartArea, spec.data);
+      const annotations = computeAnnotations(spec, scales, chartArea, fullStrategy);
+
+      const label = annotations[0].label!;
+      // Label x should be near chartArea.x (start of line) + small offset
+      expect(label.x).toBeCloseTo(chartArea.x + 4, 0);
+      expect(label.style.textAnchor).toBe('start');
+    });
+
+    it('horizontal refline: default places label at end.x with text-anchor end', () => {
+      const spec = makeSpec([{ type: 'refline', y: 20, label: 'Default label' }]);
+      const scales = computeScales(spec, chartArea, spec.data);
+      const annotations = computeAnnotations(spec, scales, chartArea, fullStrategy);
+
+      const label = annotations[0].label!;
+      // Label x should be near chartArea.x + chartArea.width (end of line) - small offset
+      expect(label.x).toBeCloseTo(chartArea.x + chartArea.width - 4, 0);
+      expect(label.style.textAnchor).toBe('end');
+    });
+
+    it('horizontal refline: "bottom" places label below the line', () => {
+      const specTop = makeSpec([{ type: 'refline', y: 20, label: 'Top', labelAnchor: 'top' }]);
+      const specBottom = makeSpec([
+        { type: 'refline', y: 20, label: 'Bottom', labelAnchor: 'bottom' },
+      ]);
+      const scales = computeScales(specTop, chartArea, specTop.data);
+
+      const top = computeAnnotations(specTop, scales, chartArea, fullStrategy);
+      const bottom = computeAnnotations(specBottom, scales, chartArea, fullStrategy);
+
+      // Bottom label should be below top label (larger y value)
+      expect(bottom[0].label!.y).toBeGreaterThan(top[0].label!.y);
+    });
+
+    it('vertical refline: "right" places label with text-anchor end', () => {
+      const spec = makeSpec([
+        { type: 'refline', x: '2020-06-01', label: 'Right', labelAnchor: 'right' },
+      ]);
+      const scales = computeScales(spec, chartArea, spec.data);
+      const annotations = computeAnnotations(spec, scales, chartArea, fullStrategy);
+
+      const label = annotations[0].label!;
+      expect(label.style.textAnchor).toBe('end');
+    });
+
+    it('vertical refline: "bottom" places label near end.y', () => {
+      const specTop = makeSpec([
+        { type: 'refline', x: '2020-06-01', label: 'Top', labelAnchor: 'top' },
+      ]);
+      const specBottom = makeSpec([
+        { type: 'refline', x: '2020-06-01', label: 'Bottom', labelAnchor: 'bottom' },
+      ]);
+      const scales = computeScales(specTop, chartArea, specTop.data);
+
+      const top = computeAnnotations(specTop, scales, chartArea, fullStrategy);
+      const bottom = computeAnnotations(specBottom, scales, chartArea, fullStrategy);
+
+      // Bottom label should be further down (near end.y which is chartArea.y + chartArea.height)
+      expect(bottom[0].label!.y).toBeGreaterThan(top[0].label!.y);
+    });
+
+    it('labelOffset still applies on top of anchor positioning', () => {
+      const spec = makeSpec([
+        {
+          type: 'refline',
+          y: 20,
+          label: 'Offset left',
+          labelAnchor: 'left',
+          labelOffset: { dx: 10, dy: -5 },
+        },
+      ]);
+      const specNoOffset = makeSpec([
+        { type: 'refline', y: 20, label: 'No offset', labelAnchor: 'left' },
+      ]);
+      const scales = computeScales(spec, chartArea, spec.data);
+
+      const withOffset = computeAnnotations(spec, scales, chartArea, fullStrategy);
+      const withoutOffset = computeAnnotations(specNoOffset, scales, chartArea, fullStrategy);
+
+      const dx = withOffset[0].label!.x - withoutOffset[0].label!.x;
+      const dy = withOffset[0].label!.y - withoutOffset[0].label!.y;
+      expect(dx).toBe(10);
+      expect(dy).toBe(-5);
+    });
+  });
+
   // -----------------------------------------------------------------
   // Connector origin auto-selection
   // -----------------------------------------------------------------

package/src/annotations/compute.ts

@@ -498,29 +498,82 @@ function resolveRefLineAnnotation(
   }
   // 'solid' gets no dasharray
 
-  // Label at the right end for horizontal, top end for vertical, with optional offset.
-  // Horizontal refline labels use text-anchor 'end' so text stays inside the chart.
-  // labelAnchor controls which side of the line the label sits on:
-  //   "top" (default): above horizontal, left of vertical
-  //   "bottom": below horizontal, right of vertical
+  // Label placement on reflines. labelAnchor controls position:
+  //
+  // Horizontal reflines (y set):
+  //   "left":   left end of line, above        "right"/"top" (default): right end, above
+  //   "bottom": right end of line, below
+  //
+  // Vertical reflines (x set):
+  //   "right": label to the left of the line, near top
+  //   "bottom": label to the right of the line, near bottom
+  //   "left"/"top" (default): label to the right of the line, near top
   let label: ResolvedLabel | undefined;
   if (annotation.label) {
     const isHorizontal = annotation.y !== undefined;
-    const anchor = annotation.labelAnchor ?? 'top';
-    const baseDx = isHorizontal ? -4 : 4;
-    const baseDy = anchor === 'bottom' ? 14 : -4;
+    const anchor = annotation.labelAnchor ?? (isHorizontal ? 'top' : 'left');
+
+    let baseDx: number;
+    let baseDy: number;
+    let labelX: number;
+    let labelY: number;
+    let textAnchor: 'start' | 'middle' | 'end';
+
+    if (isHorizontal) {
+      if (anchor === 'left') {
+        baseDx = 4;
+        baseDy = -4;
+        labelX = start.x;
+        labelY = start.y;
+        textAnchor = 'start';
+      } else if (anchor === 'bottom') {
+        baseDx = -4;
+        baseDy = 14;
+        labelX = end.x;
+        labelY = end.y;
+        textAnchor = 'end';
+      } else {
+        // 'right', 'top' (default), 'auto'
+        baseDx = -4;
+        baseDy = -4;
+        labelX = end.x;
+        labelY = end.y;
+        textAnchor = 'end';
+      }
+    } else {
+      // Vertical refline
+      if (anchor === 'right') {
+        baseDx = -4;
+        baseDy = 14;
+        labelX = start.x;
+        labelY = start.y;
+        textAnchor = 'end';
+      } else if (anchor === 'bottom') {
+        baseDx = 4;
+        baseDy = -4;
+        labelX = start.x;
+        labelY = end.y;
+        textAnchor = 'start';
+      } else {
+        // 'left', 'top' (default), 'auto' — label to the right of the line, near top
+        baseDx = 4;
+        baseDy = 14;
+        labelX = start.x;
+        labelY = start.y;
+        textAnchor = 'start';
+      }
+    }
+
     const labelDelta = applyOffset({ dx: baseDx, dy: baseDy }, annotation.labelOffset);
 
     const defaultStroke = isDark ? DARK_REFLINE_STROKE : LIGHT_REFLINE_STROKE;
     const style = makeAnnotationLabelStyle(11, 400, annotation.stroke ?? defaultStroke, isDark);
-    if (isHorizontal) {
-      style.textAnchor = 'end';
-    }
+    style.textAnchor = textAnchor;
 
     label = {
       text: annotation.label,
-      x: (isHorizontal ? end.x : start.x) + labelDelta.dx,
-      y: (isHorizontal ? end.y : start.y) + labelDelta.dy,
+      x: labelX + labelDelta.dx,
+      y: labelY + labelDelta.dy,
       style,
       visible: true,
     };

package/src/charts/bar/__tests__/compute.test.ts

@@ -203,6 +203,73 @@ describe('computeBarMarks', () => {
     });
   });
 
+  describe('colored (non-stacked) bars', () => {
+    it('renders colored bars when each category has one row with color encoding', () => {
+      const spec: NormalizedChartSpec = {
+        markType: 'bar',
+        markDef: { type: 'bar' },
+        data: [
+          { category: 'Apple', value: 50, type: 'Fruit' },
+          { category: 'Banana', value: 30, type: 'Tropical' },
+          { category: 'Cherry', value: 70, type: 'Berry' },
+        ],
+        encoding: {
+          x: { field: 'value', type: 'quantitative' },
+          y: { field: 'category', type: 'nominal' },
+          color: { field: 'type', type: 'nominal' },
+        },
+        chrome: {},
+        annotations: [],
+        responsive: true,
+        theme: {},
+        darkMode: 'off',
+        labels: { density: 'auto', format: '' },
+      };
+      const scales = computeScales(spec, chartArea, spec.data);
+      const marks = computeBarMarks(spec, scales, chartArea, fullStrategy);
+
+      expect(marks).toHaveLength(3);
+      // Each bar should have different colors
+      const colors = new Set(marks.map((m) => m.fill));
+      expect(colors.size).toBe(3);
+      // Non-stacked bars should have corner radius
+      expect(marks[0].cornerRadius).toBe(2);
+      // Bars should not be stacked (no stackGroup)
+      expect(marks[0].stackGroup).toBeUndefined();
+    });
+
+    it('handles negative values in colored bars', () => {
+      const spec: NormalizedChartSpec = {
+        markType: 'bar',
+        markDef: { type: 'bar' },
+        data: [
+          { category: 'Growth', value: 15, status: 'positive' },
+          { category: 'Decline', value: -10, status: 'negative' },
+        ],
+        encoding: {
+          x: { field: 'value', type: 'quantitative' },
+          y: { field: 'category', type: 'nominal' },
+          color: { field: 'status', type: 'nominal' },
+        },
+        chrome: {},
+        annotations: [],
+        responsive: true,
+        theme: {},
+        darkMode: 'off',
+        labels: { density: 'auto', format: '' },
+      };
+      const scales = computeScales(spec, chartArea, spec.data);
+      const marks = computeBarMarks(spec, scales, chartArea, fullStrategy);
+
+      expect(marks).toHaveLength(2);
+      const decline = marks.find((m) => m.aria.label.includes('Decline'))!;
+      const growth = marks.find((m) => m.aria.label.includes('Growth'))!;
+      // Negative bar starts to the left of positive bar
+      expect(decline.x).toBeLessThan(growth.x);
+      expect(decline.width).toBeGreaterThan(0);
+    });
+  });
+
   describe('negative values', () => {
     it('negative bars extend leftward from baseline', () => {
       const spec = makeNegativeBarSpec();

package/src/charts/bar/compute.ts

@@ -94,8 +94,26 @@ export function computeBarMarks(
     );
   }
 
-  // Stacked bars when color is present
-  return computeStackedBars(
+  // Color encoding present: decide between colored simple bars vs stacked
+  const categoryGroups = groupByField(spec.data, yChannel.field);
+  const needsStacking = Array.from(categoryGroups.values()).some((rows) => rows.length > 1);
+
+  if (needsStacking) {
+    return computeStackedBars(
+      spec.data,
+      xChannel.field,
+      yChannel.field,
+      colorField,
+      xScale,
+      yScale,
+      bandwidth,
+      baseline,
+      scales,
+    );
+  }
+
+  // Single row per category: render like simple bars but with color from scale
+  return computeColoredBars(
     spec.data,
     xChannel.field,
     yChannel.field,
@@ -166,6 +184,55 @@ function computeStackedBars(
   return marks;
 }
 
+/** Compute colored (non-stacked) horizontal bars. Used when color encoding
+ *  is present but each category has only one row (e.g., diverging charts). */
+function computeColoredBars(
+  data: DataRow[],
+  valueField: string,
+  categoryField: string,
+  colorField: string,
+  xScale: ScaleLinear<number, number>,
+  yScale: ScaleBand<string>,
+  bandwidth: number,
+  baseline: number,
+  scales: ResolvedScales,
+): RectMark[] {
+  const marks: RectMark[] = [];
+
+  for (const row of data) {
+    const category = String(row[categoryField] ?? '');
+    const value = Number(row[valueField] ?? 0);
+    if (!Number.isFinite(value)) continue;
+
+    const bandY = yScale(category);
+    if (bandY === undefined) continue;
+
+    const groupKey = String(row[colorField] ?? '');
+    const color = getColor(scales, groupKey);
+    const xPos = value >= 0 ? baseline : xScale(value);
+    const barWidth = Math.max(Math.abs(xScale(value) - baseline), MIN_BAR_WIDTH);
+
+    const aria: MarkAria = {
+      label: `${category}, ${groupKey}: ${formatBarValue(value)}`,
+    };
+
+    marks.push({
+      type: 'rect',
+      x: xPos,
+      y: bandY,
+      width: barWidth,
+      height: bandwidth,
+      fill: color,
+      cornerRadius: 2,
+      data: row as Record<string, unknown>,
+      aria,
+      orient: 'horizontal',
+    });
+  }
+
+  return marks;
+}
+
 /** Compute simple (non-grouped) horizontal bars. */
 function computeSimpleBars(
   data: DataRow[],

package/src/compiler/normalize.ts

@@ -251,6 +251,8 @@ function normalizeSankeySpec(spec: SankeySpec, _warnings: string[]): NormalizedS
     theme: spec.theme ?? {},
     darkMode: spec.darkMode ?? 'off',
     animation: spec.animation,
+    valueFormat: spec.valueFormat,
+    linkOpacity: spec.linkOpacity,
   };
 }
 

package/src/legend/compute.ts

@@ -269,11 +269,13 @@ export function computeLegend(
     }
   }
 
-  // When columns is explicitly set, allow that many rows instead of the default max.
+  // Resolve max rows: explicit maxRows wins, then columns-derived, then default.
   const maxRows =
-    spec.legend?.columns != null
-      ? Math.ceil(entries.length / spec.legend.columns)
-      : TOP_LEGEND_MAX_ROWS;
+    spec.legend?.maxRows != null
+      ? Math.max(1, spec.legend.maxRows)
+      : spec.legend?.columns != null
+        ? Math.ceil(entries.length / spec.legend.columns)
+        : TOP_LEGEND_MAX_ROWS;
   const maxFit = entriesThatFit(entries, availableWidth, maxRows, labelStyle);
 
   if (maxFit < entries.length) {

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

@@ -199,13 +199,16 @@ describe('compileSankey', () => {
       expect(result.tooltipDescriptors.has('node-E')).toBe(true);
     });
 
-    it('contains entries for links keyed as link-{source}-{target}', () => {
+    it('contains entries for links keyed as link-{source}-{target}-{index}', () => {
       const result = compileSankey(basicSpec, defaultOptions);
 
-      expect(result.tooltipDescriptors.has('link-A-C')).toBe(true);
-      expect(result.tooltipDescriptors.has('link-B-C')).toBe(true);
-      expect(result.tooltipDescriptors.has('link-C-D')).toBe(true);
-      expect(result.tooltipDescriptors.has('link-C-E')).toBe(true);
+      // 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', () => {
@@ -220,9 +223,11 @@ describe('compileSankey', () => {
     it('link tooltip has title and flow field', () => {
       const result = compileSankey(basicSpec, defaultOptions);
 
-      const tooltip = result.tooltipDescriptors.get('link-A-C')!;
-      expect(tooltip.title).toContain('A');
-      expect(tooltip.title).toContain('C');
+      // 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);
     });
   });
@@ -350,4 +355,104 @@ describe('compileSankey', () => {
       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);
+    });
+  });
 });