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

package/src/compiler/a11y-warnings.ts

@@ -1,110 +0,0 @@
-/**
- * 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

@@ -1,142 +0,0 @@
-/**
- * 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

@@ -1,47 +0,0 @@
-/**
- * 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

@@ -1,55 +0,0 @@
-/**
- * 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;
-}