@opendata-ai/openchart-engine 6.26.0 → 6.27.0

package/src/compiler/normalize.ts

@@ -217,6 +217,19 @@ function normalizeChartSpec(spec: ChartSpec, warnings: string[]): NormalizedChar
   const encoding = inferEncodingTypes(spec.encoding, spec.data, warnings);
   const markType = resolveMarkType(spec.mark);
   const markDef = resolveMarkDef(spec.mark);
+  const display = spec.display ?? 'full';
+
+  if (
+    display === 'sparkline' &&
+    markType !== 'line' &&
+    markType !== 'area' &&
+    markType !== 'bar' &&
+    markType !== 'point'
+  ) {
+    warnings.push(
+      `[openchart] display: 'sparkline' works best with mark: 'line' | 'area' | 'bar' | 'point'. Got mark: '${markType}' — rendering may degrade.`,
+    );
+  }
 
   return {
     markType,
@@ -233,6 +246,19 @@ function normalizeChartSpec(spec: ChartSpec, warnings: string[]): NormalizedChar
     hiddenSeries: spec.hiddenSeries ?? [],
     seriesStyles: spec.seriesStyles ?? {},
     watermark: spec.watermark ?? true,
+    display,
+    // Default empty userExplicit; compileChart overwrites this with the real
+    // descriptor built from the raw expanded spec before normalize runs.
+    userExplicit: {
+      chrome: false,
+      legend: false,
+      xAxis: false,
+      yAxis: false,
+      labels: false,
+      animation: false,
+      watermark: false,
+      crosshair: false,
+    },
   };
 }
 

package/src/compiler/types.ts

@@ -15,6 +15,7 @@ import type {
   ColumnConfig,
   DarkMode,
   DataRow,
+  Display,
   Encoding,
   FieldType,
   GraphEncoding,
@@ -61,6 +62,35 @@ export interface NormalizedEncodingChannel {
 // NormalizedSpec types
 // ---------------------------------------------------------------------------
 
+/**
+ * Tracks which top-level fields the user explicitly set in their input spec.
+ *
+ * Built from the raw expandedSpec (post-breakpoint-merge, pre-normalize) so
+ * that "user wrote chrome.title" vs "user wrote nothing" is distinguishable
+ * after normalization fills in defaults.
+ *
+ * Used by sparkline display mode to decide whether to suppress chrome/axes/
+ * legend/etc. by default vs. respecting an explicit user opt-in.
+ */
+export interface UserExplicit {
+  /** True if user wrote `chrome` (any non-empty chrome). */
+  chrome: boolean;
+  /** True if user wrote `legend`. */
+  legend: boolean;
+  /** True if user wrote `encoding.x.axis`. */
+  xAxis: boolean;
+  /** True if user wrote `encoding.y.axis`. */
+  yAxis: boolean;
+  /** True if user wrote `labels`. */
+  labels: boolean;
+  /** True if user wrote `animation`. */
+  animation: boolean;
+  /** True if user wrote `watermark`. */
+  watermark: boolean;
+  /** True if user wrote `crosshair`. */
+  crosshair: boolean;
+}
+
 /** A ChartSpec with all optional fields filled with sensible defaults. */
 export interface NormalizedChartSpec {
   /** Resolved mark type string (extracted from spec.mark). */
@@ -85,6 +115,14 @@ export interface NormalizedChartSpec {
   hiddenSeries: string[];
   /** Per-series visual style overrides. */
   seriesStyles: Record<string, import('@opendata-ai/openchart-core').SeriesStyle>;
+  /** Display mode controlling chrome/axes/legend stripping. Defaults to `'full'`. */
+  display: Display;
+  /**
+   * Which top-level fields the user explicitly set. Populated by compileChart
+   * from the raw expanded spec before normalization. NormalizeChartSpec runs
+   * with a default-empty descriptor; compileChart overwrites it post-normalize.
+   */
+  userExplicit: UserExplicit;
 }
 
 /** A TableSpec with all optional fields filled with sensible defaults. */

package/src/layout/axes.ts

@@ -199,6 +199,13 @@ export interface AxesDataContext {
   data: DataRow[];
   /** The encoding object to resolve field names. */
   encoding: Encoding;
+  /**
+   * When true, skip generating ticks/labels/title for the x-axis. Used by
+   * sparkline display mode when the user hasn't explicitly opted into axes.
+   */
+  skipX?: boolean;
+  /** Same as skipX, for the y-axis. */
+  skipY?: boolean;
 }
 
 /**
@@ -257,7 +264,7 @@ export function computeAxes(
   const { fontSize } = tickLabelStyle;
   const { fontWeight } = tickLabelStyle;
 
-  if (scales.x) {
+  if (scales.x && !dataContext?.skipX) {
     const axisConfig = scales.x.channel.axis;
     const isContinuousX =
       scales.x.type !== 'band' && scales.x.type !== 'point' && scales.x.type !== 'ordinal';
@@ -359,7 +366,7 @@ export function computeAxes(
     };
   }
 
-  if (scales.y) {
+  if (scales.y && !dataContext?.skipY) {
     const axisConfig = scales.y.channel.axis;
     const isContinuousY =
       scales.y.type !== 'band' && scales.y.type !== 'point' && scales.y.type !== 'ordinal';

package/src/layout/dimensions.ts

@@ -93,6 +93,30 @@ function scalePadding(basePadding: number, width: number, height: number): numbe
 const MIN_CHART_WIDTH = 60;
 const MIN_CHART_HEIGHT = 40;
 
+/**
+ * Per-display minimum chart dimensions. Sparkline mode allows much smaller
+ * containers (down to ~30x20px) since the entire chart is just the mark.
+ */
+function getMinChartDims(display: import('@opendata-ai/openchart-core').Display): {
+  width: number;
+  height: number;
+} {
+  return display === 'sparkline'
+    ? { width: 30, height: 20 }
+    : { width: MIN_CHART_WIDTH, height: MIN_CHART_HEIGHT };
+}
+
+/**
+ * Resolve the per-side safety padding for sparkline mode. Padding scales with
+ * the user-configured mark stroke width so a thick line doesn't clip at the
+ * container edge. Per-side padding = max(strokeWidth/2 + 1, 2) so even a 1px
+ * stroke gets at least 2px breathing room.
+ */
+function getSparklinePad(spec: NormalizedChartSpec): number {
+  const strokeWidth = (spec.markDef as { strokeWidth?: number }).strokeWidth ?? 2;
+  return Math.max(strokeWidth / 2 + 1, 2);
+}
+
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
@@ -125,7 +149,16 @@ export function computeDimensions(
       ? Math.max(Math.round(padding * HPAD_COMPACT_FRACTION), HPAD_COMPACT_MIN)
       : padding;
   const axisMargin = theme.spacing.axisMargin;
-  const chromeMode = strategy?.chromeMode ?? 'full';
+  const userExplicit = spec.userExplicit;
+  const isSparkline = spec.display === 'sparkline';
+
+  // Sparkline mode forces chrome hidden unless the user opted in explicitly.
+  // Force-hiding chrome here also short-circuits the watermark (which is
+  // rendered as part of chrome), so we don't need a separate watermark gate.
+  let chromeMode = strategy?.chromeMode ?? 'full';
+  if (isSparkline && !userExplicit.chrome) {
+    chromeMode = 'hidden';
+  }
 
   // Compute chrome with mode and scaled padding
   const chrome = computeChrome(
@@ -138,6 +171,47 @@ export function computeDimensions(
     watermark,
   );
 
+  // Sparkline mode: produce a near-edge-to-edge layout. Only stroke-width-based
+  // safety padding plus chrome (if user-explicit). Skip axis space, label
+  // reservations, annotation reservations, and legend reservations unless the
+  // user opted in to those individually.
+  if (isSparkline) {
+    const total: Rect = { x: 0, y: 0, width, height };
+    const sparkPad = getSparklinePad(spec);
+
+    // Axis space only when user explicitly set encoding.x/y.axis.
+    const xAxisSpace = userExplicit.xAxis ? 26 : 0;
+    const yAxisSpace = userExplicit.yAxis ? 30 : 0;
+
+    const margins: Margins = {
+      top: chrome.topHeight + sparkPad,
+      right: sparkPad,
+      bottom: chrome.bottomHeight + sparkPad + xAxisSpace,
+      left: sparkPad + yAxisSpace,
+    };
+
+    // Reserve legend space only when user explicitly opted into a legend.
+    if (userExplicit.legend && 'entries' in legendLayout && legendLayout.entries.length > 0) {
+      const gap = legendGap(width);
+      if (legendLayout.position === 'right' || legendLayout.position === 'bottom-right') {
+        margins.right += legendLayout.bounds.width + 8;
+      } else if (legendLayout.position === 'top') {
+        margins.top += legendLayout.bounds.height + gap;
+      } else if (legendLayout.position === 'bottom') {
+        margins.bottom += legendLayout.bounds.height + gap;
+      }
+    }
+
+    const chartArea: Rect = {
+      x: margins.left,
+      y: margins.top,
+      width: Math.max(0, width - margins.left - margins.right),
+      height: Math.max(0, height - margins.top - margins.bottom),
+    };
+
+    return { total, chrome, chartArea, margins, theme };
+  }
+
   // Start with the total rect
   const total: Rect = { x: 0, y: 0, width, height };
 
@@ -395,8 +469,9 @@ export function computeDimensions(
   };
 
   // Guardrail: if chart area is too small, progressively strip chrome
+  const minDims = getMinChartDims(spec.display);
   if (
-    (chartArea.width < MIN_CHART_WIDTH || chartArea.height < MIN_CHART_HEIGHT) &&
+    (chartArea.width < minDims.width || chartArea.height < minDims.height) &&
     chromeMode !== 'hidden'
   ) {
     // Try compact first, then hidden

package/src/legend/compute.ts

@@ -143,8 +143,13 @@ export function computeLegend(
   chartArea: Rect,
   watermark: boolean = true,
 ): LegendLayout {
+  // Sparkline mode: legend hidden by default unless the user opted in. Color
+  // scales still resolve normally (legend hidden != no colors), so multi-series
+  // sparklines retain their categorical palette.
+  const sparklineHidden = spec.display === 'sparkline' && !spec.userExplicit.legend;
+
   // Legend explicitly hidden via show: false, or height strategy says no legend
-  if (spec.legend?.show === false || strategy.legendMaxHeight === 0) {
+  if (sparklineHidden || spec.legend?.show === false || strategy.legendMaxHeight === 0) {
     return {
       position: 'top',
       entries: [],