@opendata-ai/openchart-engine 6.25.4 → 6.27.0

package/src/compile.ts

@@ -77,6 +77,7 @@ import { computeLegend } from './legend/compute';
 import { legendGap } from './legend/wrap';
 import { compileSankey as compileSankeyImpl } from './sankey/compile-sankey';
 import { compileTableLayout } from './tables/compile-table';
+import { compileTileMap as compileTileMapImpl } from './tilemap/compile-tilemap';
 import { computeTooltipDescriptors } from './tooltips/compute';
 import { runTransforms } from './transforms';
 
@@ -198,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
@@ -222,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) {
@@ -273,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 }
@@ -310,7 +474,7 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
   // the reserved margin. This way computeLegend positions the legend outside
   // the data area (in the margin) instead of overlapping data marks.
   const legendArea: Rect = { ...chartArea };
-  if (legendLayout.entries.length > 0) {
+  if ('entries' in legendLayout && legendLayout.entries.length > 0) {
     const gap = legendGap(options.width);
     switch (legendLayout.position) {
       case 'top':
@@ -364,10 +528,19 @@ 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);
+    : 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
   // axes.y.gridlines off the same object. Do not introduce a copy-on-write.
@@ -460,6 +633,8 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
     },
     animation: resolvedAnimation,
     watermark,
+    display: chartSpec.display,
+    crosshair,
     measureText: options.measureText,
   };
 }
@@ -504,7 +679,8 @@ export function compileLayer(spec: LayerSpec, options: CompileOptions): ChartLay
 
   const allMarks: Mark[] = [];
   const seenLabels = new Set<string>();
-  const mergedLegendEntries = [...primaryLayout.legend.entries];
+  const pLegend = primaryLayout.legend;
+  const mergedLegendEntries = 'entries' in pLegend ? [...pLegend.entries] : [];
   for (const entry of mergedLegendEntries) {
     seenLabels.add(entry.label);
   }
@@ -522,10 +698,13 @@ export function compileLayer(spec: LayerSpec, options: CompileOptions): ChartLay
 
     allMarks.push(...leafLayout.marks);
 
-    for (const entry of leafLayout.legend.entries) {
-      if (!seenLabels.has(entry.label)) {
-        seenLabels.add(entry.label);
-        mergedLegendEntries.push(entry);
+    const leafLeg = leafLayout.legend;
+    if ('entries' in leafLeg) {
+      for (const entry of leafLeg.entries) {
+        if (!seenLabels.has(entry.label)) {
+          seenLabels.add(entry.label);
+          mergedLegendEntries.push(entry);
+        }
       }
     }
   }
@@ -535,8 +714,8 @@ export function compileLayer(spec: LayerSpec, options: CompileOptions): ChartLay
     marks: allMarks,
     legend: {
       ...primaryLayout.legend,
-      entries: mergedLegendEntries,
-    },
+      ...('entries' in pLegend ? { entries: mergedLegendEntries } : {}),
+    } as typeof primaryLayout.legend,
   };
 }
 
@@ -812,9 +991,12 @@ function compileLayerIndependent(
 
   // Merge legend entries with deduplication
   const seenLabels = new Set<string>();
-  const mergedLegendEntries = [...layout0.legend.entries];
+  const l0Legend = layout0.legend;
+  const l1Legend = layout1.legend;
+  const mergedLegendEntries = 'entries' in l0Legend ? [...l0Legend.entries] : [];
   for (const entry of mergedLegendEntries) seenLabels.add(entry.label);
-  for (const entry of layout1.legend.entries) {
+  const l1Entries = 'entries' in l1Legend ? l1Legend.entries : [];
+  for (const entry of l1Entries) {
     if (!seenLabels.has(entry.label)) {
       seenLabels.add(entry.label);
       mergedLegendEntries.push(entry);
@@ -856,8 +1038,8 @@ function compileLayerIndependent(
     marks,
     legend: {
       ...layout0.legend,
-      entries: mergedLegendEntries,
-    },
+      ...('entries' in l0Legend ? { entries: mergedLegendEntries } : {}),
+    } as typeof layout0.legend,
     tooltipDescriptors: mergedTooltips,
   };
 }
@@ -1111,3 +1293,26 @@ export function compileSankey(
 ): import('@opendata-ai/openchart-core').SankeyLayout {
   return compileSankeyImpl(spec, options);
 }
+
+// ---------------------------------------------------------------------------
+// TileMap compilation
+// ---------------------------------------------------------------------------
+
+/**
+ * Compile a tilemap spec into a TileMapLayout.
+ *
+ * Takes a raw tilemap spec, validates, normalizes, resolves theme and chrome,
+ * computes tile positions, builds tile marks with colors and labels, and
+ * returns a TileMapLayout ready for rendering.
+ *
+ * @param spec - Raw tilemap spec (validated and normalized internally).
+ * @param options - Compile options (width, height, theme, darkMode).
+ * @returns TileMapLayout with computed positions and visual properties.
+ * @throws Error if spec is invalid or not a tilemap type.
+ */
+export function compileTileMap(
+  spec: unknown,
+  options: CompileOptions,
+): import('@opendata-ai/openchart-core').TileMapLayout {
+  return compileTileMapImpl(spec, options);
+}

package/src/compiler/normalize.ts

@@ -21,6 +21,7 @@ import type {
   LayerSpec,
   SankeySpec,
   TableSpec,
+  TileMapSpec,
   VizSpec,
 } from '@opendata-ai/openchart-core';
 import {
@@ -29,10 +30,13 @@ import {
   isLayerSpec,
   isSankeySpec,
   isTableSpec,
+  isTileMapSpec,
   resolveMarkDef,
   resolveMarkType,
 } from '@opendata-ai/openchart-core';
 import type { NormalizedSankeySpec } from '../sankey/types';
+import { STATE_CODE_SET } from '../tilemap/layout';
+import type { NormalizedTileMapSpec } from '../tilemap/types';
 import type {
   NormalizedChartSpec,
   NormalizedChrome,
@@ -213,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,
@@ -229,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,
+    },
   };
 }
 
@@ -303,6 +333,55 @@ function normalizeGraphSpec(spec: GraphSpec, _warnings: string[]): NormalizedGra
   };
 }
 
+function normalizeTileMapSpec(spec: TileMapSpec, warnings: string[]): NormalizedTileMapSpec {
+  // Convert record data to array if needed
+  let data: Record<string, unknown>[] = Array.isArray(spec.data) ? spec.data : [];
+
+  if (!Array.isArray(spec.data)) {
+    // Convert record map to array of rows
+    data = Object.entries(spec.data).map(([state, value]) => ({ state, value }));
+  }
+
+  // Auto-generate encoding if not provided
+  let encoding = spec.encoding;
+  if (!encoding) {
+    encoding = {
+      state: { field: 'state', type: 'nominal' },
+      value: { field: 'value', type: 'quantitative' },
+    };
+  }
+
+  // Count matched states and warn if low match ratio
+  let matchedCount = 0;
+  for (const row of data) {
+    const stateCode = String(row[encoding.state.field]);
+    if (STATE_CODE_SET.has(stateCode)) {
+      matchedCount++;
+    }
+  }
+
+  const matchRatio = data.length > 0 ? matchedCount / data.length : 0;
+  if (matchRatio < 0.5 && data.length > 0) {
+    warnings.push(
+      `TileMap data: only ${matchedCount} of ${data.length} rows have valid US state codes (expected ≥50%)`,
+    );
+  }
+
+  return {
+    type: 'tilemap',
+    data,
+    encoding,
+    palette: spec.palette ?? 'blue',
+    chrome: normalizeChrome(spec.chrome),
+    legend: spec.legend,
+    theme: spec.theme ?? {},
+    darkMode: spec.darkMode ?? 'off',
+    watermark: spec.watermark ?? true,
+    animation: spec.animation,
+    valueFormat: spec.valueFormat,
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
@@ -337,9 +416,12 @@ export function normalizeSpec(spec: VizSpec, warnings: string[] = []): Normalize
   if (isSankeySpec(spec)) {
     return normalizeSankeySpec(spec, warnings);
   }
+  if (isTileMapSpec(spec)) {
+    return normalizeTileMapSpec(spec, warnings);
+  }
   // Should never happen after validation
   throw new Error(
-    `Unknown spec shape. Expected mark (chart), layer, type: 'table', type: 'graph', or type: 'sankey'.`,
+    `Unknown spec shape. Expected mark (chart), layer, type: 'table', type: 'graph', type: 'sankey', or type: 'tilemap'.`,
   );
 }
 

package/src/compiler/types.ts

@@ -15,6 +15,7 @@ import type {
   ColumnConfig,
   DarkMode,
   DataRow,
+  Display,
   Encoding,
   FieldType,
   GraphEncoding,
@@ -29,6 +30,7 @@ import type {
   ThemeConfig,
 } from '@opendata-ai/openchart-core';
 import type { NormalizedSankeySpec } from '../sankey/types';
+import type { NormalizedTileMapSpec } from '../tilemap/types';
 
 // ---------------------------------------------------------------------------
 // NormalizedChrome: all fields are ChromeText objects (not plain strings)
@@ -60,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). */
@@ -84,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. */
@@ -124,7 +163,8 @@ export type NormalizedSpec =
   | NormalizedChartSpec
   | NormalizedTableSpec
   | NormalizedGraphSpec
-  | NormalizedSankeySpec;
+  | NormalizedSankeySpec
+  | NormalizedTileMapSpec;
 
 // ---------------------------------------------------------------------------
 // Validation types