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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opendata-ai/openchart-engine",
-  "version": "8.0.0-rc.2",
+  "version": "8.0.0-rc.3",
   "description": "Headless compiler for openchart: spec validation, data compilation, scales, and layout",
   "license": "Apache-2.0",
   "author": "Riley Hilliard",
@@ -48,7 +48,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@opendata-ai/openchart-core": "8.0.0-rc.2",
+    "@opendata-ai/openchart-core": "8.0.0-rc.3",
     "d3-array": "^3.2.0",
     "d3-format": "^3.1.2",
     "d3-interpolate": "^3.0.0",

package/src/compile/size-scale.ts

@@ -45,6 +45,8 @@ export const SIZE_SCALE_DEFAULTS = {
    * linear in font size, where a disc reads by its area.
    */
   text: { curve: 'linear', range: [11, 32] },
+  /** Map point dots. sqrt for area-proportional, tighter range than scatter. */
+  mapPoint: { curve: 'sqrt', range: [3, 20] },
 } as const satisfies Record<string, { curve: SizeCurve; range: readonly [number, number] }>;
 
 /** Size-scale options for a mark, or null when the mark has no size channel. */

package/src/compiler/normalize.ts

@@ -595,6 +595,7 @@ function normalizeMapSpec(spec: MapSpec, _warnings: string[]): NormalizedMapSpec
     watermark: spec.watermark ?? true,
     animation: spec.animation,
     valueFormat: spec.valueFormat,
+    points: spec.points,
   };
 }
 

package/src/compiler/validate.ts

@@ -1416,26 +1416,87 @@ function validateMapSpec(spec: Record<string, unknown>, errors: ValidationError[
   }
 
   const encoding = spec.encoding as Record<string, unknown>;
-  for (const channel of ['key', 'color'] as const) {
-    const ch = encoding[channel] as Record<string, unknown> | undefined;
-    if (!ch || typeof ch !== 'object') {
+  const hasPoints = spec.points && typeof spec.points === 'object' && !Array.isArray(spec.points);
+
+  // key is always required
+  const keyCh = encoding.key as Record<string, unknown> | undefined;
+  if (!keyCh || typeof keyCh !== 'object') {
+    errors.push({
+      message: 'Spec error: map encoding requires "key" channel',
+      path: 'encoding.key',
+      code: 'MISSING_FIELD',
+      suggestion: 'Add encoding.key, e.g. key: { field: "id", type: "nominal" }',
+    });
+  } else if (!keyCh.field || typeof keyCh.field !== 'string') {
+    errors.push({
+      message: 'Spec error: encoding.key must have a "field" string',
+      path: 'encoding.key.field',
+      code: 'MISSING_FIELD',
+      suggestion: 'Add a field name, e.g. key: { field: "id" }',
+    });
+  }
+
+  // color is required UNLESS points is present (basemap-only mode)
+  const colorCh = encoding.color as Record<string, unknown> | undefined;
+  if (!hasPoints) {
+    if (!colorCh || typeof colorCh !== 'object') {
       errors.push({
-        message: `Spec error: map encoding requires "${channel}" channel`,
-        path: `encoding.${channel}`,
+        message:
+          'Spec error: map encoding requires "color" channel (or add a "points" layer for basemap-only mode)',
+        path: 'encoding.color',
         code: 'MISSING_FIELD',
-        suggestion: `Add encoding.${channel}, e.g. ${channel}: { field: "${channel === 'key' ? 'id' : 'value'}", type: "${channel === 'key' ? 'nominal' : 'quantitative'}" }`,
+        suggestion: 'Add encoding.color, e.g. color: { field: "value", type: "quantitative" }',
+      });
+    } else if (!colorCh.field || typeof colorCh.field !== 'string') {
+      errors.push({
+        message: 'Spec error: encoding.color must have a "field" string',
+        path: 'encoding.color.field',
+        code: 'MISSING_FIELD',
+        suggestion: 'Add a field name, e.g. color: { field: "value" }',
       });
-      continue;
     }
+  } else if (
+    colorCh &&
+    typeof colorCh === 'object' &&
+    (!colorCh.field || typeof colorCh.field !== 'string')
+  ) {
+    errors.push({
+      message: 'Spec error: encoding.color must have a "field" string when provided',
+      path: 'encoding.color.field',
+      code: 'MISSING_FIELD',
+      suggestion: 'Add a field name, e.g. color: { field: "value" }',
+    });
+  }
 
-    if (!ch.field || typeof ch.field !== 'string') {
+  // Validate points layer if present
+  if (hasPoints) {
+    const points = spec.points as Record<string, unknown>;
+    if (!Array.isArray(points.data)) {
       errors.push({
-        message: `Spec error: encoding.${channel} must have a "field" string`,
-        path: `encoding.${channel}.field`,
-        code: 'MISSING_FIELD',
-        suggestion: `Add a field name, e.g. ${channel}: { field: "${channel === 'key' ? 'id' : 'value'}" }`,
+        message: 'Spec error: points.data must be an array of data rows',
+        path: 'points.data',
+        code: 'INVALID_TYPE',
+        suggestion: 'Provide data as an array of objects with lat/lng fields',
       });
     }
+    for (const ch of ['longitude', 'latitude'] as const) {
+      const enc = points[ch] as Record<string, unknown> | undefined;
+      if (!enc || typeof enc !== 'object') {
+        errors.push({
+          message: `Spec error: points requires "${ch}" encoding channel`,
+          path: `points.${ch}`,
+          code: 'MISSING_FIELD',
+          suggestion: `Add points.${ch}, e.g. ${ch}: { field: "${ch === 'longitude' ? 'lon' : 'lat'}", type: "quantitative" }`,
+        });
+      } else if (!enc.field || typeof enc.field !== 'string') {
+        errors.push({
+          message: `Spec error: points.${ch} must have a "field" string`,
+          path: `points.${ch}.field`,
+          code: 'MISSING_FIELD',
+          suggestion: `Add a field name, e.g. ${ch}: { field: "${ch === 'longitude' ? 'lon' : 'lat'}" }`,
+        });
+      }
+    }
   }
 }
 

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

@@ -618,4 +618,215 @@ 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);
+      }
+    });
+  });
 });