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

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

@@ -296,6 +296,55 @@ describe('compileMap', () => {
     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(
       {
@@ -582,6 +631,129 @@ describe('compileMap', () => {
     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(
       {
@@ -618,4 +790,339 @@ describe('compileMap', () => {
 
     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);
+    });
+  });
 });