@carto/api-client 0.5.31 → 0.5.32-alpha.02a4470.133

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.02a4470.133",
   "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,8 @@ import type {
   ColorRange,
   CustomMarkersRange,
   Dataset,
+  FillPatternRange,
+  LineStyleRange,
   MapLayerConfig,
   VisConfig,
   VisualChannelField,
@@ -510,6 +512,52 @@ 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 getFillPatternAccessor(
+  field: VisualChannelField,
+  range: FillPatternRange,
+  density: 'small' | 'medium' | 'large' | undefined,
+  data: any
+) {
+  const d = density ?? 'medium';
+  // `solid` / `none` are density-agnostic atlas cells; every other pattern resolves to
+  // `${pattern}-${density}`.
+  const toKey = (pattern: string) =>
+    pattern === 'solid' || pattern === 'none' ? pattern : `${pattern}-${d}`;
+  // Always resolve to a real key — an unmapped key would sample atlas bounds [0,0,0,0]
+  // (the wrong (0,0) sprite). `none` is a real transparent cell = "paints nothing".
+  const fallback = toKey(range.othersPattern ?? 'none');
+  const mapping: Record<string, string> = {};
+  for (const {value, pattern} of range.patternMap) {
+    mapping[value] = toKey(pattern);
+  }
+  const accessor = (properties: any) =>
+    mapping[properties[field.name]] ?? fallback;
+  return {
+    accessor: normalizeAccessor(accessor, data),
+    domain: range.patternMap.map(({value}) => value),
+    range: range.patternMap.map(({pattern}) => pattern),
+  };
+}
+
 export function getMaxMarkerSize(
   visConfig: VisConfig,
   visualChannels: VisualChannels

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

@@ -10,6 +10,8 @@ import {
   getTextAccessor,
   opacityToAlpha,
   getIconUrlAccessor,
+  getLineStyleAccessor,
+  getFillPatternAccessor,
   negateAccessor,
   getMaxMarkerSize,
   type LayerType,
@@ -32,6 +34,12 @@ import type {
   VisualChannelField,
 } from './types.js';
 import {isRemoteCalculationSupported} from './utils.js';
+import {
+  getPatternAtlas,
+  getPatternAtlasMapping,
+  getPatternScaleAdjustment,
+  getPatternTextureParameters,
+} from './pattern-atlas.js';
 import {
   getRasterTileLayerStylePropsRgb,
   getRasterTileLayerStylePropsScaledBand,
@@ -48,7 +56,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 +66,9 @@ export type ScaleKey =
   | 'lineColor'
   | 'lineWidth'
   | 'elevation'
-  | 'weight';
+  | 'weight'
+  | 'lineStyle'
+  | 'fillPattern';
 
 export type Scales = Partial<Record<ScaleKey, Scale>>;
 
@@ -377,6 +388,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 +578,117 @@ 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;
+        }
+      }
+    }
+  }
+
+  // fill pattern — Phase 2. The pattern is a stencil tinted by the existing fillColor
+  // (mask:true) — no separate pattern-color channel. The consumer attaches
+  // FillStyleExtension unconditionally and reads `fillPatternEnabled` as the on/off
+  // switch, mirroring how MaskExtension is gated by `maskId`. Data only — no extension
+  // instantiation here. Applies to any filled polygon layer (mvt/tileset + H3/Quadbin);
+  // the stroke-dash block above is the VectorTile-only one (per OQ 10).
+  {
+    const fillPatternEnabled = Boolean(
+      visConfig.filled && visConfig.fillPatternEnabled
+    );
+    result.fillPatternEnabled = fillPatternEnabled;
+
+    // Pattern props are emitted for every filled layer, even with the pattern off:
+    // removing them on a live layer transitions the async `fillPatternAtlas` prop to
+    // null, which crashes deck's layer matching (null image transform) and blanks the
+    // layer. A disabled layer samples the opaque `solid` cell instead — under
+    // fillPatternMask the mask multiplies by 1, i.e. a plain fill.
+    if (visConfig.filled) {
+      result.fillPatternAtlas = getPatternAtlas();
+      result.fillPatternMapping = getPatternAtlasMapping();
+      result.fillPatternMask = true;
+      const textureParameters = getPatternTextureParameters();
+      if (textureParameters) {
+        // Merged into the atlas texture's sampler by deck's image-prop transform.
+        result.textureParameters = textureParameters;
+      }
+      // Scale compensated for the atlas cell size — see getPatternScaleAdjustment.
+      result.getFillPatternScale =
+        (visConfig.fillPatternSize ?? 1) * getPatternScaleAdjustment();
+
+      const {fillPatternField, fillPatternScale} = visualChannels;
+      const {fillPatternRange, fillPatternDensity} = visConfig;
+
+      if (!fillPatternEnabled) {
+        result.getFillPattern = () => 'solid';
+        updateTriggers.getFillPattern = 'solid';
+      } else if (fillPatternField && fillPatternScale && fillPatternRange) {
+        // Flat prop for legend consumers (fallback when there is no by-column scale).
+        result.fillPattern = visConfig.fillPattern;
+        const {accessor, ...scaleProps} = getFillPatternAccessor(
+          fillPatternField,
+          fillPatternRange,
+          fillPatternDensity,
+          data
+        );
+        result.getFillPattern = accessor;
+        scales.fillPattern = updateTriggers.getFillPattern = {
+          field: fillPatternField,
+          type: fillPatternScale,
+          ...scaleProps,
+        };
+      } else {
+        // Single mode: one real pattern (never solid/none) for every feature.
+        result.fillPattern = visConfig.fillPattern;
+        const key = `${visConfig.fillPattern}-${fillPatternDensity ?? 'medium'}`;
+        result.getFillPattern = () => key;
+        updateTriggers.getFillPattern = key;
+      }
+      // getFillColor is left exactly as the fillColor channel set it; under
+      // fillPatternMask:true that IS the pattern tint.
+    }
+  }
+
   // height / elevation
   {
     const {heightField, heightScale} = visualChannels;
@@ -704,14 +834,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';