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

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as _opendata_ai_openchart_core from '@opendata-ai/openchart-core';
-import { LegendLayout, ResolvedChrome, TooltipContent, A11yMetadata, ResolvedTheme, CompileOptions, ChartLayout, LayerSpec, CompileTableOptions, TableLayout, ResolvedAnimationPhase, AnimationSpec, ResolvedAnimation, Point, DataRow, BarListEncoding, ThemeConfig, DarkMode, MapGeo, MapEncoding, LegendConfig, TileMapEncoding, TileMapPalette, MarkType, MarkDef, Encoding, ChromeText, Annotation, LabelConfig, Display, ColumnConfig, GraphSpec, GraphEncoding, GraphLayoutConfig, NodeOverride, SankeyEncoding, SankeyNodeAlign, SankeyLinkColor, ScaleType, EncodingChannel, FieldFormatContext, Rect, LayoutStrategy, VizSpec, Mark, BinTransform, CalculateTransform, ConditionalValueDef, FilterPredicate, TimeUnitTransform, Transform } from '@opendata-ai/openchart-core';
+import { LegendLayout, ResolvedChrome, TooltipContent, A11yMetadata, ResolvedTheme, CompileOptions, ChartLayout, LayerSpec, CompileTableOptions, TableLayout, ResolvedAnimationPhase, AnimationSpec, ResolvedAnimation, Point, DataRow, BarListEncoding, ThemeConfig, DarkMode, MapGeo, MapEncoding, LegendConfig, MapPointsLayer, TileMapEncoding, TileMapPalette, MarkType, MarkDef, Encoding, ChromeText, Annotation, LabelConfig, Display, ColumnConfig, GraphSpec, GraphEncoding, GraphLayoutConfig, NodeOverride, SankeyEncoding, SankeyNodeAlign, SankeyLinkColor, ScaleType, EncodingChannel, FieldFormatContext, Rect, LayoutStrategy, VizSpec, Mark, BinTransform, CalculateTransform, ConditionalValueDef, FilterPredicate, TimeUnitTransform, Transform } from '@opendata-ai/openchart-core';
 export { BarListLayout, BarListSpec, ChartLayout, ChartSpec, CompileOptions, CompileTableOptions, GraphLayout, GraphSpec, LayerSpec, MapLayout, MapSpec, SankeyLayout, SankeySpec, TableLayout, TableSpec, TileMapLayout, TileMapSpec, VizSpec } from '@opendata-ai/openchart-core';
 import { ScaleLinear, ScaleTime, ScaleLogarithmic, ScalePower, ScaleSymLog, ScaleBand, ScalePoint, ScaleOrdinal, ScaleQuantile, ScaleQuantize, ScaleThreshold } from 'd3-scale';
 
@@ -301,6 +301,7 @@ interface NormalizedMapSpec {
     watermark: boolean;
     animation?: AnimationSpec;
     valueFormat?: string;
+    points?: MapPointsLayer;
 }
 
 /**

package/dist/index.js

@@ -5545,7 +5545,9 @@ var SIZE_SCALE_DEFAULTS = {
    * Text glyphs. Linear, not sqrt -- a word reads by its height, which is
    * linear in font size, where a disc reads by its area.
    */
-  text: { curve: "linear", range: [11, 32] }
+  text: { curve: "linear", range: [11, 32] },
+  /** Map point dots. sqrt for area-proportional, tighter range than scatter. */
+  mapPoint: { curve: "sqrt", range: [3, 20] }
 };
 function sizeScaleDefaultsFor(markType) {
   const found = SIZE_SCALE_DEFAULTS[markType];
@@ -10631,7 +10633,8 @@ function normalizeMapSpec(spec, _warnings) {
     darkMode: spec.darkMode ?? "off",
     watermark: spec.watermark ?? true,
     animation: spec.animation,
-    valueFormat: spec.valueFormat
+    valueFormat: spec.valueFormat,
+    points: spec.points
   };
 }
 function normalizeBarListSpec(spec, _warnings) {
@@ -11802,25 +11805,91 @@ function validateMapSpec(spec, errors) {
     }
   }
   const encoding = spec.encoding;
-  for (const channel of ["key", "color"]) {
-    const ch = encoding[channel];
-    if (!ch || typeof ch !== "object") {
+  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 (!isBasemapOnly) {
+    if (!keyCh || typeof keyCh !== "object") {
       errors.push({
-        message: `Spec error: map encoding requires "${channel}" channel`,
-        path: `encoding.${channel}`,
+        message: 'Spec error: map encoding requires "key" channel',
+        path: "encoding.key",
         code: "MISSING_FIELD",
-        suggestion: `Add encoding.${channel}, e.g. ${channel}: { field: "${channel === "key" ? "id" : "value"}", type: "${channel === "key" ? "nominal" : "quantitative"}" }`
+        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" }'
       });
-      continue;
     }
-    if (!ch.field || typeof ch.field !== "string") {
+  }
+  const colorCh = encoding.color;
+  if (!hasPoints) {
+    if (!colorCh || typeof colorCh !== "object") {
       errors.push({
-        message: `Spec error: encoding.${channel} must have a "field" string`,
-        path: `encoding.${channel}.field`,
+        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.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. ${channel}: { field: "${channel === "key" ? "id" : "value"}" }`
+        suggestion: 'Add a field name, e.g. color: { field: "value" }'
       });
     }
+  } 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 (hasPoints) {
+    const points = spec.points;
+    if (!Array.isArray(points.data)) {
+      errors.push({
+        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"]) {
+      const enc = points[ch];
+      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"}" }`
+        });
+      }
+    }
+    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) {
@@ -17767,11 +17836,11 @@ function compileMap(spec, options) {
   const compileWarnings = [];
   const showLegend = mapSpec.legend?.show !== false;
   const colorEncoding = mapSpec.encoding.color;
-  const isQuantitative = colorEncoding.type === "quantitative";
+  const isQuantitative = colorEncoding?.type === "quantitative";
   const legendPosition = mapSpec.legend?.position === "bottom" ? "bottom" : "top";
   let legendBlockHeight = 0;
   let continuousContent = null;
-  if (showLegend && isQuantitative) {
+  if (showLegend && colorEncoding && isQuantitative) {
     const colorValues = [];
     for (const row of mapSpec.data) {
       const v = row[colorEncoding.field];
@@ -17794,10 +17863,19 @@ function compileMap(spec, options) {
       const labelRowHeight = Math.ceil(theme.fonts.sizes.small * 1.3);
       legendBlockHeight = continuousContent.barHeight + CONTINUOUS_LABEL_GAP + labelRowHeight;
     }
-  } else if (showLegend) {
+  } else if (showLegend && colorEncoding) {
     const labelHeight = Math.ceil(theme.fonts.sizes.small * 1.3);
     legendBlockHeight = Math.max(10, labelHeight) + 6;
   }
+  if (showLegend && mapSpec.points?.color) {
+    if (mapSpec.points.color.type === "quantitative") {
+      const labelRowHeight = Math.ceil(theme.fonts.sizes.small * 1.3);
+      legendBlockHeight += CONTINUOUS_BAR_HEIGHT + CONTINUOUS_LABEL_GAP + labelRowHeight + 8;
+    } else {
+      const ptLabelHeight = Math.ceil(theme.fonts.sizes.small * 1.3);
+      legendBlockHeight += Math.max(10, ptLabelHeight) + 6 + 8;
+    }
+  }
   const legendReserveGap = legendBlockHeight > 0 ? 8 : 0;
   const mapAreaHeight = fullArea.height - legendBlockHeight - legendReserveGap;
   if (mapAreaHeight <= 0) {
@@ -17819,17 +17897,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
-  );
-  compileWarnings.push(...joinWarnings);
+  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";
@@ -17837,13 +17920,21 @@ function compileMap(spec, options) {
   let featureMarks;
   let continuousLegend = null;
   let categoricalLegend = null;
-  if (isQuantitative) {
+  if (!colorEncoding) {
+    featureMarks = buildBasemapMarks({
+      geoFeatures,
+      pathGen,
+      neutralFill,
+      neutralStroke,
+      droppedFeatures
+    });
+  } else if (isQuantitative) {
     const result = buildQuantitativeMarks({
       geoFeatures,
       pathGen,
       joined,
       colorField: colorEncoding.field,
-      palette: mapSpec.encoding.color.scale?.scheme ?? "blue",
+      palette: colorEncoding.scale?.scheme ?? "blue",
       isDarkMode: !!isDarkMode,
       neutralFill,
       neutralStroke,
@@ -17893,6 +17984,7 @@ function compileMap(spec, options) {
       pathGen,
       joined,
       colorField: colorEncoding.field,
+      colorScale: colorEncoding.scale,
       isDarkMode: !!isDarkMode,
       neutralFill,
       neutralStroke,
@@ -17928,6 +18020,201 @@ function compileMap(spec, options) {
   const interiorStroke = isDarkMode ? "rgba(255,255,255,0.3)" : "rgba(0,0,0,0.15)";
   const outlineStroke = isDarkMode ? "rgba(255,255,255,0.5)" : "rgba(0,0,0,0.3)";
   const borders = { interiorPath, outlinePath, interiorStroke, outlineStroke };
+  const pointMarks = [];
+  let pointCategoricalLegend = null;
+  let pointContinuousLegend = null;
+  if (mapSpec.points) {
+    const pts = mapSpec.points;
+    const lonField = pts.longitude.field;
+    const latField = pts.latitude.field;
+    const keyChannel = pts.key;
+    const sizeScale = buildSizeScale(pts.size, pts.data, SIZE_SCALE_DEFAULTS.mapPoint);
+    let pointColorScale = null;
+    const pointCategories = [];
+    const pointCategoryColors = /* @__PURE__ */ new Map();
+    if (pts.color) {
+      if (pts.color.type === "quantitative") {
+        const colorValues = [];
+        for (const row of pts.data) {
+          const raw = row[pts.color.field];
+          if (raw != null) {
+            const v = Number(raw);
+            if (Number.isFinite(v)) colorValues.push(v);
+          }
+        }
+        if (colorValues.length > 0) {
+          const palette = pts.color.scale?.scheme ?? "blue";
+          const paletteStops = [...SEQUENTIAL_PALETTES[palette] ?? SEQUENTIAL_PALETTES.blue];
+          const qScale = quantile2().domain(colorValues).range(paletteStops);
+          pointColorScale = (val) => {
+            const v = Number(val);
+            return Number.isFinite(v) ? qScale(v) : CATEGORICAL_PALETTE[0];
+          };
+        }
+      } else {
+        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) {
+            const cat = String(raw);
+            if (!seen.has(cat)) {
+              seen.add(cat);
+              pointCategories.push(cat);
+            }
+          }
+        }
+        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 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]);
+      const lat = Number(row[latField]);
+      if (!Number.isFinite(lon) || !Number.isFinite(lat)) continue;
+      const projected = projection2([lon, lat]);
+      if (!projected) {
+        droppedPoints.push([lon, lat]);
+        continue;
+      }
+      const r = sizeScale ? sizeScale.scale(Number(row[sizeScale.field])) : 5;
+      const fill = pointColorScale && pts.color ? pointColorScale(row[pts.color.field]) : defaultFill;
+      const key = keyChannel ? String(row[keyChannel.field] ?? i) : String(i);
+      const stroke = isDarkMode ? "rgba(0,0,0,0.5)" : "rgba(255,255,255,0.8)";
+      pointMarks.push({
+        type: "map-point",
+        cx: projected[0],
+        cy: projected[1],
+        r,
+        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,
+        fontSize: theme.fonts.sizes.small,
+        fontWeight: theme.fonts.weights.normal,
+        fill: theme.colors.text,
+        lineHeight: 1.2
+      };
+      const entries = pointCategories.map((cat) => ({
+        label: cat,
+        color: pointCategoryColors.get(cat),
+        shape: "circle"
+      }));
+      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 + bottomChoroplethHeight + choroplethLegendGap;
+      const legendWidth = fullArea.width;
+      const swatchSize = 10;
+      const swatchGap = 6;
+      const entryGap = 16;
+      pointCategoricalLegend = {
+        type: "categorical",
+        position: "bottom",
+        bounds: { x: legendX, y: legendY, width: legendWidth, height: swatchSize + 6 },
+        labelStyle,
+        entries,
+        swatchSize,
+        swatchGap,
+        entryGap,
+        swatchChipFill: isDarkMode ? "rgba(255,255,255,0.06)" : "rgba(0,0,0,0.04)"
+      };
+    }
+    if (pts.color && pts.color.type === "quantitative" && showLegend) {
+      const ptColorValues = [];
+      for (const row of pts.data) {
+        const v = row[pts.color.field];
+        if (v != null) {
+          const n = Number(v);
+          if (Number.isFinite(n)) ptColorValues.push(n);
+        }
+      }
+      const ptLegendChannel = {
+        ...pts.color,
+        scale: { ...pts.color.scale, type: "quantile" }
+      };
+      const ptContinuousContent = computeContinuousLegendContentForChannel(
+        ptColorValues,
+        ptLegendChannel,
+        theme,
+        fullArea.width
+      );
+      if (ptContinuousContent) {
+        const labelStyle = {
+          fontFamily: theme.fonts.family,
+          fontSize: theme.fonts.sizes.small,
+          fontWeight: theme.fonts.weights.normal,
+          fill: theme.colors.text,
+          lineHeight: 1.3,
+          fontVariant: "tabular-nums"
+        };
+        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 + bottomChoroplethH + choroplethLegendGap;
+        const ptLabelRowHeight = Math.ceil(theme.fonts.sizes.small * 1.3);
+        const ptLegendHeight = ptContinuousContent.barHeight + CONTINUOUS_LABEL_GAP + ptLabelRowHeight;
+        const bounds = {
+          x: legendX,
+          y: legendY,
+          width: ptContinuousContent.barWidth,
+          height: ptLegendHeight
+        };
+        const bar = {
+          x: bounds.x,
+          y: bounds.y,
+          width: ptContinuousContent.barWidth,
+          height: ptContinuousContent.barHeight
+        };
+        pointContinuousLegend = {
+          type: "continuous",
+          mode: ptContinuousContent.mode,
+          position: "bottom",
+          bounds,
+          labelStyle,
+          bar,
+          colorStops: ptContinuousContent.colorStops,
+          bins: ptContinuousContent.bins.map((b) => ({ ...b, x: b.x + bar.x })),
+          ticks: ptContinuousContent.ticks.map((t) => ({ ...t, x: t.x + bar.x })),
+          labelY: bar.y + bar.height + CONTINUOUS_LABEL_GAP + labelStyle.fontSize
+        };
+      }
+    }
+  }
   const tooltipChannels = mapSpec.encoding.tooltip ? Array.isArray(mapSpec.encoding.tooltip) ? mapSpec.encoding.tooltip : [mapSpec.encoding.tooltip] : null;
   const tooltipDescriptors = /* @__PURE__ */ new Map();
   for (const mark of featureMarks) {
@@ -17945,12 +18232,12 @@ function compileMap(spec, options) {
           });
         }
       }
-    } else if (isQuantitative && mark.data[colorEncoding.field] != null) {
+    } else if (colorEncoding && isQuantitative && mark.data[colorEncoding.field] != null) {
       fields.push({
         label: colorEncoding.title ?? colorEncoding.field,
         value: formatter(Number(mark.data[colorEncoding.field]))
       });
-    } else if (!isQuantitative && mark.data[colorEncoding.field] != null) {
+    } else if (colorEncoding && !isQuantitative && mark.data[colorEncoding.field] != null) {
       fields.push({
         label: colorEncoding.title ?? colorEncoding.field,
         value: String(mark.data[colorEncoding.field])
@@ -17958,11 +18245,61 @@ function compileMap(spec, options) {
     }
     tooltipDescriptors.set(String(mark.id), { fields });
   }
+  if (mapSpec.points && pointMarks.length > 0) {
+    const ptTooltipChannels = mapSpec.points.tooltip ? Array.isArray(mapSpec.points.tooltip) ? mapSpec.points.tooltip : [mapSpec.points.tooltip] : null;
+    for (const pm of pointMarks) {
+      const fields = [];
+      if (ptTooltipChannels) {
+        for (const ch of ptTooltipChannels) {
+          const val = pm.data[ch.field];
+          if (val != null) {
+            fields.push({
+              label: ch.title ?? ch.field,
+              value: ch.type === "quantitative" ? formatter(Number(val)) : String(val)
+            });
+          }
+        }
+      } else {
+        const pts = mapSpec.points;
+        if (pts.key) {
+          const val = pm.data[pts.key.field];
+          if (val != null)
+            fields.push({ label: pts.key.title ?? pts.key.field, value: String(val) });
+        }
+        if (pts.color) {
+          const val = pm.data[pts.color.field];
+          if (val != null)
+            fields.push({
+              label: pts.color.title ?? pts.color.field,
+              value: pts.color.type === "quantitative" ? formatter(Number(val)) : String(val)
+            });
+        }
+        if (pts.size) {
+          const val = pm.data[pts.size.field];
+          if (val != null)
+            fields.push({ label: pts.size.title ?? pts.size.field, value: formatter(Number(val)) });
+        }
+      }
+      if (fields.length > 0) {
+        tooltipDescriptors.set(`point:${pm.key}`, { fields });
+      }
+    }
+  }
+  const a11yDataField = colorEncoding?.field;
   const a11y = {
-    altText: `Map showing ${geoFeatures.length} regions with ${isQuantitative ? "quantitative" : "categorical"} data`,
-    dataTableFallback: featureMarks.filter((m) => m.data).map((m) => [m.name ?? String(m.id), String(m.data?.[colorEncoding.field] ?? "")]),
+    altText: pointMarks.length > 0 ? colorEncoding ? `Map showing ${geoFeatures.length} regions with ${isQuantitative ? "quantitative" : "categorical"} data and ${pointMarks.length} point markers` : `Map showing ${geoFeatures.length} regions with ${pointMarks.length} point markers` : colorEncoding ? `Map showing ${geoFeatures.length} regions with ${isQuantitative ? "quantitative" : "categorical"} data` : `Map showing ${geoFeatures.length} regions`,
+    dataTableFallback: [
+      ...featureMarks.filter((m) => m.data).map((m) => [
+        m.name ?? String(m.id),
+        a11yDataField ? String(m.data?.[a11yDataField] ?? "") : ""
+      ]),
+      ...pointMarks.map((pm) => [
+        pm.key,
+        mapSpec.points?.color ? String(pm.data[mapSpec.points.color.field] ?? "") : ""
+      ])
+    ],
     role: "img",
-    keyboardNavigable: featureMarks.length > 0
+    keyboardNavigable: featureMarks.length > 0 || pointMarks.length > 0
   };
   const resolvedFocus = resolveFocus(mapSpec.geo.focus, featureMarks, compileWarnings);
   const resolvedAnimation = resolveAnimation(mapSpec.animation);
@@ -17987,6 +18324,9 @@ function compileMap(spec, options) {
     borders,
     continuousLegend,
     categoricalLegend,
+    pointMarks,
+    pointCategoricalLegend,
+    pointContinuousLegend,
     tooltipDescriptors,
     a11y,
     theme,
@@ -18000,6 +18340,46 @@ function compileMap(spec, options) {
     focus: resolvedFocus
   };
 }
+function buildBasemapMarks(opts) {
+  const { geoFeatures, pathGen, neutralFill, neutralStroke, droppedFeatures } = opts;
+  const marks = [];
+  let animIndex = 0;
+  for (const feat of geoFeatures) {
+    const pathD = pathGen(feat);
+    if (!pathD) {
+      const name2 = feat.properties?.name ?? String(feat.id);
+      droppedFeatures.push(name2);
+      continue;
+    }
+    const featureId = feat.id;
+    const props = feat.properties;
+    const name = props?.name ?? props?.NAME;
+    const b = pathGen.bounds(feat);
+    const bx = Number.isFinite(b[0][0]) ? b[0][0] : 0;
+    const by = Number.isFinite(b[0][1]) ? b[0][1] : 0;
+    const bw = Number.isFinite(b[1][0]) ? b[1][0] - bx : 0;
+    const bh = Number.isFinite(b[1][1]) ? b[1][1] - by : 0;
+    const bounds = { x: bx, y: by, width: bw, height: bh };
+    const rawCentroid = pathGen.centroid(feat);
+    const cx = Number.isFinite(rawCentroid[0]) ? rawCentroid[0] : bx + bw / 2;
+    const cy = Number.isFinite(rawCentroid[1]) ? rawCentroid[1] : by + bh / 2;
+    marks.push({
+      type: "map-feature",
+      path: pathD,
+      fill: neutralFill,
+      stroke: neutralStroke,
+      strokeWidth: 0.5,
+      id: featureId,
+      name,
+      data: null,
+      aria: { role: "img", label: name ?? String(featureId) },
+      animationIndex: animIndex++,
+      bounds,
+      centroid: [cx, cy]
+    });
+  }
+  return marks;
+}
 function buildQuantitativeMarks(opts) {
   const {
     geoFeatures,
@@ -18084,6 +18464,7 @@ function buildCategoricalMarks(opts) {
     pathGen,
     joined,
     colorField,
+    colorScale: scaleConfig,
     isDarkMode,
     neutralFill,
     neutralStroke,
@@ -18095,7 +18476,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) {
@@ -18106,9 +18493,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;
@@ -18256,6 +18645,9 @@ function emptyLayout3(chrome, theme, options, watermark) {
     },
     continuousLegend: null,
     categoricalLegend: null,
+    pointMarks: [],
+    pointCategoricalLegend: null,
+    pointContinuousLegend: null,
     tooltipDescriptors: /* @__PURE__ */ new Map(),
     a11y: {
       altText: "Empty map",