@opendata-ai/openchart-engine 6.26.0 → 6.27.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opendata-ai/openchart-engine",
-  "version": "6.26.0",
+  "version": "6.27.2",
   "description": "Headless compiler for openchart: spec validation, data compilation, scales, and layout",
   "license": "Apache-2.0",
   "author": "Riley Hilliard",
@@ -48,7 +48,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@opendata-ai/openchart-core": "6.26.0",
+    "@opendata-ai/openchart-core": "6.27.2",
     "d3-array": "^3.2.0",
     "d3-format": "^3.1.2",
     "d3-interpolate": "^3.0.0",

package/src/__test-fixtures__/specs.ts

@@ -74,6 +74,17 @@ export function makeLineSpec(): NormalizedChartSpec {
     hiddenSeries: [],
     seriesStyles: {},
     watermark: true,
+    display: 'full',
+    userExplicit: {
+      chrome: false,
+      legend: false,
+      xAxis: false,
+      yAxis: false,
+      labels: false,
+      animation: false,
+      watermark: false,
+      crosshair: false,
+    },
   };
 }
 
@@ -104,6 +115,17 @@ export function makeBarSpec(): NormalizedChartSpec {
     hiddenSeries: [],
     seriesStyles: {},
     watermark: true,
+    display: 'full',
+    userExplicit: {
+      chrome: false,
+      legend: false,
+      xAxis: false,
+      yAxis: false,
+      labels: false,
+      animation: false,
+      watermark: false,
+      crosshair: false,
+    },
   };
 }
 
@@ -136,5 +158,16 @@ export function makeScatterSpec(): NormalizedChartSpec {
     hiddenSeries: [],
     seriesStyles: {},
     watermark: true,
+    display: 'full',
+    userExplicit: {
+      chrome: false,
+      legend: false,
+      xAxis: false,
+      yAxis: false,
+      labels: false,
+      animation: false,
+      watermark: false,
+      crosshair: false,
+    },
   };
 }

package/src/__tests__/__snapshots__/compile-snapshot.test.ts.snap

@@ -181,10 +181,12 @@ exports[`compileChart snapshot (Step 7 oracle) > clipped-domain bar chart (data
     },
     "topHeight": 36.6,
   },
+  "crosshair": false,
   "dimensions": {
     "height": 400,
     "width": 600,
   },
+  "display": "full",
   "legend": {
     "bounds": {
       "height": 0,
@@ -731,10 +733,12 @@ exports[`compileChart snapshot (Step 7 oracle) > legend-heavy multi-series line
     },
     "topHeight": 61.599999999999994,
   },
+  "crosshair": false,
   "dimensions": {
     "height": 500,
     "width": 800,
   },
+  "display": "full",
   "legend": {
     "bounds": {
       "height": 85.2,
@@ -1574,10 +1578,12 @@ exports[`compileChart snapshot (Step 7 oracle) > watermarked column chart with g
     },
     "topHeight": 36.6,
   },
+  "crosshair": false,
   "dimensions": {
     "height": 400,
     "width": 600,
   },
+  "display": "full",
   "legend": {
     "bounds": {
       "height": 0,

package/src/__tests__/axes.test.ts

@@ -1,8 +1,11 @@
 import type { AxisTick, LayoutStrategy } from '@opendata-ai/openchart-core';
 import { resolveTheme } from '@opendata-ai/openchart-core';
+import { scaleLinear, scaleLog } from 'd3-scale';
 import { describe, expect, it } from 'vitest';
 import type { NormalizedChartSpec } from '../compiler/types';
 import { computeAxes, effectiveDensity, thinTicksUntilFit, ticksOverlap } from '../layout/axes';
+import { buildContinuousTicks } from '../layout/axes/ticks';
+import type { ResolvedScale } from '../layout/scales';
 import { computeScales } from '../layout/scales';
 
 const lineSpec: NormalizedChartSpec = {
@@ -121,16 +124,16 @@ describe('computeAxes', () => {
   // Height-aware y-axis tick reduction
   // -------------------------------------------------------------------------
 
-  it('reduces y-axis ticks for very short chart areas (< 120px)', () => {
+  it('reduces y-axis ticks for very short chart areas (< 80px)', () => {
     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)
+    // Very short chart area -- tick count clamped to at most 4
     expect(axesShort.y!.ticks.length).toBeLessThanOrEqual(4);
   });
 
-  it('reduces y-axis ticks for medium-short chart areas (120-200px)', () => {
+  it('reduces y-axis ticks for medium-short chart areas (80-100px)', () => {
     const mediumArea = { x: 50, y: 50, width: 500, height: 160 };
     const tallArea = { x: 50, y: 50, width: 500, height: 400 };
 
@@ -884,3 +887,98 @@ describe('horizontal bar y-axis label thinning regression', () => {
     expect(axes.x!.ticks.length).toBeLessThan(countries.length);
   });
 });
+
+// ---------------------------------------------------------------------------
+// Log scale tick filtering — buildContinuousTicks
+// D3 log scales ignore the count hint and return ticks at every sub-power
+// position. The engine must filter these down to powers of the base only.
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a ResolvedScale backed by a D3 log scale, matching what buildLogScale produces.
+ * Using a single `base` parameter keeps the D3 scale and channel config in sync,
+ * mirroring how they're always derived from the same spec field.
+ */
+function makeLogScale(domain: [number, number], base = 10): ResolvedScale {
+  const scale = scaleLog().domain(domain).range([400, 0]);
+  scale.base(base);
+  return {
+    scale,
+    type: 'log',
+    channel: {
+      field: 'value',
+      type: 'quantitative',
+      scale: base !== 10 ? { base } : undefined,
+    },
+  } as ResolvedScale;
+}
+
+describe('buildContinuousTicks — log scale power filtering', () => {
+  it('returns only power-of-10 ticks for [5, 25000] at tickCount 5', () => {
+    const resolved = makeLogScale([5, 25000]);
+    const ticks = buildContinuousTicks(resolved, 5);
+    const values = ticks.map((t) => t.value as number);
+    // Should be exactly the powers of 10 in domain: 10, 100, 1000, 10000
+    expect(values).toEqual([10, 100, 1000, 10000]);
+  });
+
+  it('returns only power-of-10 ticks for [1, 1000000] at tickCount 5', () => {
+    const resolved = makeLogScale([1, 1_000_000]);
+    const ticks = buildContinuousTicks(resolved, 5);
+    const values = ticks.map((t) => t.value as number);
+    // Assert invariants rather than exact output: every tick is a power of 10,
+    // and we get at least 5 (the domain spans 6 decades).
+    for (const v of values) {
+      const exp = Math.log10(v);
+      expect(Math.abs(exp - Math.round(exp))).toBeLessThan(1e-9);
+    }
+    expect(values.length).toBeGreaterThanOrEqual(5);
+  });
+
+  it('returns only powers-of-2 for [1, 64] base-2 at tickCount 5', () => {
+    const resolved = makeLogScale([1, 64], 2);
+    const ticks = buildContinuousTicks(resolved, 5);
+    const values = ticks.map((t) => t.value as number);
+    expect(values).toEqual([1, 2, 4, 8, 16, 32, 64]);
+  });
+
+  it('handles fractional powers for [0.001, 100] at tickCount 5', () => {
+    const resolved = makeLogScale([0.001, 100]);
+    const ticks = buildContinuousTicks(resolved, 5);
+    const values = ticks.map((t) => t.value as number);
+    // Tolerance check prevents floating-point false negatives on 0.001, 0.01, 0.1
+    expect(values).toEqual([0.001, 0.01, 0.1, 1, 10, 100]);
+  });
+
+  it('still produces ticks at tickCount 3 (regression guard)', () => {
+    const resolved = makeLogScale([1, 1000]);
+    const ticks = buildContinuousTicks(resolved, 3);
+    expect(ticks.length).toBeGreaterThanOrEqual(2);
+    const values = ticks.map((t) => t.value as number);
+    // Every value must be a power of 10
+    for (const v of values) {
+      const exp = Math.log10(v);
+      expect(Math.abs(exp - Math.round(exp))).toBeLessThan(1e-6);
+    }
+  });
+
+  it('does not over-filter linear scales with the same domain', () => {
+    const scale = scaleLinear().domain([5, 25000]).range([400, 0]);
+    const resolved: ResolvedScale = {
+      scale,
+      type: 'linear',
+      channel: { field: 'value', type: 'quantitative' },
+    } as ResolvedScale;
+    const ticks = buildContinuousTicks(resolved, 5);
+    // Linear scale should return normal D3 ticks — not just power-of-10 values
+    expect(ticks.length).toBeGreaterThanOrEqual(4);
+    // At least one tick should NOT be a power of 10 (e.g. 5000, 10000, 15000, 20000, 25000)
+    const values = ticks.map((t) => t.value as number);
+    const nonPowerOf10 = values.filter((v) => {
+      if (v <= 0) return true;
+      const exp = Math.log10(v);
+      return Math.abs(exp - Math.round(exp)) >= 0.01;
+    });
+    expect(nonPowerOf10.length).toBeGreaterThan(0);
+  });
+});

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

@@ -398,6 +398,307 @@ describe('compileChart', () => {
     const pointMarks = layout.marks.filter((m) => m.type === 'point');
     expect(pointMarks.length).toBe(3);
   });
+
+  // ---------------------------------------------------------------------------
+  // display field + breakpoint override
+  // ---------------------------------------------------------------------------
+
+  it('display defaults to "full" when not specified', () => {
+    const layout = compileChart(lineSpec, { width: 600, height: 400 });
+    expect(layout.display).toBe('full');
+  });
+
+  it('display: "sparkline" propagates through to ChartLayout', () => {
+    const layout = compileChart(
+      { ...lineSpec, display: 'sparkline' as const },
+      { width: 400, height: 80 },
+    );
+    expect(layout.display).toBe('sparkline');
+  });
+
+  it('breakpoint override flips display at compact width', () => {
+    const spec = {
+      ...lineSpec,
+      overrides: {
+        compact: { display: 'sparkline' as const },
+      },
+    };
+
+    const compactLayout = compileChart(spec, { width: 320, height: 200 });
+    expect(compactLayout.display).toBe('sparkline');
+
+    const desktopLayout = compileChart(spec, { width: 1200, height: 600 });
+    expect(desktopLayout.display).toBe('full');
+  });
+
+  it('sparkline mode forces watermark off when not user-explicit', () => {
+    const layout = compileChart(
+      { ...lineSpec, display: 'sparkline' as const },
+      { width: 400, height: 80 },
+    );
+    expect(layout.watermark).toBe(false);
+  });
+
+  it('sparkline mode respects explicit watermark: true', () => {
+    const layout = compileChart(
+      { ...lineSpec, display: 'sparkline' as const, watermark: true },
+      { width: 400, height: 80 },
+    );
+    expect(layout.watermark).toBe(true);
+  });
+
+  it('sparkline mode forces crosshair off when not user-explicit', () => {
+    const layout = compileChart(
+      { ...lineSpec, display: 'sparkline' as const },
+      { width: 400, height: 80 },
+    );
+    expect(layout.crosshair).toBe(false);
+  });
+
+  it('sparkline mode respects explicit crosshair: true', () => {
+    const layout = compileChart(
+      { ...lineSpec, display: 'sparkline' as const, crosshair: true },
+      { width: 400, height: 80 },
+    );
+    expect(layout.crosshair).toBe(true);
+  });
+
+  // ---------------------------------------------------------------------------
+  // Sparkline layout profile (dimensions, axes, legend)
+  // ---------------------------------------------------------------------------
+
+  it('sparkline produces near-edge-to-edge chart area (margins <= 4px per side)', () => {
+    const layout = compileChart(
+      { ...lineSpec, chrome: undefined, display: 'sparkline' as const },
+      { width: 400, height: 80 },
+    );
+
+    // No chrome, no axes, no legend by default. Mark area should be tight.
+    expect(layout.area.x).toBeLessThanOrEqual(4);
+    expect(layout.area.y).toBeLessThanOrEqual(4);
+    const rightMargin = 400 - (layout.area.x + layout.area.width);
+    const bottomMargin = 80 - (layout.area.y + layout.area.height);
+    expect(rightMargin).toBeLessThanOrEqual(4);
+    expect(bottomMargin).toBeLessThanOrEqual(4);
+  });
+
+  it('sparkline returns no axes by default', () => {
+    const layout = compileChart(
+      { ...lineSpec, chrome: undefined, display: 'sparkline' as const },
+      { width: 400, height: 80 },
+    );
+    expect(layout.axes.x).toBeUndefined();
+    expect(layout.axes.y).toBeUndefined();
+  });
+
+  it('sparkline + explicit encoding.x.axis still reserves x-axis', () => {
+    const layout = compileChart(
+      {
+        ...lineSpec,
+        chrome: undefined,
+        display: 'sparkline' as const,
+        encoding: {
+          ...lineSpec.encoding,
+          x: { ...lineSpec.encoding.x, axis: { title: 'date' } },
+        },
+      },
+      { width: 400, height: 200 },
+    );
+    expect(layout.axes.x).toBeDefined();
+  });
+
+  it('sparkline + explicit chrome.title still renders chrome', () => {
+    const layout = compileChart(
+      {
+        ...lineSpec,
+        chrome: { title: 'Q4 Revenue' },
+        display: 'sparkline' as const,
+      },
+      { width: 400, height: 200 },
+    );
+    expect(layout.chrome.title).toBeDefined();
+    expect(layout.chrome.title?.text).toBe('Q4 Revenue');
+  });
+
+  it('sparkline hides legend by default even with color encoding', () => {
+    const layout = compileChart(
+      {
+        ...lineSpec,
+        chrome: undefined,
+        display: 'sparkline' as const,
+      },
+      { width: 400, height: 80 },
+    );
+    expect('entries' in layout.legend && layout.legend.entries.length).toBe(0);
+  });
+
+  it('sparkline + explicit legend.show: true renders legend', () => {
+    const layout = compileChart(
+      {
+        ...lineSpec,
+        chrome: undefined,
+        display: 'sparkline' as const,
+        legend: { show: true },
+      },
+      { width: 400, height: 200 },
+    );
+    expect('entries' in layout.legend && layout.legend.entries.length).toBeGreaterThan(0);
+  });
+
+  it('sparkline works at heights as low as 30px', () => {
+    const layout = compileChart(
+      { ...lineSpec, chrome: undefined, display: 'sparkline' as const },
+      { width: 200, height: 30 },
+    );
+    expect(layout.area.height).toBeGreaterThan(0);
+    expect(layout.area.width).toBeGreaterThan(0);
+  });
+
+  it('chrome: {} does not count as user-explicit chrome (still stripped in sparkline)', () => {
+    // Empty chrome object is the idiom for "silence defaults" — should not
+    // opt-in to chrome rendering in sparkline mode.
+    const layout = compileChart(
+      { ...lineSpec, chrome: {}, display: 'sparkline' as const },
+      { width: 400, height: 80 },
+    );
+    expect(layout.chrome.title).toBeUndefined();
+    expect(layout.chrome.topHeight).toBe(0);
+  });
+
+  // ---------------------------------------------------------------------------
+  // Explicit-at-any-level wins (precedence matrix)
+  // ---------------------------------------------------------------------------
+
+  it('top-level animation: true wins even when breakpoint flips to sparkline', () => {
+    const spec = {
+      ...lineSpec,
+      animation: true as const,
+      overrides: { compact: { display: 'sparkline' as const } },
+    };
+    const layout = compileChart(spec, { width: 320, height: 200 });
+    expect(layout.display).toBe('sparkline');
+    expect(layout.animation?.enabled).toBe(true);
+  });
+
+  it('breakpoint chrome wins when top-level is sparkline', () => {
+    const spec = {
+      ...lineSpec,
+      chrome: undefined,
+      display: 'sparkline' as const,
+      overrides: { full: { chrome: { title: 'Q4 revenue' } } },
+    };
+    const layout = compileChart(spec, { width: 1200, height: 600 });
+    // At full breakpoint, chrome.title from override should render even
+    // though display is sparkline at top-level.
+    expect(layout.chrome.title?.text).toBe('Q4 revenue');
+  });
+
+  it('top-level display: sparkline + breakpoint display: full restores all defaults', () => {
+    const spec = {
+      ...lineSpec,
+      display: 'sparkline' as const,
+      overrides: { full: { display: 'full' as const } },
+    };
+    const layout = compileChart(spec, { width: 1200, height: 600 });
+    expect(layout.display).toBe('full');
+    // Watermark default is true in full mode.
+    expect(layout.watermark).toBe(true);
+  });
+
+  it('explicit watermark: true in sparkline mode actually paints the watermark', () => {
+    const layout = compileChart(
+      {
+        ...lineSpec,
+        chrome: undefined,
+        display: 'sparkline' as const,
+        watermark: true,
+      },
+      { width: 400, height: 200 },
+    );
+    expect(layout.watermark).toBe(true);
+  });
+
+  it('breakpoint encoding.x.axis opts back into x-axis at that breakpoint', () => {
+    const spec = {
+      ...lineSpec,
+      chrome: undefined,
+      display: 'sparkline' as const,
+      overrides: {
+        full: {
+          encoding: {
+            x: { field: 'date', type: 'temporal' as const, axis: { title: 'date' } },
+          },
+        },
+      },
+    };
+    const layoutFull = compileChart(spec, { width: 1200, height: 600 });
+    expect(layoutFull.axes.x).toBeDefined();
+    const layoutCompact = compileChart(spec, { width: 320, height: 200 });
+    expect(layoutCompact.axes.x).toBeUndefined();
+  });
+
+  // ---------------------------------------------------------------------------
+  // Animation duration: sparkline mode bumps the entrance to 1100ms when on
+  // ---------------------------------------------------------------------------
+
+  it('sparkline + animation: true bumps entrance duration to 1100ms', () => {
+    const layout = compileChart(
+      { ...lineSpec, display: 'sparkline' as const, animation: true },
+      { width: 400, height: 80 },
+    );
+    expect(layout.animation?.enabled).toBe(true);
+    expect(layout.animation?.duration).toBe(1100);
+  });
+
+  it('sparkline + animation: { enter: { duration: 500 } } respects user duration', () => {
+    const layout = compileChart(
+      {
+        ...lineSpec,
+        display: 'sparkline' as const,
+        animation: { enter: { duration: 500 } },
+      },
+      { width: 400, height: 80 },
+    );
+    expect(layout.animation?.duration).toBe(500);
+  });
+
+  it('full mode + animation: true uses default 500ms (sparkline bump does not leak)', () => {
+    const layout = compileChart({ ...lineSpec, animation: true }, { width: 600, height: 400 });
+    expect(layout.animation?.duration).toBe(500);
+  });
+
+  // ---------------------------------------------------------------------------
+  // Breakpoint encoding deep-merge: nested axis state survives an override that
+  // only touches one axis property.
+  // ---------------------------------------------------------------------------
+
+  it('breakpoint encoding.x.axis deep-merges with base axis config', () => {
+    const spec = {
+      ...lineSpec,
+      encoding: {
+        ...lineSpec.encoding,
+        x: {
+          field: 'date',
+          type: 'temporal' as const,
+          axis: { title: 'date', tickCount: 8, format: '%b' },
+        },
+      },
+      overrides: {
+        compact: {
+          encoding: {
+            x: { axis: { title: 'd' } },
+          },
+        },
+      },
+    };
+    const layout = compileChart(spec, { width: 320, height: 200 });
+    // The compact override only touched axis.title; tickCount and format
+    // should survive the deep merge.
+    expect(layout.axes.x).toBeDefined();
+    expect(layout.axes.x?.label).toBe('d');
+    // Tick count flows from base spec — if shallow-merged, tickCount would be lost.
+    expect(layout.axes.x?.ticks.length).toBeGreaterThan(0);
+  });
 });
 
 describe('compileTable', () => {