@carto/api-client 0.5.28 → 0.5.30-alpha.3cf7d80.116

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.3cf7d80.116",
   "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/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/widget-sources/types.ts

@@ -22,6 +22,12 @@ export interface ViewState {
   longitude: number;
 }
 
+/**
+ * Topology of the features referenced by {@link BaseRequestOptions#featureIds}.
+ * Must match the geometry type of the layer the features were picked from.
+ */
+export type WidgetFeatureGeometryType = 'points' | 'lines' | 'polygons';
+
 /** Common options for {@link WidgetRemoteSource} requests. */
 export interface BaseRequestOptions {
   signal?: AbortSignal;
@@ -30,6 +36,23 @@ export interface BaseRequestOptions {
   /** Overrides source filters, if any. */
   filters?: Filters;
   filterOwner?: string;
+  /**
+   * Restricts the request to a selection of features, identified by their
+   * `_carto_feature_id` (a hash of geometry). Unlike {@link filters}, this does
+   * not require `_carto_feature_id` to exist as a column on the source: the
+   * server regenerates the hash on-the-fly and AND-s the resulting predicate
+   * onto the existing source filters.
+   *
+   * Capped at 1000 IDs server-side. {@link geometryType} is required whenever
+   * `featureIds` is provided.
+   */
+  featureIds?: string[];
+  /**
+   * Geometry topology of the features in {@link featureIds}, required whenever
+   * `featureIds` is provided. Used by the server to regenerate the feature-id
+   * hash for the correct geometry type.
+   */
+  geometryType?: WidgetFeatureGeometryType;
 }
 
 export type CategoryOrderBy =
@@ -100,7 +123,7 @@ export interface FeaturesRequestOptions extends BaseRequestOptions {
   columns: string[];
 
   /** Topology of objects to be picked. */
-  dataType: 'points' | 'lines' | 'polygons';
+  dataType: WidgetFeatureGeometryType;
 
   /** Zoom level, required if using 'points' data type. */
   z?: number;

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

@@ -20,6 +20,7 @@ import type {
   TableResponse,
   TimeSeriesRequestOptions,
   TimeSeriesResponse,
+  WidgetFeatureGeometryType,
 } from './types.js';
 import {assert, normalizeObjectKeys} from '../utils.js';
 import {DEFAULT_TILE_RESOLUTION} from '../constants-internal.js';
@@ -33,6 +34,31 @@ import type {APIErrorContext} from '../api/carto-api-error.js';
 
 export type WidgetRemoteSourceProps = WidgetSourceProps;
 
+/** Maximum number of feature IDs accepted server-side per request. */
+const FEATURE_IDS_LIMIT = 1000;
+
+/**
+ * Validates and normalizes feature-selection options shared by widget
+ * requests. Returns the model params to forward, or an empty object when no
+ * selection is requested. `geometryType` is mandatory whenever `featureIds`
+ * is provided, mirroring the server-side contract.
+ */
+function getFeatureSelectionParams(options: {
+  featureIds?: string[];
+  geometryType?: WidgetFeatureGeometryType;
+}): {featureIds?: string[]; geometryType?: WidgetFeatureGeometryType} {
+  const {featureIds, geometryType} = options;
+  if (!featureIds || featureIds.length === 0) {
+    return {};
+  }
+  assert(geometryType, 'geometryType is required when featureIds are provided');
+  assert(
+    featureIds.length <= FEATURE_IDS_LIMIT,
+    `featureIds is limited to ${FEATURE_IDS_LIMIT} values, received ${featureIds.length}`
+  );
+  return {featureIds, geometryType};
+}
+
 /**
  * Source for Widget API requests.
  *
@@ -110,6 +136,7 @@ export abstract class WidgetRemoteSource<
         operationColumn: operationColumn || column,
         othersThreshold,
         orderBy,
+        ...getFeatureSelectionParams(options),
       },
       opts: {signal, headers: this.props.headers},
     });
@@ -193,6 +220,7 @@ export abstract class WidgetRemoteSource<
         column: column ?? '*',
         operation: operation ?? AggregationTypes.Count,
         operationExp,
+        ...getFeatureSelectionParams(options),
       },
       opts: {signal, headers: this.props.headers},
     }).then((res: FormulaModelResponse) => normalizeObjectKeys(res.rows[0]));
@@ -220,7 +248,7 @@ export abstract class WidgetRemoteSource<
         spatialFiltersMode,
         spatialFilter,
       },
-      params: {column, operation, ticks},
+      params: {column, operation, ticks, ...getFeatureSelectionParams(options)},
       opts: {signal, headers: this.props.headers},
     }).then((res: HistogramModelResponse) => normalizeObjectKeys(res.rows));
 
@@ -257,7 +285,7 @@ export abstract class WidgetRemoteSource<
         spatialFiltersMode,
         spatialFilter,
       },
-      params: {column},
+      params: {column, ...getFeatureSelectionParams(options)},
       opts: {signal, headers: this.props.headers},
     }).then((res: RangeModelResponse) => normalizeObjectKeys(res.rows[0]));
   }
@@ -292,6 +320,7 @@ export abstract class WidgetRemoteSource<
         yAxisColumn,
         yAxisJoinOperation,
         limit: HARD_LIMIT,
+        ...getFeatureSelectionParams(options),
       },
       opts: {signal, headers: this.props.headers},
     })
@@ -328,6 +357,7 @@ export abstract class WidgetRemoteSource<
         sortDirection,
         limit,
         offset,
+        ...getFeatureSelectionParams(options),
       },
       opts: {signal, headers: this.props.headers},
     }).then((res: TableModelResponse) => ({
@@ -388,6 +418,7 @@ export abstract class WidgetRemoteSource<
         splitByCategory,
         splitByCategoryLimit,
         splitByCategoryValues,
+        ...getFeatureSelectionParams(options),
       },
       opts: {signal, headers: this.props.headers},
     }).then((res: TimeSeriesModelResponse) => ({
@@ -417,6 +448,7 @@ export abstract class WidgetRemoteSource<
       },
       params: {
         aggregations,
+        ...getFeatureSelectionParams(options),
       },
       opts: {signal, headers: this.props.headers},
     }).then((res: AggregationsResponse) => ({