@opendata-ai/openchart-engine 6.25.4 → 6.27.0

package/src/compiler/validate.ts

@@ -645,6 +645,120 @@ function validateSankeySpec(spec: Record<string, unknown>, errors: ValidationErr
   }
 }
 
+// ---------------------------------------------------------------------------
+// TileMap validation
+// ---------------------------------------------------------------------------
+
+function validateTileMapSpec(spec: Record<string, unknown>, errors: ValidationError[]): void {
+  // Validate data (can be record or array)
+  if (!spec.data || typeof spec.data !== 'object') {
+    errors.push({
+      message: 'Spec error: tilemap spec requires a "data" field (record or array)',
+      path: 'data',
+      code: 'INVALID_TYPE',
+      suggestion:
+        'Provide data as either a record mapping state codes to values (e.g. { "CA": 12000, "TX": 8500 }) or an array of objects with state and value fields',
+    });
+    return;
+  }
+
+  // If data is an object (record), validate it has at least one entry
+  if (!Array.isArray(spec.data) && Object.keys(spec.data as Record<string, unknown>).length === 0) {
+    errors.push({
+      message: 'Spec error: "data" must have at least one entry',
+      path: 'data',
+      code: 'EMPTY_DATA',
+      suggestion: 'Add at least one state-value pair, e.g. { "CA": 12000 }',
+    });
+    return;
+  }
+
+  // If data is an array, validate it's non-empty
+  if (Array.isArray(spec.data)) {
+    if (spec.data.length === 0) {
+      errors.push({
+        message: 'Spec error: "data" array must be non-empty',
+        path: 'data',
+        code: 'EMPTY_DATA',
+        suggestion: 'Add at least one data row',
+      });
+      return;
+    }
+
+    const firstRow = spec.data[0] as unknown;
+    if (typeof firstRow !== 'object' || firstRow === null || Array.isArray(firstRow)) {
+      errors.push({
+        message: 'Spec error: each item in "data" must be a plain object',
+        path: 'data[0]',
+        code: 'INVALID_TYPE',
+        suggestion: 'Each data item should be an object, e.g. { state: "CA", value: 12000 }',
+      });
+      return;
+    }
+
+    // If data is array, encoding is required
+    if (!spec.encoding || typeof spec.encoding !== 'object') {
+      errors.push({
+        message:
+          'Spec error: tilemap spec with array data requires an "encoding" object with state and value channels',
+        path: 'encoding',
+        code: 'MISSING_FIELD',
+        suggestion:
+          'Add an encoding object, e.g. encoding: { state: { field: "state", type: "nominal" }, value: { field: "value", type: "quantitative" } }',
+      });
+      return;
+    }
+
+    const encoding = spec.encoding as Record<string, unknown>;
+    const dataColumns = new Set(Object.keys(firstRow as Record<string, unknown>));
+    const availableColumns = [...dataColumns].join(', ');
+
+    // Required channels
+    for (const channel of ['state', 'value'] as const) {
+      const ch = encoding[channel] as Record<string, unknown> | undefined;
+      if (!ch || typeof ch !== 'object') {
+        errors.push({
+          message: `Spec error: tilemap encoding requires "${channel}" channel`,
+          path: `encoding.${channel}`,
+          code: 'MISSING_FIELD',
+          suggestion: `Add encoding.${channel} with a field from your data (${availableColumns}). Example: ${channel}: { field: "${[...dataColumns][0] ?? 'myField'}", type: "${channel === 'value' ? 'quantitative' : 'nominal'}" }`,
+        });
+        continue;
+      }
+
+      if (!ch.field || typeof ch.field !== 'string') {
+        errors.push({
+          message: `Spec error: encoding.${channel} must have a "field" string`,
+          path: `encoding.${channel}.field`,
+          code: 'MISSING_FIELD',
+          suggestion: `Add a field name from your data columns: ${availableColumns}`,
+        });
+        continue;
+      }
+
+      if (!dataColumns.has(ch.field as string)) {
+        errors.push({
+          message: `Spec error: encoding.${channel}.field "${ch.field}" does not exist in data. Available columns: ${availableColumns}`,
+          path: `encoding.${channel}.field`,
+          code: 'DATA_FIELD_MISSING',
+          suggestion: `Use one of the available data columns: ${availableColumns}`,
+        });
+      }
+    }
+  }
+
+  // Validate darkMode if provided
+  if (spec.darkMode !== undefined && !VALID_DARK_MODES.has(spec.darkMode as string)) {
+    errors.push({
+      message: 'Spec error: darkMode must be "auto", "force", or "off"',
+      path: 'darkMode',
+      code: 'INVALID_VALUE',
+      suggestion:
+        'Use one of: "auto" (system preference), "force" (always dark), or "off" (always light)',
+    });
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Layer validation
 // ---------------------------------------------------------------------------
@@ -775,24 +889,27 @@ export function validateSpec(spec: unknown): ValidationResult {
   // - Chart specs have a 'mark' field (string or object with type property)
   // - Table specs have type: 'table'
   // - Graph specs have type: 'graph'
+  // - Sankey specs have type: 'sankey'
+  // - TileMap specs have type: 'tilemap'
   const hasLayer = 'layer' in obj && Array.isArray(obj.layer);
   const hasMark = 'mark' in obj;
   const isTable = obj.type === 'table';
   const isGraph = obj.type === 'graph';
   const isSankey = obj.type === 'sankey';
-  const isLayer = hasLayer && !isTable && !isGraph && !isSankey;
-  const isChart = hasMark && !hasLayer && !isTable && !isGraph && !isSankey;
+  const isTileMap = obj.type === 'tilemap';
+  const isLayer = hasLayer && !isTable && !isGraph && !isSankey && !isTileMap;
+  const isChart = hasMark && !hasLayer && !isTable && !isGraph && !isSankey && !isTileMap;
 
-  if (!isChart && !isTable && !isGraph && !isSankey && !isLayer) {
+  if (!isChart && !isTable && !isGraph && !isSankey && !isTileMap && !isLayer) {
     return {
       valid: false,
       errors: [
         {
           message:
-            'Spec error: spec must have a "mark" field for charts, a "layer" array for layered charts, or a "type" field for tables/graphs/sankey',
+            'Spec error: spec must have a "mark" field for charts, a "layer" array for layered charts, or a "type" field for tables/graphs/sankey/tilemap',
           path: 'mark',
           code: 'MISSING_FIELD',
-          suggestion: `Add a "mark" field for charts (e.g. mark: "bar"), a "layer" array for layered charts, or a "type" field for tables/graphs/sankey (type: "table", type: "graph", or type: "sankey"). Valid mark types: ${[...MARK_TYPES].join(', ')}`,
+          suggestion: `Add a "mark" field for charts (e.g. mark: "bar"), a "layer" array for layered charts, or a "type" field for tables/graphs/sankey/tilemap (type: "table", type: "graph", type: "sankey", or type: "tilemap"). Valid mark types: ${[...MARK_TYPES].join(', ')}`,
         },
       ],
       normalized: null,
@@ -837,6 +954,8 @@ export function validateSpec(spec: unknown): ValidationResult {
     validateGraphSpec(obj, errors);
   } else if (isSankey) {
     validateSankeySpec(obj, errors);
+  } else if (isTileMap) {
+    validateTileMapSpec(obj, errors);
   }
 
   if (errors.length > 0) {

package/src/index.ts

@@ -12,7 +12,14 @@
 // Main compile API
 // ---------------------------------------------------------------------------
 
-export { compileChart, compileGraph, compileLayer, compileSankey, compileTable } from './compile';
+export {
+  compileChart,
+  compileGraph,
+  compileLayer,
+  compileSankey,
+  compileTable,
+  compileTileMap,
+} from './compile';
 
 // ---------------------------------------------------------------------------
 // Animation resolution
@@ -37,6 +44,12 @@ export type {
 
 export type { NormalizedSankeySpec } from './sankey/types';
 
+// ---------------------------------------------------------------------------
+// TileMap compilation types
+// ---------------------------------------------------------------------------
+
+export type { NormalizedTileMapSpec } from './tilemap/types';
+
 // ---------------------------------------------------------------------------
 // Compiler pipeline (spec validation, normalization, generic compile)
 // ---------------------------------------------------------------------------
@@ -100,5 +113,7 @@ export type {
   SankeySpec,
   TableLayout,
   TableSpec,
+  TileMapLayout,
+  TileMapSpec,
   VizSpec,
 } from '@opendata-ai/openchart-core';

package/src/layout/axes/ticks.ts

@@ -5,7 +5,12 @@
  * not from the chart area. Density thinning lives in ./thinning.ts.
  */
 
-import type { AxisLabelDensity, AxisTick, MeasureTextFn } from '@opendata-ai/openchart-core';
+import type {
+  AxisLabelDensity,
+  AxisTick,
+  DataRow,
+  MeasureTextFn,
+} from '@opendata-ai/openchart-core';
 import {
   abbreviateNumber,
   buildD3Formatter,
@@ -221,6 +226,7 @@ export function categoricalTicks(
   fontSize?: number,
   fontWeight?: number,
   measureText?: MeasureTextFn,
+  subtitleContext?: { data: DataRow[]; fieldName: string; labelField: string },
 ): AxisTick[] {
   const scale = resolvedScale.scale as D3CategoricalScale;
   const domain: string[] = scale.domain();
@@ -275,6 +281,23 @@ export function categoricalTicks(
   }
   // vertical band scale (horizontal bar y-axis): always show all labels
 
+  let subtitleMap: Map<string, string> | undefined;
+  if (subtitleContext) {
+    const { data, fieldName, labelField } = subtitleContext;
+    if (data.length > 0) {
+      subtitleMap = new Map();
+      for (const row of data) {
+        const key = String(row[fieldName] ?? '');
+        if (!subtitleMap.has(key)) {
+          const val = row[labelField];
+          if (val != null) {
+            subtitleMap.set(key, String(val));
+          }
+        }
+      }
+    }
+  }
+
   const ticks = selectedValues.map((value: string) => {
     // Band scales: use the center of the band
     const bandScale = resolvedScale.type === 'band' ? (scale as ScaleBand<string>) : null;
@@ -282,11 +305,20 @@ export function categoricalTicks(
       ? (bandScale(value) ?? 0) + bandScale.bandwidth() / 2
       : ((scale(value) as number | undefined) ?? 0);
 
-    return {
+    const tick: AxisTick = {
       value,
       position: pos,
       label: value,
     };
+
+    if (subtitleMap) {
+      const subtitle = subtitleMap.get(value);
+      if (subtitle !== undefined) {
+        tick.subtitle = subtitle;
+      }
+    }
+
+    return tick;
   });
 
   return ticks;

package/src/layout/axes.ts

@@ -10,6 +10,8 @@ import type {
   AxisLabelDensity,
   AxisLayout,
   AxisTick,
+  DataRow,
+  Encoding,
   Gridline,
   LayoutStrategy,
   MeasureTextFn,
@@ -191,6 +193,21 @@ export interface AxesResult {
   y?: AxisLayout;
 }
 
+/** Optional data context for axis computation (enables labelField subtitles). */
+export interface AxesDataContext {
+  /** The data rows for subtitle lookup. */
+  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;
+}
+
 /**
  * Compute axis layouts with tick positions, labels, and axis lines.
  *
@@ -199,6 +216,7 @@ export interface AxesResult {
  * @param strategy - Responsive layout strategy.
  * @param theme - Resolved theme for styling.
  * @param measureText - Optional real text measurement from the adapter.
+ * @param dataContext - Optional data context for labelField subtitle support.
  */
 export function computeAxes(
   scales: ResolvedScales,
@@ -206,6 +224,7 @@ export function computeAxes(
   strategy: LayoutStrategy,
   theme: ResolvedTheme,
   measureText?: MeasureTextFn,
+  dataContext?: AxesDataContext,
 ): AxesResult {
   const result: AxesResult = {};
   const baseDensity = strategy.axisLabelDensity;
@@ -245,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';
@@ -347,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';
@@ -362,7 +381,21 @@ export function computeAxes(
     if (axisConfig?.values) {
       allTicks = resolveExplicitTicks(axisConfig.values, scales.y);
     } else if (!isContinuousY) {
-      allTicks = categoricalTicks(scales.y, yDensity, 'vertical');
+      const yFieldName = dataContext?.encoding.y?.field;
+      const yLabelField = axisConfig?.labelField;
+      allTicks = categoricalTicks(
+        scales.y,
+        yDensity,
+        'vertical',
+        undefined,
+        undefined,
+        undefined,
+        undefined,
+        undefined,
+        yFieldName && yLabelField && dataContext
+          ? { data: dataContext.data, fieldName: yFieldName, labelField: yLabelField }
+          : undefined,
+      );
     } else {
       allTicks = continuousTicks(scales.y, yDensity, yTargetCount);
     }

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 };
 
@@ -275,10 +349,26 @@ export function computeDimensions(
     ) {
       // Category labels on the left for bar/dot charts
       const yField = encoding.y.field;
+      const yLabelField = (encoding.y.axis as Record<string, unknown> | undefined)?.labelField as
+        | string
+        | undefined;
       let maxLabelWidth = 0;
       for (const row of spec.data) {
         const label = String(row[yField] ?? '');
-        const w = estimateTextWidth(label, theme.fonts.sizes.axisTick, theme.fonts.weights.normal);
+        let w = estimateTextWidth(label, theme.fonts.sizes.axisTick, theme.fonts.weights.normal);
+        // When labelField is set, add a gap and the subtitle width
+        if (yLabelField) {
+          const subtitle = String(row[yLabelField] ?? '');
+          if (subtitle) {
+            const gap = theme.fonts.sizes.axisTick * 0.6;
+            const subtitleWidth = estimateTextWidth(
+              subtitle,
+              theme.fonts.sizes.axisTick,
+              theme.fonts.weights.normal,
+            );
+            w += gap + subtitleWidth;
+          }
+        }
         if (w > maxLabelWidth) maxLabelWidth = w;
       }
       if (maxLabelWidth > 0) {
@@ -359,7 +449,7 @@ export function computeDimensions(
   }
 
   // Reserve legend space
-  if (legendLayout.entries.length > 0) {
+  if ('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;
@@ -379,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
@@ -407,7 +498,9 @@ export function computeDimensions(
       const gap = legendGap(width);
       margins.top =
         newTop +
-        (legendLayout.entries.length > 0 && legendLayout.position === 'top'
+        ('entries' in legendLayout &&
+        legendLayout.entries.length > 0 &&
+        legendLayout.position === 'top'
           ? legendLayout.bounds.height + gap
           : 0);
       margins.bottom = newBottom;

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: [],

package/src/sankey/compile-sankey.ts

@@ -312,7 +312,7 @@ export function compileSankey(spec: unknown, options: CompileOptions): SankeyLay
   );
 
   // Reserve legend space by shrinking the drawing area
-  const legendGap = legend.entries.length > 0 ? 4 : 0;
+  const legendGap = 'entries' in legend && legend.entries.length > 0 ? 4 : 0;
   const area: Rect = {
     x: fullArea.x,
     y: fullArea.y + legend.bounds.height + legendGap,