@opendata-ai/openchart-engine 8.0.0-rc.2 → 8.0.0-rc.20

package/src/compiler/sparkline-defaults.ts

@@ -1,138 +0,0 @@
-/**
- * Sparkline default resolution.
- *
- * When `display: 'sparkline'` is set on a chart spec, the engine fills in
- * "smart" defaults so a minimal spec (mark + data + encoding) renders the
- * polished mock-quality output without manual color, gradient, or endpoint
- * configuration. Every default backs off when the user has set the
- * corresponding field explicitly.
- *
- * Two public helpers:
- * - {@link computeTrend} reads a value series and decides up/down/neutral
- *   using a least-squares slope with a relative deadband. Naive
- *   `last - first` would mislabel noisy series; this is more honest.
- * - {@link resolveSparklineFill} picks the trend color, respecting the
- *   precedence ladder: explicit `markDef.fill` > `encoding.color` >
- *   theme override > sparkline trend default.
- */
-
-import type { DataRow, GradientDef, MarkDef, ResolvedTheme } from '@opendata-ai/openchart-core';
-
-/** Trend classification for a single value series. */
-export type Trend = 'up' | 'down' | 'neutral';
-
-/**
- * Relative slope below this magnitude reads as "no meaningful trend" and
- * falls into the neutral bucket. 0.0005 = 0.05% of the series mean per step,
- * which means a 20-point series needs roughly a 1% net change to register
- * as a real trend. Tuned so financial sparklines (which often show 2-10%
- * swings) reliably pick up trend color, while heavy noise around a flat
- * mean still classifies as neutral.
- */
-const TREND_DEADBAND = 0.0005;
-
-/**
- * Decide whether a numeric series trends up, down, or neutral.
- *
- * Uses ordinary least-squares slope across the series, normalized by the
- * absolute mean so the deadband applies consistently to series of any
- * magnitude. Non-finite values are dropped before fitting; series with
- * fewer than two finite points return 'neutral'.
- */
-export function computeTrend(values: readonly number[]): Trend {
-  const finite: number[] = [];
-  for (const v of values) {
-    if (Number.isFinite(v)) finite.push(v);
-  }
-  if (finite.length < 2) return 'neutral';
-
-  const n = finite.length;
-  let sumX = 0;
-  let sumY = 0;
-  for (let i = 0; i < n; i++) {
-    sumX += i;
-    sumY += finite[i];
-  }
-  const meanX = sumX / n;
-  const meanY = sumY / n;
-
-  let num = 0;
-  let den = 0;
-  for (let i = 0; i < n; i++) {
-    const dx = i - meanX;
-    num += dx * (finite[i] - meanY);
-    den += dx * dx;
-  }
-  if (den === 0) return 'neutral';
-
-  const slope = num / den;
-  const scale = Math.abs(meanY) || 1;
-  const relSlope = slope / scale;
-  if (Math.abs(relSlope) < TREND_DEADBAND) return 'neutral';
-  return relSlope > 0 ? 'up' : 'down';
-}
-
-/** Map a trend classification to a color from the resolved theme. */
-export function trendColor(trend: Trend, theme: ResolvedTheme): string {
-  if (trend === 'up') return theme.colors.positive;
-  if (trend === 'down') return theme.colors.negative;
-  return theme.colors.categorical[0];
-}
-
-/**
- * Pull the y-channel values out of a data array and classify the trend.
- * Returns 'neutral' if the field is missing or the series is too short.
- */
-export function computeTrendFromData(data: readonly DataRow[], yField: string | undefined): Trend {
-  if (!yField) return 'neutral';
-  const values: number[] = [];
-  for (const row of data) {
-    const v = Number(row[yField]);
-    if (Number.isFinite(v)) values.push(v);
-  }
-  return computeTrend(values);
-}
-
-/**
- * Channel-by-channel report of whether a spec's color is "user-explicit"
- * for that channel — the trend default backs off only for the channels
- * the user has set.
- *
- * Precedence ladder (most explicit first):
- * 1. `markDef.fill` / `markDef.stroke` set on the spec — channel-specific
- * 2. `encoding.color` field encoding (the data drives color, not trend)
- *    backs off both channels because the color scale produces both
- * 3. Sparkline trend default (returned when both flags are false)
- */
-export function hasExplicitColor(
-  markDef: MarkDef | undefined,
-  encodingHasColor: boolean,
-): { fill: boolean; stroke: boolean } {
-  if (encodingHasColor) return { fill: true, stroke: true };
-  return {
-    fill: markDef?.fill !== undefined,
-    stroke: markDef?.stroke !== undefined,
-  };
-}
-
-/**
- * Build the default area gradient for a sparkline area mark. Uses the
- * trend-derived base color and fades top→bottom from 35% to 0% opacity.
- *
- * Coordinate system is normalized [0,1] relative to the mark bounding box,
- * matching the existing `LinearGradient` shape used by user-authored
- * gradients (see `examples/src/sparkline.stories.tsx` for prior art).
- */
-export function buildSparklineAreaGradient(baseColor: string): GradientDef {
-  return {
-    gradient: 'linear',
-    x1: 0,
-    y1: 0,
-    x2: 0,
-    y2: 1,
-    stops: [
-      { offset: 0, color: baseColor, opacity: 0.35 },
-      { offset: 1, color: baseColor, opacity: 0 },
-    ],
-  };
-}

package/src/compiler/types.ts

@@ -1,241 +0,0 @@
-/**
- * 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,
-  AnimationSpec,
-  Annotation,
-  AxisConfig,
-  ChromeText,
-  ColumnConfig,
-  DarkMode,
-  DataRow,
-  Display,
-  Encoding,
-  FieldType,
-  GraphEncoding,
-  GraphLayoutConfig,
-  GraphSpec,
-  LabelConfig,
-  LegendConfig,
-  MarkDef,
-  MarkType,
-  NodeOverride,
-  ScaleConfig,
-  ThemeConfig,
-} from '@opendata-ai/openchart-core';
-import type { NormalizedBarListSpec } from '../barlist/types';
-import type { NormalizedMapSpec } from '../geo/types';
-import type { NormalizedSankeySpec } from '../sankey/types';
-import type { NormalizedTileMapSpec } from '../tilemap/types';
-
-// ---------------------------------------------------------------------------
-// NormalizedChrome: all fields are ChromeText objects (not plain strings)
-// ---------------------------------------------------------------------------
-
-/** Chrome with all string values normalized to ChromeText objects. */
-export interface NormalizedChrome {
-  eyebrow?: ChromeText;
-  title?: ChromeText;
-  subtitle?: ChromeText;
-  source?: ChromeText;
-  byline?: ChromeText;
-  footer?: ChromeText;
-  brand?: 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
-// ---------------------------------------------------------------------------
-
-/**
- * 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 `endpointLabels`. */
-  endpointLabels: 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). */
-  markType: MarkType;
-  /** Resolved mark definition with defaults filled in. */
-  markDef: MarkDef;
-  data: DataRow[];
-  encoding: Encoding;
-  chrome: NormalizedChrome;
-  /** Optional KPI metric cells, passed through unchanged. */
-  metrics?: import('@opendata-ai/openchart-core').Metric[];
-  /**
-   * Searchable series highlight config. Present only when `seriesSearch` is
-   * enabled AND the spec has a categorical color encoding to search over.
-   */
-  seriesSearch?: import('@opendata-ai/openchart-core').SeriesSearchConfig;
-  /** Resolved "you draw it" config with defaults filled in. Present only when `youDrawIt` is enabled. */
-  youDrawIt?: import('@opendata-ai/openchart-core').YouDrawItConfig;
-  annotations: Annotation[];
-  /** Normalized label configuration with defaults applied. density, format, and prefix are always set; offsets and color stay optional. */
-  labels: Required<Pick<LabelConfig, 'density' | 'format' | 'prefix'>> &
-    Pick<LabelConfig, 'offsets' | 'color' | 'fontSize' | 'suffix'>;
-  /** Legend configuration (position override). */
-  legend?: LegendConfig;
-  /** Right-side endpoint labels column config (multi-series line/area only). */
-  endpointLabels?: boolean | import('@opendata-ai/openchart-core').EndpointLabelsConfig;
-  responsive: boolean;
-  /** Whether auto-thinning of annotations at narrow widths is enabled. Resolved from `responsive.autoThin`. */
-  autoThin: boolean;
-  theme: ThemeConfig;
-  darkMode: DarkMode;
-  /** Whether the tryOpenData.ai watermark is enabled. */
-  watermark: boolean;
-  /** Series names to hide from rendering. */
-  hiddenSeries: string[];
-  /** Per-series visual style overrides. */
-  seriesStyles: Record<string, import('@opendata-ai/openchart-core').SeriesStyle>;
-  /** Author accessibility overrides (alt-text description, aria-hidden opt-out). */
-  a11y?: import('@opendata-ai/openchart-core').A11yConfig;
-  /** Display mode controlling chrome/axes/legend stripping. Defaults to `'full'`. */
-  display: Display;
-  /** Resolve configuration for independent/shared scales in faceted charts. */
-  resolve?: import('@opendata-ai/openchart-core').ResolveConfig;
-  /**
-   * 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;
-  /**
-   * Series values to visually emphasize. Non-highlighted series are muted to
-   * a neutral gray. Normalized from `encoding.color.highlight` (always an
-   * array; empty when no highlight is active).
-   */
-  highlight: string[];
-}
-
-/** 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;
-  watermark: boolean;
-  search: boolean;
-  pagination: boolean | { pageSize: number };
-  stickyFirstColumn: boolean;
-  compact: boolean;
-  responsive: boolean;
-  animation?: AnimationSpec;
-}
-
-/** 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;
-  nodeOverrides?: Record<string, NodeOverride>;
-  chrome: NormalizedChrome;
-  annotations: Annotation[];
-  theme: ThemeConfig;
-  darkMode: DarkMode;
-  watermark: boolean;
-}
-
-/** Discriminated union of all normalized spec types. */
-export type NormalizedSpec =
-  | NormalizedChartSpec
-  | NormalizedTableSpec
-  | NormalizedGraphSpec
-  | NormalizedSankeySpec
-  | NormalizedTileMapSpec
-  | NormalizedMapSpec
-  | NormalizedBarListSpec;
-
-// ---------------------------------------------------------------------------
-// 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[];
-}