@opendata-ai/openchart-engine 6.25.4 → 6.26.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opendata-ai/openchart-engine",
-  "version": "6.25.4",
+  "version": "6.26.0",
   "description": "Headless compiler for openchart: spec validation, data compilation, scales, and layout",
   "license": "Apache-2.0",
   "author": "Riley Hilliard",
@@ -48,7 +48,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@opendata-ai/openchart-core": "6.25.4",
+    "@opendata-ai/openchart-core": "6.26.0",
     "d3-array": "^3.2.0",
     "d3-format": "^3.1.2",
     "d3-interpolate": "^3.0.0",

package/src/__tests__/compound-labels.test.ts

@@ -0,0 +1,147 @@
+import { describe, expect, it } from 'vitest';
+import { compileChart } from '../compile';
+
+// ---------------------------------------------------------------------------
+// Test data
+// ---------------------------------------------------------------------------
+
+const albumData = [
+  { album: 'Abbey Road', artist: 'The Beatles', sales: 31 },
+  { album: 'Thriller', artist: 'Michael Jackson', sales: 66 },
+  { album: 'Back in Black', artist: 'AC/DC', sales: 50 },
+  { album: 'The Dark Side of the Moon', artist: 'Pink Floyd', sales: 45 },
+  { album: 'Rumours', artist: 'Fleetwood Mac', sales: 40 },
+];
+
+function makeBarSpec(axisConfig?: Record<string, unknown>) {
+  return {
+    mark: 'bar' as const,
+    data: albumData,
+    encoding: {
+      x: { field: 'sales', type: 'quantitative' as const },
+      y: {
+        field: 'album',
+        type: 'nominal' as const,
+        axis: axisConfig,
+      },
+    },
+  };
+}
+
+const compileOpts = { width: 600, height: 400 };
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('compound axis labels (labelField)', () => {
+  it('populates subtitle on ticks when labelField is set', () => {
+    const spec = makeBarSpec({ labelField: 'artist' });
+    const layout = compileChart(spec, compileOpts);
+
+    const yTicks = layout.axes.y?.ticks ?? [];
+    expect(yTicks.length).toBeGreaterThan(0);
+
+    // Every tick should have a subtitle matching the artist for that album
+    for (const tick of yTicks) {
+      const row = albumData.find((r) => r.album === tick.label);
+      expect(row).toBeDefined();
+      expect(tick.subtitle).toBe(row!.artist);
+    }
+  });
+
+  it('does not add subtitle when labelField is omitted', () => {
+    const spec = makeBarSpec();
+    const layout = compileChart(spec, compileOpts);
+
+    const yTicks = layout.axes.y?.ticks ?? [];
+    expect(yTicks.length).toBeGreaterThan(0);
+
+    for (const tick of yTicks) {
+      expect(tick.subtitle).toBeUndefined();
+    }
+  });
+
+  it('handles missing labelField value gracefully', () => {
+    const dataWithMissing = [
+      { album: 'Abbey Road', artist: 'The Beatles', sales: 31 },
+      { album: 'Unknown Album', sales: 20 }, // no artist field
+    ];
+    const spec = {
+      mark: 'bar' as const,
+      data: dataWithMissing,
+      encoding: {
+        x: { field: 'sales', type: 'quantitative' as const },
+        y: {
+          field: 'album',
+          type: 'nominal' as const,
+          axis: { labelField: 'artist' },
+        },
+      },
+    };
+
+    const layout = compileChart(spec, compileOpts);
+    const yTicks = layout.axes.y?.ticks ?? [];
+
+    // Abbey Road should have a subtitle
+    const abbeyRoad = yTicks.find((t) => t.label === 'Abbey Road');
+    expect(abbeyRoad?.subtitle).toBe('The Beatles');
+
+    // Unknown Album has no artist field, so subtitle should be undefined
+    const unknown = yTicks.find((t) => t.label === 'Unknown Album');
+    expect(unknown?.subtitle).toBeUndefined();
+  });
+
+  it('maps subtitle correctly across multiple ticks', () => {
+    const spec = makeBarSpec({ labelField: 'artist' });
+    const layout = compileChart(spec, compileOpts);
+
+    const yTicks = layout.axes.y?.ticks ?? [];
+    expect(yTicks.length).toBe(5);
+
+    // Verify specific mappings
+    const thrillerTick = yTicks.find((t) => t.label === 'Thriller');
+    expect(thrillerTick?.subtitle).toBe('Michael Jackson');
+
+    const rumoursTick = yTicks.find((t) => t.label === 'Rumours');
+    expect(rumoursTick?.subtitle).toBe('Fleetwood Mac');
+  });
+
+  it('preserves subtitle mapping with sort: descending', () => {
+    const spec = {
+      mark: 'bar' as const,
+      data: albumData,
+      encoding: {
+        x: { field: 'sales', type: 'quantitative' as const },
+        y: {
+          field: 'album',
+          type: 'nominal' as const,
+          sort: 'descending' as const,
+          axis: { labelField: 'artist' },
+        },
+      },
+    };
+
+    const layout = compileChart(spec, compileOpts);
+    const yTicks = layout.axes.y?.ticks ?? [];
+
+    // Regardless of sort order, each tick should still map to the right artist
+    for (const tick of yTicks) {
+      const row = albumData.find((r) => r.album === tick.label);
+      expect(row).toBeDefined();
+      expect(tick.subtitle).toBe(row!.artist);
+    }
+  });
+
+  it('reserves wider dimension with labelField than without', () => {
+    const specWith = makeBarSpec({ labelField: 'artist' });
+    const specWithout = makeBarSpec();
+
+    const layoutWith = compileChart(specWith, compileOpts);
+    const layoutWithout = compileChart(specWithout, compileOpts);
+
+    // Chart area x (left edge) should be larger with labelField because more
+    // left margin is reserved for the wider compound labels
+    expect(layoutWith.area.x).toBeGreaterThanOrEqual(layoutWithout.area.x);
+  });
+});

package/src/compile.ts

@@ -77,6 +77,7 @@ import { computeLegend } from './legend/compute';
 import { legendGap } from './legend/wrap';
 import { compileSankey as compileSankeyImpl } from './sankey/compile-sankey';
 import { compileTableLayout } from './tables/compile-table';
+import { compileTileMap as compileTileMapImpl } from './tilemap/compile-tilemap';
 import { computeTooltipDescriptors } from './tooltips/compute';
 import { runTransforms } from './transforms';
 
@@ -310,7 +311,7 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
   // the reserved margin. This way computeLegend positions the legend outside
   // the data area (in the margin) instead of overlapping data marks.
   const legendArea: Rect = { ...chartArea };
-  if (legendLayout.entries.length > 0) {
+  if ('entries' in legendLayout && legendLayout.entries.length > 0) {
     const gap = legendGap(options.width);
     switch (legendLayout.position) {
       case 'top':
@@ -367,7 +368,10 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
   // Compute axes (skip for radial charts)
   const axes = isRadial
     ? { x: undefined, y: undefined }
-    : computeAxes(scales, chartArea, strategy, theme, options.measureText);
+    : computeAxes(scales, chartArea, strategy, theme, options.measureText, {
+        data: renderSpec.data,
+        encoding: renderSpec.encoding as Encoding,
+      });
 
   // INVARIANT 2 — computeGridlines mutates `axes` in place. Downstream consumers read
   // axes.y.gridlines off the same object. Do not introduce a copy-on-write.
@@ -504,7 +508,8 @@ export function compileLayer(spec: LayerSpec, options: CompileOptions): ChartLay
 
   const allMarks: Mark[] = [];
   const seenLabels = new Set<string>();
-  const mergedLegendEntries = [...primaryLayout.legend.entries];
+  const pLegend = primaryLayout.legend;
+  const mergedLegendEntries = 'entries' in pLegend ? [...pLegend.entries] : [];
   for (const entry of mergedLegendEntries) {
     seenLabels.add(entry.label);
   }
@@ -522,10 +527,13 @@ export function compileLayer(spec: LayerSpec, options: CompileOptions): ChartLay
 
     allMarks.push(...leafLayout.marks);
 
-    for (const entry of leafLayout.legend.entries) {
-      if (!seenLabels.has(entry.label)) {
-        seenLabels.add(entry.label);
-        mergedLegendEntries.push(entry);
+    const leafLeg = leafLayout.legend;
+    if ('entries' in leafLeg) {
+      for (const entry of leafLeg.entries) {
+        if (!seenLabels.has(entry.label)) {
+          seenLabels.add(entry.label);
+          mergedLegendEntries.push(entry);
+        }
       }
     }
   }
@@ -535,8 +543,8 @@ export function compileLayer(spec: LayerSpec, options: CompileOptions): ChartLay
     marks: allMarks,
     legend: {
       ...primaryLayout.legend,
-      entries: mergedLegendEntries,
-    },
+      ...('entries' in pLegend ? { entries: mergedLegendEntries } : {}),
+    } as typeof primaryLayout.legend,
   };
 }
 
@@ -812,9 +820,12 @@ function compileLayerIndependent(
 
   // Merge legend entries with deduplication
   const seenLabels = new Set<string>();
-  const mergedLegendEntries = [...layout0.legend.entries];
+  const l0Legend = layout0.legend;
+  const l1Legend = layout1.legend;
+  const mergedLegendEntries = 'entries' in l0Legend ? [...l0Legend.entries] : [];
   for (const entry of mergedLegendEntries) seenLabels.add(entry.label);
-  for (const entry of layout1.legend.entries) {
+  const l1Entries = 'entries' in l1Legend ? l1Legend.entries : [];
+  for (const entry of l1Entries) {
     if (!seenLabels.has(entry.label)) {
       seenLabels.add(entry.label);
       mergedLegendEntries.push(entry);
@@ -856,8 +867,8 @@ function compileLayerIndependent(
     marks,
     legend: {
       ...layout0.legend,
-      entries: mergedLegendEntries,
-    },
+      ...('entries' in l0Legend ? { entries: mergedLegendEntries } : {}),
+    } as typeof layout0.legend,
     tooltipDescriptors: mergedTooltips,
   };
 }
@@ -1111,3 +1122,26 @@ export function compileSankey(
 ): import('@opendata-ai/openchart-core').SankeyLayout {
   return compileSankeyImpl(spec, options);
 }
+
+// ---------------------------------------------------------------------------
+// TileMap compilation
+// ---------------------------------------------------------------------------
+
+/**
+ * Compile a tilemap spec into a TileMapLayout.
+ *
+ * Takes a raw tilemap spec, validates, normalizes, resolves theme and chrome,
+ * computes tile positions, builds tile marks with colors and labels, and
+ * returns a TileMapLayout ready for rendering.
+ *
+ * @param spec - Raw tilemap spec (validated and normalized internally).
+ * @param options - Compile options (width, height, theme, darkMode).
+ * @returns TileMapLayout with computed positions and visual properties.
+ * @throws Error if spec is invalid or not a tilemap type.
+ */
+export function compileTileMap(
+  spec: unknown,
+  options: CompileOptions,
+): import('@opendata-ai/openchart-core').TileMapLayout {
+  return compileTileMapImpl(spec, options);
+}

package/src/compiler/normalize.ts

@@ -21,6 +21,7 @@ import type {
   LayerSpec,
   SankeySpec,
   TableSpec,
+  TileMapSpec,
   VizSpec,
 } from '@opendata-ai/openchart-core';
 import {
@@ -29,10 +30,13 @@ import {
   isLayerSpec,
   isSankeySpec,
   isTableSpec,
+  isTileMapSpec,
   resolveMarkDef,
   resolveMarkType,
 } from '@opendata-ai/openchart-core';
 import type { NormalizedSankeySpec } from '../sankey/types';
+import { STATE_CODE_SET } from '../tilemap/layout';
+import type { NormalizedTileMapSpec } from '../tilemap/types';
 import type {
   NormalizedChartSpec,
   NormalizedChrome,
@@ -303,6 +307,55 @@ function normalizeGraphSpec(spec: GraphSpec, _warnings: string[]): NormalizedGra
   };
 }
 
+function normalizeTileMapSpec(spec: TileMapSpec, warnings: string[]): NormalizedTileMapSpec {
+  // Convert record data to array if needed
+  let data: Record<string, unknown>[] = Array.isArray(spec.data) ? spec.data : [];
+
+  if (!Array.isArray(spec.data)) {
+    // Convert record map to array of rows
+    data = Object.entries(spec.data).map(([state, value]) => ({ state, value }));
+  }
+
+  // Auto-generate encoding if not provided
+  let encoding = spec.encoding;
+  if (!encoding) {
+    encoding = {
+      state: { field: 'state', type: 'nominal' },
+      value: { field: 'value', type: 'quantitative' },
+    };
+  }
+
+  // Count matched states and warn if low match ratio
+  let matchedCount = 0;
+  for (const row of data) {
+    const stateCode = String(row[encoding.state.field]);
+    if (STATE_CODE_SET.has(stateCode)) {
+      matchedCount++;
+    }
+  }
+
+  const matchRatio = data.length > 0 ? matchedCount / data.length : 0;
+  if (matchRatio < 0.5 && data.length > 0) {
+    warnings.push(
+      `TileMap data: only ${matchedCount} of ${data.length} rows have valid US state codes (expected ≥50%)`,
+    );
+  }
+
+  return {
+    type: 'tilemap',
+    data,
+    encoding,
+    palette: spec.palette ?? 'blue',
+    chrome: normalizeChrome(spec.chrome),
+    legend: spec.legend,
+    theme: spec.theme ?? {},
+    darkMode: spec.darkMode ?? 'off',
+    watermark: spec.watermark ?? true,
+    animation: spec.animation,
+    valueFormat: spec.valueFormat,
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
@@ -337,9 +390,12 @@ export function normalizeSpec(spec: VizSpec, warnings: string[] = []): Normalize
   if (isSankeySpec(spec)) {
     return normalizeSankeySpec(spec, warnings);
   }
+  if (isTileMapSpec(spec)) {
+    return normalizeTileMapSpec(spec, warnings);
+  }
   // Should never happen after validation
   throw new Error(
-    `Unknown spec shape. Expected mark (chart), layer, type: 'table', type: 'graph', or type: 'sankey'.`,
+    `Unknown spec shape. Expected mark (chart), layer, type: 'table', type: 'graph', type: 'sankey', or type: 'tilemap'.`,
   );
 }
 

package/src/compiler/types.ts

@@ -29,6 +29,7 @@ import type {
   ThemeConfig,
 } from '@opendata-ai/openchart-core';
 import type { NormalizedSankeySpec } from '../sankey/types';
+import type { NormalizedTileMapSpec } from '../tilemap/types';
 
 // ---------------------------------------------------------------------------
 // NormalizedChrome: all fields are ChromeText objects (not plain strings)
@@ -124,7 +125,8 @@ export type NormalizedSpec =
   | NormalizedChartSpec
   | NormalizedTableSpec
   | NormalizedGraphSpec
-  | NormalizedSankeySpec;
+  | NormalizedSankeySpec
+  | NormalizedTileMapSpec;
 
 // ---------------------------------------------------------------------------
 // Validation types

package/src/compiler/validate.ts

@@ -645,6 +645,120 @@ function validateSankeySpec(spec: Record<string, unknown>, errors: ValidationErr
   }
 }
 
+// ---------------------------------------------------------------------------
+// TileMap validation
+// ---------------------------------------------------------------------------
+
+function validateTileMapSpec(spec: Record<string, unknown>, errors: ValidationError[]): void {
+  // Validate data (can be record or array)
+  if (!spec.data || typeof spec.data !== 'object') {
+    errors.push({
+      message: 'Spec error: tilemap spec requires a "data" field (record or array)',
+      path: 'data',
+      code: 'INVALID_TYPE',
+      suggestion:
+        'Provide data as either a record mapping state codes to values (e.g. { "CA": 12000, "TX": 8500 }) or an array of objects with state and value fields',
+    });
+    return;
+  }
+
+  // If data is an object (record), validate it has at least one entry
+  if (!Array.isArray(spec.data) && Object.keys(spec.data as Record<string, unknown>).length === 0) {
+    errors.push({
+      message: 'Spec error: "data" must have at least one entry',
+      path: 'data',
+      code: 'EMPTY_DATA',
+      suggestion: 'Add at least one state-value pair, e.g. { "CA": 12000 }',
+    });
+    return;
+  }
+
+  // If data is an array, validate it's non-empty
+  if (Array.isArray(spec.data)) {
+    if (spec.data.length === 0) {
+      errors.push({
+        message: 'Spec error: "data" array must be non-empty',
+        path: 'data',
+        code: 'EMPTY_DATA',
+        suggestion: 'Add at least one data row',
+      });
+      return;
+    }
+
+    const firstRow = spec.data[0] as unknown;
+    if (typeof firstRow !== 'object' || firstRow === null || Array.isArray(firstRow)) {
+      errors.push({
+        message: 'Spec error: each item in "data" must be a plain object',
+        path: 'data[0]',
+        code: 'INVALID_TYPE',
+        suggestion: 'Each data item should be an object, e.g. { state: "CA", value: 12000 }',
+      });
+      return;
+    }
+
+    // If data is array, encoding is required
+    if (!spec.encoding || typeof spec.encoding !== 'object') {
+      errors.push({
+        message:
+          'Spec error: tilemap spec with array data requires an "encoding" object with state and value channels',
+        path: 'encoding',
+        code: 'MISSING_FIELD',
+        suggestion:
+          'Add an encoding object, e.g. encoding: { state: { field: "state", type: "nominal" }, value: { field: "value", type: "quantitative" } }',
+      });
+      return;
+    }
+
+    const encoding = spec.encoding as Record<string, unknown>;
+    const dataColumns = new Set(Object.keys(firstRow as Record<string, unknown>));
+    const availableColumns = [...dataColumns].join(', ');
+
+    // Required channels
+    for (const channel of ['state', 'value'] as const) {
+      const ch = encoding[channel] as Record<string, unknown> | undefined;
+      if (!ch || typeof ch !== 'object') {
+        errors.push({
+          message: `Spec error: tilemap encoding requires "${channel}" channel`,
+          path: `encoding.${channel}`,
+          code: 'MISSING_FIELD',
+          suggestion: `Add encoding.${channel} with a field from your data (${availableColumns}). Example: ${channel}: { field: "${[...dataColumns][0] ?? 'myField'}", type: "${channel === 'value' ? 'quantitative' : 'nominal'}" }`,
+        });
+        continue;
+      }
+
+      if (!ch.field || typeof ch.field !== 'string') {
+        errors.push({
+          message: `Spec error: encoding.${channel} must have a "field" string`,
+          path: `encoding.${channel}.field`,
+          code: 'MISSING_FIELD',
+          suggestion: `Add a field name from your data columns: ${availableColumns}`,
+        });
+        continue;
+      }
+
+      if (!dataColumns.has(ch.field as string)) {
+        errors.push({
+          message: `Spec error: encoding.${channel}.field "${ch.field}" does not exist in data. Available columns: ${availableColumns}`,
+          path: `encoding.${channel}.field`,
+          code: 'DATA_FIELD_MISSING',
+          suggestion: `Use one of the available data columns: ${availableColumns}`,
+        });
+      }
+    }
+  }
+
+  // Validate darkMode if provided
+  if (spec.darkMode !== undefined && !VALID_DARK_MODES.has(spec.darkMode as string)) {
+    errors.push({
+      message: 'Spec error: darkMode must be "auto", "force", or "off"',
+      path: 'darkMode',
+      code: 'INVALID_VALUE',
+      suggestion:
+        'Use one of: "auto" (system preference), "force" (always dark), or "off" (always light)',
+    });
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Layer validation
 // ---------------------------------------------------------------------------
@@ -775,24 +889,27 @@ export function validateSpec(spec: unknown): ValidationResult {
   // - Chart specs have a 'mark' field (string or object with type property)
   // - Table specs have type: 'table'
   // - Graph specs have type: 'graph'
+  // - Sankey specs have type: 'sankey'
+  // - TileMap specs have type: 'tilemap'
   const hasLayer = 'layer' in obj && Array.isArray(obj.layer);
   const hasMark = 'mark' in obj;
   const isTable = obj.type === 'table';
   const isGraph = obj.type === 'graph';
   const isSankey = obj.type === 'sankey';
-  const isLayer = hasLayer && !isTable && !isGraph && !isSankey;
-  const isChart = hasMark && !hasLayer && !isTable && !isGraph && !isSankey;
+  const isTileMap = obj.type === 'tilemap';
+  const isLayer = hasLayer && !isTable && !isGraph && !isSankey && !isTileMap;
+  const isChart = hasMark && !hasLayer && !isTable && !isGraph && !isSankey && !isTileMap;
 
-  if (!isChart && !isTable && !isGraph && !isSankey && !isLayer) {
+  if (!isChart && !isTable && !isGraph && !isSankey && !isTileMap && !isLayer) {
     return {
       valid: false,
       errors: [
         {
           message:
-            'Spec error: spec must have a "mark" field for charts, a "layer" array for layered charts, or a "type" field for tables/graphs/sankey',
+            'Spec error: spec must have a "mark" field for charts, a "layer" array for layered charts, or a "type" field for tables/graphs/sankey/tilemap',
           path: 'mark',
           code: 'MISSING_FIELD',
-          suggestion: `Add a "mark" field for charts (e.g. mark: "bar"), a "layer" array for layered charts, or a "type" field for tables/graphs/sankey (type: "table", type: "graph", or type: "sankey"). Valid mark types: ${[...MARK_TYPES].join(', ')}`,
+          suggestion: `Add a "mark" field for charts (e.g. mark: "bar"), a "layer" array for layered charts, or a "type" field for tables/graphs/sankey/tilemap (type: "table", type: "graph", type: "sankey", or type: "tilemap"). Valid mark types: ${[...MARK_TYPES].join(', ')}`,
         },
       ],
       normalized: null,
@@ -837,6 +954,8 @@ export function validateSpec(spec: unknown): ValidationResult {
     validateGraphSpec(obj, errors);
   } else if (isSankey) {
     validateSankeySpec(obj, errors);
+  } else if (isTileMap) {
+    validateTileMapSpec(obj, errors);
   }
 
   if (errors.length > 0) {

package/src/index.ts

@@ -12,7 +12,14 @@
 // Main compile API
 // ---------------------------------------------------------------------------
 
-export { compileChart, compileGraph, compileLayer, compileSankey, compileTable } from './compile';
+export {
+  compileChart,
+  compileGraph,
+  compileLayer,
+  compileSankey,
+  compileTable,
+  compileTileMap,
+} from './compile';
 
 // ---------------------------------------------------------------------------
 // Animation resolution
@@ -37,6 +44,12 @@ export type {
 
 export type { NormalizedSankeySpec } from './sankey/types';
 
+// ---------------------------------------------------------------------------
+// TileMap compilation types
+// ---------------------------------------------------------------------------
+
+export type { NormalizedTileMapSpec } from './tilemap/types';
+
 // ---------------------------------------------------------------------------
 // Compiler pipeline (spec validation, normalization, generic compile)
 // ---------------------------------------------------------------------------
@@ -100,5 +113,7 @@ export type {
   SankeySpec,
   TableLayout,
   TableSpec,
+  TileMapLayout,
+  TileMapSpec,
   VizSpec,
 } from '@opendata-ai/openchart-core';

package/src/layout/axes/ticks.ts

@@ -5,7 +5,12 @@
  * not from the chart area. Density thinning lives in ./thinning.ts.
  */
 
-import type { AxisLabelDensity, AxisTick, MeasureTextFn } from '@opendata-ai/openchart-core';
+import type {
+  AxisLabelDensity,
+  AxisTick,
+  DataRow,
+  MeasureTextFn,
+} from '@opendata-ai/openchart-core';
 import {
   abbreviateNumber,
   buildD3Formatter,
@@ -221,6 +226,7 @@ export function categoricalTicks(
   fontSize?: number,
   fontWeight?: number,
   measureText?: MeasureTextFn,
+  subtitleContext?: { data: DataRow[]; fieldName: string; labelField: string },
 ): AxisTick[] {
   const scale = resolvedScale.scale as D3CategoricalScale;
   const domain: string[] = scale.domain();
@@ -275,6 +281,23 @@ export function categoricalTicks(
   }
   // vertical band scale (horizontal bar y-axis): always show all labels
 
+  let subtitleMap: Map<string, string> | undefined;
+  if (subtitleContext) {
+    const { data, fieldName, labelField } = subtitleContext;
+    if (data.length > 0) {
+      subtitleMap = new Map();
+      for (const row of data) {
+        const key = String(row[fieldName] ?? '');
+        if (!subtitleMap.has(key)) {
+          const val = row[labelField];
+          if (val != null) {
+            subtitleMap.set(key, String(val));
+          }
+        }
+      }
+    }
+  }
+
   const ticks = selectedValues.map((value: string) => {
     // Band scales: use the center of the band
     const bandScale = resolvedScale.type === 'band' ? (scale as ScaleBand<string>) : null;
@@ -282,11 +305,20 @@ export function categoricalTicks(
       ? (bandScale(value) ?? 0) + bandScale.bandwidth() / 2
       : ((scale(value) as number | undefined) ?? 0);
 
-    return {
+    const tick: AxisTick = {
       value,
       position: pos,
       label: value,
     };
+
+    if (subtitleMap) {
+      const subtitle = subtitleMap.get(value);
+      if (subtitle !== undefined) {
+        tick.subtitle = subtitle;
+      }
+    }
+
+    return tick;
   });
 
   return ticks;