@opendata-ai/openchart-engine 8.0.0-rc.12 → 8.0.0-rc.3

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,26 @@
+import type {
+  AnimationSpec,
+  DarkMode,
+  LegendConfig,
+  MapEncoding,
+  MapGeo,
+  MapPointsLayer,
+  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;
+  points?: MapPointsLayer;
+}

package/src/graphs/__tests__/community.test.ts

@@ -0,0 +1,228 @@
+import { resolveTheme } from '@opendata-ai/openchart-core';
+import { describe, expect, it } from 'vitest';
+import { applyCommunityColors, assignCommunities, buildCommunityColorMap } from '../community';
+import type { CompiledGraphNode } from '../types';
+
+// ---------------------------------------------------------------------------
+// Shared fixtures
+// ---------------------------------------------------------------------------
+
+const theme = resolveTheme({});
+
+function makeNodes(): CompiledGraphNode[] {
+  return [
+    {
+      id: 'a',
+      radius: 5,
+      fill: '#aaa',
+      stroke: '#888',
+      strokeWidth: 1,
+      label: 'A',
+      labelPriority: 0.5,
+      community: undefined,
+      data: { id: 'a', group: 'X', department: 'eng' },
+    },
+    {
+      id: 'b',
+      radius: 5,
+      fill: '#bbb',
+      stroke: '#999',
+      strokeWidth: 1,
+      label: 'B',
+      labelPriority: 0.3,
+      community: undefined,
+      data: { id: 'b', group: 'X', department: 'eng' },
+    },
+    {
+      id: 'c',
+      radius: 5,
+      fill: '#ccc',
+      stroke: '#aaa',
+      strokeWidth: 1,
+      label: 'C',
+      labelPriority: 0.8,
+      community: undefined,
+      data: { id: 'c', group: 'Y', department: 'sales' },
+    },
+    {
+      id: 'd',
+      radius: 5,
+      fill: '#ddd',
+      stroke: '#bbb',
+      strokeWidth: 1,
+      label: 'D',
+      labelPriority: 0.2,
+      community: undefined,
+      data: { id: 'd' }, // no group field
+    },
+  ];
+}
+
+// ---------------------------------------------------------------------------
+// assignCommunities tests
+// ---------------------------------------------------------------------------
+
+describe('assignCommunities', () => {
+  it('assigns community labels from the specified field', () => {
+    const nodes = makeNodes();
+    assignCommunities(nodes, 'group');
+
+    expect(nodes[0].community).toBe('X');
+    expect(nodes[1].community).toBe('X');
+    expect(nodes[2].community).toBe('Y');
+  });
+
+  it('leaves community undefined when field is missing on a node', () => {
+    const nodes = makeNodes();
+    assignCommunities(nodes, 'group');
+
+    // Node 'd' doesn't have the 'group' field
+    expect(nodes[3].community).toBeUndefined();
+  });
+
+  it('does nothing when clusteringField is undefined', () => {
+    const nodes = makeNodes();
+    assignCommunities(nodes, undefined);
+
+    for (const node of nodes) {
+      expect(node.community).toBeUndefined();
+    }
+  });
+
+  it('handles non-string field values by converting to string', () => {
+    const nodes = makeNodes();
+    // Add a numeric field value
+    nodes[0].data.numericGroup = 42;
+    assignCommunities(nodes, 'numericGroup');
+
+    expect(nodes[0].community).toBe('42');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// buildCommunityColorMap tests
+// ---------------------------------------------------------------------------
+
+describe('buildCommunityColorMap', () => {
+  it('creates a color for each unique community', () => {
+    const nodes = makeNodes();
+    assignCommunities(nodes, 'group');
+
+    const colorMap = buildCommunityColorMap(nodes, theme);
+
+    expect(colorMap.size).toBe(2);
+    expect(colorMap.has('X')).toBe(true);
+    expect(colorMap.has('Y')).toBe(true);
+  });
+
+  it('uses categorical palette colors', () => {
+    const nodes = makeNodes();
+    assignCommunities(nodes, 'group');
+
+    const colorMap = buildCommunityColorMap(nodes, theme);
+
+    const colors = [...colorMap.values()];
+    const palette = theme.colors.categorical;
+
+    // First two communities should get first two palette colors
+    expect(colors[0]).toBe(palette[0]);
+    expect(colors[1]).toBe(palette[1]);
+  });
+
+  it('returns empty map when no communities assigned', () => {
+    const nodes = makeNodes();
+    // Don't assign communities
+
+    const colorMap = buildCommunityColorMap(nodes, theme);
+
+    expect(colorMap.size).toBe(0);
+  });
+
+  it('wraps around palette when more communities than colors', () => {
+    // Create enough nodes with unique communities to exceed palette size
+    const manyNodes: CompiledGraphNode[] = [];
+    const paletteSize = theme.colors.categorical.length;
+
+    for (let i = 0; i < paletteSize + 2; i++) {
+      manyNodes.push({
+        id: `n${i}`,
+        radius: 5,
+        fill: '#ccc',
+        stroke: '#aaa',
+        strokeWidth: 1,
+        label: `Node ${i}`,
+        labelPriority: 0,
+        community: `community-${i}`,
+        data: { id: `n${i}` },
+      });
+    }
+
+    const colorMap = buildCommunityColorMap(manyNodes, theme);
+
+    expect(colorMap.size).toBe(paletteSize + 2);
+    // The (paletteSize + 1)th community should wrap to palette[0]
+    const wrappedColor = [...colorMap.values()][paletteSize];
+    expect(wrappedColor).toBe(theme.colors.categorical[0]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// applyCommunityColors tests
+// ---------------------------------------------------------------------------
+
+describe('applyCommunityColors', () => {
+  it('overrides node fill with community color', () => {
+    const nodes = makeNodes();
+    assignCommunities(nodes, 'group');
+
+    const colorMap = buildCommunityColorMap(nodes, theme);
+    const xColor = colorMap.get('X')!;
+
+    applyCommunityColors(nodes, colorMap);
+
+    expect(nodes[0].fill).toBe(xColor);
+    expect(nodes[1].fill).toBe(xColor);
+  });
+
+  it('overrides node stroke with darkened community color', () => {
+    const nodes = makeNodes();
+    assignCommunities(nodes, 'group');
+
+    const colorMap = buildCommunityColorMap(nodes, theme);
+    const originalStroke0 = nodes[0].stroke;
+
+    applyCommunityColors(nodes, colorMap);
+
+    // Stroke should have changed from original
+    expect(nodes[0].stroke).not.toBe(originalStroke0);
+    // Stroke should be different from fill (darkened)
+    expect(nodes[0].stroke).not.toBe(nodes[0].fill);
+  });
+
+  it('leaves nodes without communities unchanged', () => {
+    const nodes = makeNodes();
+    assignCommunities(nodes, 'group');
+
+    const originalFill = nodes[3].fill;
+    const originalStroke = nodes[3].stroke;
+
+    const colorMap = buildCommunityColorMap(nodes, theme);
+    applyCommunityColors(nodes, colorMap);
+
+    // Node 'd' has no group field, community is undefined
+    expect(nodes[3].fill).toBe(originalFill);
+    expect(nodes[3].stroke).toBe(originalStroke);
+  });
+
+  it('nodes in the same community have the same color', () => {
+    const nodes = makeNodes();
+    assignCommunities(nodes, 'group');
+
+    const colorMap = buildCommunityColorMap(nodes, theme);
+    applyCommunityColors(nodes, colorMap);
+
+    // Nodes a and b are both in community 'X'
+    expect(nodes[0].fill).toBe(nodes[1].fill);
+    expect(nodes[0].stroke).toBe(nodes[1].stroke);
+  });
+});