@opendata-ai/openchart-core 7.6.1 → 7.7.0

package/src/theme/resolve.ts

@@ -10,8 +10,8 @@
  * enabling darkMode.
  */
 
-import type { ThemeConfig } from '../types/spec';
-import type { ResolvedTheme, Theme } from '../types/theme';
+import type { ChromeThemeOverride, ThemeConfig } from '../types/spec';
+import type { ChromeDefaults, ResolvedTheme, Theme, TokenValue } from '../types/theme';
 import { DEFAULT_THEME } from './defaults';
 
 /**
@@ -44,6 +44,11 @@ function deepMerge(target: any, source: any): any {
   return result;
 }
 
+/** Extract the light-mode string from a TokenValue. */
+function resolveTokenLight(v: TokenValue): string {
+  return typeof v === 'string' ? v : v.light;
+}
+
 /**
  * Convert a user-facing ThemeConfig (partial) into the full Theme shape
  * that deepMerge can work with.
@@ -60,10 +65,16 @@ function themeConfigToPartial(config: ThemeConfig): Partial<Theme> {
       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;
+      if (config.colors.background) colors.background = resolveTokenLight(config.colors.background);
+      if (config.colors.text) colors.text = resolveTokenLight(config.colors.text);
+      if (config.colors.gridline) colors.gridline = resolveTokenLight(config.colors.gridline);
+      if (config.colors.axis) colors.axis = resolveTokenLight(config.colors.axis);
+      if (config.colors.annotationFill)
+        colors.annotationFill = resolveTokenLight(config.colors.annotationFill);
+      if (config.colors.annotationText)
+        colors.annotationText = resolveTokenLight(config.colors.annotationText);
+      if (config.colors.positive) colors.positive = resolveTokenLight(config.colors.positive);
+      if (config.colors.negative) colors.negative = resolveTokenLight(config.colors.negative);
     }
     partial.colors = colors as Theme['colors'];
   }
@@ -73,6 +84,7 @@ function themeConfigToPartial(config: ThemeConfig): Partial<Theme> {
     if (config.fonts.family) fonts.family = config.fonts.family;
     if (config.fonts.mono) fonts.mono = config.fonts.mono;
     if (config.fonts.sizes) fonts.sizes = config.fonts.sizes as Theme['fonts']['sizes'];
+    if (config.fonts.weights) fonts.weights = config.fonts.weights as Theme['fonts']['weights'];
     partial.fonts = fonts as Theme['fonts'];
   }
 
@@ -80,6 +92,11 @@ function themeConfigToPartial(config: ThemeConfig): Partial<Theme> {
     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;
+    if (config.spacing.chromeToChart !== undefined)
+      spacing.chromeToChart = config.spacing.chromeToChart;
+    if (config.spacing.chartToFooter !== undefined)
+      spacing.chartToFooter = config.spacing.chartToFooter;
+    if (config.spacing.axisMargin !== undefined) spacing.axisMargin = config.spacing.axisMargin;
     if (config.spacing.xAxisHeight !== undefined) spacing.xAxisHeight = config.spacing.xAxisHeight;
     if (config.spacing.xAxisLabelPadding !== undefined)
       spacing.xAxisLabelPadding = config.spacing.xAxisLabelPadding;
@@ -91,19 +108,74 @@ function themeConfigToPartial(config: ThemeConfig): Partial<Theme> {
   }
 
   if (config.chrome) {
-    // Only color is overridable per chrome element. Each element becomes a
-    // partial `{ color }`; deepMerge layers it onto the full ChromeDefaults
-    // so font size/weight/lineHeight stay at their typography-scale values.
-    const chrome: Record<string, { color: string }> = {};
-    for (const [element, color] of Object.entries(config.chrome)) {
-      if (color !== undefined) chrome[element] = { color };
+    const chrome: Record<string, Partial<ChromeDefaults>> = {};
+    for (const [element, value] of Object.entries(config.chrome)) {
+      if (value === undefined) continue;
+      if (typeof value === 'string') {
+        chrome[element] = { color: value };
+      } else {
+        const override: Partial<ChromeDefaults> = {};
+        const obj = value as ChromeThemeOverride;
+        if (obj.color !== undefined) override.color = resolveTokenLight(obj.color);
+        if (obj.fontSize !== undefined) override.fontSize = obj.fontSize;
+        if (obj.fontWeight !== undefined) override.fontWeight = obj.fontWeight;
+        if (obj.lineHeight !== undefined) override.lineHeight = obj.lineHeight;
+        chrome[element] = override;
+      }
     }
     partial.chrome = chrome as unknown as Theme['chrome'];
   }
 
+  if (config.seriesStrategy) {
+    partial.seriesStrategy = config.seriesStrategy;
+  }
+
   return partial;
 }
 
+/**
+ * Collect TokenValue pairs from the user's ThemeConfig so adaptTheme()
+ * can use explicit dark values instead of algorithmic adaptation.
+ */
+function collectTokenPairs(
+  config: ThemeConfig,
+): Record<string, { light: string; dark: string }> | undefined {
+  const pairs: Record<string, { light: string; dark: string }> = {};
+  if (config.colors && !Array.isArray(config.colors)) {
+    const colorFields = [
+      'background',
+      'text',
+      'gridline',
+      'axis',
+      'annotationFill',
+      'annotationText',
+      'positive',
+      'negative',
+    ] as const;
+    for (const field of colorFields) {
+      const v = config.colors[field];
+      if (v && typeof v === 'object' && 'light' in v) {
+        pairs[`colors.${field}`] = v;
+      }
+    }
+  }
+  if (config.chrome) {
+    for (const [element, value] of Object.entries(config.chrome)) {
+      if (
+        value &&
+        typeof value === 'object' &&
+        'color' in value &&
+        value.color &&
+        typeof value.color === 'object' &&
+        'light' in value.color
+      ) {
+        pairs[`chrome.${element}.color`] = value.color;
+      }
+    }
+  }
+  return Object.keys(pairs).length > 0 ? pairs : undefined;
+}
+
 /**
  * Parse a hex color to sRGB relative luminance (WCAG 2.1).
  * Returns 0 for invalid/unparseable colors.
@@ -235,5 +307,6 @@ export function resolveTheme(userTheme?: ThemeConfig, base: Theme = DEFAULT_THEM
   return {
     ...merged,
     isDark: dark,
+    _tokenPairs: userTheme ? collectTokenPairs(userTheme) : undefined,
   } as ResolvedTheme;
 }

package/src/types/index.ts

@@ -28,6 +28,7 @@ export { elementRef } from './events';
 // Layout types (engine output)
 export type {
   A11yMetadata,
+  AnnotationFootnote,
   ArcMark,
   AreaMark,
   AxisLayout,
@@ -44,6 +45,8 @@ export type {
   CompileTableOptions,
   EndpointLabelEntry,
   EndpointLabelsLayout,
+  FacetLayout,
+  FacetPanelLayout,
   FlagTableCell,
   GradientColorStop,
   GradientLegendLayout,
@@ -124,6 +127,7 @@ export type {
   Chrome,
   ChromeText,
   ChromeTextStyle,
+  ChromeThemeOverride,
   CircleEncoding,
   Condition,
   ConditionalValueDef,
@@ -133,6 +137,7 @@ export type {
   Encoding,
   EncodingChannel,
   EndpointLabelsConfig,
+  FacetChannel,
   FieldPredicate,
   FieldType,
   FilterPredicate,
@@ -170,6 +175,7 @@ export type {
   RelativeTimeRef,
   ResolveConfig,
   ResolveMode,
+  ResponsiveConfig,
   SankeyEncoding,
   SankeyLinkColor,
   SankeyNodeAlign,
@@ -232,6 +238,7 @@ export type {
 export type {
   ChromeDefaults,
   ResolvedTheme,
+  SeriesStrategy,
   Theme,
   ThemeChromeDefaults,
   ThemeColors,
@@ -239,4 +246,5 @@ export type {
   ThemeFonts,
   ThemeFontWeights,
   ThemeSpacing,
+  TokenValue,
 } from './theme';

package/src/types/layout.ts

@@ -109,6 +109,8 @@ export interface ResolvedChrome {
   byline?: ResolvedChromeElement;
   footer?: ResolvedChromeElement;
   brand?: ResolvedChromeElement;
+  /** Annotation footnotes generated by auto-thinning. Rendered as a numbered list above the source line. */
+  footnotes?: AnnotationFootnote[];
   /** Absolute y at which bottom-chrome relative offsets are anchored: area.y + area.height + x-axis extent. */
   bottomAnchorY?: number;
 }
@@ -610,6 +612,20 @@ export interface ResolvedAnnotation {
   };
   /** Full placed extent: label bounds unioned with subtitle bounds. Collision and placement source of truth. */
   bounds?: Rect;
+  /**
+   * When set, this annotation was demoted to a footnote marker by auto-thinning.
+   * The label is replaced by a numbered dot at the data point; the original text
+   * appears in the chrome footnote band. 1-indexed.
+   */
+  footnoteIndex?: number;
+}
+
+/** A footnote entry generated by annotation auto-thinning. */
+export interface AnnotationFootnote {
+  /** 1-indexed footnote number matching the dot marker on the chart. */
+  index: number;
+  /** The original annotation text that was demoted. */
+  text: string;
 }
 
 // ---------------------------------------------------------------------------
@@ -751,6 +767,10 @@ export interface EndpointLabelsLayout {
   valueGap: number;
   /** Fill color for the rounded chip background behind the colored bar. */
   swatchChipFill: string;
+  /** Leading-edge (left side) entries when `ends: 'both'`. Empty when trailing only. */
+  leading?: EndpointLabelEntry[];
+  /** Bounding box for the leading column. Only set when `ends: 'both'`. */
+  leadingBounds?: Rect;
 }
 
 // ---------------------------------------------------------------------------
@@ -851,6 +871,38 @@ export interface ResolvedMetricBar {
 // ChartLayout (the main engine output for charts)
 // ---------------------------------------------------------------------------
 
+/**
+ * A single panel in a faceted (small-multiples) layout.
+ * Each panel has its own marks, axes, and drawing area but typically
+ * shares scales with sibling panels.
+ */
+export interface FacetPanelLayout {
+  /** Facet value that produced this panel. */
+  key: string;
+  /** Panel drawing area in SVG coordinates. */
+  area: Rect;
+  /** Data marks for this panel. */
+  marks: Mark[];
+  /** Per-panel axis layouts. Inner panels may have ticks suppressed. */
+  axes: { x?: AxisLayout; y?: AxisLayout };
+  /** Per-panel annotations. */
+  annotations: ResolvedAnnotation[];
+  /** Panel header label (facet value) positioned above the panel. */
+  header: { text: string; x: number; y: number; fontSize: number; fontWeight: number };
+}
+
+/** Layout for a faceted (small-multiples) chart. */
+export interface FacetLayout {
+  /** Ordered array of panel layouts. */
+  panels: FacetPanelLayout[];
+  /** The data field used for faceting. */
+  facetField: string;
+  /** Number of columns in the wrap grid. */
+  columns: number;
+  /** Whether scales are shared across panels. */
+  sharedScales: boolean;
+}
+
 /**
  * ChartLayout: the complete engine output for chart visualizations.
  *
@@ -903,6 +955,8 @@ export interface ChartLayout {
   crosshair: boolean;
   /** Real text measurement function from the adapter (for accurate SVG text wrapping). */
   measureText?: MeasureTextFn;
+  /** Faceted (small-multiples) layout. When present, renderers iterate panels instead of using top-level marks/axes. */
+  facet?: FacetLayout;
 }
 
 // ---------------------------------------------------------------------------
@@ -1320,8 +1374,10 @@ export interface TileMapLayout {
   chrome: ResolvedChrome;
   /** Resolved tile marks with positions, colors, and labels. */
   tiles: TileMapTileMark[];
-  /** Gradient color legend (null if legend is hidden). */
+  /** Gradient color legend for quantitative mode (null if hidden or categorical). */
   gradientLegend: GradientLegendLayout | null;
+  /** Categorical swatch legend for nominal mode (null if hidden or quantitative). */
+  categoricalLegend: CategoricalLegendLayout | null;
   /** Tooltip content descriptors keyed by state code. */
   tooltipDescriptors: Map<string, TooltipContent>;
   /** Accessibility metadata for the tile map. */

package/src/types/spec.ts

@@ -11,6 +11,7 @@
 // Re-import for use in LegendConfig and overrides (avoids circular by importing from sibling)
 import type { Breakpoint, LegendPosition } from '../responsive/breakpoints';
 import type { ColumnConfig } from './table';
+import type { SeriesStrategy, TokenValue } from './theme';
 
 // ---------------------------------------------------------------------------
 // Mark type union (Vega-Lite aligned)
@@ -417,6 +418,37 @@ export interface EncodingChannel<TData extends DataRow = DataRow> {
    * Used in tooltips; `axis.format` takes precedence for axis tick labels.
    */
   format?: string;
+  /**
+   * Emphasis highlight for the color channel. Names one or more series values
+   * to visually emphasize; all other series are muted to a neutral gray.
+   *
+   * Only meaningful on the `color` encoding channel. On other channels this
+   * property is ignored.
+   *
+   * @example
+   * encoding: {
+   *   color: { field: 'region', type: 'nominal', highlight: 'West' }
+   * }
+   */
+  highlight?: string | string[];
+}
+
+/**
+ * Facet channel definition: partitions data into small-multiple panels.
+ *
+ * Unlike positional channels, facet only needs a field, a categorical type,
+ * and optional layout hints (columns, sort). It does not carry scale/axis
+ * config because it produces a grid, not a visual encoding.
+ */
+export interface FacetChannel<TData extends DataRow = DataRow> {
+  /** Data field to partition by. Each unique value produces one panel. */
+  field: keyof TData & string;
+  /** Must be categorical. */
+  type: 'nominal' | 'ordinal';
+  /** Number of columns in the wrap grid. Auto-computed when omitted. */
+  columns?: number;
+  /** Sort order for panel values. Default ascending. */
+  sort?: 'ascending' | 'descending' | null;
 }
 
 /**
@@ -512,6 +544,13 @@ export interface Encoding<TData extends DataRow = DataRow> {
    * Not used by any other mark type.
    */
   radius?: EncodingChannel<TData>;
+  /**
+   * Facet channel: partitions data into a grid of small-multiple panels.
+   * Each unique value of the facet field produces one panel. Panels share
+   * scales by default; use `resolve: { scale: { y: 'independent' } }` for
+   * per-panel axes.
+   */
+  facet?: FacetChannel<TData>;
 }
 
 // ---------------------------------------------------------------------------
@@ -679,6 +718,8 @@ export interface TextAnnotation extends AnnotationBase {
   y: string | number;
   /** The annotation text. Required for text annotations. */
   text: string;
+  /** Thinning priority (lower = kept longer at narrow widths). When omitted, spec order is used. */
+  priority?: number;
   /**
    * Optional muted second-tone text rendered below the primary `text`.
    * Used for supporting context (e.g. methodology, source). Newlines in
@@ -804,6 +845,21 @@ export type Annotation = TextAnnotation | RangeAnnotation | RefLineAnnotation;
  */
 export type DarkMode = 'auto' | 'force' | 'off';
 
+/**
+ * Per-element chrome theme override. Pass a plain string (color only,
+ * backward-compatible) or an object with full typography control.
+ */
+export interface ChromeThemeOverride {
+  /** Text color. Accepts a TokenValue for light/dark pairs. */
+  color?: TokenValue;
+  /** Font size in pixels. */
+  fontSize?: number;
+  /** Font weight. */
+  fontWeight?: number;
+  /** Line height multiplier. */
+  lineHeight?: number;
+}
+
 /**
  * User-facing theme configuration for overriding defaults.
  * All fields are optional. The engine deep-merges these onto the default theme.
@@ -823,14 +879,22 @@ export interface ThemeConfig {
         sequential?: Record<string, string[]>;
         /** Diverging palettes keyed by name. Each is an array of color stops with a neutral midpoint. */
         diverging?: Record<string, string[]>;
-        /** Background color. */
-        background?: string;
-        /** Default text color. */
-        text?: string;
-        /** Gridline color. */
-        gridline?: string;
-        /** Axis line and tick color. */
-        axis?: string;
+        /** Background color. Accepts a TokenValue for light/dark pairs. */
+        background?: TokenValue;
+        /** Default text color. Accepts a TokenValue for light/dark pairs. */
+        text?: TokenValue;
+        /** Gridline color. Accepts a TokenValue for light/dark pairs. */
+        gridline?: TokenValue;
+        /** Axis line and tick color. Accepts a TokenValue for light/dark pairs. */
+        axis?: TokenValue;
+        /** Annotation fill color. Accepts a TokenValue for light/dark pairs. */
+        annotationFill?: TokenValue;
+        /** Annotation text color. Accepts a TokenValue for light/dark pairs. */
+        annotationText?: TokenValue;
+        /** Semantic color for positive/up-trend values. Accepts a TokenValue for light/dark pairs. */
+        positive?: TokenValue;
+        /** Semantic color for negative/down-trend values. Accepts a TokenValue for light/dark pairs. */
+        negative?: TokenValue;
       };
   /** Font overrides. */
   fonts?: {
@@ -855,6 +919,17 @@ export interface ThemeConfig {
       /** KPI metric primary value. Default: 22. Delta/secondary derive from this. */
       metricValue?: number;
     };
+    /** Font weight overrides. Partial — only specified keys are overridden. */
+    weights?: {
+      /** Normal text weight. Default: 450. */
+      normal?: number;
+      /** Medium text weight. Default: 550. */
+      medium?: number;
+      /** Semibold text weight. Default: 590. */
+      semibold?: number;
+      /** Bold text weight. Default: 700. */
+      bold?: number;
+    };
   };
   /** Spacing overrides in pixels. */
   spacing?: {
@@ -862,6 +937,12 @@ export interface ThemeConfig {
     padding?: number;
     /** Gap between chrome elements (title to subtitle, etc.). */
     chromeGap?: number;
+    /** Gap between the last chrome element and the chart area. */
+    chromeToChart?: number;
+    /** Gap between chart area and source/footer below. */
+    chartToFooter?: number;
+    /** Internal padding within the chart area (axes margins). */
+    axisMargin?: number;
     /** Height reserved below chart area for x-axis tick labels. Increase when large axisTick font sizes cause label clipping. */
     xAxisHeight?: number;
     /** Gap in pixels between the x-axis line and tick label text. Increase when larger axisTick fonts sit too close to the axis line. */
@@ -870,25 +951,29 @@ export interface ThemeConfig {
   /** Border radius for chart container and tooltips. */
   borderRadius?: number;
   /**
-   * Per-element chrome text color overrides. Font sizes and weights come
-   * from the typography scale and are not overridable here; only color is.
-   * An override survives dark-mode adaptation (adaptTheme preserves any
-   * chrome color the spec set explicitly).
+   * Per-element chrome style overrides. Pass a plain string for color-only
+   * (backward-compatible), or a ChromeThemeOverride object for full
+   * typography control (color, fontSize, fontWeight, lineHeight).
    */
   chrome?: {
-    /** Eyebrow (kicker) text color. */
-    eyebrow?: string;
-    /** Title text color. */
-    title?: string;
-    /** Subtitle text color. */
-    subtitle?: string;
-    /** Source/attribution text color. */
-    source?: string;
-    /** Byline text color. */
-    byline?: string;
-    /** Footer text color. */
-    footer?: string;
+    /** Eyebrow (kicker) style override. */
+    eyebrow?: string | ChromeThemeOverride;
+    /** Title style override. */
+    title?: string | ChromeThemeOverride;
+    /** Subtitle style override. */
+    subtitle?: string | ChromeThemeOverride;
+    /** Source/attribution style override. */
+    source?: string | ChromeThemeOverride;
+    /** Byline style override. */
+    byline?: string | ChromeThemeOverride;
+    /** Footer style override. */
+    footer?: string | ChromeThemeOverride;
   };
+  /**
+   * Series color assignment strategy.
+   * Default: 'palette' (full categorical palette always, zero visual drift).
+   */
+  seriesStrategy?: SeriesStrategy;
 }
 
 // ---------------------------------------------------------------------------
@@ -976,6 +1061,14 @@ export interface LegendConfig {
 export interface EndpointLabelsConfig {
   /** Explicit on/off. When undefined, the chart auto-decides based on series count. */
   show?: boolean;
+  /** Maximum number of series before endpoint labels switch to a legend. Default 8. */
+  maxSeries?: number;
+  /**
+   * Which ends of the chart get label columns.
+   * - `'end'` (default): labels on the right (trailing) edge only.
+   * - `'both'`: labels on both left (leading) and right (trailing) edges.
+   */
+  ends?: 'end' | 'both';
   /** Field to read the displayed value from. Defaults to `encoding.y.field`. */
   valueField?: string;
   /** d3-format string for the value. Defaults to `encoding.y.axis.format`. */
@@ -1038,6 +1131,17 @@ export interface AnimationStagger {
   order?: 'index' | 'value' | 'reverse';
 }
 
+/** Fine-grained responsive behavior configuration. */
+export interface ResponsiveConfig {
+  /**
+   * Automatic annotation thinning at narrow widths. When true (default),
+   * annotations that can't be placed without overlap are demoted to numbered
+   * dot markers with footnote text below the chart. Set false to restore
+   * the pre-auto-thinning behavior (annotations hidden at compact breakpoints).
+   */
+  autoThin?: boolean;
+}
+
 /**
  * Animation phase config. Follows Vega's enter/update/exit model.
  * Each phase can be true (use defaults) or a config object.
@@ -1282,8 +1386,12 @@ interface BaseChartSpec<TData extends DataRow = DataRow> {
    * relates this flag to `legend.show` and the legacy end-of-line labels.
    */
   endpointLabels?: boolean | EndpointLabelsConfig;
-  /** Whether the chart adapts to container width. Defaults to true. */
-  responsive?: boolean;
+  /**
+   * Responsive behavior. `true`/`false` enables/disables container-width
+   * adaptation. Pass a `ResponsiveConfig` object for fine-grained control
+   * (e.g. `{ autoThin: false }` to disable automatic annotation thinning).
+   */
+  responsive?: boolean | ResponsiveConfig;
   /** Theme configuration overrides. */
   theme?: ThemeConfig;
   /** Dark mode behavior. Defaults to "off". */
@@ -1329,6 +1437,13 @@ interface BaseChartSpec<TData extends DataRow = DataRow> {
    * top-level and per-breakpoint overrides.
    */
   display?: Display;
+  /**
+   * Resolution strategy for shared/independent scales and axes across facet
+   * panels. Only meaningful when `encoding.facet` is present. Shared scales
+   * (the default) let readers compare across panels; independent scales give
+   * each panel its own domain.
+   */
+  resolve?: ResolveConfig;
   /**
    * Render order within a LayerSpec. Higher values render on top.
    * When omitted, layers render in array order (later layers paint on top).
@@ -1667,8 +1782,14 @@ export interface SankeySpec {
 export interface TileMapEncoding {
   /** State code field (required, nominal). Maps to US state abbreviations. */
   state: EncodingChannel;
-  /** Value field (required, quantitative). Maps to the sequential color scale. */
+  /**
+   * Value field. For quantitative mode, maps to a sequential color scale.
+   * For categorical mode (when color channel is present or values are strings),
+   * maps to category labels shown in tooltips.
+   */
   value: EncodingChannel;
+  /** Color encoding channel (optional, nominal). When present, enables categorical coloring. */
+  color?: EncodingChannel;
   /** Tooltip encoding (optional). */
   tooltip?: EncodingChannel | EncodingChannel[];
 }
@@ -1682,16 +1803,24 @@ export interface TileMapSpec {
   /**
    * Data for the tile map. Accepts either:
    * - A record mapping state codes to numeric values: `{ "CA": 12000, "TX": 8500 }`
+   * - A record mapping state codes to string categories: `{ "CA": "high", "TX": "low" }`
    * - Tabular data rows with state and value fields (requires encoding)
    */
-  data: Record<string, number | null> | DataRow[];
+  data: Record<string, number | string | null> | DataRow[];
   /**
    * Encoding channels mapping data fields to visual properties.
    * Required when data is DataRow[]. Auto-generated when data is a record map.
    */
   encoding?: TileMapEncoding;
-  /** Sequential color palette. Defaults to 'blue'. */
+  /** Sequential color palette. Defaults to 'blue'. Only used in quantitative mode. */
   palette?: TileMapPalette;
+  /**
+   * Custom category-to-color mapping for categorical tilemaps.
+   * Keys are category values, values are CSS color strings.
+   * When provided, forces categorical mode regardless of encoding.
+   * Example: `{ "medical_only": "#ee4a73", "religious": "#e07d00", "philosophical": "#06b6d4" }`
+   */
+  colors?: Record<string, string>;
   /** Editorial chrome (title, subtitle, source, byline, footer). */
   chrome?: Chrome;
   /** Legend display configuration. */

package/src/types/theme.ts

@@ -5,6 +5,33 @@
  * ResolvedTheme is the engine-internal fully resolved version (no optionals).
  */
 
+// ---------------------------------------------------------------------------
+// Token value (light/dark pair)
+// ---------------------------------------------------------------------------
+
+/**
+ * A color token value: either a plain CSS color string, or a light/dark pair.
+ * When a pair is given, the resolver picks the appropriate value based on
+ * dark mode state. When a plain string is given, dark-mode adaptation
+ * derives the dark value algorithmically (existing behavior).
+ */
+export type TokenValue = string | { light: string; dark: string };
+
+// ---------------------------------------------------------------------------
+// Series strategy
+// ---------------------------------------------------------------------------
+
+/**
+ * Series color assignment strategy.
+ *
+ * - `'palette'` — always assign from the full categorical palette (current
+ *   default, zero visual drift).
+ * - `'accent-neutral'` — assign by series count: a single series gets the
+ *   accent (first categorical color) only; 2-4 series get accent for the
+ *   first and neutral grays for the rest; 5+ fall back to the full palette.
+ */
+export type SeriesStrategy = 'palette' | 'accent-neutral';
+
 // ---------------------------------------------------------------------------
 // Color palette types
 // ---------------------------------------------------------------------------
@@ -154,6 +181,8 @@ export interface Theme {
   borderRadius: number;
   /** Default chrome text styles. */
   chrome: ThemeChromeDefaults;
+  /** Series color assignment strategy. Default: 'palette' (full categorical). */
+  seriesStrategy: SeriesStrategy;
 }
 
 /**
@@ -170,4 +199,11 @@ export interface Theme {
 export interface ResolvedTheme extends Theme {
   /** Whether dark mode adaptations have been applied to this theme. */
   isDark: boolean;
+  /**
+   * Original light/dark token pairs from the user's ThemeConfig. Used
+   * by adaptTheme() to skip algorithmic adaptation for tokens with
+   * explicit dark values. Engine-internal, not part of the public API.
+   * @internal
+   */
+  _tokenPairs?: Record<string, { light: string; dark: string }>;
 }