@mapbox/mapbox-gl-style-spec 14.34.0-rc.1 → 14.34.1-alpha.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mapbox/mapbox-gl-style-spec",
-  "version": "14.34.0-rc.1",
+  "version": "14.34.1-alpha.1",
   "description": "a specification for mapbox gl styles",
   "author": "Mapbox",
   "license": "SEE LICENSE IN LICENSE.txt",

package/reference/v8.json

@@ -10792,6 +10792,64 @@
         "interpolated": false
       },
       "property-type": "data-constant"
+    },
+    "raster-mask": {
+      "type": "string",
+      "required": false,
+      "experimental": true,
+      "private": true,
+      "doc": "The id of a `fill` layer in the same style whose polygons should clip this layer. Only the geometry is used: set `fill-opacity` to 0 to keep the layer invisible, but don't hide it with `visibility`, `minzoom` or `maxzoom`. To use a featureset from another import, see `raster-mask-import`. Elevated `fill` layers and `raster-elevation` are not supported. This layer is only drawn where the mask's data has loaded, and not at all if the mask can't be used.",
+      "example": "water",
+      "transition": false,
+      "sdk-support": {
+        "basic functionality": {
+          "js": "3.34.0"
+        }
+      },
+      "property-type": "data-constant"
+    },
+    "raster-mask-import": {
+      "type": "string",
+      "required": false,
+      "experimental": true,
+      "private": true,
+      "doc": "The id of an import of this style. When set, `raster-mask` is the id of a featureset of that import instead of a layer id, and the mask is made of the `fill` layers the featureset selects. If the featureset can't be found, or selects no `fill` layers, this layer is not drawn.",
+      "example": "basemap",
+      "transition": false,
+      "requires": [
+        "raster-mask"
+      ],
+      "sdk-support": {
+        "basic functionality": {
+          "js": "3.34.0"
+        }
+      },
+      "property-type": "data-constant"
+    },
+    "raster-mask-mode": {
+      "type": "enum",
+      "doc": "Whether this layer is drawn inside or outside the mask.",
+      "values": {
+        "clip-path-intersect": {
+          "doc": "Draw only where the mask layer's geometry covers the map."
+        },
+        "clip-path-exclude": {
+          "doc": "Draw only where the mask layer's geometry does not cover the map."
+        }
+      },
+      "default": "clip-path-intersect",
+      "experimental": true,
+      "private": true,
+      "transition": false,
+      "requires": [
+        "raster-mask"
+      ],
+      "sdk-support": {
+        "basic functionality": {
+          "js": "3.34.0"
+        }
+      },
+      "property-type": "data-constant"
     }
   },
   "paint_raster-particle": {

package/types.ts

@@ -1266,7 +1266,19 @@ export type RasterLayerSpecification = {
         /**
          * @experimental This property is experimental and subject to change in future versions.
          */
-        "raster-elevation-reference"?: "sea" | "ground" | ExpressionSpecification
+        "raster-elevation-reference"?: "sea" | "ground" | ExpressionSpecification,
+        /**
+         * @experimental This property is experimental and subject to change in future versions.
+         */
+        "raster-mask"?: string,
+        /**
+         * @experimental This property is experimental and subject to change in future versions.
+         */
+        "raster-mask-import"?: string,
+        /**
+         * @experimental This property is experimental and subject to change in future versions.
+         */
+        "raster-mask-mode"?: "clip-path-intersect" | "clip-path-exclude"
     },
     "appearances"?: Array<AppearanceSpecification>
 };

package/validate/validate_layer.ts

@@ -107,6 +107,27 @@ export default function validateLayer(options: LayerValidatorOptions): Validatio
         }
     }
 
+    if (type === 'raster' && isObject(layer.paint)) {
+        const paint = layer.paint as Record<string, unknown>;
+        const maskId = unbundle(paint['raster-mask']);
+        const importId = unbundle(paint['raster-mask-import']);
+        if (isString(maskId) && maskId) {
+            if (isString(importId) && importId) {
+                // The featureset itself can only be checked once the import has loaded.
+                if (!(style.imports || []).some((i) => unbundle(i.id) === importId)) {
+                    errors.push(new ValidationError(`${key}.paint.raster-mask-import`, paint['raster-mask-import'], `import "${importId}" not found`));
+                }
+            } else {
+                const maskLayer = (style.layers || []).find((l) => unbundle(l.id) === maskId);
+                if (!maskLayer) {
+                    errors.push(new ValidationError(`${key}.paint.raster-mask`, paint['raster-mask'], `layer "${maskId}" not found`));
+                } else if (unbundle(maskLayer.type) !== 'fill') {
+                    errors.push(new ValidationError(`${key}.paint.raster-mask`, paint['raster-mask'], `layer "${maskId}" must be a "fill" layer`));
+                }
+            }
+        }
+    }
+
     errors = errors.concat(validateObject({
         key,
         value: layer,