@opendata-ai/openchart-core 7.6.1 → 7.8.0

package/dist/index.d.ts

@@ -159,6 +159,183 @@ interface ColumnConfig {
     autoAssign?: boolean;
 }
 
+/**
+ * Theme types: color palettes, typography, spacing, and chrome defaults.
+ *
+ * Theme is the user-facing partial config (all optional).
+ * ResolvedTheme is the engine-internal fully resolved version (no optionals).
+ */
+/**
+ * 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).
+ */
+type TokenValue = string | {
+    light: string;
+    dark: string;
+};
+/**
+ * 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.
+ */
+type SeriesStrategy = 'palette' | 'accent-neutral';
+/** Color palettes for the visualization. */
+interface ThemeColors {
+    /** Categorical palette for nominal data. Array of CSS color strings. */
+    categorical: string[];
+    /** Sequential palettes keyed by name. Each is an array of color stops from light to dark. */
+    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 for the visualization container. */
+    background: string;
+    /** Default text color. */
+    text: string;
+    /** Gridline color. */
+    gridline: string;
+    /** Axis line and tick color. */
+    axis: string;
+    /** Annotation fill color. */
+    annotationFill: string;
+    /** Annotation text color. */
+    annotationText: string;
+    /** Semantic color for positive/up-trend values (e.g. sparkline trend coloring). */
+    positive: string;
+    /** Semantic color for negative/down-trend values (e.g. sparkline trend coloring). */
+    negative: string;
+}
+/** Font size presets for the typography scale. */
+interface ThemeFontSizes {
+    /** Title font size in pixels. */
+    title: number;
+    /** Subtitle font size in pixels. */
+    subtitle: number;
+    /** Body/label font size in pixels. */
+    body: number;
+    /** Small text (source, footer) font size in pixels. */
+    small: number;
+    /** Axis tick label font size in pixels. */
+    axisTick: number;
+    /** KPI metric uppercase label font size in pixels. */
+    metricLabel: number;
+    /** KPI metric primary value font size in pixels. The delta and secondary
+     *  values derive from this (each ~0.55x), so scaling this scales the whole cell. */
+    metricValue: number;
+}
+/** Font weight presets. */
+interface ThemeFontWeights {
+    /** Normal text weight. */
+    normal: number;
+    /** Medium text weight (subtitles). */
+    medium: number;
+    /** Semibold text weight (titles). */
+    semibold: number;
+    /** Bold text weight. */
+    bold: number;
+}
+/** Complete typography configuration. */
+interface ThemeFonts {
+    /** Primary font family. */
+    family: string;
+    /** Monospace font family (for tabular numbers). */
+    mono: string;
+    /** Font sizes. */
+    sizes: ThemeFontSizes;
+    /** Font weights. */
+    weights: ThemeFontWeights;
+}
+/** Spacing configuration in pixels. */
+interface ThemeSpacing {
+    /** Padding inside the visualization container (all sides). */
+    padding: number;
+    /** Gap between chrome elements (title to subtitle, subtitle to chart, 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 the chart area for x-axis tick labels (and optional axis title). */
+    xAxisHeight: number;
+    /** Gap in pixels between the x-axis line and the top of non-rotated tick label text. */
+    xAxisLabelPadding: number;
+}
+/** Default style configuration for a chrome text element. */
+interface ChromeDefaults {
+    /** Font size in pixels. */
+    fontSize: number;
+    /** Font weight. */
+    fontWeight: number;
+    /** Text color (CSS color string). */
+    color: string;
+    /** Line height multiplier. */
+    lineHeight: number;
+}
+/** Default chrome styles for each element type. */
+interface ThemeChromeDefaults {
+    eyebrow: ChromeDefaults;
+    title: ChromeDefaults;
+    subtitle: ChromeDefaults;
+    source: ChromeDefaults;
+    byline: ChromeDefaults;
+    footer: ChromeDefaults;
+}
+/**
+ * Complete theme interface. Used internally after merging user overrides
+ * onto defaults. All fields are required here (this is what the engine
+ * works with).
+ *
+ * Users provide ThemeConfig (from spec.ts) which is the partial/optional
+ * version. The theme resolver deep-merges ThemeConfig onto the default Theme
+ * to produce a ResolvedTheme.
+ */
+interface Theme {
+    /** Color palettes. */
+    colors: ThemeColors;
+    /** Typography settings. */
+    fonts: ThemeFonts;
+    /** Spacing values in pixels. */
+    spacing: ThemeSpacing;
+    /** Border radius for containers and tooltips. */
+    borderRadius: number;
+    /** Default chrome text styles. */
+    chrome: ThemeChromeDefaults;
+    /** Series color assignment strategy. Default: 'palette' (full categorical). */
+    seriesStrategy: SeriesStrategy;
+}
+/**
+ * Fully resolved theme with no optional fields.
+ *
+ * This is the result of resolveTheme(): the default theme with user
+ * overrides deep-merged in. Every property is guaranteed to have a value.
+ * The engine uses ResolvedTheme internally so it never needs null checks.
+ *
+ * Structurally identical to Theme (both have all required fields), but
+ * exists as a separate type for semantic clarity: Theme is the default
+ * definition, ResolvedTheme is the runtime-resolved instance.
+ */
+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;
+    }>;
+}
+
 /**
  * Spec types: the user-facing input contract.
  *
@@ -489,6 +666,36 @@ 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.
+ */
+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;
 }
 /**
  * Encoding object mapping visual channels to data fields.
@@ -583,6 +790,13 @@ 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>;
 }
 /** Encoding channel for graph nodes and edges. */
 interface GraphEncodingChannel {
@@ -727,6 +941,8 @@ 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
@@ -843,6 +1059,20 @@ type Annotation = TextAnnotation | RangeAnnotation | RefLineAnnotation;
  * when no explicit prop is passed.
  */
 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.
+ */
+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.
@@ -860,14 +1090,22 @@ 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?: {
@@ -892,6 +1130,17 @@ 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?: {
@@ -899,6 +1148,12 @@ 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. */
@@ -907,25 +1162,29 @@ 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;
 }
 /**
  * Label density mode controlling how many data labels are shown.
@@ -1000,6 +1259,14 @@ interface LegendConfig {
 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`. */
@@ -1049,6 +1316,16 @@ interface AnimationStagger {
     /** Ordering strategy. Default: 'index' (DOM order) */
     order?: 'index' | 'value' | 'reverse';
 }
+/** Fine-grained responsive behavior configuration. */
+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.
@@ -1267,8 +1544,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". */
@@ -1314,6 +1595,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).
@@ -1639,8 +1927,14 @@ interface SankeySpec {
 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[];
 }
@@ -1652,16 +1946,24 @@ 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. */
@@ -2195,151 +2497,6 @@ interface ChartEventHandlers {
     onTextEdit?: (element: ElementRef, oldText: string, newText: string) => void;
 }
 
-/**
- * Theme types: color palettes, typography, spacing, and chrome defaults.
- *
- * Theme is the user-facing partial config (all optional).
- * ResolvedTheme is the engine-internal fully resolved version (no optionals).
- */
-/** Color palettes for the visualization. */
-interface ThemeColors {
-    /** Categorical palette for nominal data. Array of CSS color strings. */
-    categorical: string[];
-    /** Sequential palettes keyed by name. Each is an array of color stops from light to dark. */
-    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 for the visualization container. */
-    background: string;
-    /** Default text color. */
-    text: string;
-    /** Gridline color. */
-    gridline: string;
-    /** Axis line and tick color. */
-    axis: string;
-    /** Annotation fill color. */
-    annotationFill: string;
-    /** Annotation text color. */
-    annotationText: string;
-    /** Semantic color for positive/up-trend values (e.g. sparkline trend coloring). */
-    positive: string;
-    /** Semantic color for negative/down-trend values (e.g. sparkline trend coloring). */
-    negative: string;
-}
-/** Font size presets for the typography scale. */
-interface ThemeFontSizes {
-    /** Title font size in pixels. */
-    title: number;
-    /** Subtitle font size in pixels. */
-    subtitle: number;
-    /** Body/label font size in pixels. */
-    body: number;
-    /** Small text (source, footer) font size in pixels. */
-    small: number;
-    /** Axis tick label font size in pixels. */
-    axisTick: number;
-    /** KPI metric uppercase label font size in pixels. */
-    metricLabel: number;
-    /** KPI metric primary value font size in pixels. The delta and secondary
-     *  values derive from this (each ~0.55x), so scaling this scales the whole cell. */
-    metricValue: number;
-}
-/** Font weight presets. */
-interface ThemeFontWeights {
-    /** Normal text weight. */
-    normal: number;
-    /** Medium text weight (subtitles). */
-    medium: number;
-    /** Semibold text weight (titles). */
-    semibold: number;
-    /** Bold text weight. */
-    bold: number;
-}
-/** Complete typography configuration. */
-interface ThemeFonts {
-    /** Primary font family. */
-    family: string;
-    /** Monospace font family (for tabular numbers). */
-    mono: string;
-    /** Font sizes. */
-    sizes: ThemeFontSizes;
-    /** Font weights. */
-    weights: ThemeFontWeights;
-}
-/** Spacing configuration in pixels. */
-interface ThemeSpacing {
-    /** Padding inside the visualization container (all sides). */
-    padding: number;
-    /** Gap between chrome elements (title to subtitle, subtitle to chart, 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 the chart area for x-axis tick labels (and optional axis title). */
-    xAxisHeight: number;
-    /** Gap in pixels between the x-axis line and the top of non-rotated tick label text. */
-    xAxisLabelPadding: number;
-}
-/** Default style configuration for a chrome text element. */
-interface ChromeDefaults {
-    /** Font size in pixels. */
-    fontSize: number;
-    /** Font weight. */
-    fontWeight: number;
-    /** Text color (CSS color string). */
-    color: string;
-    /** Line height multiplier. */
-    lineHeight: number;
-}
-/** Default chrome styles for each element type. */
-interface ThemeChromeDefaults {
-    eyebrow: ChromeDefaults;
-    title: ChromeDefaults;
-    subtitle: ChromeDefaults;
-    source: ChromeDefaults;
-    byline: ChromeDefaults;
-    footer: ChromeDefaults;
-}
-/**
- * Complete theme interface. Used internally after merging user overrides
- * onto defaults. All fields are required here (this is what the engine
- * works with).
- *
- * Users provide ThemeConfig (from spec.ts) which is the partial/optional
- * version. The theme resolver deep-merges ThemeConfig onto the default Theme
- * to produce a ResolvedTheme.
- */
-interface Theme {
-    /** Color palettes. */
-    colors: ThemeColors;
-    /** Typography settings. */
-    fonts: ThemeFonts;
-    /** Spacing values in pixels. */
-    spacing: ThemeSpacing;
-    /** Border radius for containers and tooltips. */
-    borderRadius: number;
-    /** Default chrome text styles. */
-    chrome: ThemeChromeDefaults;
-}
-/**
- * Fully resolved theme with no optional fields.
- *
- * This is the result of resolveTheme(): the default theme with user
- * overrides deep-merged in. Every property is guaranteed to have a value.
- * The engine uses ResolvedTheme internally so it never needs null checks.
- *
- * Structurally identical to Theme (both have all required fields), but
- * exists as a separate type for semantic clarity: Theme is the default
- * definition, ResolvedTheme is the runtime-resolved instance.
- */
-interface ResolvedTheme extends Theme {
-    /** Whether dark mode adaptations have been applied to this theme. */
-    isDark: boolean;
-}
-
 /** A rectangle defined by position and dimensions. */
 interface Rect {
     x: number;
@@ -2419,6 +2576,8 @@ 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;
 }
@@ -2893,6 +3052,19 @@ 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. */
+interface AnnotationFootnote {
+    /** 1-indexed footnote number matching the dot marker on the chart. */
+    index: number;
+    /** The original annotation text that was demoted. */
+    text: string;
 }
 /** A single entry in a categorical legend. */
 interface LegendEntry {
@@ -3017,6 +3189,10 @@ 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;
 }
 /** A single field-value pair in a tooltip. */
 interface TooltipField {
@@ -3090,6 +3266,45 @@ interface ResolvedMetricBar {
     /** Cells laid out evenly across the chart width. */
     cells: ResolvedMetricCell[];
 }
+/**
+ * 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.
+ */
+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. */
+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.
  *
@@ -3145,6 +3360,8 @@ 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;
 }
 /** A resolved column definition with computed properties. */
 interface ResolvedColumn {
@@ -3532,8 +3749,10 @@ 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. */
@@ -3745,6 +3964,41 @@ declare function meetsAA(fg: string, bg: string, largeText?: boolean): boolean;
  */
 declare function findAccessibleColor(baseColor: string, bg: string, targetRatio?: number): string;
 
+/**
+ * Color palettes for @opendata-ai.
+ *
+ * Categorical palette leads with cyan and uses an OKLCH-balanced multi-hue
+ * ramp tuned to L≈0.70, C≈0.13–0.15. Hex values are precomputed sRGB
+ * (rather than raw `oklch()` strings) because raw OKLCH strings parse
+ * unreliably through d3-color and the dark-mode adapter's hsl-based
+ * 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 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
+ *
+ * Sequential palettes: 5-7 stops from light to dark.
+ * Diverging palettes: 7 stops with a neutral midpoint.
+ */
+/**
+ * Achromatic surface and supporting-series ramp. Values are the canonical
+ * dark-mode tokens; light-mode equivalents are derived per token in
+ * `theme/dark-mode.ts` and the CSS partials, not mirrored here.
+ */
+declare const ACHROMATIC_RAMP: {
+    readonly fg: "#f7f8f8";
+    readonly fg2: "#d0d6e0";
+    readonly fgMuted: "#a1a1aa";
+    readonly fgSubtle: "#71717a";
+    readonly fgFaint: "#52525b";
+    readonly secondary: "#27272a";
+    readonly card: "#111113";
+    readonly bg: "#09090b";
+};
 /**
  * Default categorical palette. Cyan-led OKLCH-balanced multi-hue ramp.
  *
@@ -3795,12 +4049,30 @@ declare function adaptColorForDarkMode(color: string, lightBg: string, darkBg: s
  * adjusts gridline and axis colors for the dark background.
  */
 declare function adaptTheme(theme: ResolvedTheme): ResolvedTheme;
+/**
+ * Returns a darker variant of a color for use as a foreground stroke on
+ * light backgrounds, where mid-lightness palette colors (e.g. cyan-500
+ * `#06b6d4`) lack contrast against white. Drops HSL lightness by ~12%
+ * absolute (clamped to >= 0) while preserving hue and saturation, which
+ * reproduces the cyan-500 → cyan-600 step the cyan accent originally
+ * needed and works for any other palette accent the user picks.
+ *
+ * Returns the input unchanged when:
+ *   - the color is already dark enough (L <= ~0.40) — further darkening
+ *     just muddies the stroke without adding contrast
+ *   - the color isn't parseable
+ *   - the color is achromatic (NaN hue) — HSL lightness on grays drifts
+ *     toward black instead of staying neutral
+ *
+ * Exposed via the `--oc-accent-strong` CSS token.
+ */
+declare function adaptForLightLineStroke(color: string): string;
 
 /**
  * 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.
  *
@@ -3812,6 +4084,21 @@ declare function adaptTheme(theme: ResolvedTheme): ResolvedTheme;
  */
 declare const DEFAULT_THEME: Theme;
 
+/**
+ * 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.
+ */
+
+/** Editorial preset: the current default look. Exported for explicit selection. */
+declare const editorial: ThemeConfig;
+/** Essay preset: serif display titles, warmer background, generous spacing. */
+declare const essay: ThemeConfig;
+/** Wire preset: dense, mono numerals, tighter chrome. Dashboard/agency feel. */
+declare const wire: ThemeConfig;
+
 /**
  * Theme resolver: deep-merges user overrides onto default theme.
  *
@@ -4393,8 +4680,10 @@ declare function dataTable(data: DataRow[], options?: TableBuilderOptions): Tabl
 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. */
@@ -4423,6 +4712,6 @@ interface TileMapBuilderOptions {
  * tileMap(data, { encoding: { state: { field: 'code' }, value: { field: 'rate' } } })
  * ```
  */
-declare function tileMap(data: Record<string, number | null> | DataRow[], options?: TileMapBuilderOptions): TileMapSpec;
+declare function tileMap(data: Record<string, number | string | null> | DataRow[], options?: TileMapBuilderOptions): TileMapSpec;
 
-export { type A11yMetadata, AXIS_TITLE_GAP, AXIS_TITLE_OFFSET_COMPACT, AXIS_TITLE_OFFSET_DEFAULT, AXIS_TITLE_TRAILING_PAD, type AggregateOp, type AggregateTransform, type AnimationConfig, type AnimationEase, type AnimationPhaseConfig, type AnimationSpec, type AnimationStagger, type Annotation, type AnnotationAnchor, type AnnotationOffset, type AnnotationPosition, type ArcEncoding, type ArcMark, type AreaEncoding, type AreaMark, type AxisConfig, type AxisLabelDensity, type AxisLayout, type AxisTick, BRAND_FONT_SIZE, BRAND_MIN_WIDTH, BRAND_RESERVE_WIDTH, BREAKPOINT_COMPACT_MAX, BREAKPOINT_MEDIUM_MAX, type BarColumnConfig, type BarEncoding, type BarListEncoding, type BarListLayout, type BarListRowMark, type BarListSpec, type BarListSpecWithoutData, type BarTableCell, type BaseLegendLayout, type BinParams, type BinTransform, type Breakpoint, CATEGORICAL_PALETTE, CHART_ENCODING_RULES, CHART_TYPES, COMPACT_WIDTH, type CalculateExpression, type CalculateTransform, type CategoricalLegendLayout, type CategoricalPalette, type CategoryColorsConfig, type CategoryTableCell, type CellStyle, type ChannelRule, type ChartBuilderOptions, type ChartEventHandlers, type ChartLayout, type ChartSpec, type ChartSpecOverride, type ChartSpecWithoutData, type ChartType, type Chrome, type ChromeDefaults, type ChromeKey, type ChromeMode, type ChromeText, type ChromeTextStyle, type CircleEncoding, type ColorBlindnessType, type ColumnConfig, type CompileOptions, type CompileTableOptions, type Condition, type ConditionalValueDef, DEFAULT_THEME, DIVERGING_PALETTES, type DarkMode, type DataRow, type DateGranularity, type Display, type DivergingPalette, EXTENDED_OFFSET_STRATEGIES, type ElementEdit, type ElementRef, type Encoding, type EncodingChannel, type EncodingRule, type EndpointLabelEntry, type EndpointLabelsConfig, type EndpointLabelsLayout, type FieldPredicate, type FieldRef, type FieldType, type FilterPredicate, type FilterTransform, type FlagTableCell, type FoldTransform, GRAPH_ENCODING_RULES, type GradientColorStop, type GradientDef, type GradientLegendLayout, type GradientStop, type GraphChannelRule, type GraphEdge, type GraphEdgeLayout, type GraphEncoding, type GraphEncodingChannel, type GraphLayout, type GraphLayoutConfig, type GraphNode, type GraphNodeLayout, type GraphSpec, type GraphSpecWithoutData, type Gridline, HEIGHT_CRAMPED_MAX, HEIGHT_SHORT_MAX, HPAD_COMPACT_FRACTION, HPAD_COMPACT_MIN, type HeatmapColumnConfig, type HeatmapTableCell, type HeightClass, type ImageColumnConfig, type ImageTableCell, LABEL_GAP_COMPACT, LABEL_GAP_DEFAULT, LABEL_GAP_NARROW_MAX, type LabelCandidate, type LabelConfig, type LabelDensity, type LabelMode, type LabelPriority, type LabelSpec, type LayerSpec, type LayoutStrategy, type LegendConfig, type LegendEntry, type LegendEntryPosition, type LegendLayout, type LegendPosition, type LineEncoding, type LineMark, type LinearGradient, type LogicalAnd, type LogicalNot, type LogicalOr, type LollipopEncoding, MARK_DISPLAY_NAMES, MARK_ENCODING_RULES, MARK_TYPES, MAX_LEFT_LABEL_FRACTION_COMPACT, MAX_LEFT_LABEL_FRACTION_DEFAULT, MAX_LEFT_LABEL_FRACTION_MEDIUM, MAX_LEFT_LABEL_FRACTION_MEDIUM_MAX, type Margins, type Mark, type MarkAria, type MarkDef, type MarkEvent, type MarkType, type MeasureTextFn, type Metric, NARROW_VIEWPORT_MAX, type NodeOverride, OFFSET_STRATEGIES, type OffsetStrategy, type PaginationState, type Point, type PointEncoding, type PointMark, type RadialGradient, type RangeAnnotation, type Rect, type RectEncoding, type RectMark, type RefLineAnnotation, type RelativeTimeRef, type ResolveConfig, type ResolveMode, type ResolvedAnimation, type ResolvedAnnotation, type ResolvedChrome, type ResolvedChromeElement, type ResolvedColumn, type ResolvedLabel, type ResolvedMetricBar, type ResolvedMetricCell, type ResolvedTheme, type RuleMarkLayout, SEQUENTIAL_PALETTES, type SankeyEncoding, type SankeyLayout, type SankeyLinkColor, type SankeyLinkMark, type SankeyNodeAlign, type SankeyNodeMark, type SankeySpec, type SankeySpecWithoutData, type ScaleConfig, type ScaleType, type SequentialPalette, type SeriesStyle, type SortState, type SparklineColumnConfig, type SparklineData, type SparklineTableCell, type StoredVizSpec, TICK_LABEL_OFFSET, TOP_PAD_EXTRA_NARROW, TOP_PAD_NARROW_MAX, type TableBuilderOptions, type TableCell, type TableCellBase, type TableLayout, type TableRow, type TableSpec, type TableSpecWithoutData, type TextAnnotation, type TextEncoding, type TextMarkLayout, type TextStyle, type TextTableCell, type Theme, type ThemeChromeDefaults, type ThemeColors, type ThemeConfig, type ThemeFontSizes, type ThemeFontWeights, type ThemeFonts, type ThemeSpacing, type TickEncoding, type TickMarkLayout, type TileMapBuilderOptions, type TileMapEncoding, type TileMapLayout, type TileMapPalette, type TileMapSpec, type TileMapSpecWithoutData, type TileMapTileMark, type TimeUnit, type TimeUnitTransform, type TooltipContent, type TooltipField, type Transform, type VizSpec, type WindowFieldDef, type WindowOp, type WindowSortField, type WindowTransform, type XAxisExtentInput, X_AXIS_BAND_HEIGHT, X_AXIS_TITLE_BAND, X_AXIS_TITLE_BAND_ROTATED, abbreviateNumber, adaptColorForDarkMode, adaptTheme, areaChart, axisTitleOffset, barChart, buildD3Formatter, buildTemporalFormatter, checkPaletteDistinguishability, columnChart, computeChrome, computeLabelBounds, computeXAxisExtentFromLabels, contrastRatio, dataTable, detectCollision, donutChart, dotChart, elementRef, estimateTextWidth, findAccessibleColor, formatDate, formatNumber, generateAltText, generateAriaLabels, generateDataTable, getAxisTitleOffset, getBreakpoint, getHeightClass, getLayoutStrategy, getRepresentativeColor, heuristicMeasure, inferFieldType, isBarListSpec, isChartSpec, isConditionalDef, isEncodingChannel, isGradientDef, isGraphSpec, isLayerSpec, isRangeAnnotation, isRefLineAnnotation, isSankeySpec, isTableSpec, isTextAnnotation, isTileMapSpec, lineChart, meetsAA, overlapArea, pickLabelColor, pieChart, resolveCollisions, resolveMarkDef, resolveMarkType, resolveMeasurer, resolveTheme, scatterChart, simulateColorBlindness, textAscent, tileMap, wrapText };
+export { type A11yMetadata, ACHROMATIC_RAMP, AXIS_TITLE_GAP, AXIS_TITLE_OFFSET_COMPACT, AXIS_TITLE_OFFSET_DEFAULT, AXIS_TITLE_TRAILING_PAD, type AggregateOp, type AggregateTransform, type AnimationConfig, type AnimationEase, type AnimationPhaseConfig, type AnimationSpec, type AnimationStagger, type Annotation, type AnnotationAnchor, type AnnotationFootnote, type AnnotationOffset, type AnnotationPosition, type ArcEncoding, type ArcMark, type AreaEncoding, type AreaMark, type AxisConfig, type AxisLabelDensity, type AxisLayout, type AxisTick, BRAND_FONT_SIZE, BRAND_MIN_WIDTH, BRAND_RESERVE_WIDTH, BREAKPOINT_COMPACT_MAX, BREAKPOINT_MEDIUM_MAX, type BarColumnConfig, type BarEncoding, type BarListEncoding, type BarListLayout, type BarListRowMark, type BarListSpec, type BarListSpecWithoutData, type BarTableCell, type BaseLegendLayout, type BinParams, type BinTransform, type Breakpoint, CATEGORICAL_PALETTE, CHART_ENCODING_RULES, CHART_TYPES, COMPACT_WIDTH, type CalculateExpression, type CalculateTransform, type CategoricalLegendLayout, type CategoricalPalette, type CategoryColorsConfig, type CategoryTableCell, type CellStyle, type ChannelRule, type ChartBuilderOptions, type ChartEventHandlers, type ChartLayout, type ChartSpec, type ChartSpecOverride, type ChartSpecWithoutData, type ChartType, type Chrome, type ChromeDefaults, type ChromeKey, type ChromeMode, type ChromeText, type ChromeTextStyle, type ChromeThemeOverride, type CircleEncoding, type ColorBlindnessType, type ColumnConfig, type CompileOptions, type CompileTableOptions, type Condition, type ConditionalValueDef, DEFAULT_THEME, DIVERGING_PALETTES, type DarkMode, type DataRow, type DateGranularity, type Display, type DivergingPalette, EXTENDED_OFFSET_STRATEGIES, type ElementEdit, type ElementRef, type Encoding, type EncodingChannel, type EncodingRule, type EndpointLabelEntry, type EndpointLabelsConfig, type EndpointLabelsLayout, type FacetChannel, type FacetLayout, type FacetPanelLayout, type FieldPredicate, type FieldRef, type FieldType, type FilterPredicate, type FilterTransform, type FlagTableCell, type FoldTransform, GRAPH_ENCODING_RULES, type GradientColorStop, type GradientDef, type GradientLegendLayout, type GradientStop, type GraphChannelRule, type GraphEdge, type GraphEdgeLayout, type GraphEncoding, type GraphEncodingChannel, type GraphLayout, type GraphLayoutConfig, type GraphNode, type GraphNodeLayout, type GraphSpec, type GraphSpecWithoutData, type Gridline, HEIGHT_CRAMPED_MAX, HEIGHT_SHORT_MAX, HPAD_COMPACT_FRACTION, HPAD_COMPACT_MIN, type HeatmapColumnConfig, type HeatmapTableCell, type HeightClass, type ImageColumnConfig, type ImageTableCell, LABEL_GAP_COMPACT, LABEL_GAP_DEFAULT, LABEL_GAP_NARROW_MAX, type LabelCandidate, type LabelConfig, type LabelDensity, type LabelMode, type LabelPriority, type LabelSpec, type LayerSpec, type LayoutStrategy, type LegendConfig, type LegendEntry, type LegendEntryPosition, type LegendLayout, type LegendPosition, type LineEncoding, type LineMark, type LinearGradient, type LogicalAnd, type LogicalNot, type LogicalOr, type LollipopEncoding, MARK_DISPLAY_NAMES, MARK_ENCODING_RULES, MARK_TYPES, MAX_LEFT_LABEL_FRACTION_COMPACT, MAX_LEFT_LABEL_FRACTION_DEFAULT, MAX_LEFT_LABEL_FRACTION_MEDIUM, MAX_LEFT_LABEL_FRACTION_MEDIUM_MAX, type Margins, type Mark, type MarkAria, type MarkDef, type MarkEvent, type MarkType, type MeasureTextFn, type Metric, NARROW_VIEWPORT_MAX, type NodeOverride, OFFSET_STRATEGIES, type OffsetStrategy, type PaginationState, type Point, type PointEncoding, type PointMark, type RadialGradient, type RangeAnnotation, type Rect, type RectEncoding, type RectMark, type RefLineAnnotation, type RelativeTimeRef, type ResolveConfig, type ResolveMode, type ResolvedAnimation, type ResolvedAnnotation, type ResolvedChrome, type ResolvedChromeElement, type ResolvedColumn, type ResolvedLabel, type ResolvedMetricBar, type ResolvedMetricCell, type ResolvedTheme, type ResponsiveConfig, type RuleMarkLayout, SEQUENTIAL_PALETTES, type SankeyEncoding, type SankeyLayout, type SankeyLinkColor, type SankeyLinkMark, type SankeyNodeAlign, type SankeyNodeMark, type SankeySpec, type SankeySpecWithoutData, type ScaleConfig, type ScaleType, type SequentialPalette, type SeriesStrategy, type SeriesStyle, type SortState, type SparklineColumnConfig, type SparklineData, type SparklineTableCell, type StoredVizSpec, TICK_LABEL_OFFSET, TOP_PAD_EXTRA_NARROW, TOP_PAD_NARROW_MAX, type TableBuilderOptions, type TableCell, type TableCellBase, type TableLayout, type TableRow, type TableSpec, type TableSpecWithoutData, type TextAnnotation, type TextEncoding, type TextMarkLayout, type TextStyle, type TextTableCell, type Theme, type ThemeChromeDefaults, type ThemeColors, type ThemeConfig, type ThemeFontSizes, type ThemeFontWeights, type ThemeFonts, type ThemeSpacing, type TickEncoding, type TickMarkLayout, type TileMapBuilderOptions, type TileMapEncoding, type TileMapLayout, type TileMapPalette, type TileMapSpec, type TileMapSpecWithoutData, type TileMapTileMark, type TimeUnit, type TimeUnitTransform, type TokenValue, type TooltipContent, type TooltipField, type Transform, type VizSpec, type WindowFieldDef, type WindowOp, type WindowSortField, type WindowTransform, type XAxisExtentInput, X_AXIS_BAND_HEIGHT, X_AXIS_TITLE_BAND, X_AXIS_TITLE_BAND_ROTATED, abbreviateNumber, adaptColorForDarkMode, adaptForLightLineStroke, adaptTheme, areaChart, axisTitleOffset, barChart, buildD3Formatter, buildTemporalFormatter, checkPaletteDistinguishability, columnChart, computeChrome, computeLabelBounds, computeXAxisExtentFromLabels, contrastRatio, dataTable, detectCollision, donutChart, dotChart, editorial, elementRef, essay, estimateTextWidth, findAccessibleColor, formatDate, formatNumber, generateAltText, generateAriaLabels, generateDataTable, getAxisTitleOffset, getBreakpoint, getHeightClass, getLayoutStrategy, getRepresentativeColor, heuristicMeasure, inferFieldType, isBarListSpec, isChartSpec, isConditionalDef, isEncodingChannel, isGradientDef, isGraphSpec, isLayerSpec, isRangeAnnotation, isRefLineAnnotation, isSankeySpec, isTableSpec, isTextAnnotation, isTileMapSpec, lineChart, meetsAA, overlapArea, pickLabelColor, pieChart, resolveCollisions, resolveMarkDef, resolveMarkType, resolveMeasurer, resolveTheme, scatterChart, simulateColorBlindness, textAscent, tileMap, wire, wrapText };