@carto/api-client 0.5.31 → 0.5.32-alpha.307c0b4.122

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.31",
+  "version": "0.5.32-alpha.307c0b4.122",
   "license": "MIT",
   "publishConfig": {
     "access": "public"
@@ -125,7 +125,7 @@
     "typescript": "~5.9.2",
     "typescript-eslint": "^8.26.1",
     "vite": "^7.3.2",
-    "vitest": "3.2.4"
+    "vitest": "3.2.6"
   },
   "resolutions": {
     "@carto/api-client": "portal:./",

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

@@ -32,6 +32,7 @@ import type {
   ColorRange,
   CustomMarkersRange,
   Dataset,
+  LineStyleRange,
   MapLayerConfig,
   VisConfig,
   VisualChannelField,
@@ -510,6 +511,25 @@ export function getIconUrlAccessor(
   return normalizeAccessor(accessor, data);
 }
 
+export function getLineStyleAccessor(
+  field: VisualChannelField,
+  range: LineStyleRange,
+  data: any
+) {
+  const fallback = range.othersDashArray ?? [0, 0];
+  const mapping: Record<string, [number, number]> = {};
+  for (const {value, dashArray} of range.dashArrayMap) {
+    mapping[value] = dashArray;
+  }
+  const accessor = (properties: any) =>
+    mapping[properties[field.name]] ?? fallback;
+  return {
+    accessor: normalizeAccessor(accessor, data),
+    domain: range.dashArrayMap.map(({value}) => value),
+    range: range.dashArrayMap.map(({dashArray}) => dashArray),
+  };
+}
+
 export function getMaxMarkerSize(
   visConfig: VisConfig,
   visualChannels: VisualChannels

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

@@ -10,6 +10,7 @@ import {
   getTextAccessor,
   opacityToAlpha,
   getIconUrlAccessor,
+  getLineStyleAccessor,
   negateAccessor,
   getMaxMarkerSize,
   type LayerType,
@@ -48,7 +49,8 @@ export type Scale = {
 
   /** Domain of the user to construct d3 scale */
   scaleDomain?: string[] | number[];
-  range?: string[] | number[];
+  // `number[][]` carries per-category `[dash, gap]` tuples for the `lineStyle` scale.
+  range?: string[] | number[] | number[][];
 };
 
 export type ScaleKey =
@@ -57,7 +59,8 @@ export type ScaleKey =
   | 'lineColor'
   | 'lineWidth'
   | 'elevation'
-  | 'weight';
+  | 'weight'
+  | 'lineStyle';
 
 export type Scales = Partial<Record<ScaleKey, Scale>>;
 
@@ -377,6 +380,14 @@ function createChannelProps(
 
   const scales: Record<string, Scale> = {};
 
+  const isVectorTile = layerType === 'mvt' || layerType === 'tileset';
+  const geometry = data.tilestats?.layers?.[0]?.geometry;
+  const isLine =
+    geometry === 'Line' ||
+    geometry === 'LineString' ||
+    geometry === 'MultiLineString';
+  const isPolygon = geometry === 'Polygon' || geometry === 'MultiPolygon';
+
   // fill color
   {
     const {colorField, colorScale} = visualChannels;
@@ -559,6 +570,54 @@ function createChannelProps(
     }
   }
 
+  // stroke dash style — only VectorTileLayer (mvt/tileset) carries dashes; H3/Quadbin excluded.
+  {
+    // A line is always stroked; a polygon border only when `stroked`. Points are excluded.
+    const strokeVisible = isLine || (isPolygon && Boolean(visConfig.stroked));
+    if (isVectorTile && strokeVisible) {
+      const {lineStyleField, lineStyleScale} = visualChannels;
+      const {lineStyleRange} = visConfig;
+
+      // Fixed preset (used when no column drives the style).
+      if (visConfig.lineStyle && visConfig.lineStyle !== 'solid') {
+        if (visConfig.lineStyle === 'dotted') {
+          result.lineCapRounded = true;
+        }
+        result.lineStyle = visConfig.lineStyle;
+        if (visConfig.dashArray) {
+          result.dashArray = visConfig.dashArray;
+          result.getDashArray = visConfig.dashArray;
+        }
+      }
+
+      // Data-driven — mirrors getLineColor/getFillColor: computed whenever the field/scale/range
+      // are set, independent of the fixed `lineStyle`. Overrides the constant accessor above.
+      if (lineStyleField && lineStyleScale && lineStyleRange) {
+        const {accessor, ...scaleProps} = getLineStyleAccessor(
+          lineStyleField,
+          lineStyleRange,
+          data
+        );
+        result.getDashArray = accessor;
+        scales.lineStyle = updateTriggers.getDashArray = {
+          field: lineStyleField,
+          type: lineStyleScale,
+          ...scaleProps,
+        };
+        // Round caps so per-category dotted values ([0, gap]) render as dots, not squares.
+        const dashArrays = [
+          ...lineStyleRange.dashArrayMap.map(({dashArray}) => dashArray),
+          ...(lineStyleRange.othersDashArray
+            ? [lineStyleRange.othersDashArray]
+            : []),
+        ];
+        if (dashArrays.some(([dash]) => dash === 0)) {
+          result.lineCapRounded = true;
+        }
+      }
+    }
+  }
+
   // height / elevation
   {
     const {heightField, heightScale} = visualChannels;
@@ -704,14 +763,7 @@ function createChannelProps(
     // 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')) {
+    if ((isLine || isPolygon) && isVectorTile) {
       const uniqueIdProperty = visConfig.textLabelUniqueIdField;
       result.autoLabels = uniqueIdProperty ? {uniqueIdProperty} : true;
       result.pointType = 'text';

package/src/fetch-map/types.ts

@@ -28,6 +28,9 @@ export type VisualChannels = {
   strokeColorField?: VisualChannelField;
   strokeColorScale?: ScaleType;
 
+  lineStyleField?: VisualChannelField;
+  lineStyleScale?: ScaleType;
+
   heightField?: VisualChannelField;
   heightScale?: ScaleType;
 
@@ -52,6 +55,16 @@ export type CustomMarkersRange = {
   othersMarker?: string;
 };
 
+// Per-category mapping for by-column stroke styles. `dashArray` is the [dash, gap]
+// tuple that flows to deck.gl's `getDashArray`.
+export type LineStyleRange = {
+  dashArrayMap: {
+    value: string;
+    dashArray: [number, number];
+  }[];
+  othersDashArray?: [number, number];
+};
+
 export type ColorBand = 'red' | 'green' | 'blue' | 'alpha';
 
 export type RasterLayerConfigColorBand = {
@@ -95,6 +108,12 @@ export type VisConfig = {
   strokeColorAggregationDomain?: [number, number];
   strokeOpacity?: number;
   strokeColorRange?: ColorRange;
+  stroked?: boolean;
+
+  // `dashArray` is [dash, gap] relative to stroke width. Dotted is [0, gap] + lineCapRounded.
+  lineStyle?: 'solid' | 'dashed' | 'dotted';
+  dashArray?: [number, number];
+  lineStyleRange?: LineStyleRange | null;
 
   heightRange?: number[];
   heightAggregation?: string;