@opendata-ai/openchart-core 7.6.0 → 7.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opendata-ai/openchart-core",
-  "version": "7.6.0",
+  "version": "7.7.0",
   "description": "Types, theme, colors, accessibility, and utilities for openchart",
   "license": "Apache-2.0",
   "author": "Riley Hilliard",

package/src/colors/palettes.ts

@@ -8,9 +8,9 @@
  * binary search. Source OKLCH values are documented inline so the ramp
  * can be regenerated if needed.
  *
- * Convention for low-cardinality charts (1 / 2-4 / 5+ series) is enforced
- * by chart-type renderer logic, not the palette itself. The palette stays
- * a flat 9-color ramp consumed by index. The convention is:
+ * Convention for low-cardinality charts (1 / 2-4 / 5+ series) is available
+ * as an opt-in via `theme.seriesStrategy`. The default strategy is 'palette'
+ * (full categorical ramp always). The accent-neutral convention is:
  *   - 1 series: cyan only
  *   - 2-4 series: cyan + zinc-400/500/600 (achromatic)
  *   - 5+ series: full multi-hue ramp below

package/src/helpers/spec-builders.ts

@@ -425,8 +425,10 @@ export function dataTable(data: DataRow[], options?: TableBuilderOptions): Table
 export interface TileMapBuilderOptions {
   /** Encoding channels (required when data is DataRow[]). */
   encoding?: TileMapEncoding;
-  /** Sequential color palette name. */
+  /** Sequential color palette name (quantitative mode only). */
   palette?: TileMapPalette;
+  /** Custom category-to-color mapping. Forces categorical mode. */
+  colors?: Record<string, string>;
   /** Editorial chrome. */
   chrome?: Chrome;
   /** Legend display configuration. */
@@ -457,7 +459,7 @@ export interface TileMapBuilderOptions {
  * ```
  */
 export function tileMap(
-  data: Record<string, number | null> | DataRow[],
+  data: Record<string, number | string | null> | DataRow[],
   options?: TileMapBuilderOptions,
 ): TileMapSpec {
   return {
@@ -465,6 +467,7 @@ export function tileMap(
     data,
     ...(options?.encoding && { encoding: options.encoding }),
     ...(options?.palette && { palette: options.palette }),
+    ...(options?.colors && { colors: options.colors }),
     ...(options?.chrome && { chrome: options.chrome }),
     ...(options?.legend && { legend: options.legend }),
     ...(options?.theme && { theme: options.theme }),

package/src/index.ts

@@ -27,6 +27,7 @@ export type {
   SequentialPalette,
 } from './colors/index';
 export {
+  ACHROMATIC_RAMP,
   CATEGORICAL_PALETTE,
   checkPaletteDistinguishability,
   contrastRatio,
@@ -44,9 +45,13 @@ export {
 
 export {
   adaptColorForDarkMode,
+  adaptForLightLineStroke,
   adaptTheme,
   DEFAULT_THEME,
+  editorial,
+  essay,
   resolveTheme,
+  wire,
 } from './theme/index';
 
 // ---------------------------------------------------------------------------

package/src/styles/dark.css

@@ -1,5 +1,9 @@
 /* ---------------------------------------------------------------------------
- * Dark mode overrides
+ * Dark mode overrides (fallback defaults)
+ *
+ * At runtime, the JS theme engine stamps dark-adapted --oc-* custom
+ * properties on each .oc-root container. These CSS values serve as
+ * fallbacks for contexts where JS hasn't mounted yet.
  * --------------------------------------------------------------------------- */
 
 .oc-dark {

package/src/styles/tokens.css

@@ -1,5 +1,11 @@
 /* ---------------------------------------------------------------------------
  * Custom properties (light mode defaults)
+ *
+ * These are FALLBACK defaults. At runtime, the JS theme engine stamps the
+ * resolved theme as inline --oc-* custom properties on each .oc-root
+ * container (see packages/vanilla/src/theme-tokens.ts). These CSS values
+ * serve as fallbacks for contexts where JS hasn't mounted yet (SSR, static
+ * HTML examples).
  * --------------------------------------------------------------------------- */
 
 .oc-root,

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

@@ -149,4 +149,84 @@ describe('adaptTheme', () => {
     // Unset chrome colors fall to the muted dark default, not the light one.
     expect(dark.chrome.subtitle.color).not.toBe('#71717a');
   });
+
+  it('uses explicit dark pair value for background instead of algorithmic adaptation', () => {
+    const light = resolveTheme({
+      colors: { background: { light: '#fff1e5', dark: '#1a1311' } },
+    });
+    const dark = adaptTheme(light);
+    expect(dark.colors.background).toBe('#1a1311');
+  });
+
+  it('uses explicit dark pair value for text instead of algorithmic adaptation', () => {
+    const light = resolveTheme({
+      colors: {
+        background: { light: '#ffffff', dark: '#111111' },
+        text: { light: '#1c1917', dark: '#e7e5e4' },
+      },
+    });
+    const dark = adaptTheme(light);
+    expect(dark.colors.text).toBe('#e7e5e4');
+  });
+
+  it('uses explicit dark pair for gridline and axis', () => {
+    const light = resolveTheme({
+      colors: {
+        background: { light: '#fff', dark: '#111' },
+        gridline: { light: 'rgba(0,0,0,0.08)', dark: 'rgba(255,255,255,0.06)' },
+        axis: { light: '#78716c', dark: '#a8a29e' },
+      },
+    });
+    const dark = adaptTheme(light);
+    expect(dark.colors.gridline).toBe('rgba(255,255,255,0.06)');
+    expect(dark.colors.axis).toBe('#a8a29e');
+  });
+
+  it('uses explicit dark pair for semantic colors', () => {
+    const light = resolveTheme({
+      colors: {
+        background: { light: '#fff', dark: '#111' },
+        positive: { light: '#10b981', dark: '#34d399' },
+        negative: { light: '#e11d48', dark: '#fb7185' },
+      },
+    });
+    const dark = adaptTheme(light);
+    expect(dark.colors.positive).toBe('#34d399');
+    expect(dark.colors.negative).toBe('#fb7185');
+  });
+
+  it('uses explicit dark pair for chrome element color', () => {
+    const light = resolveTheme({
+      colors: { background: { light: '#fff', dark: '#111' } },
+      chrome: {
+        title: { color: { light: '#33302e', dark: '#f2dfce' } },
+      },
+    });
+    const dark = adaptTheme(light);
+    expect(dark.chrome.title.color).toBe('#f2dfce');
+  });
+
+  it('uses explicit dark pair for eyebrow color (otherwise kept as-is)', () => {
+    const light = resolveTheme({
+      chrome: {
+        eyebrow: { color: { light: '#e3120b', dark: '#ff6b64' } },
+      },
+    });
+    const dark = adaptTheme(light);
+    expect(dark.chrome.eyebrow.color).toBe('#ff6b64');
+
+    // Without a pair, the eyebrow keeps its accent tint across modes.
+    const noPair = adaptTheme(resolveTheme({ chrome: { eyebrow: '#e3120b' } }));
+    expect(noPair.chrome.eyebrow.color).toBe('#e3120b');
+  });
+
+  it('falls back to algorithmic adaptation when no explicit dark pair is given', () => {
+    const light = resolveTheme({
+      colors: { background: '#ffffff' },
+    });
+    const dark = adaptTheme(light);
+    // Text should be adapted to a light color for dark bg readability
+    expect(dark.colors.text).not.toBe(light.colors.text);
+    expect(dark.colors.text).toBeDefined();
+  });
 });

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

@@ -161,3 +161,117 @@ describe('resolveTheme deep merge edge cases', () => {
     expect(resolved.chrome.title.color).not.toBe(DEFAULT_THEME.chrome.title.color);
   });
 });
+
+// ---------------------------------------------------------------------------
+// TokenValue resolution
+// ---------------------------------------------------------------------------
+
+describe('resolveTheme TokenValue handling', () => {
+  it('resolves plain string TokenValue to same string', () => {
+    const resolved = resolveTheme({ colors: { background: '#faf8f5' } });
+    expect(resolved.colors.background).toBe('#faf8f5');
+  });
+
+  it('resolves light/dark TokenValue pair to the light value', () => {
+    const resolved = resolveTheme({
+      colors: { background: { light: '#faf8f5', dark: '#1a1816' } },
+    });
+    expect(resolved.colors.background).toBe('#faf8f5');
+  });
+
+  it('stores token pairs on _tokenPairs for adaptTheme consumption', () => {
+    const resolved = resolveTheme({
+      colors: {
+        background: { light: '#fff', dark: '#111' },
+        text: { light: '#000', dark: '#eee' },
+      },
+    });
+    expect(resolved._tokenPairs).toBeDefined();
+    expect(resolved._tokenPairs?.['colors.background']).toEqual({ light: '#fff', dark: '#111' });
+    expect(resolved._tokenPairs?.['colors.text']).toEqual({ light: '#000', dark: '#eee' });
+  });
+
+  it('does not create _tokenPairs when all colors are plain strings', () => {
+    const resolved = resolveTheme({
+      colors: { background: '#fff', text: '#000' },
+    });
+    expect(resolved._tokenPairs).toBeUndefined();
+  });
+
+  it('resolves TokenValue on semantic color fields', () => {
+    const resolved = resolveTheme({
+      colors: {
+        positive: { light: '#10b981', dark: '#34d399' },
+        negative: { light: '#e11d48', dark: '#fb7185' },
+      },
+    });
+    expect(resolved.colors.positive).toBe('#10b981');
+    expect(resolved.colors.negative).toBe('#e11d48');
+    expect(resolved._tokenPairs?.['colors.positive']).toEqual({
+      light: '#10b981',
+      dark: '#34d399',
+    });
+    expect(resolved._tokenPairs?.['colors.negative']).toEqual({
+      light: '#e11d48',
+      dark: '#fb7185',
+    });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// New ThemeConfig fields
+// ---------------------------------------------------------------------------
+
+describe('resolveTheme widened ThemeConfig', () => {
+  it('overrides fonts.weights partially', () => {
+    const resolved = resolveTheme({
+      fonts: { weights: { normal: 400, bold: 700 } },
+    });
+    expect(resolved.fonts.weights.normal).toBe(400);
+    expect(resolved.fonts.weights.bold).toBe(700);
+    expect(resolved.fonts.weights.medium).toBe(DEFAULT_THEME.fonts.weights.medium);
+  });
+
+  it('overrides new spacing fields', () => {
+    const resolved = resolveTheme({
+      spacing: { chromeToChart: 16, chartToFooter: 20, axisMargin: 8 },
+    });
+    expect(resolved.spacing.chromeToChart).toBe(16);
+    expect(resolved.spacing.chartToFooter).toBe(20);
+    expect(resolved.spacing.axisMargin).toBe(8);
+    expect(resolved.spacing.padding).toBe(DEFAULT_THEME.spacing.padding);
+  });
+
+  it('overrides chrome typography with ChromeThemeOverride object', () => {
+    const resolved = resolveTheme({
+      chrome: {
+        title: { fontWeight: 700, fontSize: 32, lineHeight: 1.1 },
+      },
+    });
+    expect(resolved.chrome.title.fontWeight).toBe(700);
+    expect(resolved.chrome.title.fontSize).toBe(32);
+    expect(resolved.chrome.title.lineHeight).toBe(1.1);
+    expect(resolved.chrome.subtitle.fontWeight).toBe(DEFAULT_THEME.chrome.subtitle.fontWeight);
+  });
+
+  it('ChromeThemeOverride color accepts TokenValue', () => {
+    const resolved = resolveTheme({
+      chrome: {
+        title: { color: { light: '#111', dark: '#eee' }, fontWeight: 600 },
+      },
+    });
+    expect(resolved.chrome.title.color).toBe('#111');
+    expect(resolved.chrome.title.fontWeight).toBe(600);
+    expect(resolved._tokenPairs?.['chrome.title.color']).toEqual({ light: '#111', dark: '#eee' });
+  });
+
+  it('passes seriesStrategy through to resolved theme', () => {
+    const resolved = resolveTheme({ seriesStrategy: 'accent-neutral' });
+    expect(resolved.seriesStrategy).toBe('accent-neutral');
+  });
+
+  it('defaults seriesStrategy to palette', () => {
+    const resolved = resolveTheme();
+    expect(resolved.seriesStrategy).toBe('palette');
+  });
+});

package/src/theme/dark-mode.ts

@@ -106,6 +106,7 @@ function _luminanceFromHex(color: string): number {
  * adjusts gridline and axis colors for the dark background.
  */
 export function adaptTheme(theme: ResolvedTheme): ResolvedTheme {
+  const pairs = theme._tokenPairs;
   const inputBg = theme.colors.background;
   // "transparent" preserves the background token but must still adopt dark
   // text/gridline/axis colors — the container is dark, not the chart canvas.
@@ -115,23 +116,33 @@ export function adaptTheme(theme: ResolvedTheme): ResolvedTheme {
   // Preserve user-supplied background (including transparent) but always
   // apply dark-mode text/axis/gridline colors so labels are readable on the
   // dark host surface.
-  const darkBg = alreadyDark ? inputBg : DARK_BG;
+  const darkBg = pairs?.['colors.background']
+    ? pairs['colors.background'].dark
+    : alreadyDark
+      ? inputBg
+      : DARK_BG;
   const darkMuted = ACHROMATIC_RAMP.fgMuted;
 
   // Per the "sensible defaults, full override" convention (see spec-grammar),
   // dark-mode adaptation only swaps in dark defaults for colors the spec
   // left at their light-mode default. An explicit override is preserved.
-  // This mirrors resolveTheme's adaptChromeForDarkBg.
+  // When a TokenValue pair has an explicit dark value, use it directly.
   const light = DEFAULT_THEME.colors;
   const lightChrome = DEFAULT_THEME.chrome;
   const overridden = <T>(current: T, lightDefault: T, darkDefault: T): T =>
     current === lightDefault ? darkDefault : current;
 
-  const darkText = overridden(theme.colors.text, light.text, DARK_TEXT);
-  const darkGridline = overridden(theme.colors.gridline, light.gridline, 'rgba(255,255,255,0.05)');
+  const darkText = pairs?.['colors.text']
+    ? pairs['colors.text'].dark
+    : overridden(theme.colors.text, light.text, DARK_TEXT);
+  const darkGridline = pairs?.['colors.gridline']
+    ? pairs['colors.gridline'].dark
+    : overridden(theme.colors.gridline, light.gridline, 'rgba(255,255,255,0.05)');
   // axis is also tick-label fill — needs WCAG AA contrast on dark bg.
   // Zinc-400 (`#a1a1aa`) hits ~6:1 against #09090b.
-  const darkAxis = overridden(theme.colors.axis, light.axis, '#a1a1aa');
+  const darkAxis = pairs?.['colors.axis']
+    ? pairs['colors.axis'].dark
+    : overridden(theme.colors.axis, light.axis, '#a1a1aa');
 
   // Categorical palette is pinned to design-system tokens. The same vibrant
   // hex values render in both light and dark modes — adapting them via
@@ -148,44 +159,63 @@ export function adaptTheme(theme: ResolvedTheme): ResolvedTheme {
       text: darkText,
       gridline: darkGridline,
       axis: darkAxis,
-      annotationFill: overridden(
-        theme.colors.annotationFill,
-        light.annotationFill,
-        'rgba(255,255,255,0.06)',
-      ),
-      annotationText: overridden(theme.colors.annotationText, light.annotationText, darkMuted),
+      annotationFill: pairs?.['colors.annotationFill']
+        ? pairs['colors.annotationFill'].dark
+        : overridden(theme.colors.annotationFill, light.annotationFill, 'rgba(255,255,255,0.06)'),
+      annotationText: pairs?.['colors.annotationText']
+        ? pairs['colors.annotationText'].dark
+        : overridden(theme.colors.annotationText, light.annotationText, darkMuted),
       categorical,
-      // Sparkline trend colors tuned for dark surfaces: teal-leaning green
-      // and coral red read better than the saturated light-mode tokens.
-      // Any non-default value is treated as a user override and preserved.
-      positive: theme.colors.positive !== '#16a34a' ? theme.colors.positive : '#34d399',
-      negative: theme.colors.negative !== '#dc2626' ? theme.colors.negative : '#f87171',
+      positive: pairs?.['colors.positive']
+        ? pairs['colors.positive'].dark
+        : theme.colors.positive !== '#16a34a'
+          ? theme.colors.positive
+          : '#34d399',
+      negative: pairs?.['colors.negative']
+        ? pairs['colors.negative'].dark
+        : theme.colors.negative !== '#dc2626'
+          ? theme.colors.negative
+          : '#f87171',
     },
     chrome: {
-      // Eyebrow keeps its accent tint (cyan in both modes); the other
-      // chrome elements desaturate to a muted gray on the dark canvas.
-      // Each color only adapts if the spec left it at the light default,
-      // so explicit chrome color overrides survive dark-mode adaptation.
-      eyebrow: theme.chrome.eyebrow,
+      // Eyebrow keeps its accent tint (cyan in both modes) unless the user
+      // gave an explicit dark value; the other chrome elements desaturate
+      // to a muted gray on the dark canvas. Each color only adapts if the
+      // spec left it at the light default, so explicit chrome color
+      // overrides survive dark-mode adaptation. When a TokenValue pair has
+      // an explicit dark value, use it directly.
+      eyebrow: pairs?.['chrome.eyebrow.color']
+        ? { ...theme.chrome.eyebrow, color: pairs['chrome.eyebrow.color'].dark }
+        : theme.chrome.eyebrow,
       title: {
         ...theme.chrome.title,
-        color: overridden(theme.chrome.title.color, lightChrome.title.color, darkText),
+        color: pairs?.['chrome.title.color']
+          ? pairs['chrome.title.color'].dark
+          : overridden(theme.chrome.title.color, lightChrome.title.color, darkText),
       },
       subtitle: {
         ...theme.chrome.subtitle,
-        color: overridden(theme.chrome.subtitle.color, lightChrome.subtitle.color, darkMuted),
+        color: pairs?.['chrome.subtitle.color']
+          ? pairs['chrome.subtitle.color'].dark
+          : overridden(theme.chrome.subtitle.color, lightChrome.subtitle.color, darkMuted),
       },
       source: {
         ...theme.chrome.source,
-        color: overridden(theme.chrome.source.color, lightChrome.source.color, darkMuted),
+        color: pairs?.['chrome.source.color']
+          ? pairs['chrome.source.color'].dark
+          : overridden(theme.chrome.source.color, lightChrome.source.color, darkMuted),
       },
       byline: {
         ...theme.chrome.byline,
-        color: overridden(theme.chrome.byline.color, lightChrome.byline.color, darkMuted),
+        color: pairs?.['chrome.byline.color']
+          ? pairs['chrome.byline.color'].dark
+          : overridden(theme.chrome.byline.color, lightChrome.byline.color, darkMuted),
       },
       footer: {
         ...theme.chrome.footer,
-        color: overridden(theme.chrome.footer.color, lightChrome.footer.color, darkMuted),
+        color: pairs?.['chrome.footer.color']
+          ? pairs['chrome.footer.color'].dark
+          : overridden(theme.chrome.footer.color, lightChrome.footer.color, darkMuted),
       },
     },
   };

package/src/theme/defaults.ts

@@ -2,7 +2,7 @@
  * Default theme definition.
  *
  * Editorial design system with cyan-led categorical palette, Inter
- * Variable typography (weights 400/510/590), and zinc-based achromatic
+ * Variable typography (weights 450/550/590/700), and zinc-based achromatic
  * surfaces. Light is the default surface; dark adaptation lives in
  * dark-mode.ts.
  *
@@ -106,4 +106,5 @@ export const DEFAULT_THEME: Theme = {
       lineHeight: 1.4,
     },
   },
+  seriesStrategy: 'palette',
 };

package/src/theme/index.ts

@@ -4,4 +4,5 @@
 
 export { adaptColorForDarkMode, adaptForLightLineStroke, adaptTheme } from './dark-mode';
 export { DEFAULT_THEME } from './defaults';
+export { editorial, essay, wire } from './presets';
 export { resolveTheme } from './resolve';

package/src/theme/presets.ts

@@ -0,0 +1,64 @@
+/**
+ * Named theme presets built on the design token system.
+ *
+ * Each preset is a ThemeConfig object that can be passed to createChart()
+ * or the React/Svelte/Vue Chart component. The engine deep-merges them
+ * onto DEFAULT_THEME, so only the deltas are specified here.
+ */
+
+import type { ThemeConfig } from '../types/spec';
+
+/** Editorial preset: the current default look. Exported for explicit selection. */
+export const editorial: ThemeConfig = {};
+
+/** Essay preset: serif display titles, warmer background, generous spacing. */
+export const essay: ThemeConfig = {
+  colors: {
+    background: { light: '#faf8f5', dark: '#1a1816' },
+    text: { light: '#1c1917', dark: '#e7e5e4' },
+    gridline: { light: 'rgba(0,0,0,0.08)', dark: 'rgba(255,255,255,0.06)' },
+    axis: { light: '#78716c', dark: '#a8a29e' },
+  },
+  fonts: {
+    family: '"Source Serif 4", "Source Serif Pro", Georgia, "Times New Roman", serif',
+    sizes: { title: 28, subtitle: 15, body: 14, small: 12 },
+    weights: { normal: 400, medium: 500, semibold: 600, bold: 700 },
+  },
+  spacing: {
+    padding: 24,
+    chromeGap: 6,
+    chromeToChart: 12,
+    chartToFooter: 12,
+  },
+  chrome: {
+    title: { fontWeight: 600, lineHeight: 1.2 },
+    subtitle: { fontWeight: 400, lineHeight: 1.5 },
+  },
+  borderRadius: 0,
+};
+
+/** Wire preset: dense, mono numerals, tighter chrome. Dashboard/agency feel. */
+export const wire: ThemeConfig = {
+  colors: {
+    background: { light: '#ffffff', dark: '#0a0a0a' },
+    text: { light: '#171717', dark: '#ededed' },
+    gridline: { light: 'rgba(0,0,0,0.06)', dark: 'rgba(255,255,255,0.06)' },
+    axis: { light: '#737373', dark: '#a3a3a3' },
+  },
+  fonts: {
+    family: '"JetBrains Mono", "Fira Code", "Cascadia Code", monospace',
+    sizes: { title: 16, subtitle: 12, body: 11, small: 10, axisTick: 10 },
+    weights: { normal: 400, medium: 500, semibold: 600, bold: 700 },
+  },
+  spacing: {
+    padding: 12,
+    chromeGap: 2,
+    chromeToChart: 4,
+    chartToFooter: 4,
+  },
+  chrome: {
+    title: { fontWeight: 600, lineHeight: 1.25 },
+    subtitle: { fontWeight: 400, lineHeight: 1.3 },
+  },
+  borderRadius: 2,
+};