@opendata-ai/openchart-engine 8.0.0-rc.9 → 8.0.0

package/src/geo/join.ts

@@ -1,115 +0,0 @@
-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

@@ -1,65 +0,0 @@
-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,
-  inset = 0,
-): GeoProjection | GeoIdentityTransform {
-  if (type === 'identity') {
-    if (inset > 0) {
-      return geoIdentity().fitExtent(
-        [
-          [inset, inset],
-          [width - inset, height - inset],
-        ],
-        geojson,
-      );
-    }
-    return geoIdentity().fitSize([width, height], geojson);
-  }
-
-  const projection =
-    type === 'albersUsa' ? geoAlbersUsa() : type === 'equalEarth' ? geoEqualEarth() : geoMercator();
-
-  const fitGeometry = type === 'mercator' ? excludePolarFeatures(geojson) : geojson;
-  if (inset > 0) {
-    projection.fitExtent(
-      [
-        [inset, inset],
-        [width - inset, height - inset],
-      ],
-      fitGeometry,
-    );
-  } else {
-    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

@@ -1,26 +0,0 @@
-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

@@ -1,228 +0,0 @@
-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);
-  });
-});