@opendata-ai/openchart-engine 2.9.1 → 2.11.0

package/package.json

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

package/src/__test-fixtures__/specs.ts

@@ -24,6 +24,8 @@ export function makeFullStrategy(): LayoutStrategy {
     legendPosition: 'right',
     annotationPosition: 'inline',
     axisLabelDensity: 'full',
+    chromeMode: 'full',
+    legendMaxHeight: -1,
   };
 }
 
@@ -34,6 +36,8 @@ export function makeCompactStrategy(): LayoutStrategy {
     legendPosition: 'top',
     annotationPosition: 'tooltip-only',
     axisLabelDensity: 'minimal',
+    chromeMode: 'full',
+    legendMaxHeight: -1,
   };
 }
 

package/src/__tests__/axes.test.ts

@@ -1,8 +1,8 @@
-import type { LayoutStrategy } from '@opendata-ai/openchart-core';
+import type { AxisTick, 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, effectiveDensity } from '../layout/axes';
+import { computeAxes, effectiveDensity, thinTicksUntilFit, ticksOverlap } from '../layout/axes';
 import { computeScales } from '../layout/scales';
 
 const lineSpec: NormalizedChartSpec = {
@@ -32,6 +32,8 @@ const fullStrategy: LayoutStrategy = {
   legendPosition: 'right',
   annotationPosition: 'inline',
   axisLabelDensity: 'full',
+  chromeMode: 'full',
+  legendMaxHeight: -1,
 };
 
 const minimalStrategy: LayoutStrategy = {
@@ -39,6 +41,8 @@ const minimalStrategy: LayoutStrategy = {
   legendPosition: 'top',
   annotationPosition: 'tooltip-only',
   axisLabelDensity: 'minimal',
+  chromeMode: 'full',
+  legendMaxHeight: -1,
 };
 
 describe('computeAxes', () => {
@@ -296,3 +300,180 @@ describe('effectiveDensity', () => {
     expect(effectiveDensity('full', 400, X_MINIMAL, X_REDUCED)).toBe('full');
   });
 });
+
+// ---------------------------------------------------------------------------
+// ticksOverlap unit tests
+// ---------------------------------------------------------------------------
+
+describe('ticksOverlap', () => {
+  const fontSize = 12;
+  const fontWeight = 400;
+
+  it('returns false for empty or single tick', () => {
+    expect(ticksOverlap([], fontSize, fontWeight)).toBe(false);
+    expect(ticksOverlap([{ value: 0, position: 100, label: 'A' }], fontSize, fontWeight)).toBe(
+      false,
+    );
+  });
+
+  it('returns false when ticks are well-spaced', () => {
+    const ticks: AxisTick[] = [
+      { value: 0, position: 0, label: 'A' },
+      { value: 1, position: 200, label: 'B' },
+      { value: 2, position: 400, label: 'C' },
+    ];
+    expect(ticksOverlap(ticks, fontSize, fontWeight)).toBe(false);
+  });
+
+  it('returns true when ticks are too close together', () => {
+    const ticks: AxisTick[] = [
+      { value: 0, position: 0, label: 'January 2025' },
+      { value: 1, position: 30, label: 'February 2025' },
+      { value: 2, position: 60, label: 'March 2025' },
+    ];
+    expect(ticksOverlap(ticks, fontSize, fontWeight)).toBe(true);
+  });
+
+  it('uses measureText when provided', () => {
+    const ticks: AxisTick[] = [
+      { value: 0, position: 0, label: 'A' },
+      { value: 1, position: 100, label: 'B' },
+    ];
+
+    // With a measureText that reports very wide labels, they should overlap
+    const wideMeasure = () => ({ width: 200, height: 12 });
+    expect(ticksOverlap(ticks, fontSize, fontWeight, wideMeasure)).toBe(true);
+
+    // With a measureText that reports very narrow labels, they should not overlap
+    const narrowMeasure = () => ({ width: 1, height: 12 });
+    expect(ticksOverlap(ticks, fontSize, fontWeight, narrowMeasure)).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// thinTicksUntilFit unit tests
+// ---------------------------------------------------------------------------
+
+describe('thinTicksUntilFit', () => {
+  const fontSize = 12;
+  const fontWeight = 400;
+
+  it('returns original array when no overlap', () => {
+    const ticks: AxisTick[] = [
+      { value: 0, position: 0, label: 'A' },
+      { value: 1, position: 200, label: 'B' },
+      { value: 2, position: 400, label: 'C' },
+    ];
+    const result = thinTicksUntilFit(ticks, fontSize, fontWeight);
+    expect(result).toBe(ticks); // Same reference, not a copy
+  });
+
+  it('thins overlapping ticks while keeping first and last', () => {
+    // Ticks at 10px intervals with long labels that will overlap
+    const ticks: AxisTick[] = Array.from({ length: 8 }, (_, i) => ({
+      value: i,
+      position: i * 10,
+      label: 'Long Label Text',
+    }));
+
+    const result = thinTicksUntilFit(ticks, fontSize, fontWeight);
+
+    // Should have fewer ticks than the original
+    expect(result.length).toBeLessThan(ticks.length);
+    // Should always keep first and last
+    expect(result[0]).toBe(ticks[0]);
+    expect(result[result.length - 1]).toBe(ticks[ticks.length - 1]);
+    // Should have at least MIN_TICK_COUNT (2)
+    expect(result.length).toBeGreaterThanOrEqual(2);
+  });
+
+  it('returns at least 2 ticks even when labels are very wide', () => {
+    const ticks: AxisTick[] = [
+      { value: 0, position: 0, label: 'Very Long Label That Is Wide' },
+      { value: 1, position: 5, label: 'Another Very Long Label' },
+      { value: 2, position: 10, label: 'Yet Another Long Label Here' },
+    ];
+    const result = thinTicksUntilFit(ticks, fontSize, fontWeight);
+    expect(result.length).toBeGreaterThanOrEqual(2);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Text-aware tick density integration tests
+// ---------------------------------------------------------------------------
+
+describe('text-aware tick density', () => {
+  it('produces fewer x-axis ticks in narrow charts', () => {
+    const narrowArea = { x: 50, y: 50, width: 200, height: 300 };
+    const wideArea = { x: 50, y: 50, width: 800, height: 300 };
+
+    const scalesNarrow = computeScales(lineSpec, narrowArea, lineSpec.data);
+    const scalesWide = computeScales(lineSpec, wideArea, lineSpec.data);
+
+    const axesNarrow = computeAxes(scalesNarrow, narrowArea, fullStrategy, theme);
+    const axesWide = computeAxes(scalesWide, wideArea, fullStrategy, theme);
+
+    expect(axesNarrow.x!.ticks.length).toBeLessThanOrEqual(axesWide.x!.ticks.length);
+  });
+
+  it('does not thin x-axis ticks when explicit tickCount is set', () => {
+    const narrowArea = { x: 50, y: 50, width: 200, height: 300 };
+    const specWithTickCount: NormalizedChartSpec = {
+      ...lineSpec,
+      encoding: {
+        x: { field: 'date', type: 'temporal', axis: { tickCount: 8 } },
+        y: { field: 'value', type: 'quantitative' },
+      },
+    };
+
+    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
+    expect(axes.x!.ticks.length).toBeGreaterThan(0);
+  });
+
+  it('band scale shows all categories regardless of width', () => {
+    const categories = ['Alpha', 'Bravo', 'Charlie', 'Delta', 'Echo'];
+    const barSpec: NormalizedChartSpec = {
+      ...lineSpec,
+      type: 'column',
+      data: categories.map((cat, i) => ({ cat, val: (i + 1) * 10 })),
+      encoding: {
+        x: { field: 'cat', type: 'nominal' },
+        y: { field: 'val', type: 'quantitative' },
+      },
+    };
+
+    const narrowArea = { x: 50, y: 50, width: 200, height: 300 };
+    const scales = computeScales(barSpec, narrowArea, barSpec.data);
+    const axes = computeAxes(scales, narrowArea, fullStrategy, theme);
+
+    // Band scales show all categories (auto-rotation handles overlap instead)
+    expect(axes.x!.ticks.length).toBe(categories.length);
+  });
+
+  it('passes measureText to auto-rotation detection', () => {
+    const barSpec: NormalizedChartSpec = {
+      ...lineSpec,
+      type: 'column',
+      data: [
+        { cat: 'A', val: 10 },
+        { cat: 'B', val: 20 },
+      ],
+      encoding: {
+        x: { field: 'cat', type: 'nominal' },
+        y: { field: 'val', type: 'quantitative' },
+      },
+    };
+
+    // measureText that reports very wide labels should trigger rotation
+    const wideMeasure = () => ({ width: 1000, height: 12 });
+    const scales = computeScales(barSpec, chartArea, barSpec.data);
+    const axes = computeAxes(scales, chartArea, fullStrategy, theme, wideMeasure);
+
+    expect(axes.x!.tickAngle).toBe(-45);
+  });
+});

package/src/__tests__/legend.test.ts

@@ -40,6 +40,8 @@ const fullStrategy: LayoutStrategy = {
   legendPosition: 'right',
   annotationPosition: 'inline',
   axisLabelDensity: 'full',
+  chromeMode: 'full',
+  legendMaxHeight: -1,
 };
 
 const compactStrategy: LayoutStrategy = {
@@ -47,6 +49,8 @@ const compactStrategy: LayoutStrategy = {
   legendPosition: 'top',
   annotationPosition: 'tooltip-only',
   axisLabelDensity: 'minimal',
+  chromeMode: 'full',
+  legendMaxHeight: -1,
 };
 
 describe('computeLegend', () => {

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

@@ -354,8 +354,8 @@ describe('computeAnnotations', () => {
       // The offset annotation should be shifted by the dx/dy amount
       const dx = withOffset[0].label!.x - withoutOffset[0].label!.x;
       const dy = withOffset[0].label!.y - withoutOffset[0].label!.y;
-      expect(dx).toBe(20);
-      expect(dy).toBe(-30);
+      expect(dx).toBeCloseTo(20);
+      expect(dy).toBeCloseTo(-30);
     });
   });
 
@@ -514,8 +514,8 @@ describe('computeAnnotations', () => {
 
       const dx = withOffset[0].label!.x - withoutOffset[0].label!.x;
       const dy = withOffset[0].label!.y - withoutOffset[0].label!.y;
-      expect(dx).toBe(20);
-      expect(dy).toBe(10);
+      expect(dx).toBeCloseTo(20);
+      expect(dy).toBeCloseTo(10);
     });
   });
 
@@ -773,4 +773,173 @@ describe('computeAnnotations', () => {
       expect(connector.from.x).toBeCloseTo(label.x + 66, 1);
     });
   });
+
+  // -----------------------------------------------------------------
+  // Annotation-to-annotation collision resolution
+  // -----------------------------------------------------------------
+
+  describe('annotation-to-annotation collision', () => {
+    it('nudges second annotation when two overlap at the same data point', () => {
+      const spec = makeSpec([
+        { type: 'text', x: '2020-01-01', y: 20, text: 'First note' },
+        { type: 'text', x: '2020-01-01', y: 20, text: 'Second note' },
+      ]);
+      const scales = computeScales(spec, chartArea, spec.data);
+      const annotations = computeAnnotations(spec, scales, chartArea, fullStrategy);
+
+      expect(annotations).toHaveLength(2);
+
+      const label1 = annotations[0].label!;
+      const label2 = annotations[1].label!;
+
+      // Both should be visible
+      expect(label1.visible).toBe(true);
+      expect(label2.visible).toBe(true);
+
+      // Labels should not overlap: their positions should differ
+      const samePosition = label1.x === label2.x && label1.y === label2.y;
+      expect(samePosition).toBe(false);
+    });
+
+    it('nudges second annotation when nearby data points produce overlapping labels', () => {
+      const spec = makeSpec([
+        { type: 'text', x: '2020-01-01', y: 20, text: 'First annotation' },
+        { type: 'text', x: '2020-01-01', y: 21, text: 'Second annotation' },
+      ]);
+      const scales = computeScales(spec, chartArea, spec.data);
+      const annotations = computeAnnotations(spec, scales, chartArea, fullStrategy);
+
+      expect(annotations).toHaveLength(2);
+
+      const label1 = annotations[0].label!;
+      const label2 = annotations[1].label!;
+
+      // After collision resolution, bounding boxes should not overlap
+      // Check that at least one coordinate differs meaningfully
+      const dy = Math.abs(label1.y - label2.y);
+      const dx = Math.abs(label1.x - label2.x);
+      expect(dx + dy).toBeGreaterThan(5);
+    });
+
+    it('recomputes connector origin after nudging', () => {
+      const spec = makeSpec([
+        { type: 'text', x: '2020-01-01', y: 20, text: 'First note' },
+        { type: 'text', x: '2020-01-01', y: 20, text: 'Second note' },
+      ]);
+      const scales = computeScales(spec, chartArea, spec.data);
+      const annotations = computeAnnotations(spec, scales, chartArea, fullStrategy);
+
+      const nudgedLabel = annotations[1].label!;
+
+      // The nudged annotation should still have a connector
+      expect(nudgedLabel.connector).toBeDefined();
+
+      // The connector "from" should be near the nudged label position, not the original
+      const connFrom = nudgedLabel.connector!.from;
+      const labelCenterX = nudgedLabel.x;
+      const labelCenterY = nudgedLabel.y;
+
+      // Connector origin should be within a reasonable distance of the label
+      const distFromLabel = Math.sqrt(
+        (connFrom.x - labelCenterX) ** 2 + (connFrom.y - labelCenterY) ** 2,
+      );
+      // Should be within the label's bounding box range (text width + height)
+      expect(distFromLabel).toBeLessThan(200);
+    });
+
+    it('resolves three overlapping annotations without any collision', () => {
+      const spec = makeSpec([
+        { type: 'text', x: '2020-01-01', y: 20, text: 'Note A' },
+        { type: 'text', x: '2020-01-01', y: 20, text: 'Note B' },
+        { type: 'text', x: '2020-01-01', y: 20, text: 'Note C' },
+      ]);
+      const scales = computeScales(spec, chartArea, spec.data);
+      const annotations = computeAnnotations(spec, scales, chartArea, fullStrategy);
+
+      expect(annotations).toHaveLength(3);
+
+      // All three should be visible
+      for (const ann of annotations) {
+        expect(ann.label!.visible).toBe(true);
+      }
+
+      // All three should have distinct positions
+      const positions = annotations.map((a) => `${a.label!.x.toFixed(1)},${a.label!.y.toFixed(1)}`);
+      const unique = new Set(positions);
+      expect(unique.size).toBe(3);
+    });
+
+    it('does not nudge annotations that already have distinct positions', () => {
+      const spec = makeSpec([
+        {
+          type: 'text',
+          x: '2020-01-01',
+          y: 10,
+          text: 'Low point',
+          anchor: 'bottom',
+          offset: { dx: 0, dy: 40 },
+        },
+        {
+          type: 'text',
+          x: '2022-01-01',
+          y: 40,
+          text: 'High point',
+          anchor: 'top',
+          offset: { dx: 0, dy: -40 },
+        },
+      ]);
+      const scales = computeScales(spec, chartArea, spec.data);
+
+      // Compute once to get positions
+      const annotations = computeAnnotations(spec, scales, chartArea, fullStrategy);
+
+      expect(annotations).toHaveLength(2);
+
+      // These annotations are far apart, so positions should match what they'd
+      // be without collision resolution (i.e., not nudged)
+      const specSingle1 = makeSpec([spec.annotations[0]]);
+      const specSingle2 = makeSpec([spec.annotations[1]]);
+      const single1 = computeAnnotations(specSingle1, scales, chartArea, fullStrategy);
+      const single2 = computeAnnotations(specSingle2, scales, chartArea, fullStrategy);
+
+      expect(annotations[0].label!.x).toBeCloseTo(single1[0].label!.x, 1);
+      expect(annotations[0].label!.y).toBeCloseTo(single1[0].label!.y, 1);
+      expect(annotations[1].label!.x).toBeCloseTo(single2[0].label!.x, 1);
+      expect(annotations[1].label!.y).toBeCloseTo(single2[0].label!.y, 1);
+    });
+  });
+
+  // -----------------------------------------------------------------
+  // Obstacle avoidance (label bounds as obstacles)
+  // -----------------------------------------------------------------
+
+  describe('obstacle avoidance', () => {
+    it('nudges annotation away from an obstacle rect at the same position', () => {
+      const spec = makeSpec([{ type: 'text', x: '2020-01-01', y: 20, text: 'Annotation' }]);
+      const scales = computeScales(spec, chartArea, spec.data);
+
+      // Place an obstacle rect exactly where the annotation would land
+      const withoutObstacles = computeAnnotations(spec, scales, chartArea, fullStrategy);
+      const originalLabel = withoutObstacles[0].label!;
+
+      const obstacle: Rect = {
+        x: originalLabel.x - 5,
+        y: originalLabel.y - 5,
+        width: 80,
+        height: 30,
+      };
+
+      const withObstacles = computeAnnotations(spec, scales, chartArea, fullStrategy, false, [
+        obstacle,
+      ]);
+
+      expect(withObstacles).toHaveLength(1);
+      const nudgedLabel = withObstacles[0].label!;
+      expect(nudgedLabel.visible).toBe(true);
+
+      // The annotation should have moved away from the obstacle
+      const moved = nudgedLabel.x !== originalLabel.x || nudgedLabel.y !== originalLabel.y;
+      expect(moved).toBe(true);
+    });
+  });
 });