@opendata-ai/openchart-engine 6.25.3 → 6.26.0

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;

package/src/layout/axes.ts

@@ -10,6 +10,8 @@ import type {
   AxisLabelDensity,
   AxisLayout,
   AxisTick,
+  DataRow,
+  Encoding,
   Gridline,
   LayoutStrategy,
   MeasureTextFn,
@@ -191,6 +193,14 @@ export interface AxesResult {
   y?: AxisLayout;
 }
 
+/** Optional data context for axis computation (enables labelField subtitles). */
+export interface AxesDataContext {
+  /** The data rows for subtitle lookup. */
+  data: DataRow[];
+  /** The encoding object to resolve field names. */
+  encoding: Encoding;
+}
+
 /**
  * Compute axis layouts with tick positions, labels, and axis lines.
  *
@@ -199,6 +209,7 @@ export interface AxesResult {
  * @param strategy - Responsive layout strategy.
  * @param theme - Resolved theme for styling.
  * @param measureText - Optional real text measurement from the adapter.
+ * @param dataContext - Optional data context for labelField subtitle support.
  */
 export function computeAxes(
   scales: ResolvedScales,
@@ -206,6 +217,7 @@ export function computeAxes(
   strategy: LayoutStrategy,
   theme: ResolvedTheme,
   measureText?: MeasureTextFn,
+  dataContext?: AxesDataContext,
 ): AxesResult {
   const result: AxesResult = {};
   const baseDensity = strategy.axisLabelDensity;
@@ -362,7 +374,21 @@ export function computeAxes(
     if (axisConfig?.values) {
       allTicks = resolveExplicitTicks(axisConfig.values, scales.y);
     } else if (!isContinuousY) {
-      allTicks = categoricalTicks(scales.y, yDensity, 'vertical');
+      const yFieldName = dataContext?.encoding.y?.field;
+      const yLabelField = axisConfig?.labelField;
+      allTicks = categoricalTicks(
+        scales.y,
+        yDensity,
+        'vertical',
+        undefined,
+        undefined,
+        undefined,
+        undefined,
+        undefined,
+        yFieldName && yLabelField && dataContext
+          ? { data: dataContext.data, fieldName: yFieldName, labelField: yLabelField }
+          : undefined,
+      );
     } else {
       allTicks = continuousTicks(scales.y, yDensity, yTargetCount);
     }

package/src/layout/dimensions.ts

@@ -275,10 +275,26 @@ export function computeDimensions(
     ) {
       // Category labels on the left for bar/dot charts
       const yField = encoding.y.field;
+      const yLabelField = (encoding.y.axis as Record<string, unknown> | undefined)?.labelField as
+        | string
+        | undefined;
       let maxLabelWidth = 0;
       for (const row of spec.data) {
         const label = String(row[yField] ?? '');
-        const w = estimateTextWidth(label, theme.fonts.sizes.axisTick, theme.fonts.weights.normal);
+        let w = estimateTextWidth(label, theme.fonts.sizes.axisTick, theme.fonts.weights.normal);
+        // When labelField is set, add a gap and the subtitle width
+        if (yLabelField) {
+          const subtitle = String(row[yLabelField] ?? '');
+          if (subtitle) {
+            const gap = theme.fonts.sizes.axisTick * 0.6;
+            const subtitleWidth = estimateTextWidth(
+              subtitle,
+              theme.fonts.sizes.axisTick,
+              theme.fonts.weights.normal,
+            );
+            w += gap + subtitleWidth;
+          }
+        }
         if (w > maxLabelWidth) maxLabelWidth = w;
       }
       if (maxLabelWidth > 0) {
@@ -359,7 +375,7 @@ export function computeDimensions(
   }
 
   // Reserve legend space
-  if (legendLayout.entries.length > 0) {
+  if ('entries' in legendLayout && legendLayout.entries.length > 0) {
     const gap = legendGap(width);
     if (legendLayout.position === 'right' || legendLayout.position === 'bottom-right') {
       margins.right += legendLayout.bounds.width + 8;
@@ -407,7 +423,9 @@ export function computeDimensions(
       const gap = legendGap(width);
       margins.top =
         newTop +
-        (legendLayout.entries.length > 0 && legendLayout.position === 'top'
+        ('entries' in legendLayout &&
+        legendLayout.entries.length > 0 &&
+        legendLayout.position === 'top'
           ? legendLayout.bounds.height + gap
           : 0);
       margins.bottom = newBottom;

package/src/sankey/compile-sankey.ts

@@ -312,7 +312,7 @@ export function compileSankey(spec: unknown, options: CompileOptions): SankeyLay
   );
 
   // Reserve legend space by shrinking the drawing area
-  const legendGap = legend.entries.length > 0 ? 4 : 0;
+  const legendGap = 'entries' in legend && legend.entries.length > 0 ? 4 : 0;
   const area: Rect = {
     x: fullArea.x,
     y: fullArea.y + legend.bounds.height + legendGap,

package/src/tilemap/__tests__/compile-tilemap.test.ts

@@ -0,0 +1,322 @@
+import { describe, expect, it } from 'vitest';
+import { compileTileMap } from '../../compile';
+
+// ---------------------------------------------------------------------------
+// Shared fixtures
+// ---------------------------------------------------------------------------
+
+const basicSpec = {
+  type: 'tilemap' as const,
+  data: { CA: 5.4, TX: 4.1, NY: 4.5, FL: 3.3, IL: 4.6 } as Record<string, number>,
+};
+
+const fullSpec = {
+  type: 'tilemap' as const,
+  data: {
+    AL: 2.7,
+    AK: 6.4,
+    AZ: 3.5,
+    AR: 3.4,
+    CA: 5.4,
+    CO: 3.4,
+    CT: 4.1,
+    DE: 4.4,
+    FL: 3.3,
+    GA: 3.4,
+    HI: 3.2,
+    ID: 3.0,
+    IL: 4.6,
+    IN: 3.3,
+    IA: 2.7,
+    KS: 3.2,
+    KY: 4.4,
+    LA: 3.6,
+    ME: 3.6,
+    MD: 1.8,
+    MA: 3.3,
+    MI: 4.2,
+    MN: 2.8,
+    MS: 3.7,
+    MO: 3.5,
+    MT: 2.9,
+    NE: 2.2,
+    NV: 5.4,
+    NH: 2.4,
+    NJ: 4.8,
+    NM: 4.1,
+    NY: 4.5,
+    NC: 3.5,
+    ND: 1.9,
+    OH: 4.0,
+    OK: 3.9,
+    OR: 4.2,
+    PA: 3.4,
+    RI: 3.8,
+    SC: 3.3,
+    SD: 2.0,
+    TN: 3.5,
+    TX: 4.1,
+    UT: 2.9,
+    VT: 2.3,
+    VA: 2.9,
+    WA: 4.6,
+    WV: 4.0,
+    WI: 2.9,
+    WY: 3.2,
+    DC: 5.2,
+  } as Record<string, number>,
+};
+
+const defaultOptions = { width: 600, height: 400 };
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('compileTileMap', () => {
+  it('always renders all 51 state tiles', () => {
+    const result = compileTileMap(basicSpec, defaultOptions);
+    expect(result.tiles).toHaveLength(51);
+  });
+
+  it('marks data-bearing states as hasData: true', () => {
+    const result = compileTileMap(basicSpec, defaultOptions);
+
+    const caTile = result.tiles.find((t) => t.stateCode === 'CA')!;
+    expect(caTile.hasData).toBe(true);
+    expect(caTile.value).toBe(5.4);
+
+    const dataTiles = result.tiles.filter((t) => t.hasData);
+    expect(dataTiles).toHaveLength(5);
+    const codes = dataTiles.map((t) => t.stateCode).sort();
+    expect(codes).toEqual(['CA', 'FL', 'IL', 'NY', 'TX']);
+  });
+
+  it('marks missing states as hasData: false with neutral fill', () => {
+    const result = compileTileMap(basicSpec, defaultOptions);
+
+    const akTile = result.tiles.find((t) => t.stateCode === 'AK')!;
+    expect(akTile).toBeDefined();
+    expect(akTile.hasData).toBe(false);
+    expect(akTile.value).toBeNull();
+    expect(akTile.formattedValue).toBe('–');
+  });
+
+  it('all tiles have valid position and size (x >= 0, y >= 0, size > 0)', () => {
+    const result = compileTileMap(fullSpec, defaultOptions);
+
+    for (const tile of result.tiles) {
+      expect(tile.x).toBeGreaterThanOrEqual(0);
+      expect(tile.y).toBeGreaterThanOrEqual(0);
+      expect(tile.size).toBeGreaterThan(0);
+    }
+  });
+
+  it('data tiles have fill colors from the sequential palette', () => {
+    const result = compileTileMap(basicSpec, defaultOptions);
+
+    const dataTiles = result.tiles.filter((t) => t.hasData);
+    for (const tile of dataTiles) {
+      expect(tile.fill).toBeTruthy();
+      expect(typeof tile.fill).toBe('string');
+    }
+
+    const fills = new Set(dataTiles.map((t) => t.fill));
+    expect(fills.size).toBeGreaterThan(1);
+  });
+
+  it('compiles tabular DataRow[] data with encoding', () => {
+    const spec = {
+      type: 'tilemap' as const,
+      data: [
+        { code: 'CA', rate: 5.4 },
+        { code: 'TX', rate: 4.1 },
+        { code: 'NY', rate: 4.5 },
+      ],
+      encoding: {
+        state: { field: 'code', type: 'nominal' as const },
+        value: { field: 'rate', type: 'quantitative' as const },
+      },
+    };
+
+    const result = compileTileMap(spec, defaultOptions);
+
+    expect(result.tiles).toHaveLength(51);
+    const dataTiles = result.tiles.filter((t) => t.hasData);
+    expect(dataTiles).toHaveLength(3);
+    const codes = dataTiles.map((t) => t.stateCode).sort();
+    expect(codes).toEqual(['CA', 'NY', 'TX']);
+  });
+
+  it('handles null values in record-map data as missing', () => {
+    const spec = {
+      type: 'tilemap' as const,
+      data: { CA: 5.4, TX: null, NY: 4.5 } as Record<string, number | null>,
+    };
+
+    const result = compileTileMap(spec, defaultOptions);
+
+    const caTile = result.tiles.find((t) => t.stateCode === 'CA')!;
+    expect(caTile.hasData).toBe(true);
+
+    const txTile = result.tiles.find((t) => t.stateCode === 'TX')!;
+    expect(txTile.hasData).toBe(false);
+    expect(txTile.value).toBeNull();
+  });
+
+  describe('gradient legend', () => {
+    it('has correct min/max labels', () => {
+      const result = compileTileMap(basicSpec, defaultOptions);
+
+      expect(result.gradientLegend).not.toBeNull();
+      expect(result.gradientLegend!.minLabel).toBeTruthy();
+      expect(result.gradientLegend!.maxLabel).toBeTruthy();
+      expect(Number(result.gradientLegend!.minLabel)).toBeLessThan(
+        Number(result.gradientLegend!.maxLabel),
+      );
+    });
+
+    it('has colorStops', () => {
+      const result = compileTileMap(basicSpec, defaultOptions);
+
+      expect(result.gradientLegend!.colorStops.length).toBeGreaterThan(0);
+      for (const stop of result.gradientLegend!.colorStops) {
+        expect(stop.offset).toBeGreaterThanOrEqual(0);
+        expect(stop.offset).toBeLessThanOrEqual(1);
+        expect(stop.color).toBeTruthy();
+      }
+    });
+
+    it('is null when legend.show is false', () => {
+      const spec = { ...basicSpec, legend: { show: false } };
+      const result = compileTileMap(spec, defaultOptions);
+
+      expect(result.gradientLegend).toBeNull();
+    });
+  });
+
+  describe('valueFormat', () => {
+    it('applies to tile formattedValue', () => {
+      const spec = { ...basicSpec, valueFormat: '.1f' };
+      const result = compileTileMap(spec, defaultOptions);
+
+      const caTile = result.tiles.find((t) => t.stateCode === 'CA');
+      expect(caTile).toBeDefined();
+      expect(caTile!.formattedValue).toBe('5.4');
+    });
+  });
+
+  describe('dark mode', () => {
+    it('reverses palette direction compared to light mode', () => {
+      const lightResult = compileTileMap(basicSpec, defaultOptions);
+      const darkResult = compileTileMap(basicSpec, { ...defaultOptions, darkMode: true });
+
+      const lightFL = lightResult.tiles.find((t) => t.stateCode === 'FL');
+      const darkFL = darkResult.tiles.find((t) => t.stateCode === 'FL');
+      expect(lightFL!.fill).not.toBe(darkFL!.fill);
+    });
+  });
+
+  describe('chrome', () => {
+    it('resolves title and subtitle', () => {
+      const spec = {
+        ...basicSpec,
+        chrome: {
+          title: 'Test Title',
+          subtitle: 'Test Subtitle',
+        },
+      };
+      const result = compileTileMap(spec, defaultOptions);
+
+      expect(result.chrome.title).toBeDefined();
+      expect(result.chrome.title!.text).toBe('Test Title');
+      expect(result.chrome.subtitle).toBeDefined();
+      expect(result.chrome.subtitle!.text).toBe('Test Subtitle');
+    });
+  });
+
+  describe('tooltip descriptors', () => {
+    it('contains entries for all tiles', () => {
+      const result = compileTileMap(basicSpec, defaultOptions);
+
+      expect(result.tooltipDescriptors.has('CA')).toBe(true);
+      expect(result.tooltipDescriptors.has('TX')).toBe(true);
+      expect(result.tooltipDescriptors.size).toBe(51);
+    });
+
+    it('tooltip has title and value field', () => {
+      const result = compileTileMap(basicSpec, defaultOptions);
+
+      const tooltip = result.tooltipDescriptors.get('CA')!;
+      expect(tooltip.title).toBe('California');
+      expect(tooltip.fields.length).toBeGreaterThan(0);
+      expect(tooltip.fields.some((f) => f.label === 'Value')).toBe(true);
+    });
+  });
+
+  describe('a11y', () => {
+    it('generates descriptive alt text', () => {
+      const result = compileTileMap(basicSpec, defaultOptions);
+
+      expect(result.a11y.altText).toContain('Tile map');
+      expect(result.a11y.altText).toContain('US states');
+    });
+
+    it('has a data table fallback', () => {
+      const result = compileTileMap(basicSpec, defaultOptions);
+
+      expect(result.a11y.dataTableFallback.length).toBeGreaterThan(0);
+    });
+  });
+
+  describe('validation', () => {
+    it('throws on non-tilemap spec', () => {
+      const chartSpec = {
+        mark: 'bar' as const,
+        data: [{ x: 1, y: 2 }],
+        encoding: {
+          x: { field: 'x', type: 'quantitative' as const },
+          y: { field: 'y', type: 'quantitative' as const },
+        },
+      };
+
+      expect(() => compileTileMap(chartSpec, defaultOptions)).toThrow(/non-tilemap/);
+    });
+
+    it('throws on empty record-map data', () => {
+      const spec = {
+        type: 'tilemap' as const,
+        data: {} as Record<string, number>,
+      };
+
+      expect(() => compileTileMap(spec, defaultOptions)).toThrow();
+    });
+  });
+
+  describe('dimensions', () => {
+    it('reflects the compile options', () => {
+      const result = compileTileMap(basicSpec, defaultOptions);
+
+      expect(result.width).toBe(600);
+      expect(result.height).toBe(400);
+    });
+
+    it('works with different container sizes', () => {
+      const result = compileTileMap(basicSpec, { width: 800, height: 600 });
+
+      expect(result.width).toBe(800);
+      expect(result.height).toBe(600);
+    });
+  });
+
+  describe('palette', () => {
+    it('uses the specified palette (data tiles differ between palettes)', () => {
+      const blueResult = compileTileMap(basicSpec, defaultOptions);
+      const greenResult = compileTileMap({ ...basicSpec, palette: 'green' }, defaultOptions);
+
+      const blueCa = blueResult.tiles.find((t) => t.stateCode === 'CA')!;
+      const greenCa = greenResult.tiles.find((t) => t.stateCode === 'CA')!;
+      expect(blueCa.fill).not.toBe(greenCa.fill);
+    });
+  });
+});