@opendata-ai/openchart-engine 8.0.0-rc.12 → 8.0.0-rc.3

package/src/compiler/a11y-warnings.ts

@@ -0,0 +1,110 @@
+/**
+ * Development-time WCAG contrast diagnostics.
+ *
+ * Checks the resolved series colors and theme text tokens against WCAG 2.1
+ * thresholds and returns advisory warning strings:
+ *
+ * - 1.4.11 (non-text contrast, 3:1): adjacent stacked/grouped series pairs
+ *   and each series color against the chart background.
+ * - 1.4.3 (text contrast, 4.5:1): theme text tokens against the background.
+ *
+ * Purely advisory: this module never throws and produces nothing unless the
+ * host opts in via `compileChart(spec, { dev: true })`. The gate is a compile
+ * option, NOT an environment sniff, because the engine is isomorphic and
+ * `process.env` checks would leak a Node assumption into browser bundles.
+ */
+
+import type { MarkType, ResolvedTheme } from '@opendata-ai/openchart-core';
+import { contrastRatio, findAccessibleColor, isOpaqueColor } from '@opendata-ai/openchart-core';
+import type { ScaleOrdinal } from 'd3-scale';
+import type { ResolvedScales } from '../layout/scales';
+
+/** WCAG 1.4.11 minimum for graphical objects against adjacent colors. */
+const GRAPHIC_MIN = 3;
+/** WCAG 1.4.3 minimum for normal-size text. */
+const TEXT_MIN = 4.5;
+
+/** Mark types whose series render as adjacent filled regions when stacked/grouped. */
+const ADJACENT_FILL_MARKS: ReadonlySet<MarkType> = new Set(['bar', 'area', 'arc', 'waffle']);
+
+const fmt = (ratio: number): string => `${ratio.toFixed(2)}:1`;
+
+/**
+ * Collect WCAG contrast warnings for a compiled chart.
+ *
+ * @param scales - Resolved scales (series colors come from the color scale).
+ * @param markType - Resolved mark type (adjacency only applies to filled marks).
+ * @param theme - Resolved theme (background and text tokens).
+ * @returns Advisory warning strings; empty when everything passes.
+ */
+export function collectContrastWarnings(
+  scales: ResolvedScales,
+  markType: MarkType,
+  theme: ResolvedTheme,
+): string[] {
+  const warnings: string[] = [];
+
+  // The default background is 'transparent' (the host page shows through),
+  // which makes background-relative ratios meaningless at compile time.
+  // Adjacent-series checks below don't need the background and always run.
+  const bg = theme.colors.background;
+  const bgIsCheckable = isOpaqueColor(bg);
+
+  // Resolved per-series colors in domain (render) order. Sequential color
+  // scales encode magnitude, not series identity; adjacency checks there
+  // would flag every neighboring ramp stop, so only categorical scales apply.
+  const series: Array<{ key: string; color: string }> = [];
+  if (scales.color && scales.color.type !== 'sequential') {
+    const ordinal = scales.color.scale as unknown as ScaleOrdinal<string, string>;
+    for (const key of ordinal.domain()) {
+      series.push({ key, color: ordinal(key) });
+    }
+  }
+
+  // Adjacent series pairs (stacked segments / grouped neighbors render in
+  // domain order, so consecutive series sit next to each other).
+  if (ADJACENT_FILL_MARKS.has(markType)) {
+    for (let i = 0; i < series.length - 1; i++) {
+      const a = series[i];
+      const b = series[i + 1];
+      const ratio = contrastRatio(a.color, b.color);
+      if (ratio < GRAPHIC_MIN) {
+        const suggestion = findAccessibleColor(b.color, a.color, GRAPHIC_MIN);
+        warnings.push(
+          `[openchart a11y] Adjacent series "${a.key}" (${a.color}) and "${b.key}" (${b.color}) have ${fmt(ratio)} contrast, below the 3:1 WCAG 1.4.11 minimum for graphical objects. Nearest passing color for "${b.key}": ${suggestion}.`,
+        );
+      }
+    }
+  }
+
+  if (bgIsCheckable) {
+    // Each series against the chart background.
+    for (const s of series) {
+      const ratio = contrastRatio(s.color, bg);
+      if (ratio < GRAPHIC_MIN) {
+        const suggestion = findAccessibleColor(s.color, bg, GRAPHIC_MIN);
+        warnings.push(
+          `[openchart a11y] Series "${s.key}" (${s.color}) has ${fmt(ratio)} contrast against the background (${bg}), below the 3:1 WCAG 1.4.11 minimum. Nearest passing color: ${suggestion}.`,
+        );
+      }
+    }
+
+    // Text tokens at the 4.5:1 body-text threshold. Gridline/axis rules are
+    // exempt: they are decorative per WCAG 1.4.11.
+    const textTokens: Array<{ name: string; color: string }> = [
+      { name: 'theme.colors.text', color: theme.colors.text },
+      { name: 'theme.colors.annotationText', color: theme.colors.annotationText },
+    ];
+    for (const token of textTokens) {
+      const ratio = contrastRatio(token.color, bg);
+      if (ratio < TEXT_MIN) {
+        const suggestion = findAccessibleColor(token.color, bg, TEXT_MIN);
+        warnings.push(
+          `[openchart a11y] ${token.name} (${token.color}) has ${fmt(ratio)} contrast against the background (${bg}), below the 4.5:1 WCAG 1.4.3 minimum for text. Nearest passing color: ${suggestion}.`,
+        );
+      }
+    }
+  }
+
+  return warnings;
+}

package/src/compiler/animation.ts

@@ -0,0 +1,142 @@
+/**
+ * Animation resolver: normalizes AnimationSpec into fully resolved config.
+ *
+ * Handles the shorthand forms:
+ * - true -> all three phases with defaults
+ * - { enter: { duration: 800 } } -> merge with defaults per phase
+ * - false/undefined -> undefined (no animation)
+ *
+ * Each phase resolves independently:
+ * - true/config-object -> resolved phase merged onto that phase's defaults
+ * - false -> phase absent
+ * - undefined -> phase present with defaults (animation: {} behaves like true)
+ *
+ * Returns undefined only when ALL phases resolve absent.
+ */
+
+import type {
+  AnimationConfig,
+  AnimationPhaseConfig,
+  AnimationSpec,
+  AnimationStagger,
+  ResolvedAnimation,
+  ResolvedAnimationPhase,
+} from '@opendata-ai/openchart-core';
+
+/** Default values for entrance animation. */
+export const ENTER_DEFAULTS: ResolvedAnimationPhase = {
+  duration: 500,
+  ease: 'smooth',
+  staggerDelay: 80,
+  staggerOrder: 'index',
+};
+
+/** Default values for update (data transition) animation. */
+export const UPDATE_DEFAULTS: ResolvedAnimationPhase = {
+  duration: 500,
+  ease: 'smooth',
+  staggerDelay: 0,
+  staggerOrder: 'index',
+};
+
+/** Default values for exit animation. */
+export const EXIT_DEFAULTS: ResolvedAnimationPhase = {
+  duration: 300,
+  ease: 'smooth',
+  staggerDelay: 0,
+  staggerOrder: 'index',
+};
+
+/** Default annotation delay in ms after marks finish. */
+const DEFAULT_ANNOTATION_DELAY = 200;
+
+/** Maximum total stagger time in ms. Prevents 200-bar charts from taking 6s. */
+const MAX_TOTAL_STAGGER_MS = 2000;
+
+/**
+ * Resolve an AnimationSpec into a fully resolved config with all defaults filled.
+ * Returns undefined if animation is disabled (false or omitted).
+ */
+export function resolveAnimation(spec: AnimationSpec | undefined): ResolvedAnimation | undefined {
+  if (spec === undefined || spec === false) return undefined;
+
+  // true -> all three phases with defaults
+  if (spec === true) {
+    return {
+      enter: { ...ENTER_DEFAULTS },
+      update: { ...UPDATE_DEFAULTS },
+      exit: { ...EXIT_DEFAULTS },
+      annotationDelay: DEFAULT_ANNOTATION_DELAY,
+    };
+  }
+
+  // AnimationConfig object
+  const config = spec as AnimationConfig;
+
+  const enter = resolvePhase(config.enter, ENTER_DEFAULTS);
+  const update = resolvePhase(config.update, UPDATE_DEFAULTS);
+  const exit = resolvePhase(config.exit, EXIT_DEFAULTS);
+
+  // Return undefined only when ALL phases resolve absent
+  if (!enter && !update && !exit) return undefined;
+
+  return {
+    enter: enter ?? undefined,
+    update: update ?? undefined,
+    exit: exit ?? undefined,
+    annotationDelay: config.annotationDelay ?? DEFAULT_ANNOTATION_DELAY,
+  };
+}
+
+/**
+ * Clamp stagger delay so total stagger time doesn't exceed MAX_TOTAL_STAGGER_MS.
+ */
+export function clampStaggerDelay(delay: number, elementCount: number): number {
+  if (elementCount <= 1) return 0;
+  return Math.min(delay, MAX_TOTAL_STAGGER_MS / elementCount);
+}
+
+/**
+ * Resolve a single animation phase.
+ * - false -> null (phase absent)
+ * - undefined -> phase present with defaults
+ * - true -> phase present with defaults
+ * - config object -> merge with defaults
+ */
+function resolvePhase(
+  phase: AnimationPhaseConfig | boolean | undefined,
+  defaults: ResolvedAnimationPhase,
+): ResolvedAnimationPhase | null {
+  if (phase === false) return null;
+
+  if (phase === undefined || phase === true) {
+    return { ...defaults };
+  }
+
+  const cfg = phase as AnimationPhaseConfig;
+  const stagger = resolveStagger(cfg.stagger, defaults);
+
+  return {
+    duration: cfg.duration ?? defaults.duration,
+    ease: cfg.ease ?? defaults.ease,
+    staggerDelay: stagger.delay,
+    staggerOrder: stagger.order,
+  };
+}
+
+function resolveStagger(
+  stagger: AnimationStagger | boolean | undefined,
+  defaults: ResolvedAnimationPhase,
+): {
+  delay: number;
+  order: 'index' | 'value' | 'reverse';
+} {
+  if (stagger === false) return { delay: 0, order: 'index' };
+  if (stagger === undefined || stagger === true) {
+    return { delay: defaults.staggerDelay, order: defaults.staggerOrder };
+  }
+  return {
+    delay: stagger.delay ?? defaults.staggerDelay,
+    order: stagger.order ?? defaults.staggerOrder,
+  };
+}

package/src/compiler/index.ts

@@ -0,0 +1,47 @@
+/**
+ * Spec compiler: validate -> normalize pipeline.
+ *
+ * This is the first stage of the engine: take raw user input (possibly JSON
+ * from an API or Claude), validate it, fill in defaults, and produce a
+ * NormalizedSpec that the rest of the engine can work with safely.
+ */
+
+import { normalizeSpec } from './normalize';
+import type { CompileResult } from './types';
+import { validateSpec } from './validate';
+
+/**
+ * Compile a raw spec through the validate -> normalize pipeline.
+ *
+ * @param spec - Raw spec input (unknown type, could be anything).
+ * @returns CompileResult with the normalized spec and any warnings.
+ * @throws Error if the spec is invalid.
+ */
+export function compile(spec: unknown): CompileResult {
+  const validation = validateSpec(spec);
+
+  if (!validation.valid || !validation.normalized) {
+    const errorMessages = validation.errors.map((e) => e.message).join('\n');
+    throw new Error(`Invalid spec:\n${errorMessages}`);
+  }
+
+  const warnings: string[] = [];
+  const normalized = normalizeSpec(validation.normalized, warnings);
+
+  return { spec: normalized, warnings };
+}
+
+export { flattenLayers, normalizeSpec } from './normalize';
+export type {
+  CompileResult,
+  NormalizedChartSpec,
+  NormalizedChrome,
+  NormalizedGraphSpec,
+  NormalizedSpec,
+  NormalizedTableSpec,
+  ValidationError,
+  ValidationErrorCode,
+  ValidationResult,
+} from './types';
+// Re-export everything
+export { validateSpec } from './validate';

package/src/compiler/keys.ts

@@ -0,0 +1,55 @@
+/**
+ * Mark key utilities for data-update transitions.
+ *
+ * Keys uniquely identify marks across data updates so the renderer can
+ * match old marks to new marks and animate the difference. Each chart
+ * type stamps keys during its compute phase; these helpers provide the
+ * shared serialization and deduplication logic.
+ */
+
+/** Sentinel string for null/undefined values. Uses a Unicode symbol
+ *  that won't collide with real data values. */
+const NULL_KEY = '∅';
+
+/**
+ * Serialize a datum value into a stable key fragment.
+ * - Date -> epoch ms string (avoids locale-dependent Date.toString)
+ * - number/string/boolean -> String(v)
+ * - null/undefined -> null sentinel
+ */
+export function serializeKeyValue(v: unknown): string {
+  if (v === null || v === undefined) return NULL_KEY;
+  if (v instanceof Date) return String(v.getTime());
+  return String(v);
+}
+
+/**
+ * Append occurrence suffixes to duplicate keys, in order.
+ *
+ * Only keys that appear more than once get suffixed. Unique keys pass
+ * through unchanged so keys remain human-readable when possible.
+ * Uses U+2E31 (word separator middle dot) as separator - XML-safe and
+ * unlikely to appear in real data values.
+ */
+const KEY_DEDUP_SEP = '⸱';
+
+export function dedupeKeys(keys: string[]): string[] {
+  const counts = new Map<string, number>();
+  for (const k of keys) {
+    counts.set(k, (counts.get(k) ?? 0) + 1);
+  }
+
+  const seen = new Map<string, number>();
+  const result: string[] = [];
+  for (const k of keys) {
+    if (counts.get(k)! > 1) {
+      const idx = seen.get(k) ?? 0;
+      result.push(`${k}${KEY_DEDUP_SEP}${idx}`);
+      seen.set(k, idx + 1);
+    } else {
+      result.push(k);
+    }
+  }
+
+  return result;
+}