@carto/api-client 0.5.27 → 0.5.29

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.27",
+  "version": "0.5.29",
   "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/layer-map.ts

@@ -514,10 +514,11 @@ export function getMaxMarkerSize(
   visConfig: VisConfig,
   visualChannels: VisualChannels
 ): number {
-  const {radiusRange, radius} = visConfig;
+  const {radiusRange, radius, sizeMaxPixels} = visConfig;
   const {radiusField, sizeField} = visualChannels;
   const field = radiusField || sizeField;
-  return Math.ceil(radiusRange && field ? radiusRange[1] : radius);
+  const baseSize = radiusRange && field ? radiusRange[1] : radius;
+  return Math.ceil(sizeMaxPixels ?? baseSize);
 }
 
 type Accessor = number | ((d: any, i: any) => number);

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

@@ -128,6 +128,7 @@ export function getLayerDescriptor({
       ...createInteractionProps(interactionConfig),
       ...styleProps,
       ...channelProps,
+      ...createZoomScaleProps(config, visualChannels),
       ...createParametersProp(layerBlending, styleProps.parameters || {}), // Must come after style
       ...createLoadOptions(data.accessToken),
     },
@@ -208,6 +209,38 @@ function createInteractionProps(interactionConfig: any) {
   };
 }
 
+function createZoomScaleProps(
+  config: MapLayerConfig,
+  visualChannels: VisualChannels
+): Record<string, any> {
+  const {visConfig} = config;
+  if (
+    !visConfig.radiusScaleWithZoom ||
+    visualChannels.radiusField ||
+    visualChannels.sizeField
+  ) {
+    return {};
+  }
+  // When `radiusScaleWithZoom` is enabled, render the point in `common`
+  // coordinate space so it scales proportionally with zoom.
+  const scale = Math.pow(2, -(visConfig.radiusReferenceZoom as number));
+  const result: Record<string, any> = {
+    pointRadiusUnits: 'common',
+    pointRadiusScale: scale,
+    iconSizeUnits: 'common',
+    iconSizeScale: scale,
+  };
+  if (visConfig.sizeMinPixels !== undefined) {
+    result.pointRadiusMinPixels = visConfig.sizeMinPixels;
+    result.iconSizeMinPixels = visConfig.sizeMinPixels;
+  }
+  if (visConfig.sizeMaxPixels !== undefined) {
+    result.pointRadiusMaxPixels = visConfig.sizeMaxPixels;
+    result.iconSizeMaxPixels = visConfig.sizeMaxPixels;
+  }
+  return result;
+}
+
 function mapProps(source: any, target: any, mapping: any) {
   for (const sourceKey in mapping) {
     const sourceValue = source[sourceKey];
@@ -667,7 +700,24 @@ function createChannelProps(
     const getSecondaryText =
       secondaryField && getTextAccessor(secondaryField, data);
 
-    result.pointType = `${result.pointType}+text`;
+    // For line/polygon tileset layers, deck.gl's VectorTileLayer can synthesize
+    // point labels at line midpoints / polygon centroids via `autoLabels`. The
+    // optional `uniqueIdProperty` dedupes features that span multiple tiles so
+    // each feature gets one label instead of one-per-tile.
+    const geometry = data.tilestats?.layers?.[0]?.geometry;
+    const isLineOrPolygon =
+      geometry === 'Polygon' ||
+      geometry === 'MultiPolygon' ||
+      geometry === 'Line' ||
+      geometry === 'LineString' ||
+      geometry === 'MultiLineString';
+    if (isLineOrPolygon && (layerType === 'tileset' || layerType === 'mvt')) {
+      const uniqueIdProperty = visConfig.textLabelUniqueIdField;
+      result.autoLabels = uniqueIdProperty ? {uniqueIdProperty} : true;
+      result.pointType = 'text';
+    } else {
+      result.pointType = `${result.pointType}+text`;
+    }
     result.textCharacterSet = 'auto';
     result.textFontFamily = 'Inter, sans';
     result.textFontSettings = {sdf: true};

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

@@ -80,6 +80,11 @@ export type VisConfig = {
   radiusAggregationExp?: string;
   radiusAggregationDomain?: [number, number];
 
+  sizeMinPixels?: number;
+  sizeMaxPixels?: number;
+  radiusScaleWithZoom?: boolean;
+  radiusReferenceZoom?: number;
+
   sizeAggregation?: string;
   sizeAggregationExp?: string;
   sizeAggregationDomain?: [number, number];
@@ -108,6 +113,7 @@ export type VisConfig = {
   colorBands?: RasterLayerConfigColorBand[];
 
   uniqueValuesColorRange?: ColorRange;
+  textLabelUniqueIdField?: string | null;
 };
 
 export type TextLabel = {
@@ -259,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) => ({