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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opendata-ai/openchart-engine",
-  "version": "8.0.0-rc.3",
+  "version": "8.0.0-rc.5",
   "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.3",
+    "@opendata-ai/openchart-core": "8.0.0-rc.5",
     "d3-array": "^3.2.0",
     "d3-format": "^3.1.2",
     "d3-interpolate": "^3.0.0",

package/src/compiler/validate.ts

@@ -1364,13 +1364,40 @@ function validateMapSpec(spec: Record<string, unknown>, errors: ValidationError[
       }
     } else if (typeof focus === 'object') {
       const focusObj = focus as Record<string, unknown>;
-      if (!('features' in focusObj) || focusObj.features == null) {
+      if ('points' in focusObj) {
+        // Points form: { points: true | { field, value }, padding? } fits the
+        // point layer's cluster (all points, or a matching subset).
+        const pts = focusObj.points;
+        const isSubset =
+          typeof pts === 'object' &&
+          pts !== null &&
+          typeof (pts as Record<string, unknown>).field === 'string' &&
+          'value' in (pts as Record<string, unknown>);
+        if (pts !== true && !isSubset) {
+          errors.push({
+            message:
+              'Spec error: geo.focus.points must be true or { field: string, value: string | number }',
+            path: 'geo.focus.points',
+            code: 'INVALID_TYPE',
+            suggestion:
+              'Use { points: true } to fit all points, or { points: { field: "rating", value: "F" } } to fit a subset.',
+          });
+        }
+        if (focusObj.padding !== undefined && typeof focusObj.padding !== 'number') {
+          errors.push({
+            message: 'Spec error: geo.focus.padding must be a number',
+            path: 'geo.focus.padding',
+            code: 'INVALID_TYPE',
+            suggestion: 'Provide padding as a number in map-local units, e.g. padding: 16',
+          });
+        }
+      } else if (!('features' in focusObj) || focusObj.features == null) {
         errors.push({
-          message: 'Spec error: geo.focus object must have a "features" property',
+          message: 'Spec error: geo.focus object must have a "features" or "points" property',
           path: 'geo.focus.features',
           code: 'MISSING_FIELD',
           suggestion:
-            'Provide feature id(s) to focus on, e.g. geo: { focus: { features: "36", padding: 32 } }',
+            'Provide feature id(s) to focus on, e.g. { features: "36", padding: 32 }, or { points: true } to fit the point cluster.',
         });
       } else {
         const feats = focusObj.features;
@@ -1406,11 +1433,11 @@ function validateMapSpec(spec: Record<string, unknown>, errors: ValidationError[
     } else {
       errors.push({
         message:
-          'Spec error: geo.focus must be a string, number, array of ids, or object with { features, padding? }',
+          'Spec error: geo.focus must be a string, number, array of ids, or object with { features, padding? } or { points: true, padding? }',
         path: 'geo.focus',
         code: 'INVALID_TYPE',
         suggestion:
-          'Use a feature id, array of ids, or { features: "36", padding: 16 }. Pass null to clear focus.',
+          'Use a feature id, array of ids, { features: "36", padding: 16 }, or { points: true }. Pass null to clear focus.',
       });
     }
   }
@@ -1418,22 +1445,26 @@ function validateMapSpec(spec: Record<string, unknown>, errors: ValidationError[
   const encoding = spec.encoding as Record<string, unknown>;
   const hasPoints = spec.points && typeof spec.points === 'object' && !Array.isArray(spec.points);
 
-  // key is always required
+  // key is required unless basemap-only mode (points present + empty/no choropleth data)
+  const specData = spec.data as unknown[] | undefined;
+  const isBasemapOnly = hasPoints && (!specData || specData.length === 0);
   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" }',
-    });
+  if (!isBasemapOnly) {
+    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)
@@ -1497,6 +1528,17 @@ function validateMapSpec(spec: Record<string, unknown>, errors: ValidationError[
         });
       }
     }
+    for (const ch of ['size', 'color', 'key'] as const) {
+      const enc = points[ch] as Record<string, unknown> | undefined;
+      if (enc && typeof enc === 'object' && (!enc.field || typeof enc.field !== 'string')) {
+        errors.push({
+          message: `Spec error: points.${ch} must have a "field" string when provided`,
+          path: `points.${ch}.field`,
+          code: 'MISSING_FIELD',
+          suggestion: `Add a field name, e.g. ${ch}: { field: "myField" }`,
+        });
+      }
+    }
   }
 }
 

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

@@ -582,6 +582,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(
       {

package/src/geo/compile-map.ts

@@ -247,23 +247,27 @@ export function compileMap(spec: unknown, options: CompileOptions): MapLayout {
     }
   }
 
-  // 11. Join data to features
-  const featureObjs = geoFeatures.map((f) => ({
-    id: f.id as string | number,
-    properties: (f.properties ?? {}) as Record<string, unknown>,
-  }));
-  const { joined, warnings: joinWarnings } = joinDataToFeatures(
-    featureObjs,
-    mapSpec.data,
-    mapSpec.encoding.key.field,
-    mapSpec.geo.idField,
-  );
-  // In basemap-only mode (empty data + points layer), all features are intentionally unmatched
-  const filteredJoinWarnings =
-    mapSpec.data.length === 0 && mapSpec.points
-      ? joinWarnings.filter((w) => w.code !== 'UNMATCHED_FEATURES')
-      : joinWarnings;
-  compileWarnings.push(...filteredJoinWarnings);
+  // 11. Join data to features (skip when no key channel, e.g. basemap-only mode)
+  let joined = new Map<string | number, Record<string, unknown>>();
+  if (mapSpec.encoding.key) {
+    const featureObjs = geoFeatures.map((f) => ({
+      id: f.id as string | number,
+      properties: (f.properties ?? {}) as Record<string, unknown>,
+    }));
+    const joinResult = joinDataToFeatures(
+      featureObjs,
+      mapSpec.data,
+      mapSpec.encoding.key.field,
+      mapSpec.geo.idField,
+    );
+    joined = joinResult.joined;
+    // In basemap-only mode (empty data + points layer), all features are intentionally unmatched
+    const filteredJoinWarnings =
+      mapSpec.data.length === 0 && mapSpec.points
+        ? joinResult.warnings.filter((w) => w.code !== 'UNMATCHED_FEATURES')
+        : joinResult.warnings;
+    compileWarnings.push(...filteredJoinWarnings);
+  }
 
   // 12. Check for null-projecting features (albersUsa drops territories)
   const droppedFeatures: string[] = [];
@@ -348,6 +352,7 @@ export function compileMap(spec: unknown, options: CompileOptions): MapLayout {
       pathGen,
       joined,
       colorField: colorEncoding.field,
+      colorScale: colorEncoding.scale,
       isDarkMode: !!isDarkMode,
       neutralFill,
       neutralStroke,
@@ -432,8 +437,17 @@ export function compileMap(spec: unknown, options: CompileOptions): MapLayout {
           };
         }
       } else {
-        // nominal / ordinal
-        const seen = new Set<string>();
+        // nominal / ordinal: honor scale.domain (category order) and scale.range (explicit colors)
+        const explicitDomain = pts.color.scale?.domain as string[] | undefined;
+        const explicitRange = pts.color.scale?.range as string[] | undefined;
+
+        if (explicitDomain && Array.isArray(explicitDomain)) {
+          for (const cat of explicitDomain) {
+            pointCategories.push(String(cat));
+          }
+        }
+        // Also pick up any categories in the data that aren't in the explicit domain
+        const seen = new Set<string>(pointCategories);
         for (const row of pts.data) {
           const raw = row[pts.color.field];
           if (raw != null) {
@@ -441,22 +455,27 @@ export function compileMap(spec: unknown, options: CompileOptions): MapLayout {
             if (!seen.has(cat)) {
               seen.add(cat);
               pointCategories.push(cat);
-              pointCategoryColors.set(
-                cat,
-                CATEGORICAL_PALETTE[(pointCategories.length - 1) % CATEGORICAL_PALETTE.length],
-              );
             }
           }
         }
+
+        const colorSource =
+          explicitRange && Array.isArray(explicitRange) ? explicitRange : CATEGORICAL_PALETTE;
+        for (let i = 0; i < pointCategories.length; i++) {
+          pointCategoryColors.set(pointCategories[i], colorSource[i % colorSource.length]);
+        }
+
         pointColorScale = (val: unknown) => {
-          if (val == null) return CATEGORICAL_PALETTE[0];
-          return pointCategoryColors.get(String(val)) ?? CATEGORICAL_PALETTE[0];
+          if (val == null) return colorSource[0];
+          return pointCategoryColors.get(String(val)) ?? colorSource[0];
         };
       }
     }
 
     const defaultFill = CATEGORICAL_PALETTE[0];
+    const pointOpacity = pts.opacity ?? 0.65;
     let animIndex = 0;
+    const droppedPoints: Array<[number, number]> = [];
 
     for (let i = 0; i < pts.data.length; i++) {
       const row = pts.data[i];
@@ -466,11 +485,7 @@ export function compileMap(spec: unknown, options: CompileOptions): MapLayout {
 
       const projected = projection([lon, lat]);
       if (!projected) {
-        compileWarnings.push({
-          code: 'POINT_NULL_PROJECTION',
-          message: `Point at [${lon}, ${lat}] projects to null and was dropped.`,
-          context: { lon, lat },
-        });
+        droppedPoints.push([lon, lat]);
         continue;
       }
 
@@ -488,6 +503,7 @@ export function compileMap(spec: unknown, options: CompileOptions): MapLayout {
         fill,
         stroke,
         strokeWidth: 1,
+        fillOpacity: pointOpacity,
         key,
         data: row as Record<string, unknown>,
         aria: { role: 'img', label: key },
@@ -495,6 +511,21 @@ export function compileMap(spec: unknown, options: CompileOptions): MapLayout {
       });
     }
 
+    if (droppedPoints.length > 0) {
+      const sample = droppedPoints
+        .slice(0, 3)
+        .map(([lo, la]) => `[${lo}, ${la}]`)
+        .join(', ');
+      compileWarnings.push({
+        code: 'POINT_NULL_PROJECTION',
+        message:
+          `${droppedPoints.length} point(s) project to null and were dropped (e.g. ${sample}). ` +
+          'This is common with albersUsa which excludes territories. ' +
+          'Consider using projection: "mercator" or "equalEarth".',
+        context: { count: droppedPoints.length, samples: droppedPoints.slice(0, 5) },
+      });
+    }
+
     // Point categorical legend
     if (
       pts.color &&
@@ -516,19 +547,19 @@ export function compileMap(spec: unknown, options: CompileOptions): MapLayout {
         shape: 'circle' as const,
       }));
 
-      // Position below the choropleth legend (or at the legend position if none)
-      const choroplethLegendHeight = continuousLegend
-        ? continuousLegend.bounds.height
-        : categoricalLegend
-          ? categoricalLegend.bounds.height
+      // Position below the map. Only offset by choropleth legend height when
+      // the choropleth legend is also at the bottom (not 'top').
+      const bottomChoroplethHeight =
+        legendPosition === 'bottom'
+          ? (continuousLegend?.bounds.height ?? categoricalLegend?.bounds.height ?? 0)
           : 0;
-      const choroplethLegendGap = choroplethLegendHeight > 0 ? 8 : 0;
+      const choroplethLegendGap = bottomChoroplethHeight > 0 ? 8 : 0;
       const legendX = fullArea.x;
       const legendY =
         fullArea.y +
         mapAreaHeight +
         legendReserveGap +
-        choroplethLegendHeight +
+        bottomChoroplethHeight +
         choroplethLegendGap;
       const legendWidth = fullArea.width;
       const swatchSize = 10;
@@ -577,19 +608,14 @@ export function compileMap(spec: unknown, options: CompileOptions): MapLayout {
           lineHeight: 1.3,
           fontVariant: 'tabular-nums',
         };
-        const choroplethLegendHeight = continuousLegend
-          ? continuousLegend.bounds.height
-          : categoricalLegend
-            ? categoricalLegend.bounds.height
+        const bottomChoroplethH =
+          legendPosition === 'bottom'
+            ? (continuousLegend?.bounds.height ?? categoricalLegend?.bounds.height ?? 0)
             : 0;
-        const choroplethLegendGap = choroplethLegendHeight > 0 ? 8 : 0;
+        const choroplethLegendGap = bottomChoroplethH > 0 ? 8 : 0;
         const legendX = fullArea.x;
         const legendY =
-          fullArea.y +
-          mapAreaHeight +
-          legendReserveGap +
-          choroplethLegendHeight +
-          choroplethLegendGap;
+          fullArea.y + mapAreaHeight + legendReserveGap + bottomChoroplethH + choroplethLegendGap;
         const ptLabelRowHeight = Math.ceil(theme.fonts.sizes.small * 1.3);
         const ptLegendHeight =
           ptContinuousContent.barHeight + CONTINUOUS_LABEL_GAP + ptLabelRowHeight;
@@ -735,7 +761,7 @@ export function compileMap(spec: unknown, options: CompileOptions): MapLayout {
   };
 
   // 18. Resolve focus
-  const resolvedFocus = resolveFocus(mapSpec.geo.focus, featureMarks, compileWarnings);
+  const resolvedFocus = resolveFocus(mapSpec.geo.focus, featureMarks, pointMarks, compileWarnings);
 
   // 19. Animation
   const resolvedAnimation: ResolvedAnimation | undefined = resolveAnimation(mapSpec.animation);
@@ -976,6 +1002,7 @@ interface CategoricalOptions {
   pathGen: ReturnType<typeof geoPath>;
   joined: Map<string | number, Record<string, unknown>>;
   colorField: string;
+  colorScale?: { domain?: unknown; range?: unknown };
   isDarkMode: boolean;
   neutralFill: string;
   neutralStroke: string;
@@ -996,6 +1023,7 @@ function buildCategoricalMarks(opts: CategoricalOptions): {
     pathGen,
     joined,
     colorField,
+    colorScale: scaleConfig,
     isDarkMode,
     neutralFill,
     neutralStroke,
@@ -1007,9 +1035,15 @@ function buildCategoricalMarks(opts: CategoricalOptions): {
     droppedFeatures,
   } = opts;
 
-  // Collect unique categories in data order
+  // Collect unique categories: honor scale.domain for order, then append any unseen from data
   const categories: string[] = [];
-  const seen = new Set<string>();
+  const explicitDomain = scaleConfig?.domain;
+  if (explicitDomain && Array.isArray(explicitDomain)) {
+    for (const cat of explicitDomain) {
+      categories.push(String(cat));
+    }
+  }
+  const seen = new Set<string>(categories);
   for (const row of joined.values()) {
     const raw = row[colorField];
     if (raw != null) {
@@ -1021,9 +1055,12 @@ function buildCategoricalMarks(opts: CategoricalOptions): {
     }
   }
 
+  const explicitRange = scaleConfig?.range;
+  const colorSource =
+    explicitRange && Array.isArray(explicitRange) ? explicitRange : CATEGORICAL_PALETTE;
   const categoryColors = new Map<string, string>();
   for (let i = 0; i < categories.length; i++) {
-    categoryColors.set(categories[i], CATEGORICAL_PALETTE[i % CATEGORICAL_PALETTE.length]);
+    categoryColors.set(categories[i], colorSource[i % colorSource.length]);
   }
 
   const marks: MapFeatureMark[] = [];
@@ -1135,10 +1172,54 @@ function buildCategoricalMarks(opts: CategoricalOptions): {
 function resolveFocus(
   focus: MapFocus | null,
   features: MapFeatureMark[],
+  pointMarks: MapPointMark[],
   warnings: CompileWarning[],
 ): MapFocusLayout | null {
   if (focus === null || focus === undefined) return null;
 
+  // Points form fits the union of the point layer's circle bounds (cx +/- r)
+  // rather than any feature. Use it when the points cluster in a small part of a
+  // large feature, so fitting the feature would leave the cluster small and
+  // off-center. `points: true` fits every point; `points: { field, value }`
+  // fits only the matching subset, so a story can pan between sub-clusters.
+  if (typeof focus === 'object' && !Array.isArray(focus) && 'points' in focus) {
+    const filter = focus.points;
+    const matched =
+      filter === true
+        ? pointMarks
+        : pointMarks.filter((p) => p.data[filter.field] === filter.value);
+
+    if (matched.length === 0) {
+      const detail =
+        filter === true
+          ? 'the map has no points to fit'
+          : `no points match { field: "${filter.field}", value: ${JSON.stringify(filter.value)} }`;
+      warnings.push({
+        code: 'FOCUS_UNMATCHED',
+        message: `geo.focus.points is set but ${detail}`,
+        context: {},
+      });
+      return null;
+    }
+    const padding = focus.padding ?? 16;
+    let minX = Infinity;
+    let minY = Infinity;
+    let maxX = -Infinity;
+    let maxY = -Infinity;
+    for (const p of matched) {
+      minX = Math.min(minX, p.cx - p.r);
+      minY = Math.min(minY, p.cy - p.r);
+      maxX = Math.max(maxX, p.cx + p.r);
+      maxY = Math.max(maxY, p.cy + p.r);
+    }
+    return {
+      target: { x: minX, y: minY, width: maxX - minX, height: maxY - minY, padding },
+      // No feature ids: focus-dim is a feature concept, so a points focus
+      // dims no features (there are no "other" features to mute).
+      ids: [],
+    };
+  }
+
   // Normalize to { ids, padding }
   let ids: Array<string | number>;
   let padding = 16;