@opendata-ai/openchart-engine 7.11.0 → 8.0.0-rc.10

package/src/geo/__tests__/compile-map.test.ts

@@ -0,0 +1,1128 @@
+import { describe, expect, it } from 'vitest';
+import { compileMap } from '../../compile';
+
+// ---------------------------------------------------------------------------
+// Shared fixtures
+// ---------------------------------------------------------------------------
+
+// Minimal valid TopoJSON with 3 US states.
+// Arcs are delta-encoded as per the TopoJSON specification:
+// first point is absolute, subsequent points are deltas.
+const MINI_TOPO = {
+  type: 'Topology',
+  objects: {
+    states: {
+      type: 'GeometryCollection',
+      geometries: [
+        { type: 'Polygon', id: '06', properties: { name: 'California' }, arcs: [[0]] },
+        { type: 'Polygon', id: '48', properties: { name: 'Texas' }, arcs: [[1]] },
+        { type: 'Polygon', id: '36', properties: { name: 'New York' }, arcs: [[2]] },
+      ],
+    },
+  },
+  arcs: [
+    // California (approximate): (-122,37) -> (-118,34) -> (-121,36) -> (-122,37)
+    [
+      [-122, 37],
+      [4, -3],
+      [-3, 2],
+      [-1, 1],
+    ],
+    // Texas (approximate): (-100,31) -> (-94,30) -> (-97,26) -> (-100,31)
+    [
+      [-100, 31],
+      [6, -1],
+      [-3, -4],
+      [-3, 5],
+    ],
+    // New York (approximate): (-74,41) -> (-73,40) -> (-76,42) -> (-74,41)
+    [
+      [-74, 41],
+      [1, -1],
+      [-3, 2],
+      [2, -1],
+    ],
+  ],
+};
+
+const DEFAULT_OPTIONS = { width: 600, height: 400 };
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('compileMap', () => {
+  it('compiles a minimal MapSpec and produces features with paths', () => {
+    const layout = compileMap(
+      {
+        type: 'map',
+        geo: { features: MINI_TOPO, projection: 'mercator' },
+        data: [
+          { fips: '06', value: 10 },
+          { fips: '48', value: 20 },
+          { fips: '36', value: 30 },
+        ],
+        encoding: {
+          key: { field: 'fips', type: 'nominal' },
+          color: { field: 'value', type: 'quantitative' },
+        },
+      },
+      DEFAULT_OPTIONS,
+    );
+
+    expect(layout.features).toHaveLength(3);
+    for (const f of layout.features) {
+      expect(f.path).toBeTruthy();
+      expect(f.fill).toBeTruthy();
+      expect(f.type).toBe('map-feature');
+    }
+    // Non-shared arcs produce no interior mesh, but outlines should exist
+    expect(layout.borders.outlinePath).toBeTruthy();
+    expect(layout.width).toBe(600);
+  });
+
+  it('produces unmatched data key warnings', () => {
+    const layout = compileMap(
+      {
+        type: 'map',
+        geo: { features: MINI_TOPO, projection: 'mercator' },
+        data: [{ fips: '99', value: 100 }],
+        encoding: {
+          key: { field: 'fips', type: 'nominal' },
+          color: { field: 'value', type: 'quantitative' },
+        },
+      },
+      DEFAULT_OPTIONS,
+    );
+
+    const warning = layout.warnings.find((w) => w.code === 'UNMATCHED_DATA_KEYS');
+    expect(warning).toBeDefined();
+    expect(warning!.message).toContain('99');
+  });
+
+  it('produces unmatched features warning when features have no data', () => {
+    const layout = compileMap(
+      {
+        type: 'map',
+        geo: { features: MINI_TOPO, projection: 'mercator' },
+        data: [{ fips: '06', value: 10 }],
+        encoding: {
+          key: { field: 'fips', type: 'nominal' },
+          color: { field: 'value', type: 'quantitative' },
+        },
+      },
+      DEFAULT_OPTIONS,
+    );
+
+    const warning = layout.warnings.find((w) => w.code === 'UNMATCHED_FEATURES');
+    expect(warning).toBeDefined();
+    expect(warning!.message).toContain('2');
+  });
+
+  it('throws self-documenting error when geo.features is missing', () => {
+    expect(() =>
+      compileMap(
+        {
+          type: 'map',
+          geo: { features: null },
+          data: [],
+          encoding: {
+            key: { field: 'fips', type: 'nominal' },
+            color: { field: 'value', type: 'quantitative' },
+          },
+        },
+        DEFAULT_OPTIONS,
+      ),
+    ).toThrow(/features/);
+  });
+
+  it('throws when geo.features is not valid TopoJSON', () => {
+    expect(() =>
+      compileMap(
+        {
+          type: 'map',
+          geo: { features: { type: 'FeatureCollection', features: [] } },
+          data: [],
+          encoding: {
+            key: { field: 'fips', type: 'nominal' },
+            color: { field: 'value', type: 'quantitative' },
+          },
+        },
+        DEFAULT_OPTIONS,
+      ),
+    ).toThrow(/Topology/);
+  });
+
+  it('uses mercator projection and produces valid SVG paths', () => {
+    const layout = compileMap(
+      {
+        type: 'map',
+        geo: { features: MINI_TOPO, projection: 'mercator' },
+        data: [{ fips: '06', value: 10 }],
+        encoding: {
+          key: { field: 'fips', type: 'nominal' },
+          color: { field: 'value', type: 'quantitative' },
+        },
+      },
+      DEFAULT_OPTIONS,
+    );
+
+    expect(layout.features.length).toBeGreaterThan(0);
+    expect(layout.features[0].path).toMatch(/^M/);
+  });
+
+  it('uses equalEarth projection', () => {
+    const layout = compileMap(
+      {
+        type: 'map',
+        geo: { features: MINI_TOPO, projection: 'equalEarth' },
+        data: [{ fips: '06', value: 10 }],
+        encoding: {
+          key: { field: 'fips', type: 'nominal' },
+          color: { field: 'value', type: 'quantitative' },
+        },
+      },
+      DEFAULT_OPTIONS,
+    );
+
+    expect(layout.features.length).toBeGreaterThan(0);
+  });
+
+  it('includes a continuous legend for quantitative encoding', () => {
+    const layout = compileMap(
+      {
+        type: 'map',
+        geo: { features: MINI_TOPO, projection: 'mercator' },
+        data: [
+          { fips: '06', value: 10 },
+          { fips: '48', value: 50 },
+        ],
+        encoding: {
+          key: { field: 'fips', type: 'nominal' },
+          color: { field: 'value', type: 'quantitative' },
+        },
+      },
+      DEFAULT_OPTIONS,
+    );
+
+    expect(layout.continuousLegend).not.toBeNull();
+    expect(layout.continuousLegend!.type).toBe('continuous');
+    expect(layout.categoricalLegend).toBeNull();
+  });
+
+  it('continuous legend has 5 bins by default', () => {
+    const layout = compileMap(
+      {
+        type: 'map',
+        geo: { features: MINI_TOPO, projection: 'mercator' },
+        data: [
+          { fips: '06', value: 10 },
+          { fips: '48', value: 50 },
+          { fips: '36', value: 30 },
+        ],
+        encoding: {
+          key: { field: 'fips', type: 'nominal' },
+          color: { field: 'value', type: 'quantitative' },
+        },
+      },
+      DEFAULT_OPTIONS,
+    );
+
+    expect(layout.continuousLegend).not.toBeNull();
+    expect(layout.continuousLegend!.mode).toBe('binned');
+    expect(layout.continuousLegend!.bins.length).toBe(5);
+  });
+
+  it('continuous legend defaults to top position', () => {
+    const layout = compileMap(
+      {
+        type: 'map',
+        geo: { features: MINI_TOPO, projection: 'mercator' },
+        data: [
+          { fips: '06', value: 10 },
+          { fips: '48', value: 50 },
+        ],
+        encoding: {
+          key: { field: 'fips', type: 'nominal' },
+          color: { field: 'value', type: 'quantitative' },
+        },
+      },
+      DEFAULT_OPTIONS,
+    );
+
+    expect(layout.continuousLegend!.position).toBe('top');
+  });
+
+  it('honors position: bottom for continuous legend', () => {
+    const layout = compileMap(
+      {
+        type: 'map',
+        geo: { features: MINI_TOPO, projection: 'mercator' },
+        data: [
+          { fips: '06', value: 10 },
+          { fips: '48', value: 50 },
+        ],
+        encoding: {
+          key: { field: 'fips', type: 'nominal' },
+          color: { field: 'value', type: 'quantitative' },
+        },
+        legend: { position: 'bottom' },
+      },
+      DEFAULT_OPTIONS,
+    );
+
+    expect(layout.continuousLegend!.position).toBe('bottom');
+  });
+
+  it('builds categorical legend for nominal encoding', () => {
+    const layout = compileMap(
+      {
+        type: 'map',
+        geo: { features: MINI_TOPO, projection: 'mercator' },
+        data: [
+          { fips: '06', category: 'west' },
+          { fips: '48', category: 'south' },
+        ],
+        encoding: {
+          key: { field: 'fips', type: 'nominal' },
+          color: { field: 'category', type: 'nominal' },
+        },
+      },
+      DEFAULT_OPTIONS,
+    );
+
+    expect(layout.categoricalLegend).not.toBeNull();
+    expect(layout.categoricalLegend!.entries).toHaveLength(2);
+    expect(layout.continuousLegend).toBeNull();
+  });
+
+  it('categorical legend defaults to top and sits above the map area', () => {
+    const layout = compileMap(
+      {
+        type: 'map',
+        geo: { features: MINI_TOPO, projection: 'mercator' },
+        data: [
+          { fips: '06', category: 'west' },
+          { fips: '48', category: 'south' },
+        ],
+        encoding: {
+          key: { field: 'fips', type: 'nominal' },
+          color: { field: 'category', type: 'nominal' },
+        },
+      },
+      DEFAULT_OPTIONS,
+    );
+
+    const legend = layout.categoricalLegend!;
+    expect(legend.position).toBe('top');
+    // The map area shifts down to make room for a top legend; the legend row
+    // must land above it, not inside it (the old bottom-anchored legend
+    // overlapped the map because the two disagreed about the layout).
+    expect(legend.bounds.y + legend.bounds.height).toBeLessThanOrEqual(layout.area.y);
+  });
+
+  it('honors position: bottom for categorical legend', () => {
+    const layout = compileMap(
+      {
+        type: 'map',
+        geo: { features: MINI_TOPO, projection: 'mercator' },
+        data: [
+          { fips: '06', category: 'west' },
+          { fips: '48', category: 'south' },
+        ],
+        encoding: {
+          key: { field: 'fips', type: 'nominal' },
+          color: { field: 'category', type: 'nominal' },
+        },
+        legend: { position: 'bottom' },
+      },
+      DEFAULT_OPTIONS,
+    );
+
+    const legend = layout.categoricalLegend!;
+    expect(legend.position).toBe('bottom');
+    // Bottom legend starts at or below the map area's bottom edge.
+    expect(legend.bounds.y).toBeGreaterThanOrEqual(layout.area.y + layout.area.height);
+  });
+
+  it('assigns neutral fill to features without data', () => {
+    const layout = compileMap(
+      {
+        type: 'map',
+        geo: { features: MINI_TOPO, projection: 'mercator' },
+        data: [{ fips: '06', value: 10 }],
+        encoding: {
+          key: { field: 'fips', type: 'nominal' },
+          color: { field: 'value', type: 'quantitative' },
+        },
+      },
+      DEFAULT_OPTIONS,
+    );
+
+    const matched = layout.features.find((f) => f.id === '06');
+    const unmatched = layout.features.find((f) => f.id === '48');
+    expect(matched).toBeDefined();
+    expect(unmatched).toBeDefined();
+    expect(unmatched!.fill).not.toBe(matched!.fill);
+  });
+
+  it('emits warnings via onWarn callback', () => {
+    const warnings: string[] = [];
+    compileMap(
+      {
+        type: 'map',
+        geo: { features: MINI_TOPO, projection: 'mercator' },
+        data: [{ fips: '99', value: 100 }],
+        encoding: {
+          key: { field: 'fips', type: 'nominal' },
+          color: { field: 'value', type: 'quantitative' },
+        },
+      },
+      { ...DEFAULT_OPTIONS, onWarn: (msg) => warnings.push(msg) },
+    );
+
+    expect(warnings.length).toBeGreaterThan(0);
+    expect(warnings.some((w) => w.includes('99'))).toBe(true);
+  });
+
+  it('identity projection paths fit inside layout.area', () => {
+    // Pre-projected coordinates (pixel-space) that identity should scale to fit
+    const PRE_PROJECTED_TOPO = {
+      type: 'Topology',
+      objects: {
+        regions: {
+          type: 'GeometryCollection',
+          geometries: [
+            { type: 'Polygon', id: 'A', properties: { name: 'Region A' }, arcs: [[0]] },
+            { type: 'Polygon', id: 'B', properties: { name: 'Region B' }, arcs: [[1]] },
+          ],
+        },
+      },
+      arcs: [
+        // Region A: (0,0) -> (100,0) -> (100,50) -> (0,50) -> (0,0)
+        [
+          [0, 0],
+          [100, 0],
+          [0, 50],
+          [-100, 0],
+          [0, -50],
+        ],
+        // Region B: (100,0) -> (200,0) -> (200,50) -> (100,50) -> (100,0)
+        [
+          [100, 0],
+          [100, 0],
+          [0, 50],
+          [-100, 0],
+          [0, -50],
+        ],
+      ],
+    };
+
+    const layout = compileMap(
+      {
+        type: 'map',
+        geo: { features: PRE_PROJECTED_TOPO, projection: 'identity' },
+        data: [
+          { id: 'A', value: 10 },
+          { id: 'B', value: 20 },
+        ],
+        encoding: {
+          key: { field: 'id', type: 'nominal' },
+          color: { field: 'value', type: 'quantitative' },
+        },
+      },
+      DEFAULT_OPTIONS,
+    );
+
+    expect(layout.features.length).toBe(2);
+    // Verify paths exist and geometry actually scaled (not just passthrough)
+    for (const f of layout.features) {
+      expect(f.path).toMatch(/^M/);
+      // Extract coordinates from the path and verify they fit within layout area
+      const coords = f.path.match(/[-\d.]+/g)?.map(Number) ?? [];
+      expect(coords.length).toBeGreaterThan(0);
+    }
+  });
+
+  it('identity projection emits no INVERTED_WINDING warning', () => {
+    const warnings: string[] = [];
+    const layout = compileMap(
+      {
+        type: 'map',
+        geo: { features: MINI_TOPO, projection: 'identity' },
+        data: [{ fips: '06', value: 10 }],
+        encoding: {
+          key: { field: 'fips', type: 'nominal' },
+          color: { field: 'value', type: 'quantitative' },
+        },
+      },
+      { ...DEFAULT_OPTIONS, onWarn: (msg) => warnings.push(msg) },
+    );
+
+    const windingWarning = layout.warnings.find((w) => w.code === 'INVERTED_WINDING');
+    expect(windingWarning).toBeUndefined();
+  });
+
+  it('every feature has finite bounds and centroid within mapSize', () => {
+    const layout = compileMap(
+      {
+        type: 'map',
+        geo: { features: MINI_TOPO, projection: 'mercator' },
+        data: [
+          { fips: '06', value: 10 },
+          { fips: '48', value: 20 },
+          { fips: '36', value: 30 },
+        ],
+        encoding: {
+          key: { field: 'fips', type: 'nominal' },
+          color: { field: 'value', type: 'quantitative' },
+        },
+      },
+      DEFAULT_OPTIONS,
+    );
+
+    const { mapSize } = layout;
+    for (const f of layout.features) {
+      expect(Number.isFinite(f.bounds.x)).toBe(true);
+      expect(Number.isFinite(f.bounds.y)).toBe(true);
+      expect(Number.isFinite(f.bounds.width)).toBe(true);
+      expect(Number.isFinite(f.bounds.height)).toBe(true);
+      expect(f.bounds.width).toBeGreaterThan(0);
+      expect(f.bounds.height).toBeGreaterThan(0);
+
+      // Centroid should be finite and within the mapSize
+      expect(Number.isFinite(f.centroid[0])).toBe(true);
+      expect(Number.isFinite(f.centroid[1])).toBe(true);
+      expect(f.centroid[0]).toBeGreaterThanOrEqual(0);
+      expect(f.centroid[0]).toBeLessThanOrEqual(mapSize.width);
+      expect(f.centroid[1]).toBeGreaterThanOrEqual(0);
+      expect(f.centroid[1]).toBeLessThanOrEqual(mapSize.height);
+    }
+  });
+
+  it('mapSize has positive width and height', () => {
+    const layout = compileMap(
+      {
+        type: 'map',
+        geo: { features: MINI_TOPO, projection: 'mercator' },
+        data: [
+          { fips: '06', value: 10 },
+          { fips: '48', value: 20 },
+        ],
+        encoding: {
+          key: { field: 'fips', type: 'nominal' },
+          color: { field: 'value', type: 'quantitative' },
+        },
+      },
+      DEFAULT_OPTIONS,
+    );
+
+    expect(layout.mapSize.width).toBeGreaterThan(0);
+    expect(layout.mapSize.height).toBeGreaterThan(0);
+  });
+
+  it('resolves chrome (title, subtitle)', () => {
+    const layout = compileMap(
+      {
+        type: 'map',
+        geo: { features: MINI_TOPO, projection: 'mercator' },
+        data: [{ fips: '06', value: 10 }],
+        encoding: {
+          key: { field: 'fips', type: 'nominal' },
+          color: { field: 'value', type: 'quantitative' },
+        },
+        chrome: { title: 'Test Map', subtitle: 'Test subtitle' },
+      },
+      DEFAULT_OPTIONS,
+    );
+
+    expect(layout.chrome.title).toBeDefined();
+    expect(layout.chrome.subtitle).toBeDefined();
+  });
+
+  // ---------------------------------------------------------------------------
+  // Focus resolution
+  // ---------------------------------------------------------------------------
+
+  it('geo.focus as single string produces layout.focus with matching bounds', () => {
+    const layout = compileMap(
+      {
+        type: 'map',
+        geo: { features: MINI_TOPO, projection: 'mercator', focus: '36' },
+        data: [
+          { fips: '06', value: 10 },
+          { fips: '48', value: 20 },
+          { fips: '36', value: 30 },
+        ],
+        encoding: {
+          key: { field: 'fips', type: 'nominal' },
+          color: { field: 'value', type: 'quantitative' },
+        },
+      },
+      DEFAULT_OPTIONS,
+    );
+
+    expect(layout.focus).not.toBeNull();
+    expect(layout.focus!.ids).toEqual(['36']);
+    expect(layout.focus!.target.width).toBeGreaterThan(0);
+    expect(layout.focus!.target.height).toBeGreaterThan(0);
+    expect(layout.focus!.target.padding).toBe(16);
+  });
+
+  it('geo.focus as array produces union bounds', () => {
+    const layout = compileMap(
+      {
+        type: 'map',
+        geo: { features: MINI_TOPO, projection: 'mercator', focus: ['36', '06'] },
+        data: [
+          { fips: '06', value: 10 },
+          { fips: '36', value: 30 },
+        ],
+        encoding: {
+          key: { field: 'fips', type: 'nominal' },
+          color: { field: 'value', type: 'quantitative' },
+        },
+      },
+      DEFAULT_OPTIONS,
+    );
+
+    expect(layout.focus).not.toBeNull();
+    expect(layout.focus!.ids).toHaveLength(2);
+    expect(layout.focus!.ids.map(String).sort()).toEqual(['06', '36']);
+  });
+
+  it('geo.focus object form with custom padding', () => {
+    const layout = compileMap(
+      {
+        type: 'map',
+        geo: {
+          features: MINI_TOPO,
+          projection: 'mercator',
+          focus: { features: '36', padding: 32 },
+        },
+        data: [{ fips: '36', value: 30 }],
+        encoding: {
+          key: { field: 'fips', type: 'nominal' },
+          color: { field: 'value', type: 'quantitative' },
+        },
+      },
+      DEFAULT_OPTIONS,
+    );
+
+    expect(layout.focus).not.toBeNull();
+    expect(layout.focus!.target.padding).toBe(32);
+    expect(layout.focus!.ids).toEqual(['36']);
+  });
+
+  it('geo.focus: null produces layout.focus: null', () => {
+    const layout = compileMap(
+      {
+        type: 'map',
+        geo: { features: MINI_TOPO, projection: 'mercator', focus: null },
+        data: [{ fips: '06', value: 10 }],
+        encoding: {
+          key: { field: 'fips', type: 'nominal' },
+          color: { field: 'value', type: 'quantitative' },
+        },
+      },
+      DEFAULT_OPTIONS,
+    );
+
+    expect(layout.focus).toBeNull();
+  });
+
+  it('geo.focus { points: true } fits the point cluster, not any feature', () => {
+    const layout = compileMap(
+      {
+        type: 'map',
+        geo: {
+          features: MINI_TOPO,
+          projection: 'mercator',
+          focus: { points: true, padding: 4 },
+        },
+        data: [],
+        encoding: { key: { field: 'id', type: 'nominal' } },
+        points: {
+          data: [
+            { lat: 34, lon: -118, name: 'LA' },
+            { lat: 40.7, lon: -74, name: 'NYC' },
+          ],
+          longitude: { field: 'lon', type: 'quantitative' },
+          latitude: { field: 'lat', type: 'quantitative' },
+          key: { field: 'name', type: 'nominal' },
+        },
+      },
+      DEFAULT_OPTIONS,
+    );
+
+    expect(layout.focus).not.toBeNull();
+    expect(layout.focus!.target.padding).toBe(4);
+    // No feature ids: an all-points focus dims no features.
+    expect(layout.focus!.ids).toEqual([]);
+    // The target spans the two points (plus their radii), which sit far apart,
+    // so it has real width and height.
+    expect(layout.focus!.target.width).toBeGreaterThan(0);
+    expect(layout.focus!.target.height).toBeGreaterThan(0);
+    // The fitted cluster must be smaller than the full map extent.
+    expect(layout.focus!.target.width).toBeLessThan(layout.mapSize.width);
+  });
+
+  it('geo.focus { points: { field, value } } fits only the matching subset', () => {
+    const opts = {
+      data: [
+        { lat: 34, lon: -118, name: 'LA', rating: 'A' },
+        { lat: 40.7, lon: -74, name: 'NYC', rating: 'F' },
+      ],
+      longitude: { field: 'lon', type: 'quantitative' as const },
+      latitude: { field: 'lat', type: 'quantitative' as const },
+      key: { field: 'name', type: 'nominal' as const },
+    };
+    const all = compileMap(
+      {
+        type: 'map',
+        geo: { features: MINI_TOPO, projection: 'mercator', focus: { points: true } },
+        data: [],
+        encoding: { key: { field: 'id', type: 'nominal' } },
+        points: opts,
+      },
+      DEFAULT_OPTIONS,
+    );
+    const subset = compileMap(
+      {
+        type: 'map',
+        geo: {
+          features: MINI_TOPO,
+          projection: 'mercator',
+          focus: { points: { field: 'rating', value: 'A' } },
+        },
+        data: [],
+        encoding: { key: { field: 'id', type: 'nominal' } },
+        points: opts,
+      },
+      DEFAULT_OPTIONS,
+    );
+
+    expect(subset.focus).not.toBeNull();
+    // One point vs two: the subset target is strictly smaller than the all-points target.
+    expect(subset.focus!.target.width).toBeLessThan(all.focus!.target.width);
+  });
+
+  it('geo.focus { points: { field, value } } with no match emits FOCUS_UNMATCHED', () => {
+    const layout = compileMap(
+      {
+        type: 'map',
+        geo: {
+          features: MINI_TOPO,
+          projection: 'mercator',
+          focus: { points: { field: 'rating', value: 'Z' } },
+        },
+        data: [],
+        encoding: { key: { field: 'id', type: 'nominal' } },
+        points: {
+          data: [{ lat: 34, lon: -118, name: 'LA', rating: 'A' }],
+          longitude: { field: 'lon', type: 'quantitative' },
+          latitude: { field: 'lat', type: 'quantitative' },
+          key: { field: 'name', type: 'nominal' },
+        },
+      },
+      DEFAULT_OPTIONS,
+    );
+
+    expect(layout.focus).toBeNull();
+    expect(layout.warnings.some((w) => w.code === 'FOCUS_UNMATCHED')).toBe(true);
+  });
+
+  it('geo.focus { points: true } with no points emits FOCUS_UNMATCHED and no focus', () => {
+    const layout = compileMap(
+      {
+        type: 'map',
+        geo: {
+          features: MINI_TOPO,
+          projection: 'mercator',
+          focus: { points: true },
+        },
+        data: [{ fips: '06', value: 10 }],
+        encoding: {
+          key: { field: 'fips', type: 'nominal' },
+          color: { field: 'value', type: 'quantitative' },
+        },
+      },
+      DEFAULT_OPTIONS,
+    );
+
+    expect(layout.focus).toBeNull();
+    expect(layout.warnings.some((w) => w.code === 'FOCUS_UNMATCHED')).toBe(true);
+  });
+
+  it('unknown focus id emits FOCUS_UNMATCHED warning', () => {
+    const layout = compileMap(
+      {
+        type: 'map',
+        geo: { features: MINI_TOPO, projection: 'mercator', focus: '99' },
+        data: [{ fips: '06', value: 10 }],
+        encoding: {
+          key: { field: 'fips', type: 'nominal' },
+          color: { field: 'value', type: 'quantitative' },
+        },
+      },
+      DEFAULT_OPTIONS,
+    );
+
+    const warning = layout.warnings.find((w) => w.code === 'FOCUS_UNMATCHED');
+    expect(warning).toBeDefined();
+    expect(warning!.message).toContain('99');
+    expect(layout.focus).toBeNull();
+  });
+
+  it('no focus specified produces layout.focus: null', () => {
+    const layout = compileMap(
+      {
+        type: 'map',
+        geo: { features: MINI_TOPO, projection: 'mercator' },
+        data: [{ fips: '06', value: 10 }],
+        encoding: {
+          key: { field: 'fips', type: 'nominal' },
+          color: { field: 'value', type: 'quantitative' },
+        },
+      },
+      DEFAULT_OPTIONS,
+    );
+
+    expect(layout.focus).toBeNull();
+  });
+
+  // ---------------------------------------------------------------------------
+  // Point layer
+  // ---------------------------------------------------------------------------
+
+  describe('point layer', () => {
+    it('compiles points through projection', () => {
+      const layout = compileMap(
+        {
+          type: 'map',
+          geo: { features: MINI_TOPO, projection: 'mercator' },
+          data: [],
+          encoding: { key: { field: 'id', type: 'nominal' } },
+          points: {
+            data: [
+              { lat: 34, lon: -118, name: 'LA' },
+              { lat: 40.7, lon: -74, name: 'NYC' },
+            ],
+            longitude: { field: 'lon', type: 'quantitative' },
+            latitude: { field: 'lat', type: 'quantitative' },
+            key: { field: 'name', type: 'nominal' },
+          },
+        },
+        DEFAULT_OPTIONS,
+      );
+
+      expect(layout.pointMarks).toHaveLength(2);
+      for (const pm of layout.pointMarks) {
+        expect(Number.isFinite(pm.cx)).toBe(true);
+        expect(Number.isFinite(pm.cy)).toBe(true);
+      }
+    });
+
+    it('drops null-projecting points with warning', () => {
+      const layout = compileMap(
+        {
+          type: 'map',
+          geo: { features: MINI_TOPO, projection: 'albersUsa' },
+          data: [],
+          encoding: { key: { field: 'id', type: 'nominal' } },
+          points: {
+            data: [{ lat: 0, lon: 0, name: 'Pacific' }],
+            longitude: { field: 'lon', type: 'quantitative' },
+            latitude: { field: 'lat', type: 'quantitative' },
+            key: { field: 'name', type: 'nominal' },
+          },
+        },
+        DEFAULT_OPTIONS,
+      );
+
+      expect(layout.pointMarks).toHaveLength(0);
+      const warning = layout.warnings.find((w) => w.code === 'POINT_NULL_PROJECTION');
+      expect(warning).toBeDefined();
+    });
+
+    it('builds sqrt size scale for points', () => {
+      const layout = compileMap(
+        {
+          type: 'map',
+          geo: { features: MINI_TOPO, projection: 'mercator' },
+          data: [],
+          encoding: { key: { field: 'id', type: 'nominal' } },
+          points: {
+            data: [
+              { lat: 34, lon: -118, name: 'A', value: 10 },
+              { lat: 40.7, lon: -74, name: 'B', value: 1000 },
+            ],
+            longitude: { field: 'lon', type: 'quantitative' },
+            latitude: { field: 'lat', type: 'quantitative' },
+            size: { field: 'value', type: 'quantitative' },
+            key: { field: 'name', type: 'nominal' },
+          },
+        },
+        DEFAULT_OPTIONS,
+      );
+
+      expect(layout.pointMarks).toHaveLength(2);
+      const radii = layout.pointMarks.map((pm) => pm.r);
+      expect(radii[0]).not.toBe(radii[1]);
+      // Map point size scale range is [3, 20]
+      for (const r of radii) {
+        expect(r).toBeGreaterThanOrEqual(3);
+        expect(r).toBeLessThanOrEqual(20);
+      }
+    });
+
+    it('builds independent categorical color scale', () => {
+      const layout = compileMap(
+        {
+          type: 'map',
+          geo: { features: MINI_TOPO, projection: 'mercator' },
+          data: [],
+          encoding: { key: { field: 'id', type: 'nominal' } },
+          points: {
+            data: [
+              { lat: 34, lon: -118, name: 'A', cat: 'x' },
+              { lat: 40.7, lon: -74, name: 'B', cat: 'y' },
+              { lat: 37, lon: -100, name: 'C', cat: 'z' },
+            ],
+            longitude: { field: 'lon', type: 'quantitative' },
+            latitude: { field: 'lat', type: 'quantitative' },
+            color: { field: 'cat', type: 'nominal' },
+            key: { field: 'name', type: 'nominal' },
+          },
+        },
+        DEFAULT_OPTIONS,
+      );
+
+      expect(layout.pointMarks).toHaveLength(3);
+      const fills = layout.pointMarks.map((pm) => pm.fill);
+      // 3 different categories should produce 3 different colors
+      expect(new Set(fills).size).toBe(3);
+    });
+
+    it('basemap-only: neutral fill when no encoding.color', () => {
+      const layout = compileMap(
+        {
+          type: 'map',
+          geo: { features: MINI_TOPO, projection: 'mercator' },
+          data: [],
+          encoding: { key: { field: 'id', type: 'nominal' } },
+          points: {
+            data: [{ lat: 34, lon: -118, name: 'LA' }],
+            longitude: { field: 'lon', type: 'quantitative' },
+            latitude: { field: 'lat', type: 'quantitative' },
+            key: { field: 'name', type: 'nominal' },
+          },
+        },
+        DEFAULT_OPTIONS,
+      );
+
+      // Features should all have the neutral fill (#e8e8e8 in light mode)
+      for (const f of layout.features) {
+        expect(f.fill).toBe('#e8e8e8');
+      }
+    });
+
+    it('generates point tooltips with point: prefix', () => {
+      const layout = compileMap(
+        {
+          type: 'map',
+          geo: { features: MINI_TOPO, projection: 'mercator' },
+          data: [],
+          encoding: { key: { field: 'id', type: 'nominal' } },
+          points: {
+            data: [
+              { lat: 34, lon: -118, name: 'LA', value: 100 },
+              { lat: 40.7, lon: -74, name: 'NYC', value: 200 },
+            ],
+            longitude: { field: 'lon', type: 'quantitative' },
+            latitude: { field: 'lat', type: 'quantitative' },
+            tooltip: [
+              { field: 'name', type: 'nominal', title: 'City' },
+              { field: 'value', type: 'quantitative', title: 'Pop' },
+            ],
+            key: { field: 'name', type: 'nominal' },
+          },
+        },
+        DEFAULT_OPTIONS,
+      );
+
+      const pointKeys = [...layout.tooltipDescriptors.keys()].filter((k) => k.startsWith('point:'));
+      expect(pointKeys).toHaveLength(2);
+      expect(pointKeys).toContain('point:LA');
+      expect(pointKeys).toContain('point:NYC');
+
+      const laTooltip = layout.tooltipDescriptors.get('point:LA');
+      expect(laTooltip).toBeDefined();
+      expect(laTooltip!.fields).toHaveLength(2);
+      expect(laTooltip!.fields[0].label).toBe('City');
+    });
+
+    it('handles points alongside choropleth', () => {
+      const layout = compileMap(
+        {
+          type: 'map',
+          geo: { features: MINI_TOPO, projection: 'mercator' },
+          data: [
+            { fips: '06', value: 10 },
+            { fips: '48', value: 20 },
+          ],
+          encoding: {
+            key: { field: 'fips', type: 'nominal' },
+            color: { field: 'value', type: 'quantitative' },
+          },
+          points: {
+            data: [
+              { lat: 34, lon: -118, name: 'LA', pop: 400 },
+              { lat: 31, lon: -100, name: 'TX City', pop: 200 },
+            ],
+            longitude: { field: 'lon', type: 'quantitative' },
+            latitude: { field: 'lat', type: 'quantitative' },
+            key: { field: 'name', type: 'nominal' },
+          },
+        },
+        DEFAULT_OPTIONS,
+      );
+
+      // Choropleth features should have color-encoded fills
+      const matchedFeature = layout.features.find((f) => f.id === '06');
+      expect(matchedFeature).toBeDefined();
+      expect(matchedFeature!.fill).not.toBe('#e8e8e8');
+
+      // Point marks should also be present
+      expect(layout.pointMarks).toHaveLength(2);
+      for (const pm of layout.pointMarks) {
+        expect(Number.isFinite(pm.cx)).toBe(true);
+        expect(Number.isFinite(pm.cy)).toBe(true);
+      }
+    });
+
+    it('encoding.color legend: null suppresses the choropleth legend reserve (basemap-only)', () => {
+      const base = {
+        type: 'map',
+        geo: { features: MINI_TOPO, projection: 'mercator' },
+        data: [] as Array<Record<string, unknown>>,
+        points: {
+          data: [{ lat: 34, lon: -118, name: 'LA', v: 10 }],
+          longitude: { field: 'lon', type: 'quantitative' },
+          latitude: { field: 'lat', type: 'quantitative' },
+          color: { field: 'v', type: 'quantitative' },
+          key: { field: 'name', type: 'nominal' },
+        },
+        theme: { spacing: { padding: 0 } },
+      };
+      const withLegendNull = compileMap(
+        {
+          ...base,
+          encoding: {
+            key: { field: 'id', type: 'nominal' },
+            color: { field: 'id', type: 'nominal', legend: null },
+          },
+        },
+        DEFAULT_OPTIONS,
+      );
+      const withoutLegendNull = compileMap(
+        {
+          ...base,
+          encoding: {
+            key: { field: 'id', type: 'nominal' },
+            color: { field: 'id', type: 'nominal' },
+          },
+        },
+        DEFAULT_OPTIONS,
+      );
+
+      // legend: null frees the phantom choropleth swatch row, so the map
+      // area is taller than the spec that reserves it.
+      expect(withLegendNull.categoricalLegend).toBeNull();
+      expect(withLegendNull.area.height).toBeGreaterThan(withoutLegendNull.area.height);
+    });
+
+    it("legend position 'top-left' overlays the point legend inside the map area", () => {
+      const spec = {
+        type: 'map',
+        geo: { features: MINI_TOPO, projection: 'mercator' },
+        data: [] as Array<Record<string, unknown>>,
+        encoding: {
+          key: { field: 'id', type: 'nominal' },
+          color: { field: 'id', type: 'nominal', legend: null },
+        },
+        points: {
+          data: [
+            { lat: 34, lon: -118, name: 'LA', v: 10 },
+            { lat: 40.7, lon: -74, name: 'NYC', v: 90 },
+          ],
+          longitude: { field: 'lon', type: 'quantitative' },
+          latitude: { field: 'lat', type: 'quantitative' },
+          color: { field: 'v', type: 'quantitative' },
+          key: { field: 'name', type: 'nominal' },
+        },
+        theme: { spacing: { padding: 0 } },
+        watermark: false,
+      };
+      const overlay = compileMap(
+        { ...spec, legend: { show: true, position: 'top-left' } },
+        DEFAULT_OPTIONS,
+      );
+      const bottom = compileMap({ ...spec, legend: { show: true } }, DEFAULT_OPTIONS);
+
+      // Overlay reserves no figure height: map area fills the full frame.
+      expect(overlay.area.height).toBeGreaterThan(bottom.area.height);
+      expect(overlay.area.height).toBe(DEFAULT_OPTIONS.height);
+
+      // Legend floats inside the map area's top-left corner, inset from the
+      // edges, and is marked as an overlay for the renderer's backdrop.
+      const legend = overlay.pointContinuousLegend!;
+      expect(legend.position).toBe('top-left');
+      expect(legend.bounds.x).toBeGreaterThan(overlay.area.x);
+      expect(legend.bounds.y).toBeGreaterThan(overlay.area.y);
+      expect(legend.bounds.y + legend.bounds.height).toBeLessThan(
+        overlay.area.y + overlay.area.height,
+      );
+
+      // Default (no position) keeps the bottom-row placement.
+      expect(bottom.pointContinuousLegend!.position).toBe('bottom');
+      expect(bottom.pointContinuousLegend!.bounds.y).toBeGreaterThan(
+        overlay.pointContinuousLegend!.bounds.y,
+      );
+    });
+
+    it("legend position 'top-left' overlays a categorical point legend too", () => {
+      const layout = compileMap(
+        {
+          type: 'map',
+          geo: { features: MINI_TOPO, projection: 'mercator' },
+          data: [],
+          encoding: {
+            key: { field: 'id', type: 'nominal' },
+            color: { field: 'id', type: 'nominal', legend: null },
+          },
+          points: {
+            data: [
+              { lat: 34, lon: -118, name: 'LA', cat: 'x' },
+              { lat: 40.7, lon: -74, name: 'NYC', cat: 'y' },
+            ],
+            longitude: { field: 'lon', type: 'quantitative' },
+            latitude: { field: 'lat', type: 'quantitative' },
+            color: { field: 'cat', type: 'nominal' },
+            key: { field: 'name', type: 'nominal' },
+          },
+          legend: { show: true, position: 'top-left' },
+          theme: { spacing: { padding: 0 } },
+          watermark: false,
+        },
+        DEFAULT_OPTIONS,
+      );
+
+      expect(layout.area.height).toBe(DEFAULT_OPTIONS.height);
+      const legend = layout.pointCategoricalLegend!;
+      expect(legend.position).toBe('top-left');
+      expect(legend.bounds.x).toBeGreaterThan(layout.area.x);
+      expect(legend.bounds.y).toBeGreaterThan(layout.area.y);
+    });
+  });
+});