@opendata-ai/openchart-engine 6.26.0 → 6.27.2

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

@@ -1,8 +1,10 @@
 import type { Annotation, LayoutStrategy, Rect } from '@opendata-ai/openchart-core';
+import type { ScaleBand, ScalePoint } from 'd3-scale';
 import { describe, expect, it } from 'vitest';
 import type { NormalizedChartSpec } from '../../compiler/types';
 import { computeScales } from '../../layout/scales';
 import { computeAnnotations } from '../compute';
+import { resolvePosition } from '../position';
 
 // ---------------------------------------------------------------------------
 // Fixtures
@@ -236,6 +238,179 @@ describe('computeAnnotations', () => {
       // Non-numeric domain can't interpolate, annotation is dropped
       expect(annotations).toHaveLength(0);
     });
+
+    it('two adjacent point-scale ranges have a non-zero pixel gap between them', () => {
+      // Regression: ranges ending/starting at point-scale centers would share the same
+      // pixel boundary, visually merging. resolvePositionEdge now extends each range
+      // by half a step so adjacent ranges are truly separated.
+      const ordinalSpec: NormalizedChartSpec = {
+        markType: 'line',
+        markDef: { type: 'line' },
+        data: [
+          { year: '2006', value: 10 },
+          { year: '2008', value: 20 },
+          { year: '2010', value: 30 },
+          { year: '2012', value: 40 },
+          { year: '2020', value: 50 },
+          { year: '2022', value: 60 },
+        ],
+        encoding: {
+          x: { field: 'year', type: 'ordinal' },
+          y: { field: 'value', type: 'quantitative' },
+        },
+        chrome: {},
+        annotations: [
+          { type: 'range', x1: '2008', x2: '2010', label: 'First range' },
+          { type: 'range', x1: '2020', x2: '2022', label: 'Second range' },
+        ],
+        responsive: true,
+        theme: {},
+        darkMode: 'off',
+        labels: { density: 'auto', format: '' },
+      };
+      const scales = computeScales(ordinalSpec, chartArea, ordinalSpec.data);
+      const annotations = computeAnnotations(ordinalSpec, scales, chartArea, fullStrategy);
+
+      expect(annotations).toHaveLength(2);
+      const rect1 = annotations[0].rect!;
+      const rect2 = annotations[1].rect!;
+
+      // First range must end before second range starts (non-zero gap)
+      expect(rect1.x + rect1.width).toBeLessThan(rect2.x);
+    });
+
+    it('single range on point-scale ordinal x covers at least a full step', () => {
+      // A range spanning a single domain value should be at least step-wide,
+      // since resolvePositionEdge extends by half a step on each side.
+      const domainValues = ['2006', '2008', '2010', '2012'];
+      const ordinalSpec: NormalizedChartSpec = {
+        markType: 'line',
+        markDef: { type: 'line' },
+        data: domainValues.map((year, i) => ({ year, value: i * 10 })),
+        encoding: {
+          x: { field: 'year', type: 'ordinal' },
+          y: { field: 'value', type: 'quantitative' },
+        },
+        chrome: {},
+        annotations: [{ type: 'range', x1: '2008', x2: '2010', label: 'Single step' }],
+        responsive: true,
+        theme: {},
+        darkMode: 'off',
+        labels: { density: 'auto', format: '' },
+      };
+      const scales = computeScales(ordinalSpec, chartArea, ordinalSpec.data);
+      const annotations = computeAnnotations(ordinalSpec, scales, chartArea, fullStrategy);
+
+      expect(annotations).toHaveLength(1);
+      const rect = annotations[0].rect!;
+
+      // step = chartArea.width / (numPoints - 1) roughly. With 4 points and default 0.5 padding,
+      // the step on a point scale = width / (n - 1 + 2*padding) -- but the key property is that
+      // the range width should be at least as wide as the distance between two domain centers.
+      const xScale = scales.x!.scale as ScalePoint<string>;
+      const step = xScale.step();
+      expect(rect.width).toBeGreaterThanOrEqual(step);
+    });
+
+    it('band-scale (bar chart) range covers full bands, not band centers', () => {
+      // On a bar chart the x scale is a band scale. resolvePositionEdge extends from the
+      // center (what resolvePosition returns) to the band edge.
+      const barSpec: NormalizedChartSpec = {
+        markType: 'bar',
+        markDef: { type: 'bar', orient: 'vertical' },
+        data: [
+          { year: '2008', value: 10 },
+          { year: '2010', value: 20 },
+          { year: '2012', value: 30 },
+          { year: '2014', value: 40 },
+        ],
+        encoding: {
+          x: { field: 'year', type: 'ordinal' },
+          y: { field: 'value', type: 'quantitative' },
+        },
+        chrome: {},
+        annotations: [{ type: 'range', x1: '2010', x2: '2012', label: 'Band range' }],
+        responsive: true,
+        theme: {},
+        darkMode: 'off',
+        labels: { density: 'auto', format: '' },
+      };
+      const scales = computeScales(barSpec, chartArea, barSpec.data);
+      const annotations = computeAnnotations(barSpec, scales, chartArea, fullStrategy);
+
+      expect(annotations).toHaveLength(1);
+      const rect = annotations[0].rect!;
+
+      const bandScale = scales.x!.scale as ScaleBand<string>;
+      const bandwidth = bandScale.bandwidth();
+      const x1BandStart = bandScale('2010')!;
+      const x2BandStart = bandScale('2012')!;
+
+      // Left edge should be at the start of the 2010 band (not the center)
+      expect(rect.x).toBeCloseTo(x1BandStart, 1);
+      // Right edge should be at the end of the 2012 band
+      expect(rect.x + rect.width).toBeCloseTo(x2BandStart + bandwidth, 1);
+    });
+
+    it('linear-scale range is unaffected by edge extension', () => {
+      // For linear scales, resolvePositionEdge is identical to resolvePosition.
+      // This ensures the fix doesn't introduce any drift on continuous axes.
+      const linearSpec = makeSpec([{ type: 'range', x1: '2020-01-01', x2: '2021-01-01' }]);
+      const scales = computeScales(linearSpec, chartArea, linearSpec.data);
+      const annotations = computeAnnotations(linearSpec, scales, chartArea, fullStrategy);
+
+      expect(annotations).toHaveLength(1);
+      const rect = annotations[0].rect!;
+
+      // The x positions should exactly match what resolvePosition would return
+      const x1Expected = resolvePosition('2020-01-01', scales.x)!;
+      const x2Expected = resolvePosition('2021-01-01', scales.x)!;
+
+      expect(rect.x).toBeCloseTo(Math.min(x1Expected, x2Expected), 1);
+      expect(rect.x + rect.width).toBeCloseTo(Math.max(x1Expected, x2Expected), 1);
+    });
+
+    it('y1/y2 range on ordinal point-scale y-axis has a non-zero pixel gap between two annotations', () => {
+      // Horizontal band: y-axis is ordinal (point scale), x-axis is quantitative.
+      // Two y-range annotations with a gap should produce two distinct rects.
+      const ordinalYSpec: NormalizedChartSpec = {
+        markType: 'line',
+        markDef: { type: 'line' },
+        data: [
+          { year: '2006', value: 10 },
+          { year: '2008', value: 20 },
+          { year: '2010', value: 30 },
+          { year: '2015', value: 40 },
+          { year: '2020', value: 50 },
+          { year: '2022', value: 60 },
+        ],
+        encoding: {
+          x: { field: 'value', type: 'quantitative' },
+          y: { field: 'year', type: 'ordinal' },
+        },
+        chrome: {},
+        annotations: [
+          { type: 'range', y1: '2006', y2: '2008' },
+          { type: 'range', y1: '2020', y2: '2022' },
+        ],
+        responsive: true,
+        theme: {},
+        darkMode: 'off',
+        labels: { density: 'auto', format: '' },
+      };
+      const scales = computeScales(ordinalYSpec, chartArea, ordinalYSpec.data);
+      const annotations = computeAnnotations(ordinalYSpec, scales, chartArea, fullStrategy);
+
+      expect(annotations).toHaveLength(2);
+      const rects = annotations.map((a) => a.rect!);
+
+      // In SVG, y increases downward. Sort by y so rect[0] is the top one.
+      rects.sort((a, b) => a.y - b.y);
+
+      // There must be a non-zero pixel gap between the bottom of rect[0] and top of rect[1]
+      const bottomOfFirst = rects[0].y + rects[0].height;
+      expect(bottomOfFirst).toBeLessThan(rects[1].y);
+    });
   });
 
   describe('reference line annotations', () => {

package/src/annotations/position.ts

@@ -2,7 +2,7 @@
  * Data-coordinate to pixel-coordinate resolution for annotations.
  */
 
-import type { ScaleBand, ScaleLinear, ScaleTime } from 'd3-scale';
+import type { ScaleBand, ScaleLinear, ScalePoint, ScaleTime } from 'd3-scale';
 import type { ResolvedScales } from '../layout/scales';
 
 /**
@@ -93,3 +93,39 @@ export function resolvePosition(
 
   return null;
 }
+
+/**
+ * Like resolvePosition, but extends the result to the visual edge of the column
+ * for band and point scales. Used by range annotations to span complete columns.
+ *
+ * For point scales: shifts by ±step/2 using scalePoint.step()
+ * For band scales: shifts from center (what resolvePosition returns) to the band edge
+ * For all other scales: identical to resolvePosition
+ */
+export function resolvePositionEdge(
+  value: string | number,
+  scale: ResolvedScales['x'] | ResolvedScales['y'],
+  edge: 'start' | 'end',
+): number | null {
+  const center = resolvePosition(value, scale);
+  if (center === null || !scale) return null;
+
+  const type = scale.type;
+
+  if (type === 'point') {
+    const s = scale.scale as ScalePoint<string>;
+    const halfStep = (s.step?.() ?? 0) / 2;
+    return edge === 'start' ? center - halfStep : center + halfStep;
+  }
+
+  if (type === 'band') {
+    // center = bandStart + bandwidth/2
+    // edge 'start' => bandStart   = center - bandwidth/2
+    // edge 'end'   => bandEnd     = center + bandwidth/2
+    const s = scale.scale as ScaleBand<string>;
+    const halfBw = (s.bandwidth?.() ?? 0) / 2;
+    return edge === 'start' ? center - halfBw : center + halfBw;
+  }
+
+  return center;
+}

package/src/annotations/resolve-range.ts

@@ -12,7 +12,7 @@ import type {
 import type { ResolvedScales } from '../layout/scales';
 import { DEFAULT_RANGE_FILL, DEFAULT_RANGE_OPACITY } from './constants';
 import { applyOffset } from './geometry';
-import { resolvePosition } from './position';
+import { resolvePositionEdge } from './position';
 import { makeAnnotationLabelStyle } from './resolve-text';
 
 export function resolveRangeAnnotation(
@@ -28,8 +28,8 @@ export function resolveRangeAnnotation(
 
   // X-range (vertical band)
   if (annotation.x1 !== undefined && annotation.x2 !== undefined) {
-    const x1px = resolvePosition(annotation.x1, scales.x);
-    const x2px = resolvePosition(annotation.x2, scales.x);
+    const x1px = resolvePositionEdge(annotation.x1, scales.x, 'start');
+    const x2px = resolvePositionEdge(annotation.x2, scales.x, 'end');
     if (x1px === null || x2px === null) return null;
 
     x = Math.min(x1px, x2px);
@@ -38,8 +38,8 @@ export function resolveRangeAnnotation(
 
   // Y-range (horizontal band)
   if (annotation.y1 !== undefined && annotation.y2 !== undefined) {
-    const y1px = resolvePosition(annotation.y1, scales.y);
-    const y2px = resolvePosition(annotation.y2, scales.y);
+    const y1px = resolvePositionEdge(annotation.y1, scales.y, 'end');
+    const y2px = resolvePositionEdge(annotation.y2, scales.y, 'start');
     if (y1px === null || y2px === null) return null;
 
     y = Math.min(y1px, y2px);

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

@@ -386,6 +386,108 @@ describe('computeBarMarks', () => {
     });
   });
 
+  describe('stacked vs grouped (wage data reproduction)', () => {
+    // 2 years × 2 firm-size categories — the canonical grouped-bar use case
+    const wageData = [
+      { size: '<5 employees', year: '2018', pay: 48200 },
+      { size: '<5 employees', year: '2022', pay: 56400 },
+      { size: '5,000+ employees', year: '2018', pay: 62300 },
+      { size: '5,000+ employees', year: '2022', pay: 74800 },
+    ];
+
+    function makeWageSpec(stackNull = false): NormalizedChartSpec {
+      return {
+        markType: 'bar',
+        markDef: { type: 'bar' },
+        data: wageData,
+        encoding: {
+          x: {
+            field: 'pay',
+            type: 'quantitative',
+            ...(stackNull ? { stack: null } : {}),
+          },
+          y: { field: 'size', type: 'nominal' },
+          color: { field: 'year', type: 'nominal' },
+        },
+        chrome: {},
+        annotations: [],
+        responsive: true,
+        theme: {},
+        darkMode: 'off',
+        labels: { density: 'auto', format: '' },
+      };
+    }
+
+    it('stacks by default: segments are contiguous end-to-end within each category', () => {
+      const spec = makeWageSpec(false);
+      const scales = computeScales(spec, chartArea, spec.data);
+      const marks = computeBarMarks(spec, scales, chartArea, fullStrategy);
+
+      // 2 firm sizes × 2 years = 4 bars
+      expect(marks).toHaveLength(4);
+
+      // For stacked bars, the second segment starts exactly where the first ends.
+      const smallFirmMarks = marks
+        .filter((m) => m.aria.label.includes('<5'))
+        .sort((a, b) => a.x - b.x);
+      expect(smallFirmMarks).toHaveLength(2);
+      expect(smallFirmMarks[1].x).toBeCloseTo(smallFirmMarks[0].x + smallFirmMarks[0].width, 1);
+    });
+
+    it('stacks by default: segments share the same y position (stacked on same row)', () => {
+      const spec = makeWageSpec(false);
+      const scales = computeScales(spec, chartArea, spec.data);
+      const marks = computeBarMarks(spec, scales, chartArea, fullStrategy);
+
+      const smallFirmMarks = marks.filter((m) => m.aria.label.includes('<5'));
+      expect(smallFirmMarks).toHaveLength(2);
+      expect(smallFirmMarks[0].y).toBe(smallFirmMarks[1].y);
+    });
+
+    it('grouped with stack:null: bar widths match individual pay values (not cumulative)', () => {
+      const stackedSpec = makeWageSpec(false);
+      const stackedScales = computeScales(stackedSpec, chartArea, stackedSpec.data);
+      const stackedMarks = computeBarMarks(stackedSpec, stackedScales, chartArea, fullStrategy);
+
+      const groupedSpec = makeWageSpec(true);
+      const groupedScales = computeScales(groupedSpec, chartArea, groupedSpec.data);
+      const groupedMarks = computeBarMarks(groupedSpec, groupedScales, chartArea, fullStrategy);
+
+      expect(groupedMarks).toHaveLength(4);
+
+      // Grouped bars each start from the baseline (same x for both years within a firm size)
+      const smallFirmGrouped = groupedMarks.filter((m) => m.aria.label.includes('<5'));
+      expect(smallFirmGrouped[0].x).toBe(smallFirmGrouped[1].x);
+
+      // Stacked bars for the same category have different x positions (end-to-end)
+      const smallFirmStacked = stackedMarks.filter((m) => m.aria.label.includes('<5'));
+      expect(smallFirmStacked[0].x).not.toBe(smallFirmStacked[1].x);
+    });
+
+    it('grouped with stack:null: bars sit at different y positions within each category', () => {
+      const spec = makeWageSpec(true);
+      const scales = computeScales(spec, chartArea, spec.data);
+      const marks = computeBarMarks(spec, scales, chartArea, fullStrategy);
+
+      const smallFirmMarks = marks.filter((m) => m.aria.label.includes('<5'));
+      expect(smallFirmMarks).toHaveLength(2);
+      expect(smallFirmMarks[0].y).not.toBe(smallFirmMarks[1].y);
+    });
+
+    it('grouped with stack:null: scale domain covers max individual value, not stacked sum', () => {
+      const spec = makeWageSpec(true);
+      const scales = computeScales(spec, chartArea, spec.data);
+
+      // Max individual pay is 74800. Stacked sum for 5000+ employees = 62300 + 74800 = 137100.
+      // With stack:null the domain should NOT reach 137100.
+      const xScale = scales.x!.scale;
+      const domain = xScale.domain() as number[];
+      expect(domain[1]).toBeLessThan(137100);
+      // But it should cover the max individual value
+      expect(domain[1]).toBeGreaterThanOrEqual(74800);
+    });
+  });
+
   describe('edge cases', () => {
     it('returns empty array when no x encoding', () => {
       const spec: NormalizedChartSpec = {

package/src/charts/bar/compute.ts

@@ -118,6 +118,7 @@ export function computeBarMarks(
   const needsStacking = Array.from(categoryGroups.values()).some((rows) => rows.length > 1);
 
   if (needsStacking) {
+    // stack: null or false -> grouped (side-by-side) bars
     const stackDisabled = xChannel.stack === null || xChannel.stack === false;
 
     if (stackDisabled) {

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,

package/src/compile.ts

@@ -199,7 +199,7 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
 
   // Resolve watermark: explicit spec value wins, then options fallback, then default true.
   const rawWatermark = (expandedSpec as Record<string, unknown>).watermark;
-  const watermark = rawWatermark !== undefined ? chartSpec.watermark : (options.watermark ?? true);
+  let watermark = rawWatermark !== undefined ? chartSpec.watermark : (options.watermark ?? true);
 
   // Run data transforms (filter, bin, calculate, timeUnit) before any other data processing.
   // Transforms are defined on the expanded spec (which includes any auto-generated
@@ -223,10 +223,49 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
     | Partial<
         Record<
           string,
-          { chrome?: unknown; labels?: unknown; legend?: unknown; annotations?: unknown }
+          {
+            chrome?: unknown;
+            labels?: unknown;
+            legend?: unknown;
+            annotations?: unknown;
+            animation?: unknown;
+            display?: unknown;
+            encoding?: unknown;
+            watermark?: unknown;
+            crosshair?: unknown;
+          }
         >
       >
     | undefined;
+
+  // Build userExplicit descriptor BEFORE applying any overrides so we capture
+  // the union of "user wrote this at top-level" and "user wrote this in the
+  // active breakpoint override." Sparkline display mode reads this to decide
+  // whether to suppress chrome/axes/legend/etc. by default vs. respecting an
+  // explicit user opt-in. Precedence: explicit at any level wins.
+  const rawEncoding = rawSpec.encoding as
+    | { x?: { axis?: unknown }; y?: { axis?: unknown } }
+    | undefined;
+  const bpForExplicit = overrides?.[breakpoint];
+  const bpEncoding = bpForExplicit?.encoding as
+    | { x?: { axis?: unknown }; y?: { axis?: unknown } }
+    | undefined;
+  // chrome: {} (empty object) is not "explicit" — it's an idiom users write to
+  // silence defaults. Require at least one chrome key set to count as opt-in.
+  const hasChromeKeys = (v: unknown): boolean =>
+    !!v && typeof v === 'object' && Object.keys(v as Record<string, unknown>).length > 0;
+  const userExplicit = {
+    chrome: hasChromeKeys(rawSpec.chrome) || hasChromeKeys(bpForExplicit?.chrome),
+    legend: rawSpec.legend !== undefined || bpForExplicit?.legend !== undefined,
+    xAxis: rawEncoding?.x?.axis !== undefined || bpEncoding?.x?.axis !== undefined,
+    yAxis: rawEncoding?.y?.axis !== undefined || bpEncoding?.y?.axis !== undefined,
+    labels: rawSpec.labels !== undefined || bpForExplicit?.labels !== undefined,
+    animation: rawSpec.animation !== undefined || bpForExplicit?.animation !== undefined,
+    watermark: rawSpec.watermark !== undefined || bpForExplicit?.watermark !== undefined,
+    crosshair: rawSpec.crosshair !== undefined || bpForExplicit?.crosshair !== undefined,
+  };
+  chartSpec = { ...chartSpec, userExplicit };
+
   if (overrides?.[breakpoint]) {
     const bp = overrides[breakpoint]!;
     if (bp.chrome) {
@@ -274,14 +313,138 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
       // responsive strategy so they render inline instead of being stripped.
       strategy = { ...strategy, annotationPosition: 'inline' };
     }
+    // New override branches for sparkline mode and related fields:
+    if (bp.display !== undefined) {
+      chartSpec = {
+        ...chartSpec,
+        display: bp.display as NormalizedChartSpec['display'],
+      };
+    }
+    if (bp.encoding !== undefined) {
+      // Merge encoding so a breakpoint can flip on/off encoding.x.axis or
+      // encoding.y.axis (used by sparkline display mode to opt back in to
+      // axes at a specific breakpoint). Channels merge per-key, and `axis`
+      // and `scale` deep-merge one level so a breakpoint can set
+      // `axis: { title: 'foo' }` without dropping the base spec's
+      // `axis.tickCount` / `axis.format`.
+      const bpEnc = bp.encoding as Record<string, Record<string, unknown> | undefined>;
+      const mergedEncoding = { ...chartSpec.encoding } as Record<
+        string,
+        Record<string, unknown> | undefined
+      >;
+      const NESTED_CHANNEL_KEYS = ['axis', 'scale'];
+      for (const channel of Object.keys(bpEnc)) {
+        const baseCh = mergedEncoding[channel];
+        const bpCh = bpEnc[channel];
+        if (bpCh && baseCh) {
+          const merged: Record<string, unknown> = { ...baseCh, ...bpCh };
+          for (const key of NESTED_CHANNEL_KEYS) {
+            const baseNested = baseCh[key];
+            const bpNested = bpCh[key];
+            if (
+              baseNested &&
+              bpNested &&
+              typeof baseNested === 'object' &&
+              typeof bpNested === 'object' &&
+              !Array.isArray(baseNested) &&
+              !Array.isArray(bpNested)
+            ) {
+              merged[key] = { ...baseNested, ...bpNested };
+            }
+          }
+          mergedEncoding[channel] = merged;
+        } else if (bpCh) {
+          mergedEncoding[channel] = bpCh;
+        }
+      }
+      chartSpec = {
+        ...chartSpec,
+        encoding: mergedEncoding as unknown as NormalizedChartSpec['encoding'],
+      };
+    }
+    if (typeof bp.watermark === 'boolean') {
+      // Update the resolved watermark value used downstream. ChartSpec carries
+      // this in its normalized shape; the local `watermark` variable controls
+      // chrome computation and rendering.
+      watermark = bp.watermark;
+      chartSpec = { ...chartSpec, watermark };
+    }
+  }
+
+  // Sparkline mode: default labels off. Mark renderers draw value labels per
+  // labels.density (default 'auto'), which fills tiny sparklines with text and
+  // is never what you want. Explicit user labels at any level wins via
+  // userExplicit.labels.
+  if (chartSpec.display === 'sparkline' && !chartSpec.userExplicit.labels) {
+    chartSpec = {
+      ...chartSpec,
+      labels: { ...chartSpec.labels, density: 'none' },
+    };
   }
 
   // Resolve animation spec. Breakpoint override wins over base spec (matching
   // chrome, labels, legend, and annotation override precedence).
-  const rawAnimationSpec = ((overrides?.[breakpoint] as Record<string, unknown> | undefined)
+  // Precedence rule for sparkline mode: an explicit user animation at ANY
+  // level (top-level OR breakpoint) always wins, regardless of display mode.
+  // resolveAnimation handles the explicit-user value; the sparkline default-off
+  // behavior is applied below when no explicit value exists.
+  let rawAnimationSpec = ((overrides?.[breakpoint] as Record<string, unknown> | undefined)
     ?.animation ?? rawSpec.animation) as AnimationSpec | undefined;
+  if (rawAnimationSpec === undefined && chartSpec.display === 'sparkline') {
+    // Sparkline mode: animation defaults to false. User-explicit (top OR bp)
+    // already short-circuits this branch via userExplicit.animation.
+    rawAnimationSpec = false;
+  }
+  // Sparkline mode: when animation is on but the user didn't specify duration,
+  // bump to 1100ms so the line/area reveal feels paced rather than mechanical.
+  // The CSS override pairs this with an expo-out easing curve. AnimationConfig
+  // nests duration under `enter`, so we set it there.
+  if (
+    chartSpec.display === 'sparkline' &&
+    rawAnimationSpec !== false &&
+    rawAnimationSpec !== undefined
+  ) {
+    const SPARK_DURATION = 1100;
+    if (rawAnimationSpec === true) {
+      rawAnimationSpec = { enter: { duration: SPARK_DURATION } } as AnimationSpec;
+    } else if (typeof rawAnimationSpec === 'object') {
+      const cfg = rawAnimationSpec as { enter?: unknown; annotationDelay?: number };
+      const enter = cfg.enter;
+      if (enter === undefined || enter === true) {
+        rawAnimationSpec = {
+          ...cfg,
+          enter: { duration: SPARK_DURATION },
+        } as AnimationSpec;
+      } else if (
+        typeof enter === 'object' &&
+        enter !== null &&
+        (enter as { duration?: number }).duration === undefined
+      ) {
+        rawAnimationSpec = {
+          ...cfg,
+          enter: { ...(enter as object), duration: SPARK_DURATION },
+        } as AnimationSpec;
+      }
+    }
+  }
   const resolvedAnimation = resolveAnimation(rawAnimationSpec);
 
+  // Crosshair: explicit user value at any level wins. In sparkline mode the
+  // default is off, otherwise default is off too (crosshair is opt-in). The
+  // value is plumbed through ChartLayout so the renderer doesn't need to
+  // re-inspect the raw spec.
+  const rawCrosshair = (bpForExplicit?.crosshair ?? rawSpec.crosshair) as boolean | undefined;
+  const crosshair =
+    chartSpec.display === 'sparkline' && !chartSpec.userExplicit.crosshair
+      ? false
+      : rawCrosshair === true;
+
+  // Watermark default-off in sparkline mode unless user-explicit.
+  if (chartSpec.display === 'sparkline' && !chartSpec.userExplicit.watermark) {
+    watermark = false;
+    chartSpec = { ...chartSpec, watermark: false };
+  }
+
   // Resolve theme: merge spec-level theme with options-level overrides
   const mergedThemeConfig = options.theme
     ? { ...chartSpec.theme, ...options.theme }
@@ -365,12 +528,18 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
   // Arc charts (pie/donut) don't use axes or gridlines
   const isRadial = chartSpec.markType === 'arc';
 
-  // Compute axes (skip for radial charts)
+  // Compute axes (skip for radial charts).
+  // Sparkline mode skips axes by default unless the user explicitly opted into
+  // an axis on a specific channel.
+  const skipX = chartSpec.display === 'sparkline' && !chartSpec.userExplicit.xAxis;
+  const skipY = chartSpec.display === 'sparkline' && !chartSpec.userExplicit.yAxis;
   const axes = isRadial
     ? { x: undefined, y: undefined }
     : computeAxes(scales, chartArea, strategy, theme, options.measureText, {
         data: renderSpec.data,
         encoding: renderSpec.encoding as Encoding,
+        skipX,
+        skipY,
       });
 
   // INVARIANT 2 — computeGridlines mutates `axes` in place. Downstream consumers read
@@ -464,6 +633,8 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
     },
     animation: resolvedAnimation,
     watermark,
+    display: chartSpec.display,
+    crosshair,
     measureText: options.measureText,
   };
 }