@opendata-ai/openchart-core 2.0.0

package/src/theme/__tests__/dark-mode.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, it } from 'vitest';
+import { contrastRatio } from '../../colors/contrast';
+import { adaptColorForDarkMode, adaptTheme } from '../dark-mode';
+import { resolveTheme } from '../resolve';
+
+describe('adaptColorForDarkMode', () => {
+  const lightBg = '#ffffff';
+  const darkBg = '#1a1a2e';
+
+  it('adapted color has similar contrast on dark bg as original on light bg', () => {
+    const original = '#1b7fa3'; // teal from palette
+    const adapted = adaptColorForDarkMode(original, lightBg, darkBg);
+
+    const originalRatio = contrastRatio(original, lightBg);
+    const adaptedRatio = contrastRatio(adapted, darkBg);
+
+    // Should be within 30% of the original ratio
+    const tolerance = originalRatio * 0.3;
+    expect(Math.abs(adaptedRatio - originalRatio)).toBeLessThan(tolerance);
+  });
+
+  it('returns a valid hex color', () => {
+    const result = adaptColorForDarkMode('#e15759', lightBg, darkBg);
+    expect(result).toMatch(/^#[0-9a-f]{6}$/i);
+  });
+
+  it('handles pure black gracefully', () => {
+    const result = adaptColorForDarkMode('#000000', lightBg, darkBg);
+    expect(result).toMatch(/^#[0-9a-f]{6}$/i);
+  });
+});
+
+describe('adaptTheme', () => {
+  it('sets isDark to true', () => {
+    const light = resolveTheme();
+    const dark = adaptTheme(light);
+    expect(dark.isDark).toBe(true);
+  });
+
+  it('swaps to dark background', () => {
+    const light = resolveTheme();
+    const dark = adaptTheme(light);
+    expect(dark.colors.background).toBe('#1a1a2e');
+  });
+
+  it('updates text color for dark mode', () => {
+    const light = resolveTheme();
+    const dark = adaptTheme(light);
+    expect(dark.colors.text).not.toBe(light.colors.text);
+    // Dark text should be light
+    const ratio = contrastRatio(dark.colors.text, dark.colors.background);
+    expect(ratio).toBeGreaterThan(4);
+  });
+
+  it('adapts categorical palette colors', () => {
+    const light = resolveTheme();
+    const dark = adaptTheme(light);
+    // Colors should be different (adjusted for dark bg)
+    expect(dark.colors.categorical).not.toEqual(light.colors.categorical);
+    expect(dark.colors.categorical).toHaveLength(light.colors.categorical.length);
+  });
+
+  it('updates chrome text colors', () => {
+    const light = resolveTheme();
+    const dark = adaptTheme(light);
+    expect(dark.chrome.title.color).not.toBe(light.chrome.title.color);
+  });
+});

package/src/theme/__tests__/defaults.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it } from 'vitest';
+import { contrastRatio } from '../../colors/contrast';
+import { DEFAULT_THEME } from '../defaults';
+
+describe('DEFAULT_THEME', () => {
+  it('has all required top-level fields', () => {
+    expect(DEFAULT_THEME.colors).toBeDefined();
+    expect(DEFAULT_THEME.fonts).toBeDefined();
+    expect(DEFAULT_THEME.spacing).toBeDefined();
+    expect(DEFAULT_THEME.borderRadius).toBeDefined();
+    expect(DEFAULT_THEME.chrome).toBeDefined();
+  });
+
+  it('uses Inter as primary font', () => {
+    expect(DEFAULT_THEME.fonts.family).toContain('Inter');
+  });
+
+  it('title is 22px bold', () => {
+    expect(DEFAULT_THEME.chrome.title.fontSize).toBe(22);
+    expect(DEFAULT_THEME.chrome.title.fontWeight).toBe(700);
+  });
+
+  it('subtitle is 15px normal weight', () => {
+    expect(DEFAULT_THEME.chrome.subtitle.fontSize).toBe(15);
+    expect(DEFAULT_THEME.chrome.subtitle.fontWeight).toBe(400);
+  });
+
+  it('source is 12px normal weight', () => {
+    expect(DEFAULT_THEME.chrome.source.fontSize).toBe(12);
+    expect(DEFAULT_THEME.chrome.source.fontWeight).toBe(400);
+  });
+
+  it('categorical palette has sufficient contrast on white background', () => {
+    const bg = DEFAULT_THEME.colors.background;
+    for (const color of DEFAULT_THEME.colors.categorical) {
+      const ratio = contrastRatio(color, bg);
+      // AA for large text is 3:1. Some editorial palette colors may not
+      // hit 4.5:1 on pure white, but they should all clear 3:1.
+      expect(ratio).toBeGreaterThanOrEqual(3);
+    }
+  });
+
+  it('has sequential and diverging palette entries', () => {
+    expect(Object.keys(DEFAULT_THEME.colors.sequential).length).toBeGreaterThan(0);
+    expect(Object.keys(DEFAULT_THEME.colors.diverging).length).toBeGreaterThan(0);
+  });
+});

package/src/theme/__tests__/resolve.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, it } from 'vitest';
+import { DEFAULT_THEME } from '../defaults';
+import { resolveTheme } from '../resolve';
+
+describe('resolveTheme', () => {
+  it('returns default theme when no overrides given', () => {
+    const resolved = resolveTheme();
+    expect(resolved.colors.background).toBe(DEFAULT_THEME.colors.background);
+    expect(resolved.fonts.family).toBe(DEFAULT_THEME.fonts.family);
+    expect(resolved.isDark).toBe(false);
+  });
+
+  it('deep merges color overrides without losing other color fields', () => {
+    const resolved = resolveTheme({
+      colors: { background: '#111111' },
+    });
+    expect(resolved.colors.background).toBe('#111111');
+    // Other color fields preserved from defaults
+    expect(resolved.colors.text).toBe(DEFAULT_THEME.colors.text);
+    expect(resolved.colors.categorical).toEqual(DEFAULT_THEME.colors.categorical);
+  });
+
+  it('overrides font family', () => {
+    const resolved = resolveTheme({
+      fonts: { family: 'Helvetica' },
+    });
+    expect(resolved.fonts.family).toBe('Helvetica');
+    // Mono should still be default
+    expect(resolved.fonts.mono).toBe(DEFAULT_THEME.fonts.mono);
+  });
+
+  it('overrides spacing partially', () => {
+    const resolved = resolveTheme({
+      spacing: { padding: 24 },
+    });
+    expect(resolved.spacing.padding).toBe(24);
+    expect(resolved.spacing.chromeGap).toBe(DEFAULT_THEME.spacing.chromeGap);
+  });
+
+  it('overrides border radius', () => {
+    const resolved = resolveTheme({ borderRadius: 8 });
+    expect(resolved.borderRadius).toBe(8);
+  });
+
+  it('overrides categorical palette completely', () => {
+    const custom = ['#ff0000', '#00ff00', '#0000ff'];
+    const resolved = resolveTheme({
+      colors: { categorical: custom },
+    });
+    expect(resolved.colors.categorical).toEqual(custom);
+  });
+
+  it('accepts a custom base theme', () => {
+    const customBase = {
+      ...DEFAULT_THEME,
+      borderRadius: 12,
+    };
+    const resolved = resolveTheme(undefined, customBase);
+    expect(resolved.borderRadius).toBe(12);
+  });
+});

package/src/theme/dark-mode.ts

@@ -0,0 +1,123 @@
+/**
+ * Dark mode theme adaptation.
+ *
+ * Preserves hue of colors while adjusting lightness and saturation
+ * to maintain the same relative contrast ratios on a dark background.
+ */
+
+import { hsl, rgb } from 'd3-color';
+import { contrastRatio } from '../colors/contrast';
+import type { ResolvedTheme } from '../types/theme';
+
+// ---------------------------------------------------------------------------
+// Dark mode background
+// ---------------------------------------------------------------------------
+
+/** Default dark mode background color. */
+const DARK_BG = '#1a1a2e';
+/** Default dark mode text color. */
+const DARK_TEXT = '#e0e0e0';
+
+// ---------------------------------------------------------------------------
+// Color adaptation
+// ---------------------------------------------------------------------------
+
+/**
+ * Adapt a single color for dark mode.
+ *
+ * Preserves the hue and adjusts lightness/saturation so the adapted
+ * color has the same contrast ratio against darkBg as the original
+ * had against lightBg.
+ */
+export function adaptColorForDarkMode(color: string, lightBg: string, darkBg: string): string {
+  const originalRatio = contrastRatio(color, lightBg);
+  const c = hsl(color);
+  if (c == null || Number.isNaN(c.h)) {
+    // Achromatic or invalid color: just adjust lightness
+    const r = rgb(color);
+    if (r == null) return color;
+    const darkBgLum = _luminanceFromHex(darkBg);
+    const isLight = darkBgLum < 0.5;
+    if (isLight) return color;
+    // Invert the lightness
+    const inverted = hsl(color);
+    if (inverted == null) return color;
+    inverted.l = 1 - inverted.l;
+    return inverted.formatHex();
+  }
+
+  // Binary search for lightness that gives equivalent contrast on dark bg
+  let lo = 0.0;
+  let hi = 1.0;
+  let bestColor = color;
+  let bestDiff = Infinity;
+
+  for (let i = 0; i < 20; i++) {
+    const mid = (lo + hi) / 2;
+    const candidate = hsl(c.h, c.s, mid);
+    const hex = candidate.formatHex();
+    const ratio = contrastRatio(hex, darkBg);
+    const diff = Math.abs(ratio - originalRatio);
+
+    if (diff < bestDiff) {
+      bestDiff = diff;
+      bestColor = hex;
+    }
+
+    if (ratio < originalRatio) {
+      // Need more contrast = more lightness on dark bg
+      lo = mid;
+    } else {
+      hi = mid;
+    }
+  }
+
+  return bestColor;
+}
+
+/** Quick luminance estimation from a hex color. */
+function _luminanceFromHex(color: string): number {
+  const c = rgb(color);
+  if (c == null) return 0;
+  return (0.2126 * c.r + 0.7152 * c.g + 0.0722 * c.b) / 255;
+}
+
+// ---------------------------------------------------------------------------
+// Full theme adaptation
+// ---------------------------------------------------------------------------
+
+/**
+ * Adapt an entire resolved theme for dark mode.
+ *
+ * Swaps background/text, adapts categorical and annotation colors,
+ * adjusts gridline and axis colors for the dark background.
+ */
+export function adaptTheme(theme: ResolvedTheme): ResolvedTheme {
+  const lightBg = theme.colors.background;
+  const darkBg = DARK_BG;
+
+  return {
+    ...theme,
+    isDark: true,
+    colors: {
+      ...theme.colors,
+      background: darkBg,
+      text: DARK_TEXT,
+      gridline: '#333344',
+      axis: '#888899',
+      annotationFill: 'rgba(255,255,255,0.08)',
+      annotationText: '#bbbbcc',
+      categorical: theme.colors.categorical.map((c) => adaptColorForDarkMode(c, lightBg, darkBg)),
+      // Sequential and diverging palettes are kept as-is since they're
+      // typically used for fills where the lightness range still works.
+      // If a specific use case needs adaptation, it can be done per-color.
+    },
+    chrome: {
+      title: { ...theme.chrome.title, color: DARK_TEXT },
+      subtitle: { ...theme.chrome.subtitle, color: '#aaaaaa' },
+      source: { ...theme.chrome.source, color: '#888888' },
+      byline: { ...theme.chrome.byline, color: '#888888' },
+      footer: { ...theme.chrome.footer, color: '#888888' },
+    },
+  };
+}

package/src/theme/defaults.ts

@@ -0,0 +1,85 @@
+/**
+ * Default theme definition.
+ *
+ * Tuned to match Infrographic's visual weight and editorial style.
+ * Inter font family, typography hierarchy for chrome, and color
+ * palettes from the colors module.
+ */
+
+import { CATEGORICAL_PALETTE, DIVERGING_PALETTES, SEQUENTIAL_PALETTES } from '../colors/palettes';
+import type { Theme } from '../types/theme';
+
+/**
+ * The default theme. All fields are required and fully specified.
+ * resolveTheme() deep-merges user overrides onto this base.
+ */
+export const DEFAULT_THEME: Theme = {
+  colors: {
+    categorical: [...CATEGORICAL_PALETTE],
+    sequential: SEQUENTIAL_PALETTES,
+    diverging: DIVERGING_PALETTES,
+    background: '#ffffff',
+    text: '#1d1d1d',
+    gridline: '#e8e8e8',
+    axis: '#888888',
+    annotationFill: 'rgba(0,0,0,0.04)',
+    annotationText: '#555555',
+  },
+  fonts: {
+    family: 'Inter, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif',
+    mono: '"JetBrains Mono", "Fira Code", "Cascadia Code", monospace',
+    sizes: {
+      title: 22,
+      subtitle: 15,
+      body: 13,
+      small: 11,
+      axisTick: 11,
+    },
+    weights: {
+      normal: 400,
+      medium: 500,
+      semibold: 600,
+      bold: 700,
+    },
+  },
+  spacing: {
+    padding: 12,
+    chromeGap: 4,
+    chromeToChart: 8,
+    chartToFooter: 8,
+    axisMargin: 6,
+  },
+  borderRadius: 4,
+  chrome: {
+    title: {
+      fontSize: 22,
+      fontWeight: 700,
+      color: '#333333',
+      lineHeight: 1.3,
+    },
+    subtitle: {
+      fontSize: 15,
+      fontWeight: 400,
+      color: '#666666',
+      lineHeight: 1.4,
+    },
+    source: {
+      fontSize: 12,
+      fontWeight: 400,
+      color: '#999999',
+      lineHeight: 1.3,
+    },
+    byline: {
+      fontSize: 12,
+      fontWeight: 400,
+      color: '#999999',
+      lineHeight: 1.3,
+    },
+    footer: {
+      fontSize: 12,
+      fontWeight: 400,
+      color: '#999999',
+      lineHeight: 1.3,
+    },
+  },
+};

package/src/theme/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Theme module barrel export.
+ */
+
+export { adaptColorForDarkMode, adaptTheme } from './dark-mode';
+export { DEFAULT_THEME } from './defaults';
+export { resolveTheme } from './resolve';

package/src/theme/resolve.ts

@@ -0,0 +1,190 @@
+/**
+ * Theme resolver: deep-merges user overrides onto default theme.
+ *
+ * Produces a ResolvedTheme where every property is guaranteed to have
+ * a value. The engine uses ResolvedTheme internally so it never needs
+ * null checks on theme properties.
+ *
+ * Auto-detects dark backgrounds and adapts chrome text colors so
+ * custom themes with dark canvases are readable without explicitly
+ * enabling darkMode.
+ */
+
+import type { ThemeConfig } from '../types/spec';
+import type { ResolvedTheme, Theme } from '../types/theme';
+import { DEFAULT_THEME } from './defaults';
+
+/**
+ * Deep merge source into target, creating a new object.
+ * Only merges plain objects; arrays and primitives replace directly.
+ */
+// biome-ignore lint/suspicious/noExplicitAny: recursive object merge requires dynamic typing
+function deepMerge(target: any, source: any): any {
+  const result = { ...target };
+
+  for (const key of Object.keys(source)) {
+    const sourceVal = source[key];
+    const targetVal = target[key];
+
+    if (
+      sourceVal !== undefined &&
+      sourceVal !== null &&
+      typeof sourceVal === 'object' &&
+      !Array.isArray(sourceVal) &&
+      typeof targetVal === 'object' &&
+      targetVal !== null &&
+      !Array.isArray(targetVal)
+    ) {
+      result[key] = deepMerge(targetVal, sourceVal);
+    } else if (sourceVal !== undefined) {
+      result[key] = sourceVal;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Convert a user-facing ThemeConfig (partial) into the full Theme shape
+ * that deepMerge can work with.
+ */
+function themeConfigToPartial(config: ThemeConfig): Partial<Theme> {
+  const partial: Partial<Theme> = {};
+
+  if (config.colors) {
+    const colors: Partial<Theme['colors']> = {};
+    if (config.colors.categorical) colors.categorical = config.colors.categorical;
+    if (config.colors.sequential) colors.sequential = config.colors.sequential;
+    if (config.colors.diverging) colors.diverging = config.colors.diverging;
+    if (config.colors.background) colors.background = config.colors.background;
+    if (config.colors.text) colors.text = config.colors.text;
+    if (config.colors.gridline) colors.gridline = config.colors.gridline;
+    if (config.colors.axis) colors.axis = config.colors.axis;
+    partial.colors = colors as Theme['colors'];
+  }
+
+  if (config.fonts) {
+    const fonts: Partial<Theme['fonts']> = {};
+    if (config.fonts.family) fonts.family = config.fonts.family;
+    if (config.fonts.mono) fonts.mono = config.fonts.mono;
+    partial.fonts = fonts as Theme['fonts'];
+  }
+
+  if (config.spacing) {
+    const spacing: Partial<Theme['spacing']> = {};
+    if (config.spacing.padding !== undefined) spacing.padding = config.spacing.padding;
+    if (config.spacing.chromeGap !== undefined) spacing.chromeGap = config.spacing.chromeGap;
+    partial.spacing = spacing as Theme['spacing'];
+  }
+
+  if (config.borderRadius !== undefined) {
+    partial.borderRadius = config.borderRadius;
+  }
+
+  return partial;
+}
+
+/**
+ * Parse a hex color to sRGB relative luminance (WCAG 2.1).
+ * Returns 0 for invalid/unparseable colors.
+ */
+function relativeLuminance(hex: string): number {
+  const m = /^#?([0-9a-f]{6})$/i.exec(hex.trim());
+  if (!m) return 0;
+  const r = parseInt(m[1].slice(0, 2), 16) / 255;
+  const g = parseInt(m[1].slice(2, 4), 16) / 255;
+  const b = parseInt(m[1].slice(4, 6), 16) / 255;
+  const toLinear = (c: number) => (c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4);
+  return 0.2126 * toLinear(r) + 0.7152 * toLinear(g) + 0.0722 * toLinear(b);
+}
+
+/** Returns true if the hex color is perceptually dark (luminance < 0.2). */
+function isDarkBackground(hex: string): boolean {
+  return relativeLuminance(hex) < 0.2;
+}
+
+/**
+ * Adapt chrome text colors for a dark background.
+ * Only overrides values that still match the light-mode defaults,
+ * so explicit user overrides are preserved.
+ */
+function adaptChromeForDarkBg(theme: Theme, textColor: string): Theme {
+  const light = DEFAULT_THEME.chrome;
+  return {
+    ...theme,
+    chrome: {
+      title: {
+        ...theme.chrome.title,
+        color:
+          theme.chrome.title.color === light.title.color ? textColor : theme.chrome.title.color,
+      },
+      subtitle: {
+        ...theme.chrome.subtitle,
+        color:
+          theme.chrome.subtitle.color === light.subtitle.color
+            ? adjustOpacity(textColor, 0.7)
+            : theme.chrome.subtitle.color,
+      },
+      source: {
+        ...theme.chrome.source,
+        color:
+          theme.chrome.source.color === light.source.color
+            ? adjustOpacity(textColor, 0.5)
+            : theme.chrome.source.color,
+      },
+      byline: {
+        ...theme.chrome.byline,
+        color:
+          theme.chrome.byline.color === light.byline.color
+            ? adjustOpacity(textColor, 0.5)
+            : theme.chrome.byline.color,
+      },
+      footer: {
+        ...theme.chrome.footer,
+        color:
+          theme.chrome.footer.color === light.footer.color
+            ? adjustOpacity(textColor, 0.5)
+            : theme.chrome.footer.color,
+      },
+    },
+  };
+}
+
+/** Blend a hex color toward white/black by a factor to simulate opacity. */
+function adjustOpacity(hex: string, opacity: number): string {
+  const m = /^#?([0-9a-f]{6})$/i.exec(hex.trim());
+  if (!m) return hex;
+  const r = parseInt(m[1].slice(0, 2), 16);
+  const g = parseInt(m[1].slice(2, 4), 16);
+  const b = parseInt(m[1].slice(4, 6), 16);
+  // Blend toward mid-gray for muted secondary text
+  const mix = (c: number) => Math.round(c * opacity + 128 * (1 - opacity));
+  const toHex = (n: number) => n.toString(16).padStart(2, '0');
+  return `#${toHex(mix(r))}${toHex(mix(g))}${toHex(mix(b))}`;
+}
+
+/**
+ * Resolve a theme by deep-merging user overrides onto a base theme.
+ *
+ * Auto-detects dark backgrounds: if the resolved background color is
+ * perceptually dark and chrome text colors are still the light-mode
+ * defaults, they're adapted for readability.
+ *
+ * @param userTheme - Optional partial theme overrides from the spec.
+ * @param base - Base theme to merge onto. Defaults to DEFAULT_THEME.
+ * @returns A ResolvedTheme with all properties guaranteed.
+ */
+export function resolveTheme(userTheme?: ThemeConfig, base: Theme = DEFAULT_THEME): ResolvedTheme {
+  let merged: Theme = userTheme ? deepMerge(base, themeConfigToPartial(userTheme)) : { ...base };
+
+  // Auto-adapt chrome for dark backgrounds
+  const dark = isDarkBackground(merged.colors.background);
+  if (dark) {
+    merged = adaptChromeForDarkBg(merged, merged.colors.text);
+  }
+
+  return {
+    ...merged,
+    isDark: dark,
+  } as ResolvedTheme;
+}