@opendata-ai/openchart-engine 6.8.0 → 6.10.0

package/package.json

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

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

@@ -203,6 +203,98 @@ describe('computeBarMarks', () => {
     });
   });
 
+  describe('grouped bars (stack: null)', () => {
+    function makeDodgedBarSpec(): NormalizedChartSpec {
+      const spec = makeGroupedBarSpec();
+      (spec.encoding.x as { stack?: boolean | null }).stack = null;
+      return spec;
+    }
+
+    it('produces marks for all data rows', () => {
+      const spec = makeDodgedBarSpec();
+      const scales = computeScales(spec, chartArea, spec.data);
+      const marks = computeBarMarks(spec, scales, chartArea, fullStrategy);
+
+      expect(marks).toHaveLength(6);
+    });
+
+    it('grouped bars within a category have different y positions', () => {
+      const spec = makeDodgedBarSpec();
+      const scales = computeScales(spec, chartArea, spec.data);
+      const marks = computeBarMarks(spec, scales, chartArea, fullStrategy);
+
+      const q1East = marks.find(
+        (m) => m.aria.label.includes('Q1') && m.aria.label.includes('East'),
+      )!;
+      const q1West = marks.find(
+        (m) => m.aria.label.includes('Q1') && m.aria.label.includes('West'),
+      )!;
+
+      expect(q1East.y).not.toBe(q1West.y);
+    });
+
+    it('grouped bars all start from baseline (not cumulative)', () => {
+      const spec = makeDodgedBarSpec();
+      const scales = computeScales(spec, chartArea, spec.data);
+      const marks = computeBarMarks(spec, scales, chartArea, fullStrategy);
+
+      const q1East = marks.find(
+        (m) => m.aria.label.includes('Q1') && m.aria.label.includes('East'),
+      )!;
+      const q1West = marks.find(
+        (m) => m.aria.label.includes('Q1') && m.aria.label.includes('West'),
+      )!;
+
+      // Both bars start at the same x position (baseline)
+      expect(q1East.x).toBe(q1West.x);
+    });
+
+    it('grouped bars have cornerRadius 2', () => {
+      const spec = makeDodgedBarSpec();
+      const scales = computeScales(spec, chartArea, spec.data);
+      const marks = computeBarMarks(spec, scales, chartArea, fullStrategy);
+
+      for (const mark of marks) {
+        expect(mark.cornerRadius).toBe(2);
+      }
+    });
+
+    it('grouped bars do not set stackGroup', () => {
+      const spec = makeDodgedBarSpec();
+      const scales = computeScales(spec, chartArea, spec.data);
+      const marks = computeBarMarks(spec, scales, chartArea, fullStrategy);
+
+      for (const mark of marks) {
+        expect(mark.stackGroup).toBeUndefined();
+      }
+    });
+
+    it('sub-band heights are smaller than full bandwidth', () => {
+      const spec = makeDodgedBarSpec();
+      const scales = computeScales(spec, chartArea, spec.data);
+      const marks = computeBarMarks(spec, scales, chartArea, fullStrategy);
+
+      // With 2 groups, each sub-bar should be less than the full bandwidth
+      const stackedSpec = makeGroupedBarSpec();
+      const stackedScales = computeScales(stackedSpec, chartArea, stackedSpec.data);
+      const stackedMarks = computeBarMarks(stackedSpec, stackedScales, chartArea, fullStrategy);
+
+      expect(marks[0].height).toBeLessThan(stackedMarks[0].height);
+      expect(marks[0].height).toBeGreaterThan(0);
+    });
+
+    it('scale domain covers max individual value, not stacked sum', () => {
+      const spec = makeDodgedBarSpec();
+      const scales = computeScales(spec, chartArea, spec.data);
+
+      // Max individual value is 70 (Q3 West), not 115 (Q3 stacked sum)
+      const xScale = scales.x!.scale;
+      const domain = xScale.domain() as number[];
+      // Domain should not extend to the stacked sum (115)
+      expect(domain[1]).toBeLessThanOrEqual(80); // some nice rounding above 70
+    });
+  });
+
   describe('colored (non-stacked) bars', () => {
     it('renders colored bars when each category has one row with color encoding', () => {
       const spec: NormalizedChartSpec = {

package/src/charts/bar/compute.ts

@@ -99,6 +99,22 @@ export function computeBarMarks(
   const needsStacking = Array.from(categoryGroups.values()).some((rows) => rows.length > 1);
 
   if (needsStacking) {
+    const stackDisabled = xChannel.stack === null || xChannel.stack === false;
+
+    if (stackDisabled) {
+      return computeGroupedBars(
+        spec.data,
+        xChannel.field,
+        yChannel.field,
+        colorField,
+        xScale,
+        yScale,
+        bandwidth,
+        baseline,
+        scales,
+      );
+    }
+
     return computeStackedBars(
       spec.data,
       xChannel.field,
@@ -184,6 +200,73 @@ function computeStackedBars(
   return marks;
 }
 
+/** Compute grouped (dodged) horizontal bars -- side-by-side within each category band. */
+function computeGroupedBars(
+  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[] = [];
+  const categoryGroups = groupByField(data, categoryField);
+
+  // Build a stable group order from first appearance in data (Map for O(1) lookup)
+  const groupIndexMap = new Map<string, number>();
+  for (const row of data) {
+    const key = String(row[colorField] ?? '');
+    if (!groupIndexMap.has(key)) {
+      groupIndexMap.set(key, groupIndexMap.size);
+    }
+  }
+  const groupCount = groupIndexMap.size;
+  if (groupCount === 0) return marks;
+
+  // Subdivide the band height by group count with a small gap
+  const gap = Math.min(1, bandwidth * 0.05);
+  const subBandHeight = Math.max((bandwidth - gap * (groupCount - 1)) / groupCount, MIN_BAR_WIDTH);
+
+  for (const [category, rows] of categoryGroups) {
+    const bandY = yScale(category);
+    if (bandY === undefined) continue;
+
+    for (const row of rows) {
+      const groupKey = String(row[colorField] ?? '');
+      const value = Number(row[valueField] ?? 0);
+      if (!Number.isFinite(value)) continue;
+
+      const groupIndex = groupIndexMap.get(groupKey) ?? 0;
+      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 subY = bandY + groupIndex * (subBandHeight + gap);
+
+      const aria: MarkAria = {
+        label: `${category}, ${groupKey}: ${formatBarValue(value)}`,
+      };
+
+      marks.push({
+        type: 'rect',
+        x: xPos,
+        y: subY,
+        width: barWidth,
+        height: subBandHeight,
+        fill: color,
+        cornerRadius: 2,
+        data: row as Record<string, unknown>,
+        aria,
+        orient: 'horizontal',
+      });
+    }
+  }
+
+  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(

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

@@ -187,6 +187,72 @@ describe('computeColumnMarks', () => {
     });
   });
 
+  describe('grouped columns (stack: null)', () => {
+    function makeDodgedColumnSpec(): NormalizedChartSpec {
+      const spec = makeGroupedColumnSpec();
+      (spec.encoding.y as { stack?: boolean | null }).stack = null;
+      return spec;
+    }
+
+    it('produces marks for all data rows', () => {
+      const spec = makeDodgedColumnSpec();
+      const scales = computeScales(spec, chartArea, spec.data);
+      const marks = computeColumnMarks(spec, scales, chartArea, fullStrategy);
+
+      expect(marks).toHaveLength(6);
+    });
+
+    it('grouped columns within a category have different x positions', () => {
+      const spec = makeDodgedColumnSpec();
+      const scales = computeScales(spec, chartArea, spec.data);
+      const marks = computeColumnMarks(spec, scales, chartArea, fullStrategy);
+
+      const janNorth = marks.find(
+        (m) => m.aria.label.includes('Jan') && m.aria.label.includes('North'),
+      )!;
+      const janSouth = marks.find(
+        (m) => m.aria.label.includes('Jan') && m.aria.label.includes('South'),
+      )!;
+
+      expect(janNorth.x).not.toBe(janSouth.x);
+    });
+
+    it('grouped columns have subdivided widths', () => {
+      const spec = makeDodgedColumnSpec();
+      const scales = computeScales(spec, chartArea, spec.data);
+      const marks = computeColumnMarks(spec, scales, chartArea, fullStrategy);
+
+      // With 2 groups, each sub-column should be narrower than full bandwidth
+      const stackedSpec = makeGroupedColumnSpec();
+      const stackedScales = computeScales(stackedSpec, chartArea, stackedSpec.data);
+      const stackedMarks = computeColumnMarks(stackedSpec, stackedScales, chartArea, fullStrategy);
+
+      expect(marks[0].width).toBeLessThan(stackedMarks[0].width);
+      expect(marks[0].width).toBeGreaterThan(0);
+    });
+
+    it('grouped columns have cornerRadius 2 and no stackGroup', () => {
+      const spec = makeDodgedColumnSpec();
+      const scales = computeScales(spec, chartArea, spec.data);
+      const marks = computeColumnMarks(spec, scales, chartArea, fullStrategy);
+
+      for (const mark of marks) {
+        expect(mark.cornerRadius).toBe(2);
+        expect(mark.stackGroup).toBeUndefined();
+      }
+    });
+
+    it('scale domain covers max individual value, not stacked sum', () => {
+      const spec = makeDodgedColumnSpec();
+      const scales = computeScales(spec, chartArea, spec.data);
+
+      // Max individual value is 150 (Mar North), not 280 (Mar stacked sum)
+      const yScale = scales.y!.scale;
+      const domain = yScale.domain() as number[];
+      expect(domain[1]).toBeLessThanOrEqual(170); // some nice rounding above 150
+    });
+  });
+
   describe('negative values', () => {
     it('negative columns extend downward from baseline', () => {
       const spec = makeNegativeColumnSpec();

package/src/charts/column/compute.ts

@@ -3,7 +3,8 @@
  *
  * Takes a normalized chart spec with resolved scales and produces
  * RectMark[] for rendering vertical columns. When a color encoding
- * is present, columns are stacked (cumulative heights per category).
+ * is present, columns are either stacked (cumulative heights) or grouped
+ * (side-by-side) based on the `stack` property of the quantitative channel.
  *
  * Shares conceptual logic with bar chart but axes are swapped:
  * x-axis is categorical (band scale), y-axis is quantitative.
@@ -88,6 +89,22 @@ export function computeColumnMarks(
     const needsStacking = Array.from(categoryGroups.values()).some((rows) => rows.length > 1);
 
     if (needsStacking) {
+      const stackDisabled = yChannel.stack === null || yChannel.stack === false;
+
+      if (stackDisabled) {
+        return computeGroupedColumns(
+          spec.data,
+          xChannel.field,
+          yChannel.field,
+          colorField,
+          xScale,
+          yScale,
+          bandwidth,
+          baseline,
+          scales,
+        );
+      }
+
       return computeStackedColumns(
         spec.data,
         xChannel.field,
@@ -241,6 +258,77 @@ function computeColoredColumns(
   return marks;
 }
 
+/** Compute grouped (dodged) vertical columns -- side-by-side within each category band. */
+function computeGroupedColumns(
+  data: DataRow[],
+  categoryField: string,
+  valueField: string,
+  colorField: string,
+  xScale: ScaleBand<string>,
+  yScale: ScaleLinear<number, number>,
+  bandwidth: number,
+  baseline: number,
+  scales: ResolvedScales,
+): RectMark[] {
+  const marks: RectMark[] = [];
+  const categoryGroups = groupByField(data, categoryField);
+
+  // Build a stable group order from first appearance in data (Map for O(1) lookup)
+  const groupIndexMap = new Map<string, number>();
+  for (const row of data) {
+    const key = String(row[colorField] ?? '');
+    if (!groupIndexMap.has(key)) {
+      groupIndexMap.set(key, groupIndexMap.size);
+    }
+  }
+  const groupCount = groupIndexMap.size;
+  if (groupCount === 0) return marks;
+
+  // Subdivide the band width by group count with a small gap
+  const gap = Math.min(1, bandwidth * 0.05);
+  const subBandWidth = Math.max(
+    (bandwidth - gap * (groupCount - 1)) / groupCount,
+    MIN_COLUMN_HEIGHT,
+  );
+
+  for (const [category, rows] of categoryGroups) {
+    const bandX = xScale(category);
+    if (bandX === undefined) continue;
+
+    for (const row of rows) {
+      const groupKey = String(row[colorField] ?? '');
+      const value = Number(row[valueField] ?? 0);
+      if (!Number.isFinite(value)) continue;
+
+      const groupIndex = groupIndexMap.get(groupKey) ?? 0;
+      const color = getColor(scales, groupKey);
+      const yPos = yScale(value);
+      const columnHeight = Math.max(Math.abs(baseline - yPos), MIN_COLUMN_HEIGHT);
+      const y = value >= 0 ? yPos : baseline;
+      const subX = bandX + groupIndex * (subBandWidth + gap);
+
+      const aria: MarkAria = {
+        label: `${category}, ${groupKey}: ${formatColumnValue(value)}`,
+      };
+
+      marks.push({
+        type: 'rect',
+        x: subX,
+        y,
+        width: subBandWidth,
+        height: columnHeight,
+        fill: color,
+        cornerRadius: 2,
+        data: row as Record<string, unknown>,
+        aria,
+        orient: 'vertical',
+      });
+    }
+  }
+
+  return marks;
+}
+
 /** Compute stacked vertical columns. */
 function computeStackedColumns(
   data: DataRow[],

package/src/compiler/normalize.ts

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

package/src/layout/scales.ts

@@ -622,7 +622,13 @@ export function computeScales(
     // For stacked bars, the x-domain needs the max category sum, not max individual value.
     // Without this, stacked bars would clip past the chart area.
     let xData = data;
-    if (spec.markType === 'bar' && encoding.color && encoding.x.type === 'quantitative') {
+    const xStackDisabled = encoding.x.stack === null || encoding.x.stack === false;
+    if (
+      spec.markType === 'bar' &&
+      encoding.color &&
+      encoding.x.type === 'quantitative' &&
+      !xStackDisabled
+    ) {
       const yField = encoding.y?.field;
       const xField = encoding.x.field;
       if (yField) {
@@ -660,10 +666,12 @@ export function computeScales(
       spec.markType === 'bar' &&
       (encoding.x?.type === 'nominal' || encoding.x?.type === 'ordinal') &&
       encoding.y.type === 'quantitative';
+    const yStackDisabled = encoding.y.stack === null || encoding.y.stack === false;
     if (
       (isVerticalBar || spec.markType === 'area') &&
       encoding.color &&
-      encoding.y.type === 'quantitative'
+      encoding.y.type === 'quantitative' &&
+      !yStackDisabled
     ) {
       const xField = encoding.x?.field;
       const yField = encoding.y.field;

package/src/sankey/compile-sankey.ts

@@ -131,18 +131,28 @@ function getLinkColors(
 
 /**
  * Determine label position for a node based on its column depth.
- * Leftmost column: label to the right.
- * Rightmost column: label to the left.
- * Middle columns: label to the right (default).
+ * 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',
 ): SankeyNodeMark['label'] {
   const depth = node.depth ?? 0;
-  const isRightmost = depth === maxDepth;
+
+  // 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,
@@ -158,8 +168,7 @@ function computeNodeLabel(
   const y1 = node.y1 ?? 0;
   const midY = (y0 + y1) / 2;
 
-  if (isRightmost) {
-    // Label to the left of the node
+  if (placeLeft) {
     return {
       text: node.label ?? node.id,
       x: x0 - LABEL_GAP,
@@ -169,7 +178,6 @@ function computeNodeLabel(
     };
   }
 
-  // Label to the right of the node (leftmost and middle columns)
   return {
     text: node.label ?? node.id,
     x: x1 + LABEL_GAP,
@@ -311,15 +319,17 @@ export function compileSankey(spec: unknown, options: CompileOptions): SankeyLay
     sankeySpec.iterations,
   );
 
-  // 6b. Check if any non-rightmost node labels overflow the right edge.
-  //     Non-rightmost nodes get labels to the right (textAnchor: start),
-  //     which can extend past the drawing area boundary.
+  // 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;
-    if (depth === maxDepthFirst) continue; // rightmost labels go left, no overflow
+    // 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);
@@ -375,7 +385,7 @@ export function compileSankey(spec: unknown, options: CompileOptions): SankeyLay
       height: (node.y1 ?? 0) - (node.y0 ?? 0),
       fill,
       cornerRadius: NODE_CORNER_RADIUS,
-      label: computeNodeLabel(node, maxDepth, theme, sankeySpec.nodeWidth),
+      label: computeNodeLabel(node, maxDepth, theme, sankeySpec.nodeWidth, nodeLabelAlign),
       nodeId: node.id,
       value: node.value ?? 0,
       depth,

package/src/sankey/types.ts

@@ -28,6 +28,7 @@ export interface NormalizedSankeySpec {
   nodeAlign: SankeyNodeAlign;
   iterations: number;
   linkStyle: SankeyLinkColor;
+  nodeLabelAlign: 'auto' | 'left' | 'right';
   chrome: NormalizedChrome;
   legend?: LegendConfig;
   theme: ThemeConfig;