@opendata-ai/openchart-engine 7.10.0 → 8.0.0-rc.1

package/src/geo/join.ts

@@ -0,0 +1,115 @@
+import type { CompileWarning } from '@opendata-ai/openchart-core';
+
+export function normalizeFips(value: string | number, digits: 2 | 5 = 2): string {
+  return String(value).padStart(digits, '0');
+}
+
+function detectKeyFormat(keys: string[]): string | null {
+  if (keys.length === 0) return null;
+  const allNumeric = keys.every((k) => /^\d+$/.test(k));
+  if (allNumeric) {
+    const maxLen = Math.max(...keys.map((k) => k.length));
+    if (maxLen <= 2) return 'state-fips';
+    if (maxLen <= 3) return 'iso-numeric';
+    if (maxLen <= 5) return 'county-fips';
+  }
+  if (keys.every((k) => /^[A-Z]{2}$/.test(k))) return 'iso-alpha2';
+  if (keys.every((k) => /^[A-Z]{3}$/.test(k))) return 'iso-alpha3';
+  return null;
+}
+
+function suggestNormalization(unmatchedKeys: string[], featureIds: string[]): string | null {
+  const dataFormat = detectKeyFormat(unmatchedKeys);
+  const featureFormat = detectKeyFormat(featureIds);
+
+  if (dataFormat === 'state-fips' && featureFormat === 'state-fips') {
+    const needsPadding = unmatchedKeys.some((k) => k.length === 1);
+    if (needsPadding) return 'Data keys appear to need zero-padding (e.g. "1" -> "01").';
+  }
+  if (dataFormat === 'county-fips') {
+    const needsPadding = unmatchedKeys.some((k) => k.length < 5);
+    if (needsPadding)
+      return 'County FIPS codes should be 5 digits with zero-padding (e.g. "1001" -> "01001").';
+  }
+  return null;
+}
+
+export interface JoinResult {
+  joined: Map<string | number, Record<string, unknown>>;
+  warnings: CompileWarning[];
+}
+
+export function joinDataToFeatures(
+  features: Array<{ id: string | number; properties: Record<string, unknown> }>,
+  data: Record<string, unknown>[],
+  dataKeyField: string,
+  featureIdField: string,
+): JoinResult {
+  const warnings: CompileWarning[] = [];
+
+  const dataLookup = new Map<string, Record<string, unknown>>();
+  for (const row of data) {
+    const key = String(row[dataKeyField]);
+    dataLookup.set(key, row);
+  }
+
+  const joined = new Map<string | number, Record<string, unknown>>();
+  const usedDataKeys = new Set<string>();
+  let lowerLookup: Map<string, Record<string, unknown>> | null = null;
+  let unmatchedFeatureCount = 0;
+
+  for (const feature of features) {
+    const featureId =
+      featureIdField === 'id'
+        ? String(feature.id)
+        : String(feature.properties[featureIdField] ?? feature.id);
+
+    let match = dataLookup.get(featureId);
+
+    // Try case-insensitive fallback for name-based joins
+    if (!match) {
+      if (!lowerLookup) {
+        lowerLookup = new Map<string, Record<string, unknown>>();
+        for (const [key, row] of dataLookup) {
+          lowerLookup.set(key.toLowerCase(), row);
+        }
+      }
+      match = lowerLookup.get(featureId.toLowerCase());
+    }
+
+    if (match) {
+      joined.set(feature.id, match);
+      usedDataKeys.add(String(match[dataKeyField]));
+    } else {
+      unmatchedFeatureCount++;
+    }
+  }
+
+  const unmatchedDataKeys: string[] = [];
+  for (const key of dataLookup.keys()) {
+    if (!usedDataKeys.has(key)) {
+      unmatchedDataKeys.push(key);
+    }
+  }
+
+  if (unmatchedDataKeys.length > 0) {
+    const sampleKeys = unmatchedDataKeys.slice(0, 5);
+    const sampleFeatureIds = features.slice(0, 3).map((f) => String(f.id));
+    const suggestion = suggestNormalization(unmatchedDataKeys, sampleFeatureIds);
+    warnings.push({
+      code: 'UNMATCHED_DATA_KEYS',
+      message: `${unmatchedDataKeys.length} data row(s) matched no geo feature. Keys: ${sampleKeys.join(', ')}${unmatchedDataKeys.length > 5 ? ` (and ${unmatchedDataKeys.length - 5} more)` : ''}.${suggestion ? ` ${suggestion}` : ''} Expected format matches feature IDs like: ${sampleFeatureIds.join(', ')}.`,
+      context: { keys: unmatchedDataKeys },
+    });
+  }
+
+  if (unmatchedFeatureCount > 0) {
+    warnings.push({
+      code: 'UNMATCHED_FEATURES',
+      message: `${unmatchedFeatureCount} geo feature(s) have no matching data and will use neutral fill.`,
+      context: { count: unmatchedFeatureCount },
+    });
+  }
+
+  return { joined, warnings };
+}

package/src/geo/projections.ts

@@ -0,0 +1,45 @@
+import type { MapProjection } from '@opendata-ai/openchart-core';
+import type { GeoIdentityTransform, GeoPermissibleObjects, GeoProjection } from 'd3-geo';
+import { geoAlbersUsa, geoBounds, geoEqualEarth, geoIdentity, geoMercator } from 'd3-geo';
+
+// Mercator inflates polar regions toward infinity. Fitting against features
+// entirely below this latitude (Antarctica) wastes most of the map area on
+// empty ocean. Exclude them from the fit; they still render if in view.
+const MERCATOR_FIT_MIN_LAT = -60;
+
+export function createProjection(
+  type: MapProjection,
+  width: number,
+  height: number,
+  geojson: GeoPermissibleObjects,
+): GeoProjection | GeoIdentityTransform {
+  if (type === 'identity') {
+    return geoIdentity().fitSize([width, height], geojson);
+  }
+
+  const projection =
+    type === 'albersUsa' ? geoAlbersUsa() : type === 'equalEarth' ? geoEqualEarth() : geoMercator();
+
+  const fitGeometry = type === 'mercator' ? excludePolarFeatures(geojson) : geojson;
+  projection.fitSize([width, height], fitGeometry);
+  return projection;
+}
+
+function excludePolarFeatures(geojson: GeoPermissibleObjects): GeoPermissibleObjects {
+  // GeoPermissibleObjects doesn't include FeatureCollection in its type union,
+  // but topojson.feature() returns one at runtime. Work with the runtime shape.
+  const obj = geojson as unknown as Record<string, unknown>;
+  if (obj.type !== 'FeatureCollection' || !Array.isArray(obj.features)) return geojson;
+
+  const features = obj.features as Array<Record<string, unknown>>;
+  const filtered = features.filter((f) => {
+    try {
+      const b = geoBounds(f as unknown as GeoPermissibleObjects);
+      return b[1][1] > MERCATOR_FIT_MIN_LAT;
+    } catch {
+      return true;
+    }
+  });
+  if (filtered.length === 0) return geojson;
+  return { type: 'FeatureCollection', features: filtered } as unknown as GeoPermissibleObjects;
+}

package/src/geo/types.ts

@@ -0,0 +1,24 @@
+import type {
+  AnimationSpec,
+  DarkMode,
+  LegendConfig,
+  MapEncoding,
+  MapGeo,
+  ThemeConfig,
+} from '@opendata-ai/openchart-core';
+
+import type { NormalizedChrome } from '../compiler/types';
+
+export interface NormalizedMapSpec {
+  type: 'map';
+  geo: Required<MapGeo>;
+  data: Record<string, unknown>[];
+  encoding: MapEncoding;
+  chrome: NormalizedChrome;
+  legend?: LegendConfig;
+  theme: ThemeConfig;
+  darkMode: DarkMode;
+  watermark: boolean;
+  animation?: AnimationSpec;
+  valueFormat?: string;
+}

package/src/graphs/__tests__/compile-graph.test.ts

@@ -228,6 +228,31 @@ describe('compileGraph', () => {
     });
   });
 
+  describe('legend', () => {
+    it('is empty when there is no color encoding and no clustering', () => {
+      // Every node shares one fill, so a legend would list each node label
+      // against an identical swatch and communicate nothing.
+      const result = compileGraph(makeBasicGraphSpec(), compileOptions);
+
+      expect(result.legend.entries).toEqual([]);
+    });
+
+    it('entries come from the nodeColor field, not node labels', () => {
+      const result = compileGraph(makeEncodedGraphSpec(), compileOptions);
+
+      const labels = result.legend.entries.map((e) => e.label).sort();
+      expect(labels).toEqual(['X', 'Y']);
+    });
+
+    it('is empty when the nodeColor field has only one category', () => {
+      const spec = makeEncodedGraphSpec();
+      for (const node of spec.nodes) node.group = 'X';
+      const result = compileGraph(spec, compileOptions);
+
+      expect(result.legend.entries).toEqual([]);
+    });
+  });
+
   describe('tooltips', () => {
     it('generates tooltip descriptors for each node', () => {
       const result = compileGraph(makeBasicGraphSpec(), compileOptions);

package/src/graphs/compile-graph.ts

@@ -22,14 +22,21 @@ import type {
   TooltipContent,
   TooltipField,
 } from '@opendata-ai/openchart-core';
-import { adaptTheme, computeChrome, resolveTheme } from '@opendata-ai/openchart-core';
-
+import {
+  adaptTheme,
+  computeChrome,
+  defaultNumberFormatter,
+  resolveTheme,
+} from '@opendata-ai/openchart-core';
+import { emitSpecWarnings } from '../compile/spec-sugar';
 import { compile as compileSpec } from '../compiler/index';
 import type { NormalizedGraphSpec } from '../compiler/types';
 import { applyCommunityColors, assignCommunities, buildCommunityColorMap } from './community';
 import { resolveEdgeVisuals, resolveNodeVisuals } from './encoding';
 import type { CompiledGraphNode, GraphCompilation, SimulationConfig } from './types';
 
+const graphNumberFormatter = defaultNumberFormatter({ allIntegers: false, surface: 'chart' });
+
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
@@ -74,31 +81,32 @@ function buildGraphLegend(
       shape: 'circle' as const,
       active: true,
     }));
-  } else {
+  } else if (nodeColorField) {
     // Build legend from nodeColor encoding: group by the color field value
     // so each legend entry shows the categorical value (e.g. "Dataset", "bls")
     // rather than an arbitrary node label.
     const categoryColors = new Map<string, string>();
     for (const node of nodes) {
-      const category = nodeColorField
-        ? String(node.data[nodeColorField] ?? node.label ?? node.id)
-        : (node.label ?? node.id);
+      const category = String(node.data[nodeColorField] ?? node.label ?? node.id);
       if (!categoryColors.has(category)) {
         categoryColors.set(category, node.fill);
       }
     }
 
     // Only show legend if there are multiple categories
-    if (categoryColors.size <= 1) {
-      entries = [];
-    } else {
-      entries = [...categoryColors.entries()].map(([label, color]) => ({
-        label,
-        color,
-        shape: 'circle' as const,
-        active: true,
-      }));
-    }
+    entries =
+      categoryColors.size <= 1
+        ? []
+        : [...categoryColors.entries()].map(([label, color]) => ({
+            label,
+            color,
+            shape: 'circle' as const,
+            active: true,
+          }));
+  } else {
+    // No communities and no color encoding: every node shares one fill, so a
+    // legend would just list every node label against identical swatches.
+    entries = [];
   }
 
   return {
@@ -144,7 +152,7 @@ function buildGraphTooltips(nodes: CompiledGraphNode[]): Map<string, TooltipCont
 
       fields.push({
         label: key,
-        value: typeof value === 'number' ? value.toLocaleString() : String(value),
+        value: typeof value === 'number' ? graphNumberFormatter(value) : String(value),
       });
     }
 
@@ -185,7 +193,8 @@ function buildGraphTooltips(nodes: CompiledGraphNode[]): Map<string, TooltipCont
  */
 export function compileGraph(spec: unknown, options: CompileOptions): GraphCompilation {
   // 1. Validate + normalize
-  const { spec: normalized } = compileSpec(spec);
+  const { spec: normalized, warnings } = compileSpec(spec);
+  emitSpecWarnings(warnings, options.onWarn);
 
   if (!('type' in normalized) || normalized.type !== 'graph') {
     throw new Error(

package/src/index.ts

@@ -17,6 +17,7 @@ export {
   compileChart,
   compileGraph,
   compileLayer,
+  compileMap,
   compileSankey,
   compileTable,
   compileTileMap,
@@ -69,6 +70,8 @@ export type { NormalizedSankeySpec } from './sankey/types';
 
 export type { NormalizedBarListSpec } from './barlist/types';
 
+export type { NormalizedMapSpec } from './geo/types';
+
 export type { NormalizedTileMapSpec } from './tilemap/types';
 
 // ---------------------------------------------------------------------------
@@ -76,9 +79,19 @@ export type { NormalizedTileMapSpec } from './tilemap/types';
 // ---------------------------------------------------------------------------
 
 export type { AnnotationContext } from './annotations/compute';
-export type { AnnotationMeasureTextFn } from './annotations/geometry';
-export { heuristicMeasure } from './annotations/geometry';
+export {
+  ARROWHEAD_LENGTH,
+  DEFAULT_ANNOTATION_FONT_SIZE,
+  DEFAULT_LINE_HEIGHT,
+} from './annotations/constants';
+export type { AnnotationMeasureTextFn, ArrowheadPoints } from './annotations/geometry';
+export {
+  computeArrowheadPoints,
+  heuristicMeasure,
+} from './annotations/geometry';
 export type { ObstacleKind, PlacementObstacle } from './annotations/placement';
+export type { RichSpan } from './annotations/rich-text';
+export { BOLD_SPAN_FONT_WEIGHT, parseAnnotationSpans } from './annotations/rich-text';
 
 // ---------------------------------------------------------------------------
 // Compiler pipeline (spec validation, normalization, generic compile)
@@ -112,6 +125,17 @@ export {
   registerChartRenderer,
 } from './charts/registry';
 
+// ---------------------------------------------------------------------------
+// Legend geometry
+// ---------------------------------------------------------------------------
+
+// Used by the vanilla mount to compute facet height growth for auto-height
+// figures; single-sourcing avoids constant divergence with facet.ts.
+export { facetMinHeight } from './layout/facet';
+// Used by the vanilla mount to compute the top-legend block when growing
+// auto-height figures; exporting it keeps the gap math single-sourced.
+export { legendGap } from './legend/wrap';
+
 // ---------------------------------------------------------------------------
 // Data transforms
 // ---------------------------------------------------------------------------
@@ -141,6 +165,8 @@ export type {
   GraphLayout,
   GraphSpec,
   LayerSpec,
+  MapLayout,
+  MapSpec,
   SankeyLayout,
   SankeySpec,
   TableLayout,

package/src/layout/axes/ticks.ts

@@ -7,13 +7,12 @@
 
 import type { AxisLabelDensity, AxisTick, DataRow } from '@opendata-ai/openchart-core';
 import {
-  abbreviateNumber,
-  buildD3Formatter,
   buildTemporalFormatter,
   formatDate,
-  formatNumber,
+  resolveNumberFormatter,
 } from '@opendata-ai/openchart-core';
 import type { ScaleBand } from 'd3-scale';
+import { resolveFieldFormatter } from '../../format/field-format';
 import type { D3CategoricalScale, D3ContinuousScale, ResolvedScale } from '../scales';
 
 /**
@@ -122,8 +121,18 @@ const NUMERIC_SCALE_TYPES = new Set([
 /** Set of temporal scale types. */
 const TEMPORAL_SCALE_TYPES = new Set(['time', 'utc']);
 
+interface TickContext {
+  step?: number;
+  maxAbsTick?: number;
+}
+
 /** Format a tick value based on the scale type. */
-function formatTickLabel(value: unknown, resolvedScale: ResolvedScale, compact = false): string {
+function formatTickLabel(
+  value: unknown,
+  resolvedScale: ResolvedScale,
+  compact = false,
+  tickContext?: TickContext,
+): string {
   const axisConfig = resolvedScale.channel.axis || undefined;
   const formatStr = axisConfig?.format;
   const suffix = axisConfig?.labelSuffix ?? '';
@@ -139,17 +148,54 @@ function formatTickLabel(value: unknown, resolvedScale: ResolvedScale, compact =
   if (NUMERIC_SCALE_TYPES.has(resolvedScale.type)) {
     const num = value as number;
     if (formatStr) {
-      const fmt = buildD3Formatter(formatStr);
+      const ctx = {
+        ...resolvedScale.formatContext,
+        step: tickContext?.step,
+        stepReference: tickContext?.maxAbsTick,
+      };
+      const fmt = resolveNumberFormatter(formatStr, ctx);
       if (fmt) return fmt(num) + suffix;
     }
-    // Abbreviate large numbers for axis labels
-    if (Math.abs(num) >= 1000) return abbreviateNumber(num) + suffix;
-    return formatNumber(num) + suffix;
+    const fmt = resolveFieldFormatter({
+      channelFormat: resolvedScale.channel.format,
+      context: {
+        ...resolvedScale.formatContext,
+        step: tickContext?.step,
+        stepReference: tickContext?.maxAbsTick,
+      },
+    });
+    return fmt(num) + suffix;
   }
 
   return String(value) + suffix;
 }
 
+function computeTickContext(ticks: unknown[]): TickContext | undefined {
+  if (ticks.length < 2) return undefined;
+  const nums = ticks.filter((v) => typeof v === 'number' && Number.isFinite(v)) as number[];
+  if (nums.length < 2) return undefined;
+
+  const firstGap = Math.abs(nums[1] - nums[0]);
+  if (firstGap === 0) return undefined;
+
+  let uniform = true;
+  for (let i = 2; i < nums.length; i++) {
+    const gap = Math.abs(nums[i] - nums[i - 1]);
+    const relDiff = Math.abs(gap - firstGap) / Math.max(firstGap, 1e-15);
+    if (relDiff > 1e-9) {
+      uniform = false;
+      break;
+    }
+  }
+
+  if (!uniform) return undefined;
+
+  return {
+    step: firstGap,
+    maxAbsTick: Math.max(Math.abs(nums[0]), Math.abs(nums[nums.length - 1])),
+  };
+}
+
 /**
  * Generate ticks for a continuous scale (linear, time, log, pow, sqrt, symlog).
  *
@@ -225,10 +271,12 @@ export function buildContinuousTicks(
     }
   }
 
+  const tickCtx = computeTickContext(ticks);
+
   return ticks.map((value: unknown) => ({
     value,
     position: scale(value as number & Date) as number,
-    label: formatTickLabel(value, resolvedScale, compact),
+    label: formatTickLabel(value, resolvedScale, compact, tickCtx),
   }));
 }
 
@@ -333,6 +381,7 @@ export function categoricalTicks(
  */
 export function resolveExplicitTicks(values: unknown[], resolvedScale: ResolvedScale): AxisTick[] {
   const scale = resolvedScale.scale;
+  const tickCtx = computeTickContext(values);
   return values.map((value) => {
     let position: number;
     if (TEMPORAL_SCALE_TYPES.has(resolvedScale.type)) {
@@ -354,7 +403,7 @@ export function resolveExplicitTicks(values: unknown[], resolvedScale: ResolvedS
     return {
       value,
       position,
-      label: formatTickLabel(value, resolvedScale),
+      label: formatTickLabel(value, resolvedScale, false, tickCtx),
     };
   });
 }

package/src/layout/axes.ts

@@ -24,6 +24,7 @@ import {
   computeXAxisExtentFromLabels,
   estimateTextWidth,
   getAxisTitleOffset,
+  truncateRotatedLabel,
   X_AXIS_TITLE_BAND_ROTATED,
 } from '@opendata-ai/openchart-core';
 import type { ScaleBand } from 'd3-scale';
@@ -513,6 +514,30 @@ export function computeAxes(
       ticks = thinTicksUntilFit(allTicks, fontSize, fontWeight, measureText);
     }
 
+    // Truncate rotated labels that would overflow the capped reservation.
+    // computeXAxisExtentFromLabels clamps the reserved band to
+    // X_AXIS_ROTATED_EXTENT_CAP, but nothing shortened the drawn string, so a
+    // long label rendered straight past the axis and through the source line.
+    // Clip to the same budget the reservation is computed from. `fullLabel`
+    // carries the original text so tooltips and the a11y table stay complete.
+    if (tickAngle && Math.abs(tickAngle) > 10) {
+      // MeasureTextFn returns { width }, not a number — adapt it the same way
+      // measureLabel does, or every comparison against the width budget is NaN
+      // and the search collapses every label to a bare ellipsis.
+      const measureWidth = (text: string, size: number, weight?: number) =>
+        measureLabel(text, size, weight ?? fontWeight, measureText);
+      ticks = ticks.map((t) => {
+        const truncated = truncateRotatedLabel(
+          t.label,
+          tickAngle,
+          fontSize,
+          fontWeight,
+          measureWidth,
+        );
+        return truncated === t.label ? t : { ...t, label: truncated, fullLabel: t.label };
+      });
+    }
+
     const axisTitle = axisConfig?.title;
     const xLabelColor = axisConfig?.labelColor;
     // X-axis defaults to gutter (no inline mode is sensible for the x axis
@@ -637,8 +662,11 @@ export function computeAxes(
 
     result.y = {
       ticks,
-      // Y-axis gridlines are shown by default (standard editorial practice)
-      gridlines,
+      // Y-axis gridlines are shown by default (standard editorial practice).
+      // Not for heatmaps: the cells tile the plot, so a gridline can only draw
+      // *through* them. The cell grid already is the grid. Explicit `grid: true`
+      // still wins.
+      gridlines: (axisConfig?.grid ?? dataContext?.markType !== 'rect') ? gridlines : [],
       label: axisTitle,
       labelStyle: yLabelColor ? { ...axisLabelStyle, fill: yLabelColor } : axisLabelStyle,
       tickLabelStyle: yLabelColor ? { ...tickLabelStyle, fill: yLabelColor } : tickLabelStyle,