@opendata-ai/openchart-engine 6.16.0 → 6.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opendata-ai/openchart-engine",
-  "version": "6.16.0",
+  "version": "6.18.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.16.0",
+    "@opendata-ai/openchart-core": "6.18.0",
     "d3-array": "^3.2.0",
     "d3-format": "^3.1.2",
     "d3-interpolate": "^3.0.0",

package/src/__tests__/axes.test.ts

@@ -127,7 +127,7 @@ describe('computeAxes', () => {
     const axesShort = computeAxes(scales, shortArea, fullStrategy, theme);
 
     // Even though the strategy says 'full', height < 120 forces minimal (3 ticks)
-    expect(axesShort.y!.ticks.length).toBeLessThanOrEqual(3);
+    expect(axesShort.y!.ticks.length).toBeLessThanOrEqual(4);
   });
 
   it('reduces y-axis ticks for medium-short chart areas (120-200px)', () => {
@@ -150,7 +150,7 @@ describe('computeAxes', () => {
 
     // Strategy already says minimal - short height shouldn't change anything
     const axes = computeAxes(scales, shortArea, minimalStrategy, theme);
-    expect(axes.y!.ticks.length).toBeLessThanOrEqual(3);
+    expect(axes.y!.ticks.length).toBeLessThanOrEqual(4);
   });
 
   // -------------------------------------------------------------------------
@@ -163,7 +163,7 @@ describe('computeAxes', () => {
     const axes = computeAxes(scales, narrowArea, fullStrategy, theme);
 
     // Width < 150 forces minimal density for x-axis
-    expect(axes.x!.ticks.length).toBeLessThanOrEqual(3);
+    expect(axes.x!.ticks.length).toBeLessThanOrEqual(4);
   });
 
   it('reduces x-axis ticks for medium-narrow chart areas (150-300px)', () => {
@@ -194,8 +194,8 @@ describe('computeAxes', () => {
     const axesFull = computeAxes(scalesFull, fullArea, fullStrategy, theme);
 
     // Both axes should have minimal ticks in a thumbnail
-    expect(axesThumb.x!.ticks.length).toBeLessThanOrEqual(3);
-    expect(axesThumb.y!.ticks.length).toBeLessThanOrEqual(3);
+    expect(axesThumb.x!.ticks.length).toBeLessThanOrEqual(4);
+    expect(axesThumb.y!.ticks.length).toBeLessThanOrEqual(4);
 
     // And fewer than full-size
     expect(axesThumb.x!.ticks.length).toBeLessThanOrEqual(axesFull.x!.ticks.length);

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

@@ -66,8 +66,8 @@ describe('compileChart', () => {
     // Annotations array exists (empty for this spec since none were specified)
     expect(layout.annotations).toEqual([]);
 
-    // Legend has entries for the two series
-    expect(layout.legend.entries.length).toBe(2);
+    // Legend is auto-suppressed for line charts with endpoint labels
+    expect(layout.legend.entries.length).toBe(0);
 
     // Tooltip descriptors is a Map (may or may not have entries depending on marks)
     expect(layout.tooltipDescriptors).toBeInstanceOf(Map);
@@ -147,8 +147,11 @@ describe('compileChart', () => {
     expect(layout.axes.y!.start.y).not.toBe(layout.axes.y!.end.y);
   });
 
-  it('has a legend when color encoding is present', () => {
-    const layout = compileChart(lineSpec, { width: 600, height: 400 });
+  it('has a legend when color encoding is present and legend forced on', () => {
+    const layout = compileChart(
+      { ...lineSpec, legend: { show: true } },
+      { width: 600, height: 400 },
+    );
     expect(layout.legend.entries.length).toBeGreaterThan(0);
     expect(layout.legend.entries.some((e) => e.label === 'US')).toBe(true);
     expect(layout.legend.entries.some((e) => e.label === 'UK')).toBe(true);
@@ -280,6 +283,7 @@ describe('compileChart', () => {
     const spec = {
       ...lineSpec,
       hiddenSeries: ['UK'],
+      legend: { show: true },
     };
     const layout = compileChart(spec, { width: 600, height: 400 });
 
@@ -583,6 +587,7 @@ describe('compileGraph', () => {
   it('applies breakpoint override for legend show', () => {
     const spec = {
       ...lineSpec,
+      legend: { show: true },
       overrides: {
         compact: {
           legend: { show: false },

package/src/__tests__/legend.test.ts

@@ -22,7 +22,7 @@ const specWithColor: NormalizedChartSpec = {
   responsive: true,
   theme: {},
   darkMode: 'off',
-  labels: { density: 'auto', format: '' },
+  labels: { density: 'none', format: '', prefix: '' },
 };
 
 const specWithoutColor: NormalizedChartSpec = {
@@ -305,4 +305,92 @@ describe('computeLegend', () => {
     const scatterLegend = computeLegend(scatterSpec, fullStrategy, theme, chartArea);
     expect(scatterLegend.entries[0].shape).toBe('circle');
   });
+
+  describe('auto-suppression for line/area with endpoint labels', () => {
+    /** Line spec with labels enabled for suppression tests. */
+    const lineWithLabels: NormalizedChartSpec = {
+      ...specWithColor,
+      labels: { density: 'auto', format: '', prefix: '' },
+    };
+
+    it('suppresses legend for multi-series line chart with default labels', () => {
+      const legend = computeLegend(lineWithLabels, fullStrategy, theme, chartArea);
+      expect(legend.entries).toHaveLength(0);
+    });
+
+    it('preserves legend when legend.show is explicitly true', () => {
+      const spec: NormalizedChartSpec = {
+        ...lineWithLabels,
+        legend: { show: true },
+        hiddenSeries: [],
+        seriesStyles: {},
+      };
+      const legend = computeLegend(spec, fullStrategy, theme, chartArea);
+      expect(legend.entries).toHaveLength(3);
+    });
+
+    it('preserves legend when labels density is none', () => {
+      const spec: NormalizedChartSpec = {
+        ...lineWithLabels,
+        labels: { density: 'none', format: '', prefix: '' },
+      };
+      const legend = computeLegend(spec, fullStrategy, theme, chartArea);
+      expect(legend.entries).toHaveLength(3);
+    });
+
+    it('preserves legend at compact breakpoint where labelMode is none', () => {
+      const legend = computeLegend(lineWithLabels, compactStrategy, theme, chartArea);
+      expect(legend.entries).toHaveLength(3);
+    });
+
+    it('preserves legend for stacked area chart (default stacking)', () => {
+      const areaSpec: NormalizedChartSpec = {
+        ...lineWithLabels,
+        markType: 'area',
+        markDef: { type: 'area' },
+      };
+      const legend = computeLegend(areaSpec, fullStrategy, theme, chartArea);
+      expect(legend.entries).toHaveLength(3);
+    });
+
+    it('suppresses legend for unstacked area chart with labels', () => {
+      const areaSpec: NormalizedChartSpec = {
+        ...lineWithLabels,
+        markType: 'area',
+        markDef: { type: 'area' },
+        encoding: {
+          x: { field: 'date', type: 'temporal' },
+          y: { field: 'value', type: 'quantitative', stack: null },
+          color: { field: 'country', type: 'nominal' },
+        },
+      };
+      const legend = computeLegend(areaSpec, fullStrategy, theme, chartArea);
+      expect(legend.entries).toHaveLength(0);
+    });
+
+    it('preserves legend for bar chart (not line/area)', () => {
+      const barSpec: NormalizedChartSpec = {
+        ...lineWithLabels,
+        markType: 'bar',
+        markDef: { type: 'bar' },
+        encoding: {
+          x: { field: 'date', type: 'nominal' },
+          y: { field: 'value', type: 'quantitative' },
+          color: { field: 'country', type: 'nominal' },
+        },
+      };
+      const legend = computeLegend(barSpec, fullStrategy, theme, chartArea);
+      expect(legend.entries).toHaveLength(3);
+    });
+
+    it('does not suppress for single-series line (no color encoding)', () => {
+      const noColorWithLabels: NormalizedChartSpec = {
+        ...specWithoutColor,
+        labels: { density: 'auto', format: '', prefix: '' },
+      };
+      const legend = computeLegend(noColorWithLabels, fullStrategy, theme, chartArea);
+      expect(legend.entries).toHaveLength(0);
+      expect(legend.bounds.width).toBe(0);
+    });
+  });
 });

package/src/compiler/normalize.ts

@@ -249,6 +249,7 @@ function normalizeSankeySpec(spec: SankeySpec, _warnings: string[]): NormalizedS
     iterations: spec.iterations ?? 6,
     linkStyle: spec.linkStyle ?? 'gradient',
     nodeLabelAlign: spec.nodeLabelAlign ?? 'auto',
+    nodeSort: spec.nodeSort,
     chrome: normalizeChrome(spec.chrome),
     legend: spec.legend,
     theme: spec.theme ?? {},

package/src/layout/axes.ts

@@ -38,9 +38,9 @@ import type {
 
 /** Base tick counts by axis label density. */
 const TICK_COUNTS: Record<AxisLabelDensity, number> = {
-  full: 10,
-  reduced: 7,
-  minimal: 3,
+  full: 12,
+  reduced: 8,
+  minimal: 4,
 };
 
 /**

package/src/legend/compute.ts

@@ -184,6 +184,27 @@ export function computeLegend(
 
   let entries = extractColorEntries(spec, theme);
 
+  // Auto-suppress legend when endpoint labels identify series on line/area charts.
+  // Guards: keep legend at compact breakpoints (labels hidden), for stacked areas
+  // (endpoint labels overlap), and when user explicitly forces legend on.
+  const isLineOrArea = spec.markType === 'line' || spec.markType === 'area';
+  const hasLabels = spec.labels.density !== 'none';
+  const labelsWillRender = strategy.labelMode !== 'none';
+  const hasColorEncoding = spec.encoding.color != null;
+  const legendNotForced = spec.legend?.show !== true;
+
+  if (isLineOrArea && hasLabels && labelsWillRender && hasColorEncoding && legendNotForced) {
+    const isArea = spec.markType === 'area';
+    const quantChannel =
+      spec.encoding.y?.type === 'quantitative' ? spec.encoding.y : spec.encoding.x;
+    const stackValue = quantChannel?.stack;
+    const isStacked = stackValue !== null && stackValue !== false;
+
+    if (!isArea || !isStacked) {
+      entries = [];
+    }
+  }
+
   const labelStyle: TextStyle = {
     fontFamily: theme.fonts.family,
     fontSize: theme.fonts.sizes.small,

package/src/sankey/compile-sankey.ts

@@ -324,6 +324,7 @@ export function compileSankey(spec: unknown, options: CompileOptions): SankeyLay
     sankeySpec.nodePadding,
     sankeySpec.nodeAlign,
     sankeySpec.iterations,
+    sankeySpec.nodeSort,
   );
 
   // 6b. Check if any right-side node labels overflow the right edge.
@@ -363,6 +364,7 @@ export function compileSankey(spec: unknown, options: CompileOptions): SankeyLay
       sankeySpec.nodePadding,
       sankeySpec.nodeAlign,
       sankeySpec.iterations,
+      sankeySpec.nodeSort,
     ));
   }
 

package/src/sankey/layout.ts

@@ -73,6 +73,7 @@ export function computeSankeyLayout(
   nodePadding: number,
   nodeAlign: SankeyNodeAlign,
   iterations: number,
+  nodeSort?: string[],
 ): SankeyLayoutResult {
   // Extract unique node IDs from source and target columns
   const nodeSet = new Set<string>();
@@ -113,6 +114,19 @@ export function computeSankeyLayout(
     ])
     .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>>,

package/src/sankey/types.ts

@@ -29,6 +29,7 @@ export interface NormalizedSankeySpec {
   iterations: number;
   linkStyle: SankeyLinkColor;
   nodeLabelAlign: 'auto' | 'left' | 'right';
+  nodeSort?: string[];
   chrome: NormalizedChrome;
   legend?: LegendConfig;
   theme: ThemeConfig;

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

@@ -27,32 +27,53 @@ describe('computeCategoryColors', () => {
     const theme = getTheme();
     const colors = computeCategoryColors(data, col, theme, false);
 
-    expect(colors.size).toBe(4);
+    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('unmapped values get palette colors', () => {
+  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);
 
-    // "inactive" and "pending" are not in the explicit map, should get palette colors
+    // 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!;
-
-    // They should be assigned from the categorical palette
     expect(inactiveBg).toBeTruthy();
     expect(pendingBg).toBeTruthy();
-    // They should not be the explicit mapped color
     expect(inactiveBg).not.toBe('#00ff00');
   });
 
@@ -112,6 +133,7 @@ describe('computeCategoryColors', () => {
       categoryColors: {
         active: '#ffff00',
       },
+      autoAssign: true,
     };
     const darkTheme = getTheme(true);
     const darkColors = computeCategoryColors(data, col, darkTheme, true);
@@ -125,6 +147,19 @@ describe('computeCategoryColors', () => {
     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',

package/src/tables/category-colors.ts

@@ -48,13 +48,18 @@ export function computeCategoryColors(
       }
       bg = explicitMap[key];
       isExplicit = true;
-    } else if (autoAssigned.has(key)) {
-      bg = autoAssigned.get(key)!;
+    } else if (column.autoAssign) {
+      // Auto-assign from palette only when explicitly opted in
+      if (autoAssigned.has(key)) {
+        bg = autoAssigned.get(key)!;
+      } else {
+        bg = categoricalPalette[nextPaletteIndex % categoricalPalette.length];
+        nextPaletteIndex++;
+        autoAssigned.set(key, bg);
+      }
     } else {
-      // Assign from categorical palette
-      bg = categoricalPalette[nextPaletteIndex % categoricalPalette.length];
-      nextPaletteIndex++;
-      autoAssigned.set(key, bg);
+      // Default: skip unmapped values (no color assigned)
+      continue;
     }
 
     // Dark mode adaptation (skip for explicit user-provided colors)