@carto/api-client 0.5.28 → 0.5.30-alpha.143d135.117

package/package.json

@@ -8,7 +8,7 @@
   "homepage": "https://github.com/CartoDB/carto-api-client#readme",
   "author": "Don McCurdy <donmccurdy@carto.com>",
   "packageManager": "yarn@4.3.1",
-  "version": "0.5.28",
+  "version": "0.5.30-alpha.143d135.117",
   "license": "MIT",
   "publishConfig": {
     "access": "public"

package/src/fetch-map/fetch-map.ts

@@ -302,6 +302,28 @@ export async function fetchMap({
     }
   });
 
+  // Flag datasets that need feature bounding boxes for label positioning.
+  // Some data waraehouse (notably when using MVT) only support clipped
+  // geometry. The server-provided bbox enables stable label placement.
+  const layers = map.keplerMapConfig.config.visState.layers;
+  const datasetsWithLabels = new Set<string>();
+  for (const layer of layers) {
+    const hasTextLabel = layer.config?.textLabel?.some(
+      (t: any) => t.field?.name
+    );
+    if (hasTextLabel) {
+      datasetsWithLabels.add(layer.config.dataId);
+    }
+  }
+  map.datasets.forEach((dataset: any) => {
+    if (
+      datasetsWithLabels.has(dataset.id) &&
+      (dataset.type === 'table' || dataset.type === 'query')
+    ) {
+      dataset.featureBbox = true;
+    }
+  });
+
   const [basemap] = await Promise.all([
     fetchBasemapProps({config: map.keplerMapConfig.config, errorContext}),
 

package/src/fetch-map/source.ts

@@ -106,11 +106,13 @@ export function configureSource({
     tileResolution,
     ...(queryParameters && {queryParameters}),
   } as QuerySourceOptions;
+  const {featureBbox} = dataset;
   const vectorOptions = {
     spatialDataColumn,
     ...(columns && {columns}),
     ...(filters && {filters}),
     ...(aggregationExp && {aggregationExp}),
+    ...(featureBbox && {featureBbox}),
   } as VectorTableSourceOptions;
 
   if (type === 'raster') {

package/src/fetch-map/types.ts

@@ -265,6 +265,7 @@ export type Dataset = {
   name?: string | null;
   spatialIndex?: string | null;
   exportToBucketAvailable?: boolean;
+  featureBbox?: boolean;
 };
 
 export type AttributeType = 'String' | 'Number' | 'Timestamp' | 'Boolean';

package/src/filters/geosjonFeatures.ts

@@ -1,7 +1,7 @@
 import intersects from '@turf/boolean-intersects';
 import type {FeatureCollection} from 'geojson';
 import type {FeatureData} from '../types-internal.js';
-import type {SpatialFilter} from '../types.js';
+import type {GeometrySpatialFilter} from '../types.js';
 
 export function geojsonFeatures({
   geojson,
@@ -9,7 +9,7 @@ export function geojsonFeatures({
   uniqueIdProperty,
 }: {
   geojson: FeatureCollection;
-  spatialFilter: SpatialFilter;
+  spatialFilter: GeometrySpatialFilter;
   uniqueIdProperty?: string;
 }): FeatureData[] {
   let uniqueIdx = 0;

package/src/filters/tileFeatures.ts

@@ -1,6 +1,6 @@
 import type {
   RasterTile,
-  SpatialFilter,
+  GeometrySpatialFilter,
   SpatialIndexTile,
   Tile,
 } from '../types.js';
@@ -19,7 +19,7 @@ export type TileFeatures = {
   tileFormat: TileFormat;
   spatialDataType: SpatialDataType;
   spatialDataColumn?: string;
-  spatialFilter?: SpatialFilter;
+  spatialFilter?: GeometrySpatialFilter;
   uniqueIdProperty?: string;
   rasterMetadata?: RasterMetadata;
   storeGeometry?: boolean;

package/src/filters/tileFeaturesGeometries.ts

@@ -9,7 +9,7 @@ import type {
   Polygon,
   Position,
 } from 'geojson';
-import type {SpatialFilter, Tile} from '../types.js';
+import type {GeometrySpatialFilter, Tile} from '../types.js';
 import type {FeatureData} from '../types-internal.js';
 import type {
   BinaryAttribute,
@@ -45,7 +45,7 @@ export function tileFeaturesGeometries({
 }: {
   tiles: Tile[];
   tileFormat?: TileFormat;
-  spatialFilter?: SpatialFilter;
+  spatialFilter?: GeometrySpatialFilter;
   uniqueIdProperty?: string;
   options?: GeometryExtractOptions;
 }): FeatureData[] {
@@ -334,7 +334,7 @@ function calculateFeatures({
   options,
 }: {
   map: TileMap;
-  spatialFilter?: SpatialFilter;
+  spatialFilter?: GeometrySpatialFilter;
   data: BinaryFeature;
   type: BinaryGeometryType;
   bbox: BBox;

package/src/filters/tileFeaturesRaster.ts

@@ -1,5 +1,5 @@
 import {cellToTile, getResolution, tileToCell} from 'quadbin';
-import type {RasterTile, SpatialFilter, Tile} from '../types.js';
+import type {RasterTile, GeometrySpatialFilter, Tile} from '../types.js';
 import type {FeatureData} from '../types-internal.js';
 import type {
   RasterMetadata,
@@ -10,7 +10,7 @@ import {intersectTileRaster} from './tileIntersection.js';
 
 export type TileFeaturesRasterOptions = {
   tiles: RasterTile[];
-  spatialFilter?: SpatialFilter;
+  spatialFilter?: GeometrySpatialFilter;
   spatialDataColumn: string;
   spatialDataType: SpatialDataType;
   rasterMetadata: RasterMetadata;

package/src/filters/tileFeaturesSpatialIndex.ts

@@ -1,6 +1,6 @@
 import {SpatialIndex} from '../constants.js';
 import {getResolution as quadbinGetResolution} from 'quadbin';
-import type {SpatialFilter, SpatialIndexTile} from '../types.js';
+import type {GeometrySpatialFilter, SpatialIndexTile} from '../types.js';
 import type {Feature} from 'geojson';
 import {getResolution as h3GetResolution} from 'h3-js';
 import type {FeatureData} from '../types-internal.js';
@@ -9,7 +9,7 @@ import {intersectTileH3, intersectTileQuadbin} from './tileIntersection.js';
 
 export type TileFeaturesSpatialIndexOptions = {
   tiles: SpatialIndexTile[];
-  spatialFilter?: SpatialFilter;
+  spatialFilter?: GeometrySpatialFilter;
   spatialDataColumn: string;
   spatialDataType: SpatialDataType;
 };

package/src/filters/tileIntersection.ts

@@ -1,5 +1,5 @@
 import type {BBox} from 'geojson';
-import type {SpatialFilter} from '../types.js';
+import type {GeometrySpatialFilter} from '../types.js';
 import bboxPolygon from '@turf/bbox-polygon';
 import booleanWithin from '@turf/boolean-within';
 import intersect from '@turf/intersect';
@@ -19,7 +19,7 @@ import bboxClip from '@turf/bbox-clip';
 // Return types:
 // - true: All features in tile are within spatial filter.
 // - false: No features in tile are within spatial filter; skip tile.
-// - SpatialFilter/Set: Requires a more detailed per-feature check for each
+// - GeometrySpatialFilter/Set: Requires a more detailed per-feature check for each
 //    feature in the tile. Provides a clipped spatial filter local to the tile
 //    or, for spatial indexes, a set of indices ("covering set").
 //
@@ -41,8 +41,8 @@ import bboxClip from '@turf/bbox-clip';
 export function intersectTileGeometry(
   tileBbox: BBox,
   tileFormat?: TileFormat,
-  spatialFilter?: SpatialFilter
-): boolean | SpatialFilter {
+  spatialFilter?: GeometrySpatialFilter
+): boolean | GeometrySpatialFilter {
   const tilePolygon = bboxPolygon(tileBbox);
 
   if (!spatialFilter || booleanWithin(tilePolygon, spatialFilter)) {
@@ -71,7 +71,7 @@ export function intersectTileGeometry(
 export function intersectTileRaster(
   parent: bigint,
   cellResolution: bigint,
-  spatialFilter?: SpatialFilter
+  spatialFilter?: GeometrySpatialFilter
 ) {
   return intersectTileQuadbin(parent, cellResolution, spatialFilter);
 }
@@ -83,7 +83,7 @@ export function intersectTileRaster(
 export function intersectTileQuadbin(
   parent: bigint,
   cellResolution: bigint,
-  spatialFilter?: SpatialFilter
+  spatialFilter?: GeometrySpatialFilter
 ): boolean | Set<bigint> {
   const tilePolygon = quadbinCellToBoundary(parent);
 
@@ -116,7 +116,7 @@ const BBOX_EAST: BBox = [0, -90, 180, 90];
 /** @internal */
 export function intersectTileH3(
   cellResolution: number,
-  spatialFilter?: SpatialFilter
+  spatialFilter?: GeometrySpatialFilter
 ): true | Set<string> {
   if (!spatialFilter) {
     return true;

package/src/sources/vector-query-source.ts

@@ -23,7 +23,15 @@ import type {
 export type VectorQuerySourceOptions = SourceOptions &
   QuerySourceOptions &
   FilterOptions &
-  ColumnsOption;
+  ColumnsOption & {
+    /**
+     * If `true`, the server includes a `_carto_bbox` property on each polygon
+     * feature, containing the bounding box of the full (unclipped) geometry as
+     * a `"west,south,east,north"` string in WGS84. Used by clients to compute
+     * stable label positions for polygons that span multiple tiles.
+     */
+    featureBbox?: boolean;
+  };
 
 type UrlParameters = {
   columns?: string;
@@ -34,6 +42,7 @@ type UrlParameters = {
   q: string;
   queryParameters?: Record<string, unknown> | unknown[];
   aggregationExp?: string;
+  featureBbox?: boolean;
 };
 
 export type VectorQuerySourceResponse = TilejsonResult &
@@ -50,6 +59,7 @@ export const vectorQuerySource = async function (
     tileResolution = DEFAULT_TILE_RESOLUTION,
     queryParameters,
     aggregationExp,
+    featureBbox,
   } = options;
 
   const spatialDataType = 'geo';
@@ -73,6 +83,9 @@ export const vectorQuerySource = async function (
   if (aggregationExp) {
     urlParameters.aggregationExp = aggregationExp;
   }
+  if (featureBbox) {
+    urlParameters.featureBbox = true;
+  }
 
   return baseSource<UrlParameters>('query', options, urlParameters).then(
     (result) => ({

package/src/sources/vector-table-source.ts

@@ -23,7 +23,15 @@ import type {
 export type VectorTableSourceOptions = SourceOptions &
   TableSourceOptions &
   FilterOptions &
-  ColumnsOption;
+  ColumnsOption & {
+    /**
+     * If `true`, the server includes a `_carto_bbox` property on each polygon
+     * feature, containing the bounding box of the full (unclipped) geometry as
+     * a `"west,south,east,north"` string in WGS84. Used by clients to compute
+     * stable label positions for polygons that span multiple tiles.
+     */
+    featureBbox?: boolean;
+  };
 
 type UrlParameters = {
   columns?: string;
@@ -33,6 +41,7 @@ type UrlParameters = {
   tileResolution?: string;
   name: string;
   aggregationExp?: string;
+  featureBbox?: boolean;
 };
 
 export type VectorTableSourceResponse = TilejsonResult &
@@ -48,6 +57,7 @@ export const vectorTableSource = async function (
     tableName,
     tileResolution = DEFAULT_TILE_RESOLUTION,
     aggregationExp,
+    featureBbox,
   } = options;
 
   const spatialDataType = 'geo';
@@ -68,6 +78,9 @@ export const vectorTableSource = async function (
   if (aggregationExp) {
     urlParameters.aggregationExp = aggregationExp;
   }
+  if (featureBbox) {
+    urlParameters.featureBbox = true;
+  }
 
   return baseSource<UrlParameters>('table', options, urlParameters).then(
     (result) => ({

package/src/types.ts

@@ -112,8 +112,37 @@ export type AggregationType =
  * FILTERS
  */
 
+/** A spatial filter expressed as a GeoJSON polygon, applied client- or server-side. */
+export type GeometrySpatialFilter = Polygon | MultiPolygon;
+
+/**
+ * Filter restricting a widget query to a set of spatial-index cells (H3 or
+ * Quadbin). Used for point-and-click selection on cell-rendered layers. Sent to
+ * the server-side model API only; maps-api chooses the SQL strategy from
+ * `spatialDataType`, so the same payload works for both natively-indexed
+ * sources and point/geometry sources dynamically aggregated into cells.
+ *
+ * @privateRemarks Source: @carto/query-builder (SpatialIndexFilter)
+ */
+export interface SpatialIndexFilter {
+  /**
+   * Selected cell ids. h3 = hex string; h3int = `BigInt(\`0x${id}\`)`; quadbin
+   * = decimal or `0x`-hex string.
+   */
+  indexes: string[];
+  /** Must match the column type; `h3` and `h3int` are interchangeable. */
+  type: 'h3' | 'h3int' | 'quadbin';
+}
+
 /** @privateRemarks Source: @carto/react-api */
-export type SpatialFilter = Polygon | MultiPolygon;
+export type SpatialFilter = GeometrySpatialFilter | SpatialIndexFilter;
+
+/** True when a {@link SpatialFilter} selects spatial-index cells rather than a polygon. */
+export function isSpatialIndexFilter(
+  spatialFilter: SpatialFilter
+): spatialFilter is SpatialIndexFilter {
+  return Array.isArray((spatialFilter as SpatialIndexFilter).indexes);
+}
 
 /** @privateRemarks Source: @deck.gl/carto */
 export interface Filters {

package/src/widget-sources/widget-tileset-source-impl.ts

@@ -20,7 +20,13 @@ import type {
   TimeSeriesResponse,
 } from './types.js';
 import {InvalidColumnError, assert, assignOptional} from '../utils.js';
-import type {Filter, SpatialFilter, Tile} from '../types.js';
+import type {
+  Filter,
+  GeometrySpatialFilter,
+  SpatialFilter,
+  Tile,
+} from '../types.js';
+import {isSpatialIndexFilter} from '../types.js';
 
 import {
   type TileFeatureExtractOptions,
@@ -59,8 +65,9 @@ export class WidgetTilesetSourceImpl extends WidgetSource<WidgetTilesetSourcePro
   private _tiles: Tile[] = [];
   private _features: FeatureData[] = [];
   private _tileFeatureExtractOptions: TileFeatureExtractOptions = {};
-  private _tileFeatureExtractPreviousInputs: {spatialFilter?: SpatialFilter} =
-    {};
+  private _tileFeatureExtractPreviousInputs: {
+    spatialFilter?: GeometrySpatialFilter;
+  } = {};
 
   /**
    * Loads features as a list of tiles (typically provided by deck.gl).
@@ -79,12 +86,19 @@ export class WidgetTilesetSourceImpl extends WidgetSource<WidgetTilesetSourcePro
   }
 
   protected _extractTileFeatures(spatialFilter?: SpatialFilter) {
+    // Tilesets are filtered client-side, which only supports polygon filters;
+    // spatial-index filters are a server-side concern and don't apply here.
+    const geometryFilter =
+      spatialFilter && !isSpatialIndexFilter(spatialFilter)
+        ? spatialFilter
+        : undefined;
+
     // When spatial filter has not changed, don't redo extraction. If tiles or
     // tile extract options change, features will have been cleared already.
     const prevInputs = this._tileFeatureExtractPreviousInputs;
     if (
       this._features.length &&
-      spatialFilterEquals(prevInputs.spatialFilter, spatialFilter)
+      spatialFilterEquals(prevInputs.spatialFilter, geometryFilter)
     ) {
       return;
     }
@@ -92,10 +106,10 @@ export class WidgetTilesetSourceImpl extends WidgetSource<WidgetTilesetSourcePro
     this._features = tileFeatures({
       ...assignOptional({}, this.props, this._tileFeatureExtractOptions),
       tiles: this._tiles,
-      spatialFilter,
+      spatialFilter: geometryFilter,
     });
 
-    prevInputs.spatialFilter = spatialFilter;
+    prevInputs.spatialFilter = geometryFilter;
   }
 
   /**
@@ -108,7 +122,7 @@ export class WidgetTilesetSourceImpl extends WidgetSource<WidgetTilesetSourcePro
     spatialFilter,
   }: {
     geojson: FeatureCollection;
-    spatialFilter: SpatialFilter;
+    spatialFilter: GeometrySpatialFilter;
   }) {
     this._features = geojsonFeatures({
       geojson,
@@ -493,7 +507,10 @@ function normalizeColumns(columns: string | string[]): string[] {
       : [];
 }
 
-function spatialFilterEquals(a?: SpatialFilter, b?: SpatialFilter) {
+function spatialFilterEquals(
+  a?: GeometrySpatialFilter,
+  b?: GeometrySpatialFilter
+) {
   if (a === b) return true;
   if (!a || !b) return false;
   return booleanEqual(a, b);

package/src/widget-sources/widget-tileset-source.ts

@@ -18,7 +18,7 @@ import type {
   TimeSeriesRequestOptions,
   TimeSeriesResponse,
 } from './types.js';
-import type {SpatialFilter, Tile} from '../types.js';
+import type {GeometrySpatialFilter, Tile} from '../types.js';
 import type {TileFeatureExtractOptions} from '../filters/index.js';
 import type {BBox, FeatureCollection} from 'geojson';
 import {WidgetSource, type WidgetSourceProps} from './widget-source.js';
@@ -257,7 +257,7 @@ export class WidgetTilesetSource<
     spatialFilter,
   }: {
     geojson: FeatureCollection;
-    spatialFilter: SpatialFilter;
+    spatialFilter: GeometrySpatialFilter;
   }) {
     if (!this._workerEnabled) {
       return this._localImpl!.loadGeoJSON({geojson, spatialFilter});