@opendata-ai/openchart-engine 8.0.0-rc.4 → 8.0.0-rc.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opendata-ai/openchart-engine",
-  "version": "8.0.0-rc.4",
+  "version": "8.0.0-rc.6",
   "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.4",
+    "@opendata-ai/openchart-core": "8.0.0-rc.6",
     "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.',
       });
     }
   }

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(
       {

package/src/geo/compile-map.ts

@@ -360,6 +360,7 @@ export function compileMap(spec: unknown, options: CompileOptions): MapLayout {
       fullArea,
       mapAreaHeight,
       legendReserveGap,
+      legendPosition,
       showLegend,
       droppedFeatures,
     });
@@ -761,7 +762,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);
@@ -1010,6 +1011,7 @@ interface CategoricalOptions {
   fullArea: { x: number; y: number; width: number; height: number };
   mapAreaHeight: number;
   legendReserveGap: number;
+  legendPosition: 'top' | 'bottom';
   showLegend: boolean;
   droppedFeatures: string[];
 }
@@ -1031,6 +1033,7 @@ function buildCategoricalMarks(opts: CategoricalOptions): {
     fullArea,
     mapAreaHeight,
     legendReserveGap,
+    legendPosition,
     showLegend,
     droppedFeatures,
   } = opts;
@@ -1142,8 +1145,15 @@ function buildCategoricalMarks(opts: CategoricalOptions): {
       shape: 'square' as const,
     }));
 
+    // Honor legend.position like the continuous path does. The map drawing
+    // area (mapAreaY in compileMap) already shifts down for top legends, so
+    // the legend row here must agree with it — a bottom-anchored legend with
+    // a top-shifted map is how legends used to land on top of Alaska.
     const legendX = fullArea.x;
-    const legendY = fullArea.y + mapAreaHeight + legendReserveGap;
+    const legendY =
+      legendPosition === 'bottom'
+        ? fullArea.y + mapAreaHeight + legendReserveGap
+        : fullArea.y + legendReserveGap;
     const legendWidth = fullArea.width;
     const swatchSize = 10;
     const swatchGap = 6;
@@ -1151,7 +1161,7 @@ function buildCategoricalMarks(opts: CategoricalOptions): {
 
     legend = {
       type: 'categorical',
-      position: 'bottom',
+      position: legendPosition,
       bounds: { x: legendX, y: legendY, width: legendWidth, height: swatchSize + 6 },
       labelStyle,
       entries,
@@ -1172,10 +1182,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;