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

package/dist/index.js

@@ -11758,12 +11758,31 @@ function validateMapSpec(spec, errors) {
       }
     } else if (typeof focus === "object") {
       const focusObj = focus;
-      if (!("features" in focusObj) || focusObj.features == null) {
+      if ("points" in focusObj) {
+        const pts = focusObj.points;
+        const isSubset = typeof pts === "object" && pts !== null && typeof pts.field === "string" && "value" in pts;
+        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 !== void 0 && 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 } }'
+          suggestion: '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;
@@ -11797,30 +11816,34 @@ function validateMapSpec(spec, errors) {
       }
     } else {
       errors.push({
-        message: "Spec error: geo.focus must be a string, number, array of ids, or object with { features, padding? }",
+        message: "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.'
+        suggestion: 'Use a feature id, array of ids, { features: "36", padding: 16 }, or { points: true }. Pass null to clear focus.'
       });
     }
   }
   const encoding = spec.encoding;
   const hasPoints = spec.points && typeof spec.points === "object" && !Array.isArray(spec.points);
+  const specData = spec.data;
+  const isBasemapOnly = hasPoints && (!specData || specData.length === 0);
   const keyCh = encoding.key;
-  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" }'
+      });
+    }
   }
   const colorCh = encoding.color;
   if (!hasPoints) {
@@ -11875,6 +11898,17 @@ function validateMapSpec(spec, errors) {
         });
       }
     }
+    for (const ch of ["size", "color", "key"]) {
+      const enc = points[ch];
+      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" }`
+        });
+      }
+    }
   }
 }
 function validateBarListSpec(spec, errors) {
@@ -17882,18 +17916,22 @@ function compileMap(spec, options) {
       }
     }
   }
-  const featureObjs = geoFeatures.map((f) => ({
-    id: f.id,
-    properties: f.properties ?? {}
-  }));
-  const { joined, warnings: joinWarnings } = joinDataToFeatures(
-    featureObjs,
-    mapSpec.data,
-    mapSpec.encoding.key.field,
-    mapSpec.geo.idField
-  );
-  const filteredJoinWarnings = mapSpec.data.length === 0 && mapSpec.points ? joinWarnings.filter((w) => w.code !== "UNMATCHED_FEATURES") : joinWarnings;
-  compileWarnings.push(...filteredJoinWarnings);
+  let joined = /* @__PURE__ */ new Map();
+  if (mapSpec.encoding.key) {
+    const featureObjs = geoFeatures.map((f) => ({
+      id: f.id,
+      properties: f.properties ?? {}
+    }));
+    const joinResult = joinDataToFeatures(
+      featureObjs,
+      mapSpec.data,
+      mapSpec.encoding.key.field,
+      mapSpec.geo.idField
+    );
+    joined = joinResult.joined;
+    const filteredJoinWarnings = mapSpec.data.length === 0 && mapSpec.points ? joinResult.warnings.filter((w) => w.code !== "UNMATCHED_FEATURES") : joinResult.warnings;
+    compileWarnings.push(...filteredJoinWarnings);
+  }
   const droppedFeatures = [];
   const formatter = buildD3Formatter2(mapSpec.valueFormat) ?? formatNumber3;
   const neutralFill = isDarkMode ? "#2a2a2a" : "#e8e8e8";
@@ -17965,6 +18003,7 @@ function compileMap(spec, options) {
       pathGen,
       joined,
       colorField: colorEncoding.field,
+      colorScale: colorEncoding.scale,
       isDarkMode: !!isDarkMode,
       neutralFill,
       neutralStroke,
@@ -18032,7 +18071,14 @@ function compileMap(spec, options) {
           };
         }
       } else {
-        const seen = /* @__PURE__ */ new Set();
+        const explicitDomain = pts.color.scale?.domain;
+        const explicitRange = pts.color.scale?.range;
+        if (explicitDomain && Array.isArray(explicitDomain)) {
+          for (const cat of explicitDomain) {
+            pointCategories.push(String(cat));
+          }
+        }
+        const seen = new Set(pointCategories);
         for (const row of pts.data) {
           const raw = row[pts.color.field];
           if (raw != null) {
@@ -18040,21 +18086,23 @@ function compileMap(spec, options) {
             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) => {
-          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 = [];
     for (let i = 0; i < pts.data.length; i++) {
       const row = pts.data[i];
       const lon = Number(row[lonField]);
@@ -18062,11 +18110,7 @@ function compileMap(spec, options) {
       if (!Number.isFinite(lon) || !Number.isFinite(lat)) continue;
       const projected = projection2([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;
       }
       const r = sizeScale ? sizeScale.scale(Number(row[sizeScale.field])) : 5;
@@ -18081,12 +18125,21 @@ function compileMap(spec, options) {
         fill,
         stroke,
         strokeWidth: 1,
+        fillOpacity: pointOpacity,
         key,
         data: row,
         aria: { role: "img", label: key },
         animationIndex: animIndex++
       });
     }
+    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) }
+      });
+    }
     if (pts.color && pts.color.type !== "quantitative" && pointCategories.length > 0 && showLegend) {
       const labelStyle = {
         fontFamily: theme.fonts.family,
@@ -18100,10 +18153,10 @@ function compileMap(spec, options) {
         color: pointCategoryColors.get(cat),
         shape: "circle"
       }));
-      const choroplethLegendHeight = continuousLegend ? continuousLegend.bounds.height : categoricalLegend ? categoricalLegend.bounds.height : 0;
-      const choroplethLegendGap = choroplethLegendHeight > 0 ? 8 : 0;
+      const bottomChoroplethHeight = legendPosition === "bottom" ? continuousLegend?.bounds.height ?? categoricalLegend?.bounds.height ?? 0 : 0;
+      const choroplethLegendGap = bottomChoroplethHeight > 0 ? 8 : 0;
       const legendX = fullArea.x;
-      const legendY = fullArea.y + mapAreaHeight + legendReserveGap + choroplethLegendHeight + choroplethLegendGap;
+      const legendY = fullArea.y + mapAreaHeight + legendReserveGap + bottomChoroplethHeight + choroplethLegendGap;
       const legendWidth = fullArea.width;
       const swatchSize = 10;
       const swatchGap = 6;
@@ -18148,10 +18201,10 @@ function compileMap(spec, options) {
           lineHeight: 1.3,
           fontVariant: "tabular-nums"
         };
-        const choroplethLegendHeight = continuousLegend ? continuousLegend.bounds.height : categoricalLegend ? categoricalLegend.bounds.height : 0;
-        const choroplethLegendGap = choroplethLegendHeight > 0 ? 8 : 0;
+        const bottomChoroplethH = legendPosition === "bottom" ? continuousLegend?.bounds.height ?? categoricalLegend?.bounds.height ?? 0 : 0;
+        const choroplethLegendGap = bottomChoroplethH > 0 ? 8 : 0;
         const legendX = fullArea.x;
-        const legendY = fullArea.y + mapAreaHeight + legendReserveGap + choroplethLegendHeight + choroplethLegendGap;
+        const legendY = fullArea.y + mapAreaHeight + legendReserveGap + bottomChoroplethH + choroplethLegendGap;
         const ptLabelRowHeight = Math.ceil(theme.fonts.sizes.small * 1.3);
         const ptLegendHeight = ptContinuousContent.barHeight + CONTINUOUS_LABEL_GAP + ptLabelRowHeight;
         const bounds = {
@@ -18267,7 +18320,7 @@ function compileMap(spec, options) {
     role: "img",
     keyboardNavigable: featureMarks.length > 0 || pointMarks.length > 0
   };
-  const resolvedFocus = resolveFocus(mapSpec.geo.focus, featureMarks, compileWarnings);
+  const resolvedFocus = resolveFocus(mapSpec.geo.focus, featureMarks, pointMarks, compileWarnings);
   const resolvedAnimation = resolveAnimation(mapSpec.animation);
   const mapAreaY = legendPosition === "top" && legendBlockHeight > 0 ? fullArea.y + legendBlockHeight + legendReserveGap : fullArea.y;
   const mapArea = {
@@ -18430,6 +18483,7 @@ function buildCategoricalMarks(opts) {
     pathGen,
     joined,
     colorField,
+    colorScale: scaleConfig,
     isDarkMode,
     neutralFill,
     neutralStroke,
@@ -18441,7 +18495,13 @@ function buildCategoricalMarks(opts) {
     droppedFeatures
   } = opts;
   const categories = [];
-  const seen = /* @__PURE__ */ new Set();
+  const explicitDomain = scaleConfig?.domain;
+  if (explicitDomain && Array.isArray(explicitDomain)) {
+    for (const cat of explicitDomain) {
+      categories.push(String(cat));
+    }
+  }
+  const seen = new Set(categories);
   for (const row of joined.values()) {
     const raw = row[colorField];
     if (raw != null) {
@@ -18452,9 +18512,11 @@ function buildCategoricalMarks(opts) {
       }
     }
   }
+  const explicitRange = scaleConfig?.range;
+  const colorSource = explicitRange && Array.isArray(explicitRange) ? explicitRange : CATEGORICAL_PALETTE;
   const categoryColors = /* @__PURE__ */ new Map();
   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 = [];
   let animIndex = 0;
@@ -18541,8 +18603,38 @@ function buildCategoricalMarks(opts) {
   }
   return { marks, legend };
 }
-function resolveFocus(focus, features, warnings) {
+function resolveFocus(focus, features, pointMarks, warnings) {
   if (focus === null || focus === void 0) return null;
+  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 padding2 = focus.padding ?? 16;
+    let minX2 = Infinity;
+    let minY2 = Infinity;
+    let maxX2 = -Infinity;
+    let maxY2 = -Infinity;
+    for (const p of matched) {
+      minX2 = Math.min(minX2, p.cx - p.r);
+      minY2 = Math.min(minY2, p.cy - p.r);
+      maxX2 = Math.max(maxX2, p.cx + p.r);
+      maxY2 = Math.max(maxY2, p.cy + p.r);
+    }
+    return {
+      target: { x: minX2, y: minY2, width: maxX2 - minX2, height: maxY2 - minY2, padding: padding2 },
+      // No feature ids: focus-dim is a feature concept, so a points focus
+      // dims no features (there are no "other" features to mute).
+      ids: []
+    };
+  }
   let ids;
   let padding = 16;
   if (typeof focus === "string" || typeof focus === "number") {