@opendata-ai/openchart-engine 6.23.0 → 6.24.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opendata-ai/openchart-engine",
-  "version": "6.23.0",
+  "version": "6.24.0",
   "description": "Headless compiler for openchart: spec validation, data compilation, scales, and layout",
   "license": "Apache-2.0",
   "author": "Riley Hilliard",
@@ -30,7 +30,10 @@
     "dist",
     "src"
   ],
-  "sideEffects": false,
+  "sideEffects": [
+    "./src/charts/builtin.ts",
+    "./dist/index.js"
+  ],
   "keywords": [
     "chart",
     "visualization",
@@ -45,7 +48,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@opendata-ai/openchart-core": "6.23.0",
+    "@opendata-ai/openchart-core": "6.24.0",
     "d3-array": "^3.2.0",
     "d3-format": "^3.1.2",
     "d3-interpolate": "^3.0.0",

package/src/__tests__/axes.test.ts

@@ -418,7 +418,7 @@ describe('text-aware tick density', () => {
     expect(axesNarrow.x!.ticks.length).toBeLessThanOrEqual(axesWide.x!.ticks.length);
   });
 
-  it('does not thin x-axis ticks when explicit tickCount is set', () => {
+  it('still thins x-axis ticks when tickCount is set but D3 overshoots', () => {
     const narrowArea = { x: 50, y: 50, width: 200, height: 300 };
     const specWithTickCount: NormalizedChartSpec = {
       ...lineSpec,
@@ -431,12 +431,33 @@ describe('text-aware tick density', () => {
     const scales = computeScales(specWithTickCount, narrowArea, specWithTickCount.data);
     const axes = computeAxes(scales, narrowArea, fullStrategy, theme);
 
-    // With explicit tickCount, the engine should not thin
-    // D3 may return fewer than 8 for this small dataset, but the point is
-    // thinTicksUntilFit should not be called
+    // tickCount is advisory for D3 - if it overshoots, thinning still applies
+    // to prevent overlap. The result should still have ticks, just not more
+    // than the narrow area can display without overlap.
     expect(axes.x!.ticks.length).toBeGreaterThan(0);
   });
 
+  it('does not thin x-axis ticks when explicit values are set', () => {
+    const narrowArea = { x: 50, y: 50, width: 200, height: 300 };
+    const specWithValues: NormalizedChartSpec = {
+      ...lineSpec,
+      encoding: {
+        x: {
+          field: 'date',
+          type: 'temporal',
+          axis: { values: ['2020-01-01', '2021-01-01', '2022-01-01'] },
+        },
+        y: { field: 'value', type: 'quantitative' },
+      },
+    };
+
+    const scales = computeScales(specWithValues, narrowArea, specWithValues.data);
+    const axes = computeAxes(scales, narrowArea, fullStrategy, theme);
+
+    // Explicit values should be preserved exactly as specified
+    expect(axes.x!.ticks.length).toBe(3);
+  });
+
   it('band scale shows all categories regardless of width', () => {
     const categories = ['Alpha', 'Bravo', 'Charlie', 'Delta', 'Echo'];
     const barSpec: NormalizedChartSpec = {

package/src/__tests__/dimensions.test.ts

@@ -265,4 +265,52 @@ describe('computeDimensions', () => {
     // Tooltip-only should NOT reserve extra margin (annotations are hidden)
     expect(dimsTooltipOnly.margins.right).toBe(dimsNoAnnotations.margins.right);
   });
+
+  it('clamps y-axis label margin on narrow containers to preserve chart area', () => {
+    const longLabelSpec: NormalizedChartSpec = {
+      ...baseSpec,
+      markType: 'bar',
+      markDef: { type: 'bar' },
+      data: [
+        {
+          category: 'This is a very long category label that would consume lots of space',
+          value: 10,
+        },
+        { category: 'Another extremely verbose category name', value: 20 },
+      ],
+      encoding: {
+        x: { field: 'value', type: 'quantitative' },
+        y: { field: 'category', type: 'nominal' },
+      },
+    };
+
+    const narrowDims = computeDimensions(
+      longLabelSpec,
+      { width: 350, height: 300 },
+      emptyLegend,
+      lightTheme,
+    );
+
+    // On narrow viewports, left margin should be clamped so the chart area
+    // retains at least ~45% of the container width
+    expect(narrowDims.chartArea.width).toBeGreaterThanOrEqual(350 * 0.4);
+  });
+
+  it('tightens legend gap on narrow viewports', () => {
+    const wideDims = computeDimensions(
+      baseSpec,
+      { width: 600, height: 400 },
+      topLegend,
+      lightTheme,
+    );
+    const narrowDims = computeDimensions(
+      baseSpec,
+      { width: 360, height: 400 },
+      topLegend,
+      lightTheme,
+    );
+
+    // Narrow viewport should have more chart height available (smaller legend gap)
+    expect(narrowDims.chartArea.height).toBeGreaterThanOrEqual(wideDims.chartArea.height - 10);
+  });
 });

package/src/__tests__/legend.test.ts

@@ -276,6 +276,30 @@ describe('computeLegend', () => {
     expect(deEntry.color).toBe('#00ff00');
   });
 
+  it('orders legend entries by explicit domain, not data order', () => {
+    const specExplicit: NormalizedChartSpec = {
+      ...specWithColor,
+      data: [
+        { date: '2020', value: 10, country: 'Germany' },
+        { date: '2021', value: 20, country: 'UK' },
+        { date: '2022', value: 30, country: 'US' },
+      ],
+      encoding: {
+        x: { field: 'date', type: 'temporal' },
+        y: { field: 'value', type: 'quantitative' },
+        color: {
+          field: 'country',
+          type: 'nominal',
+          scale: {
+            domain: ['US', 'UK', 'Germany'],
+          },
+        },
+      },
+    };
+    const legend = computeLegend(specExplicit, compactStrategy, theme, chartArea);
+    expect(legend.entries.map((e) => e.label)).toEqual(['US', 'UK', 'Germany']);
+  });
+
   it('uses correct swatch shape for chart type', () => {
     const lineLegend = computeLegend(specWithColor, fullStrategy, theme, chartArea);
     expect(lineLegend.entries[0].shape).toBe('line');
@@ -395,32 +419,25 @@ describe('computeLegend', () => {
     });
   });
 
-  // ---------------------------------------------------------------------------
-  // Characterization test (refactor/v7-cohesion step 1):
-  // Pins the 4px gap between a top-positioned legend and the chart area,
-  // as enforced at packages/engine/src/compile.ts:331. Refactor step 4 will
-  // consolidate legend row-wrapping geometry; this test guards the spacing
-  // invariant through that change.
-  // ---------------------------------------------------------------------------
   describe('top legend spacing', () => {
-    it('places the legend exactly 4px above the chart area', () => {
-      const spec = {
-        mark: 'bar' as const,
-        data: [
-          { name: 'A', value: 10, group: 'X' },
-          { name: 'A', value: 20, group: 'Y' },
-          { name: 'B', value: 30, group: 'X' },
-          { name: 'B', value: 25, group: 'Y' },
-        ],
-        encoding: {
-          x: { field: 'name', type: 'nominal' as const },
-          y: { field: 'value', type: 'quantitative' as const },
-          color: { field: 'group', type: 'nominal' as const },
-        },
-        legend: { position: 'top' as const },
-      };
+    const topLegendSpec = {
+      mark: 'bar' as const,
+      data: [
+        { name: 'A', value: 10, group: 'X' },
+        { name: 'A', value: 20, group: 'Y' },
+        { name: 'B', value: 30, group: 'X' },
+        { name: 'B', value: 25, group: 'Y' },
+      ],
+      encoding: {
+        x: { field: 'name', type: 'nominal' as const },
+        y: { field: 'value', type: 'quantitative' as const },
+        color: { field: 'group', type: 'nominal' as const },
+      },
+      legend: { position: 'top' as const },
+    };
 
-      const layout = compileChart(spec, { width: 600, height: 400 });
+    it('places the legend exactly 4px above the chart area at standard width', () => {
+      const layout = compileChart(topLegendSpec, { width: 600, height: 400 });
 
       expect(layout.legend.position).toBe('top');
       expect(layout.legend.entries.length).toBeGreaterThan(0);
@@ -428,8 +445,18 @@ describe('computeLegend', () => {
 
       const legendBottom = layout.legend.bounds.y + layout.legend.bounds.height;
       const gap = layout.area.y - legendBottom;
-      // Pin value matches the literal at compile.ts:331 (legendArea.y -= legendLayout.bounds.height + 4)
       expect(gap).toBe(4);
     });
+
+    it('eliminates legend gap on narrow viewports (< 420px)', () => {
+      const layout = compileChart(topLegendSpec, { width: 360, height: 400 });
+
+      expect(layout.legend.position).toBe('top');
+      expect(layout.legend.entries.length).toBeGreaterThan(0);
+
+      const legendBottom = layout.legend.bounds.y + layout.legend.bounds.height;
+      const gap = layout.area.y - legendBottom;
+      expect(gap).toBe(0);
+    });
   });
 });

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

@@ -264,6 +264,37 @@ describe('computeDotMarks', () => {
     });
   });
 
+  describe('baseline clamping', () => {
+    it('clamps stems to the plot area when domain does not include zero', () => {
+      const spec: NormalizedChartSpec = {
+        markType: 'circle',
+        markDef: { type: 'circle' },
+        data: [
+          { country: 'USA', score: 50 },
+          { country: 'UK', score: 80 },
+        ],
+        encoding: {
+          x: { field: 'score', type: 'quantitative', scale: { domain: [40, 100] } },
+          y: { field: 'country', type: 'nominal' },
+        },
+        chrome: {},
+        annotations: [],
+        responsive: true,
+        theme: {},
+        darkMode: 'off',
+        labels: { density: 'auto', format: '' },
+      };
+      const scales = computeScales(spec, chartArea, spec.data);
+      const marks = computeDotMarks(spec, scales, chartArea, fullStrategy);
+
+      const stems = marks.filter((m): m is RectMark => m.type === 'rect');
+      for (const stem of stems) {
+        expect(stem.x).toBeGreaterThanOrEqual(chartArea.x);
+        expect(stem.x + stem.width).toBeLessThanOrEqual(chartArea.x + chartArea.width);
+      }
+    });
+  });
+
   describe('edge cases', () => {
     it('returns empty array when no x encoding', () => {
       const spec: NormalizedChartSpec = {

package/src/charts/dot/compute.ts

@@ -67,7 +67,12 @@ export function computeDotMarks(
   }
 
   const bandwidth = yScale.bandwidth();
-  const baseline = xScale(0);
+  // Clamp baseline to the scale range so stems never extend past the plot area
+  // (e.g., when domain doesn't include zero, xScale(0) would land outside).
+  const [rangeStart, rangeEnd] = xScale.range();
+  const rangeMin = Math.min(rangeStart, rangeEnd);
+  const rangeMax = Math.max(rangeStart, rangeEnd);
+  const baseline = Math.max(rangeMin, Math.min(rangeMax, xScale(0)));
   const colorEnc = encoding.color && 'field' in encoding.color ? encoding.color : undefined;
   const isSequentialColor = colorEnc?.type === 'quantitative';
   const colorField = isSequentialColor ? undefined : colorEnc?.field;

package/src/compile.ts

@@ -64,6 +64,7 @@ import { computeDimensions } from './layout/dimensions';
 import { computeGridlines } from './layout/gridlines';
 import { computeScales } from './layout/scales';
 import { computeLegend } from './legend/compute';
+import { legendGap } from './legend/wrap';
 import { compileSankey as compileSankeyImpl } from './sankey/compile-sankey';
 import { compileTableLayout } from './tables/compile-table';
 import { computeTooltipDescriptors } from './tooltips/compute';
@@ -291,13 +292,14 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
   // the data area (in the margin) instead of overlapping data marks.
   const legendArea: Rect = { ...chartArea };
   if (legendLayout.entries.length > 0) {
+    const gap = legendGap(options.width);
     switch (legendLayout.position) {
       case 'top':
-        legendArea.y -= legendLayout.bounds.height + 4;
-        legendArea.height += legendLayout.bounds.height + 4;
+        legendArea.y -= legendLayout.bounds.height + gap;
+        legendArea.height += legendLayout.bounds.height + gap;
         break;
       case 'bottom':
-        legendArea.height += legendLayout.bounds.height + 4;
+        legendArea.height += legendLayout.bounds.height + gap;
         break;
       case 'right':
       case 'bottom-right':

package/src/layout/axes.ts

@@ -272,8 +272,11 @@ export function computeAxes(
     }));
 
     // Thin tick labels to prevent overlap (skip for band scales which use
-    // auto-rotation, and when the user set an explicit tickCount or values).
-    const shouldThin = scales.x.type !== 'band' && !axisConfig?.tickCount && !axisConfig?.values;
+    // auto-rotation, and when the user set explicit tick values).
+    // When tickCount is set, we still thin if D3 overshot the requested count
+    // (common with log scales where ticks(4) can return 26 values).
+    const hasExplicitValues = !!axisConfig?.values;
+    const shouldThin = scales.x.type !== 'band' && !hasExplicitValues;
     let ticks: AxisTick[];
     if (!shouldThin) {
       ticks = allTicks;
@@ -352,10 +355,12 @@ export function computeAxes(
       allTicks = continuousTicks(scales.y, yDensity, yTargetCount);
     }
 
-    // Thin tick labels to prevent overlap (skip for band scales, explicit tickCount, and values).
-    const shouldThin = scales.y.type !== 'band' && !axisConfig?.tickCount && !axisConfig?.values;
+    // Thin tick labels to prevent overlap (skip for band scales and explicit tick values).
+    // When tickCount is set, we still thin if D3 overshot the requested count
+    // (common with log scales where ticks(4) can return 26 values).
+    const shouldThinY = scales.y.type !== 'band' && !axisConfig?.values;
     let ticks: AxisTick[];
-    if (!shouldThin) {
+    if (!shouldThinY) {
       ticks = allTicks;
     } else if (isContinuousY) {
       // Continuous y-axis: re-request ticks at a lower count on overlap so

package/src/layout/dimensions.ts

@@ -25,6 +25,7 @@ import { computeChrome, estimateTextWidth } from '@opendata-ai/openchart-core';
 import { format as d3Format } from 'd3-format';
 
 import type { NormalizedChartSpec, NormalizedChrome } from '../compiler/types';
+import { legendGap } from '../legend/wrap';
 
 // ---------------------------------------------------------------------------
 // Types
@@ -251,7 +252,15 @@ export function computeDimensions(
         if (w > maxLabelWidth) maxLabelWidth = w;
       }
       if (maxLabelWidth > 0) {
-        margins.left = Math.max(margins.left, padding + maxLabelWidth + 12);
+        // Tighter label-to-chart gap on narrow containers
+        const labelGap = width < 500 ? 8 : 12;
+        // Clamp reservation so bars keep at least ~45% of container width on
+        // narrow viewports. Labels that exceed the cap will be truncated by
+        // the axis renderer (see axes.ts).
+        const maxLeftFraction = width < 400 ? 0.45 : width < 600 ? 0.55 : 1;
+        const maxLeftReserved = Math.floor(width * maxLeftFraction);
+        const reserved = Math.min(padding + maxLabelWidth + labelGap, maxLeftReserved);
+        margins.left = Math.max(margins.left, reserved);
       }
     } else if (encoding.y.type === 'quantitative' || encoding.y.type === 'temporal') {
       // Numeric tick labels on the left. Estimate width from the data range.
@@ -305,12 +314,13 @@ export function computeDimensions(
 
   // Reserve legend space
   if (legendLayout.entries.length > 0) {
+    const gap = legendGap(width);
     if (legendLayout.position === 'right' || legendLayout.position === 'bottom-right') {
       margins.right += legendLayout.bounds.width + 8;
     } else if (legendLayout.position === 'top') {
-      margins.top += legendLayout.bounds.height + 4;
+      margins.top += legendLayout.bounds.height + gap;
     } else if (legendLayout.position === 'bottom') {
-      margins.bottom += legendLayout.bounds.height + 4;
+      margins.bottom += legendLayout.bounds.height + gap;
     }
   }
 
@@ -347,10 +357,11 @@ export function computeDimensions(
     const bottomDelta = margins.bottom - newBottom;
 
     if (topDelta > 0 || bottomDelta > 0) {
+      const gap = legendGap(width);
       margins.top =
         newTop +
         (legendLayout.entries.length > 0 && legendLayout.position === 'top'
-          ? legendLayout.bounds.height + 4
+          ? legendLayout.bounds.height + gap
           : 0);
       margins.bottom = newBottom;
 

package/src/legend/compute.ts

@@ -20,10 +20,10 @@ import type {
   ResolvedTheme,
   TextStyle,
 } from '@opendata-ai/openchart-core';
-import { BRAND_RESERVE_WIDTH, estimateTextWidth } from '@opendata-ai/openchart-core';
+import { BRAND_RESERVE_WIDTH, COMPACT_WIDTH, estimateTextWidth } from '@opendata-ai/openchart-core';
 
 import type { NormalizedChartSpec } from '../compiler/types';
-import { ENTRY_GAP, measureLegendWrap, SWATCH_GAP, SWATCH_SIZE } from './wrap';
+import { ENTRY_GAP, ENTRY_GAP_COMPACT, measureLegendWrap, SWATCH_GAP, SWATCH_SIZE } from './wrap';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -67,12 +67,22 @@ function extractColorEntries(spec: NormalizedChartSpec, theme: ResolvedTheme): L
   // Sequential (quantitative) color doesn't produce discrete legend entries
   if (colorEnc.type === 'quantitative') return [];
 
-  const uniqueValues = [...new Set(spec.data.map((d) => String(d[colorEnc.field])))];
+  const dataValues = [...new Set(spec.data.map((d) => String(d[colorEnc.field])))];
   const explicitDomain = colorEnc.scale?.domain as string[] | undefined;
   const explicitRange = colorEnc.scale?.range as string[] | undefined;
   const palette = explicitRange ?? theme.colors.categorical;
   const shape = swatchShapeForType(spec.markType);
 
+  // Order legend entries by explicit domain when provided so the author
+  // controls which entries render first (and which get truncated last when
+  // symbolLimit applies). Without explicit domain, preserve data order.
+  const uniqueValues = explicitDomain
+    ? [
+        ...explicitDomain.filter((v) => dataValues.includes(v)),
+        ...dataValues.filter((v) => !explicitDomain.includes(v)),
+      ]
+    : dataValues;
+
   return uniqueValues.map((value, i) => {
     // When explicit domain+range are provided, look up the color by domain index
     // so legend colors match the mark colors exactly.
@@ -258,8 +268,12 @@ export function computeLegend(
   // Reserve space on the right for bottom legends so they don't overlap the brand
   // watermark. Top legends don't need this since the brand renders at the bottom.
   const reserveBrand = watermark && resolvedPosition === 'bottom';
+  // Tighten gaps on narrow viewports so horizontal legends keep fitting on one row.
+  const isCompact = chartArea.width < COMPACT_WIDTH;
+  const effectivePadding = isCompact ? 2 : LEGEND_PADDING;
+  const effectiveEntryGap = isCompact ? ENTRY_GAP_COMPACT : ENTRY_GAP;
   const availableWidth =
-    chartArea.width - LEGEND_PADDING * 2 - (reserveBrand ? BRAND_RESERVE_WIDTH : 0);
+    chartArea.width - effectivePadding * 2 - (reserveBrand ? BRAND_RESERVE_WIDTH : 0);
 
   // Apply symbolLimit first if set (minimum 1), then fit remaining entries to available rows.
   if (spec.legend?.symbolLimit != null) {
@@ -276,7 +290,13 @@ export function computeLegend(
       : spec.legend?.columns != null
         ? Math.ceil(entries.length / spec.legend.columns)
         : TOP_LEGEND_MAX_ROWS;
-  const { fittingCount } = measureLegendWrap(entries, availableWidth, labelStyle, maxRows);
+  const { fittingCount } = measureLegendWrap(
+    entries,
+    availableWidth,
+    labelStyle,
+    maxRows,
+    effectiveEntryGap,
+  );
 
   if (fittingCount < entries.length) {
     entries = truncateEntries(entries, fittingCount);
@@ -284,14 +304,20 @@ export function computeLegend(
 
   const totalWidth = entries.reduce((sum, entry) => {
     const labelWidth = estimateTextWidth(entry.label, labelStyle.fontSize, labelStyle.fontWeight);
-    return sum + SWATCH_SIZE + SWATCH_GAP + labelWidth + ENTRY_GAP;
+    return sum + SWATCH_SIZE + SWATCH_GAP + labelWidth + effectiveEntryGap;
   }, 0);
 
   // Calculate actual row count for height (recompute after truncation).
-  const { rowCount } = measureLegendWrap(entries, availableWidth, labelStyle);
+  const { rowCount } = measureLegendWrap(
+    entries,
+    availableWidth,
+    labelStyle,
+    undefined,
+    effectiveEntryGap,
+  );
 
   const rowHeight = SWATCH_SIZE + 4;
-  const legendHeight = rowCount * rowHeight + LEGEND_PADDING * 2;
+  const legendHeight = rowCount * rowHeight + effectivePadding * 2;
 
   // Apply user-provided legend offset
   const offsetDx = spec.legend?.offset?.dx ?? 0;
@@ -312,6 +338,6 @@ export function computeLegend(
     labelStyle,
     swatchSize: SWATCH_SIZE,
     swatchGap: SWATCH_GAP,
-    entryGap: ENTRY_GAP,
+    entryGap: effectiveEntryGap,
   };
 }

package/src/legend/wrap.ts

@@ -15,7 +15,7 @@
  */
 
 import type { LegendEntry, TextStyle } from '@opendata-ai/openchart-core';
-import { estimateTextWidth } from '@opendata-ai/openchart-core';
+import { COMPACT_WIDTH, estimateTextWidth } from '@opendata-ai/openchart-core';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -28,6 +28,16 @@ import { estimateTextWidth } from '@opendata-ai/openchart-core';
 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 = 4;
+
+/** 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
@@ -55,6 +65,7 @@ export function measureLegendWrap(
   maxWidth: number,
   labelStyle: TextStyle,
   maxRows?: number,
+  entryGap: number = ENTRY_GAP,
 ): LegendWrapResult {
   if (entries.length === 0) {
     return { rowCount: 0, fittingCount: 0, rowWidths: [] };
@@ -72,7 +83,7 @@ export function measureLegendWrap(
       labelStyle.fontSize,
       labelStyle.fontWeight,
     );
-    const entryWidth = SWATCH_SIZE + SWATCH_GAP + labelWidth + ENTRY_GAP;
+    const entryWidth = SWATCH_SIZE + SWATCH_GAP + labelWidth + entryGap;
 
     if (rowWidth + entryWidth > maxWidth && rowWidth > 0) {
       rowWidths.push(rowWidth);

package/src/sankey/compile-sankey.ts

@@ -507,6 +507,7 @@ export function compileSankey(spec: unknown, options: CompileOptions): SankeyLay
     },
     animation: resolvedAnimation,
     watermark,
+    measureText: options.measureText,
   };
 }