@opendata-ai/openchart-engine 2.3.4 → 2.4.0

package/package.json

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

package/src/__tests__/axes.test.ts

@@ -2,7 +2,7 @@ import type { LayoutStrategy } from '@opendata-ai/openchart-core';
 import { resolveTheme } from '@opendata-ai/openchart-core';
 import { describe, expect, it } from 'vitest';
 import type { NormalizedChartSpec } from '../compiler/types';
-import { computeAxes } from '../layout/axes';
+import { computeAxes, effectiveDensity } from '../layout/axes';
 import { computeScales } from '../layout/scales';
 
 const lineSpec: NormalizedChartSpec = {
@@ -111,4 +111,188 @@ describe('computeAxes', () => {
     expect(axes.y!.start.x).toBe(chartArea.x);
     expect(axes.y!.end.x).toBe(chartArea.x);
   });
+
+  // -------------------------------------------------------------------------
+  // Height-aware y-axis tick reduction
+  // -------------------------------------------------------------------------
+
+  it('reduces y-axis ticks for very short chart areas (< 120px)', () => {
+    const shortArea = { x: 50, y: 50, width: 500, height: 80 };
+    const scales = computeScales(lineSpec, shortArea, lineSpec.data);
+    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);
+  });
+
+  it('reduces y-axis ticks for medium-short chart areas (120-200px)', () => {
+    const mediumArea = { x: 50, y: 50, width: 500, height: 160 };
+    const tallArea = { x: 50, y: 50, width: 500, height: 400 };
+
+    const scalesMedium = computeScales(lineSpec, mediumArea, lineSpec.data);
+    const scalesTall = computeScales(lineSpec, tallArea, lineSpec.data);
+
+    const axesMedium = computeAxes(scalesMedium, mediumArea, fullStrategy, theme);
+    const axesTall = computeAxes(scalesTall, tallArea, fullStrategy, theme);
+
+    // Medium height should have fewer ticks than a tall chart with same 'full' density
+    expect(axesMedium.y!.ticks.length).toBeLessThanOrEqual(axesTall.y!.ticks.length);
+  });
+
+  it('does not increase y-axis ticks beyond base density for short charts', () => {
+    const shortArea = { x: 50, y: 50, width: 500, height: 80 };
+    const scales = computeScales(lineSpec, shortArea, lineSpec.data);
+
+    // Strategy already says minimal - short height shouldn't change anything
+    const axes = computeAxes(scales, shortArea, minimalStrategy, theme);
+    expect(axes.y!.ticks.length).toBeLessThanOrEqual(3);
+  });
+
+  // -------------------------------------------------------------------------
+  // Width-aware x-axis tick reduction
+  // -------------------------------------------------------------------------
+
+  it('reduces x-axis ticks for very narrow chart areas (< 150px)', () => {
+    const narrowArea = { x: 50, y: 50, width: 100, height: 300 };
+    const scales = computeScales(lineSpec, narrowArea, lineSpec.data);
+    const axes = computeAxes(scales, narrowArea, fullStrategy, theme);
+
+    // Width < 150 forces minimal density for x-axis
+    expect(axes.x!.ticks.length).toBeLessThanOrEqual(3);
+  });
+
+  it('reduces x-axis ticks for medium-narrow chart areas (150-300px)', () => {
+    const mediumArea = { x: 50, y: 50, width: 250, height: 300 };
+    const wideArea = { x: 50, y: 50, width: 600, height: 300 };
+
+    const scalesMedium = computeScales(lineSpec, mediumArea, lineSpec.data);
+    const scalesWide = computeScales(lineSpec, wideArea, lineSpec.data);
+
+    const axesMedium = computeAxes(scalesMedium, mediumArea, fullStrategy, theme);
+    const axesWide = computeAxes(scalesWide, wideArea, fullStrategy, theme);
+
+    expect(axesMedium.x!.ticks.length).toBeLessThanOrEqual(axesWide.x!.ticks.length);
+  });
+
+  // -------------------------------------------------------------------------
+  // Both axes constrained simultaneously (thumbnail scenario)
+  // -------------------------------------------------------------------------
+
+  it('reduces ticks on both axes for thumbnail-sized charts', () => {
+    const thumbnailArea = { x: 10, y: 10, width: 120, height: 80 };
+    const fullArea = { x: 50, y: 50, width: 600, height: 400 };
+
+    const scalesThumb = computeScales(lineSpec, thumbnailArea, lineSpec.data);
+    const scalesFull = computeScales(lineSpec, fullArea, lineSpec.data);
+
+    const axesThumb = computeAxes(scalesThumb, thumbnailArea, fullStrategy, theme);
+    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);
+
+    // And fewer than full-size
+    expect(axesThumb.x!.ticks.length).toBeLessThanOrEqual(axesFull.x!.ticks.length);
+    expect(axesThumb.y!.ticks.length).toBeLessThanOrEqual(axesFull.y!.ticks.length);
+  });
+
+  // -------------------------------------------------------------------------
+  // tickAngle propagation
+  // -------------------------------------------------------------------------
+
+  it('propagates tickAngle from encoding to x-axis layout', () => {
+    const specWithAngle: NormalizedChartSpec = {
+      ...lineSpec,
+      type: 'column',
+      data: [
+        { cat: 'California', val: 10 },
+        { cat: 'New York', val: 20 },
+      ],
+      encoding: {
+        x: { field: 'cat', type: 'nominal', axis: { tickAngle: -90 } },
+        y: { field: 'val', type: 'quantitative' },
+      },
+    };
+    const scales = computeScales(specWithAngle, chartArea, specWithAngle.data);
+    const axes = computeAxes(scales, chartArea, fullStrategy, theme);
+
+    expect(axes.x!.tickAngle).toBe(-90);
+  });
+
+  it('leaves tickAngle undefined when not specified', () => {
+    const scales = computeScales(lineSpec, chartArea, lineSpec.data);
+    const axes = computeAxes(scales, chartArea, fullStrategy, theme);
+
+    expect(axes.x!.tickAngle).toBeUndefined();
+    expect(axes.y!.tickAngle).toBeUndefined();
+  });
+
+  it('propagates tickAngle to y-axis layout', () => {
+    const specWithAngle: NormalizedChartSpec = {
+      ...lineSpec,
+      encoding: {
+        x: { field: 'date', type: 'temporal' },
+        y: { field: 'value', type: 'quantitative', axis: { tickAngle: -45 } },
+      },
+    };
+    const scales = computeScales(specWithAngle, chartArea, specWithAngle.data);
+    const axes = computeAxes(scales, chartArea, fullStrategy, theme);
+
+    expect(axes.y!.tickAngle).toBe(-45);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// effectiveDensity unit tests
+// ---------------------------------------------------------------------------
+
+describe('effectiveDensity', () => {
+  const MINIMAL_THRESHOLD = 120;
+  const REDUCED_THRESHOLD = 200;
+
+  it('returns base density when axis length exceeds all thresholds', () => {
+    expect(effectiveDensity('full', 500, MINIMAL_THRESHOLD, REDUCED_THRESHOLD)).toBe('full');
+    expect(effectiveDensity('reduced', 500, MINIMAL_THRESHOLD, REDUCED_THRESHOLD)).toBe('reduced');
+    expect(effectiveDensity('minimal', 500, MINIMAL_THRESHOLD, REDUCED_THRESHOLD)).toBe('minimal');
+  });
+
+  it('forces minimal density below the minimal threshold', () => {
+    expect(effectiveDensity('full', 80, MINIMAL_THRESHOLD, REDUCED_THRESHOLD)).toBe('minimal');
+    expect(effectiveDensity('reduced', 80, MINIMAL_THRESHOLD, REDUCED_THRESHOLD)).toBe('minimal');
+    expect(effectiveDensity('minimal', 80, MINIMAL_THRESHOLD, REDUCED_THRESHOLD)).toBe('minimal');
+  });
+
+  it('caps at reduced density between thresholds', () => {
+    // 'full' base should step down to 'reduced'
+    expect(effectiveDensity('full', 160, MINIMAL_THRESHOLD, REDUCED_THRESHOLD)).toBe('reduced');
+  });
+
+  it('does not increase density beyond base when between thresholds', () => {
+    // 'minimal' base should stay 'minimal' even between thresholds
+    expect(effectiveDensity('minimal', 160, MINIMAL_THRESHOLD, REDUCED_THRESHOLD)).toBe('minimal');
+    // 'reduced' base should stay 'reduced'
+    expect(effectiveDensity('reduced', 160, MINIMAL_THRESHOLD, REDUCED_THRESHOLD)).toBe('reduced');
+  });
+
+  it('handles exact threshold boundaries', () => {
+    // At exactly the minimal threshold, we're NOT below it
+    expect(effectiveDensity('full', 120, MINIMAL_THRESHOLD, REDUCED_THRESHOLD)).toBe('reduced');
+    // At exactly the reduced threshold, we're NOT below it
+    expect(effectiveDensity('full', 200, MINIMAL_THRESHOLD, REDUCED_THRESHOLD)).toBe('full');
+  });
+
+  it('handles zero and negative lengths', () => {
+    expect(effectiveDensity('full', 0, MINIMAL_THRESHOLD, REDUCED_THRESHOLD)).toBe('minimal');
+    expect(effectiveDensity('full', -10, MINIMAL_THRESHOLD, REDUCED_THRESHOLD)).toBe('minimal');
+  });
+
+  it('works with custom thresholds (x-axis uses different values)', () => {
+    const X_MINIMAL = 150;
+    const X_REDUCED = 300;
+
+    expect(effectiveDensity('full', 100, X_MINIMAL, X_REDUCED)).toBe('minimal');
+    expect(effectiveDensity('full', 200, X_MINIMAL, X_REDUCED)).toBe('reduced');
+    expect(effectiveDensity('full', 400, X_MINIMAL, X_REDUCED)).toBe('full');
+  });
 });

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

@@ -457,4 +457,56 @@ describe('compileGraph', () => {
       ),
     ).toThrow('compileGraph received a scatter spec');
   });
+
+  it('propagates tickAngle through the full compilation pipeline', () => {
+    const columnSpec = {
+      type: 'column' as const,
+      data: [
+        { state: 'California', pop: 39000000 },
+        { state: 'Texas', pop: 29000000 },
+        { state: 'Florida', pop: 22000000 },
+        { state: 'New York', pop: 20000000 },
+        { state: 'Pennsylvania', pop: 13000000 },
+      ],
+      encoding: {
+        x: { field: 'state', type: 'nominal' as const, axis: { tickAngle: -90 } },
+        y: { field: 'pop', type: 'quantitative' as const },
+      },
+    };
+
+    const layout = compileChart(columnSpec, { width: 400, height: 300 });
+
+    // tickAngle should be propagated to the x-axis layout
+    expect(layout.axes.x!.tickAngle).toBe(-90);
+    // y-axis should not have a tickAngle
+    expect(layout.axes.y!.tickAngle).toBeUndefined();
+  });
+
+  it('reserves extra bottom margin for rotated x-axis labels', () => {
+    const baseColumnSpec = {
+      type: 'column' as const,
+      data: [
+        { state: 'California', pop: 39000000 },
+        { state: 'Texas', pop: 29000000 },
+        { state: 'Massachusetts', pop: 7000000 },
+      ],
+      encoding: {
+        x: { field: 'state', type: 'nominal' as const },
+        y: { field: 'pop', type: 'quantitative' as const },
+      },
+    };
+    const rotatedColumnSpec = {
+      ...baseColumnSpec,
+      encoding: {
+        x: { field: 'state', type: 'nominal' as const, axis: { tickAngle: -90 } },
+        y: { field: 'pop', type: 'quantitative' as const },
+      },
+    };
+
+    const layoutNormal = compileChart(baseColumnSpec, { width: 400, height: 300 });
+    const layoutRotated = compileChart(rotatedColumnSpec, { width: 400, height: 300 });
+
+    // Rotated labels should shrink the chart area height
+    expect(layoutRotated.area.height).toBeLessThan(layoutNormal.area.height);
+  });
 });

package/src/__tests__/dimensions.test.ts

@@ -148,4 +148,72 @@ describe('computeDimensions', () => {
     expect(dims.chartArea.width).toBeGreaterThanOrEqual(0);
     expect(dims.chartArea.height).toBeGreaterThanOrEqual(0);
   });
+
+  it('reserves extra bottom space for rotated x-axis labels', () => {
+    const rotatedSpec: NormalizedChartSpec = {
+      ...baseSpec,
+      type: 'column',
+      data: [
+        { category: 'California', value: 10 },
+        { category: 'New York', value: 20 },
+        { category: 'Massachusetts', value: 15 },
+      ],
+      encoding: {
+        x: { field: 'category', type: 'nominal', axis: { tickAngle: -90 } },
+        y: { field: 'value', type: 'quantitative' },
+      },
+    };
+    const normalSpec: NormalizedChartSpec = {
+      ...baseSpec,
+      type: 'column',
+      data: rotatedSpec.data,
+      encoding: {
+        x: { field: 'category', type: 'nominal' },
+        y: { field: 'value', type: 'quantitative' },
+      },
+    };
+
+    const dimsRotated = computeDimensions(
+      rotatedSpec,
+      { width: 600, height: 400 },
+      emptyLegend,
+      lightTheme,
+    );
+    const dimsNormal = computeDimensions(
+      normalSpec,
+      { width: 600, height: 400 },
+      emptyLegend,
+      lightTheme,
+    );
+
+    // Rotated labels should reserve more bottom space, shrinking the chart area
+    expect(dimsRotated.chartArea.height).toBeLessThan(dimsNormal.chartArea.height);
+    expect(dimsRotated.margins.bottom).toBeGreaterThan(dimsNormal.margins.bottom);
+  });
+
+  it('does not change bottom space for small tick angles', () => {
+    const smallAngleSpec: NormalizedChartSpec = {
+      ...baseSpec,
+      encoding: {
+        x: { field: 'date', type: 'temporal', axis: { tickAngle: 5 } },
+        y: { field: 'value', type: 'quantitative' },
+      },
+    };
+
+    const dimsSmall = computeDimensions(
+      smallAngleSpec,
+      { width: 600, height: 400 },
+      emptyLegend,
+      lightTheme,
+    );
+    const dimsNone = computeDimensions(
+      baseSpec,
+      { width: 600, height: 400 },
+      emptyLegend,
+      lightTheme,
+    );
+
+    // Small angles (< 10 degrees) should not trigger rotated label logic
+    expect(dimsSmall.margins.bottom).toBe(dimsNone.margins.bottom);
+  });
 });

package/src/layout/axes.ts

@@ -35,6 +35,60 @@ const TICK_COUNTS: Record<AxisLabelDensity, number> = {
   minimal: 3,
 };
 
+/**
+ * Height thresholds for reducing y-axis tick density.
+ * Below these pixel heights, we step down the density regardless of the
+ * width-based strategy. This prevents overlapping y-axis labels in short
+ * containers like thumbnail previews.
+ */
+const HEIGHT_MINIMAL_THRESHOLD = 120;
+const HEIGHT_REDUCED_THRESHOLD = 200;
+
+/**
+ * Width thresholds for reducing x-axis tick density.
+ * Mirrors the height logic for the x-axis: narrow containers get fewer ticks.
+ */
+const WIDTH_MINIMAL_THRESHOLD = 150;
+const WIDTH_REDUCED_THRESHOLD = 300;
+
+/** Ordered densities from most to fewest ticks. */
+const DENSITY_ORDER: AxisLabelDensity[] = ['full', 'reduced', 'minimal'];
+
+/**
+ * Compute effective axis tick density by considering available space.
+ *
+ * The width-based breakpoint system sets a base density, but it doesn't know
+ * about the actual chart area dimensions (which shrink after chrome/legend
+ * allocation). This function steps density down further when the axis
+ * dimension is too small for the requested tick count.
+ *
+ * @param baseDensity - The density from the responsive layout strategy.
+ * @param axisLength - Available pixels along this axis (height for y, width for x).
+ * @param minimalThreshold - Below this pixel size, force minimal density.
+ * @param reducedThreshold - Below this pixel size, cap at reduced density.
+ * @returns The effective density, never looser than the base.
+ */
+export function effectiveDensity(
+  baseDensity: AxisLabelDensity,
+  axisLength: number,
+  minimalThreshold: number,
+  reducedThreshold: number,
+): AxisLabelDensity {
+  let density = baseDensity;
+
+  if (axisLength < minimalThreshold) {
+    density = 'minimal';
+  } else if (axisLength < reducedThreshold) {
+    // Don't increase density beyond what the base strategy allows.
+    // If base is already 'minimal', keep it.
+    const baseIdx = DENSITY_ORDER.indexOf(baseDensity);
+    const reducedIdx = DENSITY_ORDER.indexOf('reduced');
+    density = DENSITY_ORDER[Math.max(baseIdx, reducedIdx)];
+  }
+
+  return density;
+}
+
 // ---------------------------------------------------------------------------
 // Tick generation
 // ---------------------------------------------------------------------------
@@ -127,7 +181,22 @@ export function computeAxes(
   theme: ResolvedTheme,
 ): AxesResult {
   const result: AxesResult = {};
-  const density = strategy.axisLabelDensity;
+  const baseDensity = strategy.axisLabelDensity;
+
+  // Compute per-axis density based on available space.
+  // Y-axis density adapts to chart height; X-axis density adapts to chart width.
+  const yDensity = effectiveDensity(
+    baseDensity,
+    chartArea.height,
+    HEIGHT_MINIMAL_THRESHOLD,
+    HEIGHT_REDUCED_THRESHOLD,
+  );
+  const xDensity = effectiveDensity(
+    baseDensity,
+    chartArea.width,
+    WIDTH_MINIMAL_THRESHOLD,
+    WIDTH_REDUCED_THRESHOLD,
+  );
 
   const tickLabelStyle: TextStyle = {
     fontFamily: theme.fonts.family,
@@ -149,8 +218,8 @@ export function computeAxes(
   if (scales.x) {
     const ticks =
       scales.x.type === 'band' || scales.x.type === 'point' || scales.x.type === 'ordinal'
-        ? categoricalTicks(scales.x, density)
-        : continuousTicks(scales.x, density);
+        ? categoricalTicks(scales.x, xDensity)
+        : continuousTicks(scales.x, xDensity);
 
     const gridlines: Gridline[] = ticks.map((t) => ({
       position: t.position,
@@ -163,6 +232,7 @@ export function computeAxes(
       label: scales.x.channel.axis?.label,
       labelStyle: axisLabelStyle,
       tickLabelStyle,
+      tickAngle: scales.x.channel.axis?.tickAngle,
       start: { x: chartArea.x, y: chartArea.y + chartArea.height },
       end: { x: chartArea.x + chartArea.width, y: chartArea.y + chartArea.height },
     };
@@ -171,8 +241,8 @@ export function computeAxes(
   if (scales.y) {
     const ticks =
       scales.y.type === 'band' || scales.y.type === 'point' || scales.y.type === 'ordinal'
-        ? categoricalTicks(scales.y, density)
-        : continuousTicks(scales.y, density);
+        ? categoricalTicks(scales.y, yDensity)
+        : continuousTicks(scales.y, yDensity);
 
     const gridlines: Gridline[] = ticks.map((t) => ({
       position: t.position,
@@ -186,6 +256,7 @@ export function computeAxes(
       label: scales.y.channel.axis?.label,
       labelStyle: axisLabelStyle,
       tickLabelStyle,
+      tickAngle: scales.y.channel.axis?.tickAngle,
       start: { x: chartArea.x, y: chartArea.y },
       end: { x: chartArea.x, y: chartArea.y + chartArea.height },
     };

package/src/layout/dimensions.ts

@@ -90,8 +90,34 @@ export function computeDimensions(
   // Estimate x-axis height below chart area: tick labels sit 14px below,
   // axis title sits 35px below. These extend past the chart area bottom
   // and source/footer chrome must be positioned below them.
-  const hasXAxisLabel = !!(encoding.x?.axis as Record<string, unknown> | undefined)?.label;
-  const xAxisHeight = isRadial ? 0 : hasXAxisLabel ? 48 : 26;
+  const xAxis = encoding.x?.axis as (Record<string, unknown> & { tickAngle?: number }) | undefined;
+  const hasXAxisLabel = !!xAxis?.label;
+  const xTickAngle = xAxis?.tickAngle;
+
+  let xAxisHeight: number;
+  if (isRadial) {
+    xAxisHeight = 0;
+  } else if (xTickAngle && Math.abs(xTickAngle) > 10) {
+    // Rotated labels: estimate height from the longest label text.
+    // At -90 degrees, the label height = text width. At -45, it's width * sin(45).
+    const angleRad = Math.abs(xTickAngle) * (Math.PI / 180);
+    const xField = encoding.x?.field;
+    let maxLabelWidth = 40; // fallback
+    if (xField) {
+      for (const row of spec.data) {
+        const label = String(row[xField] ?? '');
+        const w = estimateTextWidth(label, theme.fonts.sizes.axisTick, theme.fonts.weights.normal);
+        if (w > maxLabelWidth) maxLabelWidth = w;
+      }
+    }
+    // Rotated label height: width * sin(angle), plus a small gap
+    const rotatedHeight = maxLabelWidth * Math.sin(angleRad) + 6;
+    // Cap at a reasonable max to avoid absurd margins
+    const labelHeight = Math.min(rotatedHeight, 120);
+    xAxisHeight = hasXAxisLabel ? labelHeight + 20 : labelHeight;
+  } else {
+    xAxisHeight = hasXAxisLabel ? 48 : 26;
+  }
 
   // Build margins: padding + chrome + axis space
   const margins: Margins = {