@mapbox/mapbox-gl-style-spec 14.6.0 → 14.7.0

package/reference/v8.json

@@ -200,6 +200,65 @@
         "spruce1-lod1": "asset://spruce1-lod1.glb",
         "spruce1-lod2": "asset://spruce1-lod2.glb"
       }
+    },
+   "featuresets": {
+      "experimental": true,
+      "type": "featuresets",
+      "doc": "Defines sets of features for querying, interaction, and feature state manipulation.",
+      "example": {
+        "poi": {
+          "selectors": [
+            {
+              "layer": "poi",
+              "properties": {
+                "type": ["get", "type"],
+                "name": ["get", "name"],
+                "brand": "ABC"
+              }
+            }
+          ]
+        }
+      }
+    }
+  },
+  "featuresets": {
+    "experimental": true,
+    "*": {
+      "type": "featureset",
+      "doc": "Defines a combined set of features from one or more underlying layers within the current style. Features in a style featureset can be queried, interacted with, and their states can be queried and updated."
+    }
+  },
+  "featureset": {
+    "experimental": true,
+    "selectors": {
+      "type": "array",
+      "value": "selector",
+      "doc": "A collection of categorized selectors."
+    }
+  },
+  "selector": {
+    "experimental": true,
+    "layer": {
+      "type": "string",
+      "doc": "The ID of a layer that exists in the current style.",
+      "required": true
+    },
+    "properties": {
+      "type": "selectorProperty",
+      "required": false,
+      "doc": "Properties accessible to the end user through queried feautures. If properties are empty, no feature properties are exposed. If undefined, all original feature properties will be accessible."
+    },
+    "featureNamespace": {
+      "type": "string",
+      "required": false,
+      "doc": "An optional field that represents the feature namespace defined by the selector within a featureset to which this feature belongs. If the underlying source is the same for multiple selectors within a featureset, the same featureNamespace should be used across those selectors."
+    }
+  },
+  "selectorProperty": {
+    "experimental": true,
+    "*": {
+      "type": "*",
+      "doc": "The value of the property. It can be an expression that generates the returned value from the feature, or a constant value specifying the returned value."
     }
   },
   "model": {
@@ -424,9 +483,6 @@
       "default": false,
       "doc": "Enable/Disable shadow casting for this light",
       "transition": false,
-      "expression": {
-        "interpolated": false
-      },
       "property-type": "data-constant",
       "sdk-support": {
         "basic functionality": {
@@ -512,7 +568,7 @@
           "doc": "The position of the light source is aligned to the rotation of the map."
         },
         "viewport": {
-          "doc": "The position of the light source is aligned to the rotation of the viewport."
+          "doc": "The position of the light source is aligned to the rotation of the viewport. If terrain is enabled, performance regressions may occur in certain scenarios, particularly on lower-end hardware. Ensure that you test your target scenarios on the appropriate hardware to verify performance."
         }
       },
       "property-type": "data-constant",
@@ -1679,7 +1735,6 @@
     "fill-extrusion-edge-radius": {
       "type": "number",
       "experimental": true,
-      "private": true,
       "default": 0,
       "minimum": 0,
       "maximum": 1,
@@ -5410,6 +5465,30 @@
         ]
       },
       "property-type": "data-constant"
+    },
+    "fill-z-offset": {
+      "type": "number",
+      "doc": "Specifies an uniform elevation in meters. Note: If the value is zero, the layer will be rendered on the ground. Non-zero values will elevate the layer from the sea level, which can cause it to be rendered below the terrain.",
+      "default": 0,
+      "minimum": 0,
+      "transition": true,
+      "experimental": true,
+      "sdk-support": {
+        "basic functionality": {
+          "js": "3.7.0"
+        },
+        "data-driven styling": {
+          "js": "3.7.0"
+        }
+      },
+      "expression": {
+        "interpolated": true,
+        "parameters": [
+          "zoom",
+          "feature"
+        ]
+      },
+      "property-type": "data-driven"
     }
   },
   "paint_fill-extrusion": {
@@ -5633,7 +5712,6 @@
     "fill-extrusion-ambient-occlusion-intensity": {
       "property-type": "data-constant",
       "type": "number",
-      "private": true,
       "default": 0.0,
       "minimum": 0,
       "maximum": 1,
@@ -5656,7 +5734,6 @@
     "fill-extrusion-ambient-occlusion-radius": {
       "property-type": "data-constant",
       "type": "number",
-      "private": true,
       "default": 3.0,
       "minimum": 0,
       "expression": {
@@ -5845,7 +5922,7 @@
       "experimental": true,
       "units": "meters",
       "default": 0,
-      "doc": "The extent of the flood light effect on the ground beneath the extruded buildings in meters.",
+      "doc": "The extent of the flood light effect on the ground beneath the extruded buildings in meters. Note: this experimental property is evaluated once per tile, during tile initialization. Changing the property value could trigger tile reload. The `feature-state` styling is deprecated and will get removed soon.",
       "requires": [
         "lights"
       ],
@@ -5976,30 +6053,42 @@
           "js": "3.0.0",
           "android": "11.0.0",
           "ios": "11.0.0"
+        },
+        "data-driven styling": {
+          "js": "3.8.0",
+          "android": "11.8.0",
+          "ios": "11.8.0"
         }
       },
       "expression": {
         "interpolated": true,
         "parameters": [
           "zoom",
-          "measure-light"
+          "measure-light",
+          "feature-state"
         ]
       },
-      "property-type": "data-constant"
+      "property-type": "data-driven"
     },
     "fill-extrusion-line-width": {
       "type": "number",
       "default": 0,
       "minimum": 0,
       "transition": true,
+      "experimental": true,
       "units": "meters",
       "doc": "If a non-zero value is provided, it sets the fill-extrusion layer into wall rendering mode. The value is used to render the feature with the given width over the outlines of the geometry. Note: This property is experimental and some other fill-extrusion properties might not be supported with non-zero line width.",
       "sdk-support": {
         "basic functionality": {
-          "js": "3.7.0"
+          "js": "3.7.0",
+          "android": "11.7.0",
+          "ios": "11.7.0"
+
         },
         "data-driven styling": {
-          "js": "3.7.0"
+          "js": "3.7.0",
+          "android": "11.7.0",
+          "ios": "11.7.0"
         }
       },
       "expression": {
@@ -6013,27 +6102,16 @@
       },
       "property-type": "data-driven"
     },
-    "fill-extrusion-line-alignment": {
-      "type": "enum",
-      "values": {
-        "inside": {
-          "doc": "Aligns the wall inside of the outline."
-        },
-        "outside": {
-          "doc": "Aligns the wall outside of the outline."
-        },
-        "center": {
-          "doc": "Aligns the wall relative to the center of the outline."
-        }
-      },
-      "default": "center",
-      "doc": "Specifies the alignment for offset of the walls relative to the outlines of the geometry. For open-ended line string geometries the positioning is considered based on the ordering of the points, where inside is in clockwise order and outside is counter-clockwise. This property only has an effect if a non-zero fill-extrusion-line-width is used. Center alignment is automatically used for non-closed lines.",
-      "requires": [
-        "fill-extrusion-line-width"
-      ],
+    "fill-extrusion-cast-shadows": {
+      "type": "boolean",
+      "default": true,
+      "doc": "Enable/Disable shadow casting for this layer",
+      "transition": false,
       "sdk-support": {
-        "basic functionality": {
-          "js": "3.7.0"
+          "basic functionality": {
+          "js": "3.7.0",
+          "android": "11.8.0",
+          "ios": "11.8.0"
         }
       },
       "property-type": "data-constant"
@@ -7160,7 +7238,8 @@
         "interpolated": true,
         "parameters": [
           "zoom",
-          "measure-light"
+          "measure-light",
+          "feature-state"
         ]
       },
       "property-type": "data-driven"
@@ -7191,7 +7270,8 @@
         "interpolated": true,
         "parameters": [
           "zoom",
-          "measure-light"
+          "measure-light",
+          "feature-state"
         ]
       },
       "property-type": "data-driven"
@@ -7747,6 +7827,62 @@
         "interpolated": false
       },
       "property-type": "data-constant"
+    },
+    "symbol-z-offset": {
+      "type": "number",
+      "doc": "Specifies an uniform elevation from the ground, in meters.",
+      "default": 0,
+      "minimum": 0,
+      "transition": true,
+      "experimental": true,
+      "sdk-support": {
+        "basic functionality": {
+          "js": "3.7.0",
+          "android": "11.7.0",
+          "ios": "11.7.0"
+        },
+        "data-driven styling": {
+          "js": "3.7.0",
+          "android": "11.7.0",
+          "ios": "11.7.0"
+        }
+      },
+      "expression": {
+        "interpolated": true,
+        "parameters": [
+          "zoom",
+          "feature"
+        ]
+      },
+      "property-type": "data-driven"
+    },
+    "symbol-elevation-reference": {
+      "type": "enum",
+      "doc": "Selects the base of symbol-elevation.",
+      "values": {
+        "sea": {
+          "doc": "Elevate symbols relative to the sea level."
+        },
+        "ground": {
+          "doc": "Elevate symbols relative to the ground's height below them."
+        }
+      },
+      "default": "ground",
+      "experimental": true,
+      "sdk-support": {
+        "basic functionality": {
+          "js": "3.7.0",
+          "android": "11.7.0",
+          "ios": "11.7.0"
+        }
+      },
+      "expression": {
+        "interpolated": false,
+        "parameters": [
+          "zoom"
+        ]
+      },
+      "property-type": "data-constant"
     }
   },
   "paint_raster": {
@@ -8396,6 +8532,31 @@
     }
   },
   "paint_background": {
+    "background-pitch-alignment": {
+      "type": "enum",
+      "values": {
+        "map": {
+          "doc": "The background is aligned to the plane of the map."
+        },
+        "viewport": {
+          "doc": "The background is aligned to the plane of the viewport, covering the whole screen."
+        }
+      },
+      "default": "map",
+      "doc": "Orientation of background layer.",
+      "sdk-support": {
+        "basic functionality": {
+          "js": "3.8.0",
+          "android": "11.8.0",
+          "ios": "11.8.0"
+        }
+      },
+      "expression": {
+        "interpolated": false,
+        "parameters": []
+      },
+      "property-type": "data-constant"
+    },
     "background-color": {
       "type": "color",
       "default": "#000000",
@@ -9059,9 +9220,7 @@
       "doc": "An array for configuring the fade-out effect for the front cutoff of content on pitched map views. It contains three values: start, range and final opacity. The start parameter defines the point at which the fade-out effect begins, with smaller values causing the effect to start earlier. The range parameter specifies how long the fade-out effect will last. A value of 0.0 for range makes content disappear immediately without a fade-out effect. The final opacity determines content opacity at the end of the fade-out effect. A value of 1.0 for final opacity means that the cutoff is completely disabled.",
       "sdk-support": {
         "basic functionality": {
-          "js": "3.5.0",
-          "android": "11.5.0",
-          "ios": "11.5.0"
+          "js": "3.5.0"
         }
       }
     }

package/rollup.config.js

@@ -1,15 +1,14 @@
-import path from 'path';
 import replace from '@rollup/plugin-replace';
 import resolve from '@rollup/plugin-node-resolve';
 import commonjs from '@rollup/plugin-commonjs';
 import unassert from 'rollup-plugin-unassert';
 import json from '@rollup/plugin-json';
 import esbuild from 'rollup-plugin-esbuild';
+import {fileURLToPath} from 'url';
 
 // Build es modules?
 const esm = 'esm' in process.env;
 
-import {fileURLToPath} from 'url';
 const __dirname = fileURLToPath(new URL('.', import.meta.url));
 
 const config = [{

package/style-spec.ts

@@ -26,8 +26,9 @@ export type StylePropertySpecification = {
     'property-type': ExpressionType,
     expression?: ExpressionSpecification,
     transition?: boolean,
+    overridable?: boolean,
     default?: boolean,
-    tokens: never
+    tokens?: never
 } | {
     type: 'enum',
     'property-type': ExpressionType,
@@ -82,13 +83,11 @@ import ValidationError from './error/validation_error';
 import ParsingError from './error/parsing_error';
 import {StyleExpression, isExpression, createExpression, createPropertyExpression, normalizePropertyExpression, ZoomConstantExpression, ZoomDependentExpression, StylePropertyFunction} from './expression/index';
 import featureFilter, {isExpressionFilter} from './feature_filter/index';
-
 import convertFilter from './feature_filter/convert';
 import Color from './util/color';
 import {createFunction, isFunction} from './function/index';
 import convertFunction from './function/convert';
 import {eachSource, eachLayer, eachProperty} from './visit';
-
 import validate from './validate_style';
 import validateMapboxApiSupported from './validate_mapbox_api_supported';
 

package/types.ts

@@ -1,5 +1,6 @@
 // Generated code; do not edit. Edit build/generate-typed-style-spec.ts instead.
-/* eslint-disable */
+
+import type {UnionToIntersection} from './union-to-intersection';
 
 export type ColorSpecification = string;
 
@@ -97,7 +98,11 @@ export type StyleSpecification = {
     "transition"?: TransitionSpecification,
     "projection"?: ProjectionSpecification,
     "layers": Array<LayerSpecification>,
-    "models"?: ModelsSpecification
+    "models"?: ModelsSpecification,
+    /**
+     * @experimental This property is experimental and subject to change in future versions.
+     */
+    "featuresets"?: FeaturesetsSpecification
 }
 
 export type SourcesSpecification = {
@@ -182,6 +187,36 @@ export type OptionSpecification = {
     "metadata"?: unknown
 }
 
+/**
+ * @experimental This is experimental and subject to change in future versions.
+ */
+export type FeaturesetsSpecification = {
+    [_: string]: FeaturesetSpecification
+}
+
+/**
+ * @experimental This is experimental and subject to change in future versions.
+ */
+export type FeaturesetSpecification = {
+    "selectors"?: Array<SelectorSpecification>
+}
+
+/**
+ * @experimental This is experimental and subject to change in future versions.
+ */
+export type SelectorSpecification = {
+    "layer": string,
+    "properties"?: SelectorPropertySpecification,
+    "featureNamespace"?: string
+}
+
+/**
+ * @experimental This is experimental and subject to change in future versions.
+ */
+export type SelectorPropertySpecification = {
+    [_: string]: unknown
+}
+
 export type VectorSourceSpecification = {
     "type": "vector",
     "url"?: string,
@@ -312,7 +347,7 @@ export type DirectionalLightSpecification = {
         "color-transition"?: TransitionSpecification,
         "intensity"?: PropertyValueSpecification<number>,
         "intensity-transition"?: TransitionSpecification,
-        "cast-shadows"?: ExpressionSpecification,
+        "cast-shadows"?: boolean,
         "shadow-intensity"?: PropertyValueSpecification<number>,
         "shadow-intensity-transition"?: TransitionSpecification
     },
@@ -365,7 +400,9 @@ export type FillLayerSpecification = {
         "fill-translate-anchor"?: PropertyValueSpecification<"map" | "viewport">,
         "fill-pattern"?: DataDrivenPropertyValueSpecification<ResolvedImageSpecification>,
         "fill-emissive-strength"?: PropertyValueSpecification<number>,
-        "fill-emissive-strength-transition"?: TransitionSpecification
+        "fill-emissive-strength-transition"?: TransitionSpecification,
+        "fill-z-offset"?: DataDrivenPropertyValueSpecification<number>,
+        "fill-z-offset-transition"?: TransitionSpecification
     }
 }
 
@@ -543,7 +580,13 @@ export type SymbolLayerSpecification = {
         "icon-color-saturation"?: ExpressionSpecification,
         "icon-color-contrast"?: ExpressionSpecification,
         "icon-color-brightness-min"?: ExpressionSpecification,
-        "icon-color-brightness-max"?: ExpressionSpecification
+        "icon-color-brightness-max"?: ExpressionSpecification,
+        "symbol-z-offset"?: DataDrivenPropertyValueSpecification<number>,
+        "symbol-z-offset-transition"?: TransitionSpecification,
+        /**
+         * @experimental This property is experimental and subject to change in future versions.
+         */
+        "symbol-elevation-reference"?: PropertyValueSpecification<"sea" | "ground">
     }
 }
 
@@ -699,11 +742,11 @@ export type FillExtrusionLayerSpecification = {
          */
         "fill-extrusion-rounded-roof"?: PropertyValueSpecification<boolean>,
         "fill-extrusion-cutoff-fade-range"?: ExpressionSpecification,
-        "fill-extrusion-emissive-strength"?: PropertyValueSpecification<number>,
+        "fill-extrusion-emissive-strength"?: DataDrivenPropertyValueSpecification<number>,
         "fill-extrusion-emissive-strength-transition"?: TransitionSpecification,
         "fill-extrusion-line-width"?: DataDrivenPropertyValueSpecification<number>,
         "fill-extrusion-line-width-transition"?: TransitionSpecification,
-        "fill-extrusion-line-alignment"?: "inside" | "outside" | "center"
+        "fill-extrusion-cast-shadows"?: boolean
     }
 }
 
@@ -915,6 +958,7 @@ export type BackgroundLayerSpecification = {
         "visibility"?: "visible" | "none" | ExpressionSpecification
     },
     "paint"?: {
+        "background-pitch-alignment"?: "map" | "viewport" | ExpressionSpecification,
         "background-color"?: PropertyValueSpecification<ColorSpecification>,
         "background-color-transition"?: TransitionSpecification,
         "background-pattern"?: PropertyValueSpecification<ResolvedImageSpecification>,
@@ -1030,6 +1074,10 @@ export type LayerSpecification =
     | SlotLayerSpecification
     | ClipLayerSpecification;
 
+export type LayoutSpecification = UnionToIntersection<NonNullable<LayerSpecification['layout']>>;
+
+export type PaintSpecification = UnionToIntersection<NonNullable<LayerSpecification['paint']>>;
+
 // Aliases for easier migration from @types/mapbox-gl
 
 export type Layer = Pick<
@@ -1128,39 +1176,14 @@ export type SlotLayer = SlotLayerSpecification;
 export type ClipLayer = ClipLayerSpecification;
 
 /**
- * @deprecated
+ * @deprecated Use `LayoutSpecification` instead.
  */
-export type AnyLayout =
-    | FillLayout
-    | LineLayout
-    | SymbolLayout
-    | CircleLayout
-    | HeatmapLayout
-    | FillExtrusionLayout
-    | RasterLayout
-    | RasterParticleLayout
-    | HillshadeLayout
-    | ModelLayout
-    | BackgroundLayout
-    | SkyLayout
-    | ClipLayout;
+export type AnyLayout = LayoutSpecification;
 
 /**
- * @deprecated
+ * @deprecated Use `PaintSpecification` instead.
  */
-export type AnyPaint =
-    | FillPaint
-    | LinePaint
-    | SymbolPaint
-    | CirclePaint
-    | HeatmapPaint
-    | FillExtrusionPaint
-    | RasterPaint
-    | RasterParticlePaint
-    | HillshadePaint
-    | ModelPaint
-    | BackgroundPaint
-    | SkyPaint;
+export type AnyPaint = PaintSpecification;
 
 /**
  * @deprecated Use `ExpressionSpecification` instead.

package/union-to-intersection.ts

@@ -0,0 +1,4 @@
+export type UnionToIntersection<U> =
+    (U extends any ? (k: U) => void : never) extends (k: infer I) => void ?
+    {[K in keyof I]: I[K]} :
+    never;

package/util/color.ts

@@ -1,5 +1,6 @@
 import {parseCSSColor} from 'csscolorparser';
 import {number as lerp} from './interpolate';
+
 import type {LUT} from '../types/lut';
 
 /**

package/util/color_spaces.ts

@@ -1,5 +1,4 @@
 import Color from './color';
-
 import {number as interpolateNumber} from './interpolate';
 
 type LABColor = {

package/util/deep_equal.ts

@@ -3,7 +3,7 @@
  *
  * @private
  */
-function deepEqual(a?: unknown | null, b?: unknown | null): boolean {
+function deepEqual(a?: unknown, b?: unknown): boolean {
     if (Array.isArray(a)) {
         if (!Array.isArray(b) || a.length !== b.length) return false;
         for (let i = 0; i < a.length; i++) {

package/util/geometry_util.ts

@@ -1,7 +1,6 @@
-import type Point from '@mapbox/point-geometry';
 import quickselect from 'quickselect';
 
-type GeoJSONPosition = [number, number] | [number, number, number];
+import type Point from '@mapbox/point-geometry';
 
 // minX, minY, maxX, maxY
 export type BBox = [number, number, number, number];

package/validate/validate.ts

@@ -1,9 +1,7 @@
 import extend from '../util/extend';
-import ValidationError from '../error/validation_error';
 import {unbundle, deepUnbundle} from '../util/unbundle_jsonlint';
 import {isExpression} from '../expression/index';
 import {isFunction} from '../function/index';
-
 import validateImport from './validate_import';
 import validateFunction from './validate_function';
 import validateExpression from './validate_expression';
@@ -25,10 +23,11 @@ import validateString from './validate_string';
 import validateFormatted from './validate_formatted';
 import validateImage from './validate_image';
 import validateProjection from './validate_projection';
+import getType from '../util/get_type';
 
 import type {StyleReference} from '../reference/latest';
 import type {StyleSpecification} from '../types';
-import getType from '../util/get_type';
+import type ValidationError from '../error/validation_error';
 
 const VALIDATORS = {
     '*'() {

package/validate/validate_expression.ts

@@ -1,5 +1,4 @@
 import ValidationError from '../error/validation_error';
-
 import {createExpression, createPropertyExpression} from '../expression/index';
 import {deepUnbundle} from '../util/unbundle_jsonlint';
 import {isStateConstant, isGlobalPropertyConstant, isFeatureConstant} from '../expression/is_constant';

package/validate/validate_function.ts

@@ -19,7 +19,7 @@ export default function validateFunction(options: ValidationOptions): any {
     const functionType = unbundle(options.value.type);
     let stopKeyType;
     let stopDomainValues: Partial<Record<string | number, boolean>> = {};
-    let previousStopDomainValue: unknown | null | undefined;
+    let previousStopDomainValue: unknown;
     let previousStopDomainZoom;
 
     const isZoomFunction = functionType !== 'categorical' && options.value.property === undefined;

package/validate/validate_property.ts

@@ -5,9 +5,9 @@ import {isFunction} from '../function/index';
 import {unbundle, deepUnbundle} from '../util/unbundle_jsonlint';
 import {supportsLightExpression, supportsPropertyExpression, supportsZoomExpression} from '../util/properties';
 import {isGlobalPropertyConstant, isFeatureConstant, isStateConstant} from '../expression/is_constant';
+import {createPropertyExpression} from '../expression/index';
 
 import type {ValidationOptions} from './validate';
-import {createPropertyExpression} from '../expression/index';
 
 export type PropertyValidationOptions = ValidationOptions & {
     objectKey: string;
@@ -42,8 +42,7 @@ export default function validateProperty(options: PropertyValidationOptions, pro
         return [new ValidationWarning(key, value, `unknown property "${propertyKey}"`)];
     }
 
-    // @ts-expect-error - TS2702 - 'RegExp' only refers to a type, but is being used as a namespace here.
-    let tokenMatch: RegExp.matchResult | null | undefined;
+    let tokenMatch: RegExpExecArray | undefined;
     if (getType(value) === 'string' && supportsPropertyExpression(valueSpec) && !valueSpec.tokens && (tokenMatch = /^{([^}]+)}$/.exec(value))) {
         const example = `\`{ "type": "identity", "property": ${tokenMatch ? JSON.stringify(tokenMatch[1]) : '"_"'} }\``;
         return [new ValidationError(