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

package/dist/index.d.ts

@@ -2424,9 +2424,21 @@ interface TileMapSpec {
 /** Supported map projections. */
 type MapProjection = 'albersUsa' | 'mercator' | 'equalEarth' | 'identity';
 /** Focus target for map camera: feature id(s) to zoom/pan to. */
+/**
+ * Fit the point layer's cluster. `true` fits every point; `{ field, value }`
+ * fits only the points whose data row has `row[field] === value` (e.g. only the
+ * campuses rated "F"), which lets a story pan between sub-clusters.
+ */
+type MapPointsFocus = true | {
+    field: string;
+    value: string | number;
+};
 type MapFocus = string | number | Array<string | number> | {
     features: string | number | Array<string | number>;
     padding?: number;
+} | {
+    points: MapPointsFocus;
+    padding?: number;
 };
 /** Geo configuration for map specs. */
 interface MapGeo {
@@ -2436,13 +2448,20 @@ interface MapGeo {
     idField?: string;
     /** Map projection. Defaults to 'albersUsa'. */
     projection?: MapProjection;
-    /** Focus on specific feature(s). null clears focus from a prior story step. */
+    /**
+     * Focus the camera. A feature id (or array) fits those features; `{ features, padding }`
+     * adds breathing room; `{ points: true, padding }` fits the points layer's cluster
+     * instead of any feature (use when points occupy a small part of a large feature, so
+     * fitting the feature would leave the cluster small and off-center);
+     * `{ points: { field, value }, padding }` fits only the matching point subset, so a
+     * story can pan between sub-clusters. null clears focus from a prior story step.
+     */
     focus?: MapFocus | null;
 }
 /** Encoding channels specific to map visualizations. */
 interface MapEncoding {
-    /** Join key field in the data (required). Maps data rows to geo features via geo.idField. */
-    key: EncodingChannel;
+    /** Join key field in the data. Required for choropleth; optional in basemap-only mode (points layer with empty data). */
+    key?: EncodingChannel;
     /** Color encoding (quantitative or nominal). Drives fill color of features. Optional when a points layer is present (basemap-only mode). */
     color?: EncodingChannel;
     /** Tooltip encoding (optional). */
@@ -2456,14 +2475,16 @@ interface MapPointsLayer {
     longitude: EncodingChannel;
     /** Field holding latitude (y coordinate). */
     latitude: EncodingChannel;
-    /** Optional quantitative size encoding. Area-proportional: r proportional to sqrt(value). */
+    /** Optional quantitative size encoding. Area-proportional: r proportional to sqrt(value). No size legend is rendered in v1; explain the scale in chrome.subtitle if needed. */
     size?: EncodingChannel;
     /** Optional color encoding (nominal or quantitative). Independent scale from choropleth. */
     color?: EncodingChannel;
     /** Tooltip channel(s), same shape as MapEncoding.tooltip. */
     tooltip?: EncodingChannel | EncodingChannel[];
-    /** Stable id field for transitions and event callbacks. */
+    /** Stable id for event callbacks. Data-update transitions for points are not yet supported. */
     key?: EncodingChannel;
+    /** Fill opacity for point circles. Default 0.65. Range 0-1. */
+    opacity?: number;
 }
 interface MapSpec {
     /** Discriminant: always "map". */
@@ -4678,7 +4699,9 @@ interface MapPointMark {
     stroke: string;
     /** Stroke width in px. */
     strokeWidth: number;
-    /** Stable key for events and transitions. */
+    /** Fill opacity (0-1). */
+    fillOpacity: number;
+    /** Stable key for events. */
     key: string;
     /** Original data row. */
     data: Record<string, unknown>;