@opendata-ai/openchart-engine 6.25.4 → 6.27.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opendata-ai/openchart-engine",
-  "version": "6.25.4",
+  "version": "6.27.0",
   "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.25.4",
+    "@opendata-ai/openchart-core": "6.27.0",
     "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__/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', () => {

package/src/__tests__/compound-labels.test.ts

@@ -0,0 +1,147 @@
+import { describe, expect, it } from 'vitest';
+import { compileChart } from '../compile';
+
+// ---------------------------------------------------------------------------
+// Test data
+// ---------------------------------------------------------------------------
+
+const albumData = [
+  { album: 'Abbey Road', artist: 'The Beatles', sales: 31 },
+  { album: 'Thriller', artist: 'Michael Jackson', sales: 66 },
+  { album: 'Back in Black', artist: 'AC/DC', sales: 50 },
+  { album: 'The Dark Side of the Moon', artist: 'Pink Floyd', sales: 45 },
+  { album: 'Rumours', artist: 'Fleetwood Mac', sales: 40 },
+];
+
+function makeBarSpec(axisConfig?: Record<string, unknown>) {
+  return {
+    mark: 'bar' as const,
+    data: albumData,
+    encoding: {
+      x: { field: 'sales', type: 'quantitative' as const },
+      y: {
+        field: 'album',
+        type: 'nominal' as const,
+        axis: axisConfig,
+      },
+    },
+  };
+}
+
+const compileOpts = { width: 600, height: 400 };
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('compound axis labels (labelField)', () => {
+  it('populates subtitle on ticks when labelField is set', () => {
+    const spec = makeBarSpec({ labelField: 'artist' });
+    const layout = compileChart(spec, compileOpts);
+
+    const yTicks = layout.axes.y?.ticks ?? [];
+    expect(yTicks.length).toBeGreaterThan(0);
+
+    // Every tick should have a subtitle matching the artist for that album
+    for (const tick of yTicks) {
+      const row = albumData.find((r) => r.album === tick.label);
+      expect(row).toBeDefined();
+      expect(tick.subtitle).toBe(row!.artist);
+    }
+  });
+
+  it('does not add subtitle when labelField is omitted', () => {
+    const spec = makeBarSpec();
+    const layout = compileChart(spec, compileOpts);
+
+    const yTicks = layout.axes.y?.ticks ?? [];
+    expect(yTicks.length).toBeGreaterThan(0);
+
+    for (const tick of yTicks) {
+      expect(tick.subtitle).toBeUndefined();
+    }
+  });
+
+  it('handles missing labelField value gracefully', () => {
+    const dataWithMissing = [
+      { album: 'Abbey Road', artist: 'The Beatles', sales: 31 },
+      { album: 'Unknown Album', sales: 20 }, // no artist field
+    ];
+    const spec = {
+      mark: 'bar' as const,
+      data: dataWithMissing,
+      encoding: {
+        x: { field: 'sales', type: 'quantitative' as const },
+        y: {
+          field: 'album',
+          type: 'nominal' as const,
+          axis: { labelField: 'artist' },
+        },
+      },
+    };
+
+    const layout = compileChart(spec, compileOpts);
+    const yTicks = layout.axes.y?.ticks ?? [];
+
+    // Abbey Road should have a subtitle
+    const abbeyRoad = yTicks.find((t) => t.label === 'Abbey Road');
+    expect(abbeyRoad?.subtitle).toBe('The Beatles');
+
+    // Unknown Album has no artist field, so subtitle should be undefined
+    const unknown = yTicks.find((t) => t.label === 'Unknown Album');
+    expect(unknown?.subtitle).toBeUndefined();
+  });
+
+  it('maps subtitle correctly across multiple ticks', () => {
+    const spec = makeBarSpec({ labelField: 'artist' });
+    const layout = compileChart(spec, compileOpts);
+
+    const yTicks = layout.axes.y?.ticks ?? [];
+    expect(yTicks.length).toBe(5);
+
+    // Verify specific mappings
+    const thrillerTick = yTicks.find((t) => t.label === 'Thriller');
+    expect(thrillerTick?.subtitle).toBe('Michael Jackson');
+
+    const rumoursTick = yTicks.find((t) => t.label === 'Rumours');
+    expect(rumoursTick?.subtitle).toBe('Fleetwood Mac');
+  });
+
+  it('preserves subtitle mapping with sort: descending', () => {
+    const spec = {
+      mark: 'bar' as const,
+      data: albumData,
+      encoding: {
+        x: { field: 'sales', type: 'quantitative' as const },
+        y: {
+          field: 'album',
+          type: 'nominal' as const,
+          sort: 'descending' as const,
+          axis: { labelField: 'artist' },
+        },
+      },
+    };
+
+    const layout = compileChart(spec, compileOpts);
+    const yTicks = layout.axes.y?.ticks ?? [];
+
+    // Regardless of sort order, each tick should still map to the right artist
+    for (const tick of yTicks) {
+      const row = albumData.find((r) => r.album === tick.label);
+      expect(row).toBeDefined();
+      expect(tick.subtitle).toBe(row!.artist);
+    }
+  });
+
+  it('reserves wider dimension with labelField than without', () => {
+    const specWith = makeBarSpec({ labelField: 'artist' });
+    const specWithout = makeBarSpec();
+
+    const layoutWith = compileChart(specWith, compileOpts);
+    const layoutWithout = compileChart(specWithout, compileOpts);
+
+    // Chart area x (left edge) should be larger with labelField because more
+    // left margin is reserved for the wider compound labels
+    expect(layoutWith.area.x).toBeGreaterThanOrEqual(layoutWithout.area.x);
+  });
+});

package/src/charts/line/area.ts

@@ -151,7 +151,7 @@ function computeSingleArea(
       fill: fillValue,
       fillOpacity: fillOpacity,
       stroke: getRepresentativeColor(isGradientDef(fillValue) ? color : fillValue),
-      strokeWidth: 2,
+      strokeWidth: spec.display === 'sparkline' ? 1.25 : 2,
       seriesKey: seriesKey === '__default__' ? undefined : seriesKey,
       data: validPoints.map((p) => p.row),
       dataPoints: validPoints.map((p) => ({ x: p.x, y: p.yTop, datum: p.row })),

package/src/charts/line/compute.ts

@@ -32,6 +32,10 @@ import { resolveCurve } from './curves';
 /** Default stroke width for line marks. */
 const DEFAULT_STROKE_WIDTH = 2.5;
 
+/** Sparkline mode uses a thinner stroke since the chart area is tiny and a
+ *  2.5px line reads as clunky. 1.25px keeps the trend legible without dominating. */
+const SPARKLINE_STROKE_WIDTH = 1.25;
+
 /** Default radius for point marks (hover targets). */
 const DEFAULT_POINT_RADIUS = 3;
 
@@ -174,7 +178,9 @@ export function computeLineMarks(
       points: allPoints,
       path: combinedPath,
       stroke: strokeColor,
-      strokeWidth: styleOverride?.strokeWidth ?? DEFAULT_STROKE_WIDTH,
+      strokeWidth:
+        styleOverride?.strokeWidth ??
+        (spec.display === 'sparkline' ? SPARKLINE_STROKE_WIDTH : DEFAULT_STROKE_WIDTH),
       strokeDasharray,
       opacity: styleOverride?.opacity,
       seriesKey: seriesStyleKey,