@opendata-ai/openchart-engine 6.26.0 → 6.27.2

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/ticks.ts

@@ -38,13 +38,18 @@ import type { D3CategoricalScale, D3ContinuousScale, ResolvedScale } from '../sc
  * "full" is the publication-ready default; "reduced" and "minimal" step down as the
  * responsive breakpoint system shifts to smaller containers.
  *
+ * Y full is set to 40px/tick (tighter than Observable Plot's 50) because chart areas
+ * are measured after chrome subtraction. A 400px container with title+subtitle leaves
+ * ~270px of chart area; 55px/tick would only produce 4 ticks. 40px/tick reaches 5-6
+ * on typical chart areas (150-300px) and the overlap check acts as a safety net.
+ *
  * @internal — these are tuning constants, not part of the configuration API.
  * Consumers should configure tick density through `axis.tickCount` on the spec.
  */
 const Y_PX_PER_TICK: Record<AxisLabelDensity, number> = {
-  full: 55,
-  reduced: 90,
-  minimal: 140,
+  full: 40,
+  reduced: 70,
+  minimal: 120,
 };
 
 const X_PX_PER_TICK: Record<AxisLabelDensity, number> = {
@@ -194,7 +199,29 @@ export function buildContinuousTicks(resolvedScale: ResolvedScale, count: number
     return continuousTicks(resolvedScale, 'full');
   }
   const raw: unknown[] = scale.ticks(count);
-  return raw.map((value: unknown) => ({
+
+  // D3 log scales ignore the count hint and return ticks at every sub-power
+  // position (e.g. 5, 6, 7, 8, 9, 10, 20, 30... for a domain of [5, 25000]).
+  // Filter down to powers of the base only when the raw set overshoots.
+  let ticks = raw;
+  if (resolvedScale.type === 'log' && raw.length > count) {
+    const base = resolvedScale.channel.scale?.base ?? 10;
+    const logBase = Math.log(base);
+    const powered = raw.filter((v) => {
+      const n = v as number;
+      if (n <= 0) return false;
+      const exp = Math.log(n) / logBase;
+      return Math.abs(exp - Math.round(exp)) < 1e-9;
+    });
+    // Only use the filtered set if it has at least 2 ticks; otherwise fall back
+    // to raw ticks. This handles domains like [5, 9] (no powers of 10 at all) or
+    // [5, 50] (only one power: 10) where filtering would leave too few meaningful ticks.
+    if (powered.length >= 2) {
+      ticks = powered;
+    }
+  }
+
+  return ticks.map((value: unknown) => ({
     value,
     position: scale(value as number & Date) as number,
     label: formatTickLabel(value, resolvedScale),

package/src/layout/axes.ts

@@ -44,9 +44,16 @@ export { thinTicksUntilFit, ticksOverlap } from './axes/thinning';
  * Below these pixel heights, we step down the density regardless of the
  * width-based strategy. This prevents overlapping y-axis labels in short
  * containers like thumbnail previews.
+ *
+ * These thresholds apply to the chart area height (after chrome/margins),
+ * not the total container height. A 400px container with title+subtitle
+ * leaves ~270px of chart area; a 320px container leaves ~186px. The old
+ * HEIGHT_REDUCED_THRESHOLD of 200 kicked in on nearly every common chart
+ * size, producing only 3 ticks. Lowering to 100 keeps 'full' density for
+ * all but the most compact thumbnail-style containers.
  */
-const HEIGHT_MINIMAL_THRESHOLD = 120;
-const HEIGHT_REDUCED_THRESHOLD = 200;
+const HEIGHT_MINIMAL_THRESHOLD = 80;
+const HEIGHT_REDUCED_THRESHOLD = 100;
 
 /**
  * Width thresholds for reducing x-axis tick density.
@@ -199,6 +206,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 +271,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 +373,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: [],