@opendata-ai/openchart-engine 1.2.0

package/src/compiler/normalize.ts

@@ -0,0 +1,269 @@
+/**
+ * Spec normalization: fill in defaults and infer types.
+ *
+ * Takes a validated VizSpec and produces a NormalizedSpec where:
+ * - All optional fields have sensible defaults
+ * - Chrome strings are converted to ChromeText objects
+ * - Encoding types are inferred from data if not specified
+ * - Annotations have default styles
+ */
+
+import type {
+  Annotation,
+  ChartSpec,
+  Chrome,
+  ChromeText,
+  DataRow,
+  Encoding,
+  FieldType,
+  GraphSpec,
+  TableSpec,
+  VizSpec,
+} from '@opendata-ai/openchart-core';
+import { isChartSpec, isGraphSpec, isTableSpec } from '@opendata-ai/openchart-core';
+
+import type {
+  NormalizedChartSpec,
+  NormalizedChrome,
+  NormalizedGraphSpec,
+  NormalizedSpec,
+  NormalizedTableSpec,
+} from './types';
+
+// ---------------------------------------------------------------------------
+// Chrome normalization
+// ---------------------------------------------------------------------------
+
+/** Convert a string | ChromeText | undefined to ChromeText | undefined. */
+function normalizeChromeField(value: string | ChromeText | undefined): ChromeText | undefined {
+  if (value === undefined) return undefined;
+  if (typeof value === 'string') return { text: value };
+  return value;
+}
+
+/** Normalize all chrome fields from strings to ChromeText objects. */
+function normalizeChrome(chrome: Chrome | undefined): NormalizedChrome {
+  if (!chrome) return {};
+  return {
+    title: normalizeChromeField(chrome.title),
+    subtitle: normalizeChromeField(chrome.subtitle),
+    source: normalizeChromeField(chrome.source),
+    byline: normalizeChromeField(chrome.byline),
+    footer: normalizeChromeField(chrome.footer),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Type inference
+// ---------------------------------------------------------------------------
+
+/** Sample values from a data column and infer the field type. */
+function inferFieldType(data: DataRow[], field: string): FieldType {
+  // Sample up to 10 rows
+  const sampleSize = Math.min(10, data.length);
+  let numericCount = 0;
+  let dateCount = 0;
+  let totalNonNull = 0;
+
+  for (let i = 0; i < sampleSize; i++) {
+    const value = data[i][field];
+    if (value == null) continue;
+    totalNonNull++;
+
+    // Check numeric
+    if (typeof value === 'number' && Number.isFinite(value)) {
+      numericCount++;
+      continue;
+    }
+
+    // Check date-like strings
+    if (typeof value === 'string') {
+      // Try as number first
+      const num = Number(value);
+      if (!Number.isNaN(num) && Number.isFinite(num) && value.trim() !== '') {
+        numericCount++;
+        continue;
+      }
+
+      // Try as date
+      const date = new Date(value);
+      if (!Number.isNaN(date.getTime())) {
+        dateCount++;
+        continue;
+      }
+    }
+
+    if (value instanceof Date && !Number.isNaN(value.getTime())) {
+      dateCount++;
+    }
+  }
+
+  if (totalNonNull === 0) return 'nominal';
+
+  // If >80% of sampled values are dates, it's temporal
+  if (dateCount / totalNonNull > 0.8) return 'temporal';
+  // If >80% are numeric, it's quantitative
+  if (numericCount / totalNonNull > 0.8) return 'quantitative';
+  // Otherwise it's nominal
+  return 'nominal';
+}
+
+/** Infer types for encoding channels that don't have one specified. */
+function inferEncodingTypes(encoding: Encoding, data: DataRow[], warnings: string[]): Encoding {
+  const result = { ...encoding };
+
+  for (const channel of ['x', 'y', 'color', 'size', 'detail'] as const) {
+    const spec = result[channel];
+    if (!spec) continue;
+
+    if (!spec.type) {
+      const inferred = inferFieldType(data, spec.field);
+      result[channel] = { ...spec, type: inferred };
+      warnings.push(
+        `Inferred encoding.${channel}.type as "${inferred}" from data values for field "${spec.field}"`,
+      );
+    } else {
+      // Check for potential mismatches and warn
+      const actualType = inferFieldType(data, spec.field);
+      if (spec.type === 'nominal' && actualType === 'temporal') {
+        warnings.push(`Field "${spec.field}" looks temporal but was declared as nominal`);
+      }
+      if (spec.type === 'nominal' && actualType === 'quantitative') {
+        warnings.push(`Field "${spec.field}" looks quantitative but was declared as nominal`);
+      }
+    }
+  }
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Annotation normalization
+// ---------------------------------------------------------------------------
+
+/** Apply default styles to annotations that don't have them. */
+function normalizeAnnotations(annotations: Annotation[] | undefined): Annotation[] {
+  if (!annotations || annotations.length === 0) return [];
+
+  return annotations.map((ann) => {
+    switch (ann.type) {
+      case 'text':
+        return {
+          ...ann,
+          fontSize: ann.fontSize ?? 12,
+          fontWeight: ann.fontWeight ?? 400,
+          opacity: ann.opacity ?? 1,
+        };
+      case 'range':
+        return {
+          ...ann,
+          opacity: ann.opacity ?? 0.1,
+          fill: ann.fill ?? '#000000',
+        };
+      case 'refline':
+        return {
+          ...ann,
+          style: ann.style ?? 'dashed',
+          strokeWidth: ann.strokeWidth ?? 1,
+          stroke: ann.stroke ?? '#666666',
+          opacity: ann.opacity ?? 0.8,
+        };
+      default:
+        return ann;
+    }
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Spec-level normalization
+// ---------------------------------------------------------------------------
+
+function normalizeChartSpec(spec: ChartSpec, warnings: string[]): NormalizedChartSpec {
+  const encoding = inferEncodingTypes(spec.encoding, spec.data, warnings);
+
+  return {
+    type: spec.type,
+    data: spec.data,
+    encoding,
+    chrome: normalizeChrome(spec.chrome),
+    annotations: normalizeAnnotations(spec.annotations),
+    labels: {
+      density: spec.labels?.density ?? 'auto',
+      format: spec.labels?.format ?? '',
+      offsets: spec.labels?.offsets,
+    },
+    legend: spec.legend,
+    responsive: spec.responsive ?? true,
+    theme: spec.theme ?? {},
+    darkMode: spec.darkMode ?? 'off',
+  };
+}
+
+function normalizeTableSpec(spec: TableSpec, _warnings: string[]): NormalizedTableSpec {
+  return {
+    type: 'table',
+    data: spec.data,
+    columns: spec.columns,
+    rowKey: spec.rowKey,
+    chrome: normalizeChrome(spec.chrome),
+    theme: spec.theme ?? {},
+    darkMode: spec.darkMode ?? 'off',
+    search: spec.search ?? false,
+    pagination: spec.pagination ?? false,
+    stickyFirstColumn: spec.stickyFirstColumn ?? false,
+    compact: spec.compact ?? false,
+    responsive: spec.responsive ?? true,
+  };
+}
+
+function normalizeGraphSpec(spec: GraphSpec, _warnings: string[]): NormalizedGraphSpec {
+  // Default layout with chargeStrength and linkDistance
+  const defaultLayout = {
+    type: 'force' as const,
+    chargeStrength: -300,
+    linkDistance: 30,
+  };
+  const layout = spec.layout
+    ? {
+        ...defaultLayout,
+        ...spec.layout,
+      }
+    : defaultLayout;
+
+  return {
+    type: 'graph',
+    nodes: spec.nodes,
+    edges: spec.edges,
+    encoding: spec.encoding ?? {},
+    layout,
+    chrome: normalizeChrome(spec.chrome),
+    annotations: normalizeAnnotations(spec.annotations),
+    theme: spec.theme ?? {},
+    darkMode: spec.darkMode ?? 'off',
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Normalize a validated VizSpec, filling in all defaults.
+ *
+ * @param spec - A validated VizSpec (must pass validateSpec first).
+ * @param warnings - Mutable array to collect non-fatal warnings.
+ * @returns A NormalizedSpec with all optionals filled.
+ */
+export function normalizeSpec(spec: VizSpec, warnings: string[] = []): NormalizedSpec {
+  if (isChartSpec(spec)) {
+    return normalizeChartSpec(spec, warnings);
+  }
+  if (isTableSpec(spec)) {
+    return normalizeTableSpec(spec, warnings);
+  }
+  if (isGraphSpec(spec)) {
+    return normalizeGraphSpec(spec, warnings);
+  }
+  // Should never happen after validation
+  throw new Error(`Unknown spec type: ${(spec as Record<string, unknown>).type}`);
+}

package/src/compiler/types.ts

@@ -0,0 +1,148 @@
+/**
+ * Internal engine types for the compilation pipeline.
+ *
+ * NormalizedSpec is the engine's internal representation where all optionals
+ * have been filled with defaults. It's intentionally NOT in the core package
+ * since it's an engine implementation detail, not a public contract.
+ */
+
+import type {
+  AggregateOp,
+  Annotation,
+  AxisConfig,
+  ChartType,
+  ChromeText,
+  ColumnConfig,
+  DarkMode,
+  DataRow,
+  Encoding,
+  FieldType,
+  GraphEncoding,
+  GraphLayoutConfig,
+  GraphSpec,
+  LabelConfig,
+  LegendConfig,
+  ScaleConfig,
+  ThemeConfig,
+} from '@opendata-ai/openchart-core';
+
+// ---------------------------------------------------------------------------
+// NormalizedChrome: all fields are ChromeText objects (not plain strings)
+// ---------------------------------------------------------------------------
+
+/** Chrome with all string values normalized to ChromeText objects. */
+export interface NormalizedChrome {
+  title?: ChromeText;
+  subtitle?: ChromeText;
+  source?: ChromeText;
+  byline?: ChromeText;
+  footer?: ChromeText;
+}
+
+// ---------------------------------------------------------------------------
+// NormalizedEncoding: all encoding channels have their type filled in
+// ---------------------------------------------------------------------------
+
+/** An encoding channel with a guaranteed type (inferred if not provided). */
+export interface NormalizedEncodingChannel {
+  field: string;
+  type: FieldType;
+  aggregate?: AggregateOp;
+  axis?: AxisConfig;
+  scale?: ScaleConfig;
+}
+
+// ---------------------------------------------------------------------------
+// NormalizedSpec types
+// ---------------------------------------------------------------------------
+
+/** A ChartSpec with all optional fields filled with sensible defaults. */
+export interface NormalizedChartSpec {
+  type: ChartType;
+  data: DataRow[];
+  encoding: Encoding;
+  chrome: NormalizedChrome;
+  annotations: Annotation[];
+  /** Normalized label configuration with defaults applied. density and format are always set; offsets stays optional. */
+  labels: Required<Pick<LabelConfig, 'density' | 'format'>> & Pick<LabelConfig, 'offsets'>;
+  /** Legend configuration (position override). */
+  legend?: LegendConfig;
+  responsive: boolean;
+  theme: ThemeConfig;
+  darkMode: DarkMode;
+}
+
+/** A TableSpec with all optional fields filled with sensible defaults. */
+export interface NormalizedTableSpec {
+  type: 'table';
+  data: DataRow[];
+  columns: ColumnConfig[];
+  rowKey?: string;
+  chrome: NormalizedChrome;
+  theme: ThemeConfig;
+  darkMode: DarkMode;
+  search: boolean;
+  pagination: boolean | { pageSize: number };
+  stickyFirstColumn: boolean;
+  compact: boolean;
+  responsive: boolean;
+}
+
+/** A GraphSpec with all optional fields filled with sensible defaults. */
+export interface NormalizedGraphSpec {
+  type: 'graph';
+  nodes: GraphSpec['nodes'];
+  edges: GraphSpec['edges'];
+  encoding: GraphEncoding;
+  layout: GraphLayoutConfig;
+  chrome: NormalizedChrome;
+  annotations: Annotation[];
+  theme: ThemeConfig;
+  darkMode: DarkMode;
+}
+
+/** Discriminated union of all normalized spec types. */
+export type NormalizedSpec = NormalizedChartSpec | NormalizedTableSpec | NormalizedGraphSpec;
+
+// ---------------------------------------------------------------------------
+// Validation types
+// ---------------------------------------------------------------------------
+
+/** Machine-readable error code for programmatic handling. */
+export type ValidationErrorCode =
+  | 'MISSING_FIELD'
+  | 'INVALID_TYPE'
+  | 'INVALID_VALUE'
+  | 'ENCODING_MISMATCH'
+  | 'DATA_FIELD_MISSING'
+  | 'EMPTY_DATA';
+
+/** A single validation error with context. */
+export interface ValidationError {
+  /** Error message describing what's wrong. */
+  message: string;
+  /** The path to the problematic value (e.g. "encoding.x.field"). */
+  path?: string;
+  /** Machine-readable error code for programmatic handling. */
+  code: ValidationErrorCode;
+  /** Actionable suggestion for fixing the error. */
+  suggestion: string;
+}
+
+/** Result of spec validation. */
+export interface ValidationResult {
+  /** Whether the spec is valid. */
+  valid: boolean;
+  /** Validation errors (empty if valid). */
+  errors: ValidationError[];
+  /** The validated spec cast to VizSpec, or null if invalid. */
+  normalized: import('@opendata-ai/openchart-core').VizSpec | null;
+}
+
+/** Result of the compile pipeline (validate + normalize). */
+export interface CompileResult {
+  /** The normalized spec with all defaults applied. */
+  spec: NormalizedSpec;
+  /** Non-fatal warnings (e.g. type mismatches that were auto-corrected). */
+  warnings: string[];
+}