global-state expression support in filter and paint properties (#5613)

Natalia Kowalczyk · Natalia Kowalczyk · commit 7925d00b4d1e · 2025-07-30T12:05:12.000-06:00
maplibre/maplibre-gl-js#5613 - adds a new map methods: `setGlobalStateProperty` and `getGlobalState` - `global-state` expression won't work in layout properties (`setGlobalStateProperty` will have no effect on those)
diff --git a/src/data/bucket/circle_bucket.js b/src/data/bucket/circle_bucket.js
@@ -23,6 +23,7 @@ function addCircleVertex(layoutVertexArray, x, y, extrudeX, extrudeY) {
 class CircleBucket {
   constructor(options) {
     this.zoom = options.zoom;
+    this.globalState = options.globalState;
     this.overscaling = options.overscaling;
     this.layers = options.layers;
     this.layerIds = this.layers.map(layer => layer.id);
@@ -37,7 +38,9 @@ class CircleBucket {
 
   populate(features, options) {
     for (const { feature, index, sourceLayerIndex } of features) {
-      if (this.layers[0]._featureFilter(new EvaluationParameters(this.zoom), feature)) {
+      if (
+        this.layers[0]._featureFilter(new EvaluationParameters(this.zoom, { globalState: this.globalState }), feature)
+      ) {
         const geometry = loadGeometry(feature);
         this.addFeature(feature, geometry, index);
         options.featureIndex.insert(feature, geometry, index, sourceLayerIndex, this.index);
diff --git a/src/data/bucket/fill_bucket.js b/src/data/bucket/fill_bucket.js
@@ -16,6 +16,7 @@ const EvaluationParameters = require('../../style/evaluation_parameters');
 class FillBucket {
   constructor(options) {
     this.zoom = options.zoom;
+    this.globalState = options.globalState;
     this.overscaling = options.overscaling;
     this.layers = options.layers;
     this.layerIds = this.layers.map(layer => layer.id);
@@ -35,7 +36,10 @@ class FillBucket {
     this.hasPattern = hasPattern('fill', this.layers, options);
 
     for (const { feature, index, sourceLayerIndex } of features) {
-      if (!this.layers[0]._featureFilter(new EvaluationParameters(this.zoom), feature)) continue;
+      if (
+        !this.layers[0]._featureFilter(new EvaluationParameters(this.zoom, { globalState: this.globalState }), feature)
+      )
+        continue;
 
       const geometry = loadGeometry(feature);
 
diff --git a/src/data/bucket/fill_extrusion_bucket.js b/src/data/bucket/fill_extrusion_bucket.js
@@ -36,6 +36,7 @@ function addVertex(vertexArray, x, y, nx, ny, nz, t, e) {
 class FillExtrusionBucket {
   constructor(options) {
     this.zoom = options.zoom;
+    this.globalState = options.globalState;
     this.overscaling = options.overscaling;
     this.layers = options.layers;
     this.layerIds = this.layers.map(layer => layer.id);
@@ -53,7 +54,10 @@ class FillExtrusionBucket {
     this.hasPattern = hasPattern('fill-extrusion', this.layers, options);
 
     for (const { feature, index, sourceLayerIndex } of features) {
-      if (!this.layers[0]._featureFilter(new EvaluationParameters(this.zoom), feature)) continue;
+      if (
+        !this.layers[0]._featureFilter(new EvaluationParameters(this.zoom, { globalState: this.globalState }), feature)
+      )
+        continue;
 
       const geometry = loadGeometry(feature);
 
diff --git a/src/data/bucket/line_bucket.js b/src/data/bucket/line_bucket.js
@@ -72,6 +72,7 @@ function addLineVertex(layoutVertexBuffer, point, extrude, round, up, dir, lines
 class LineBucket {
   constructor(options) {
     this.zoom = options.zoom;
+    this.globalState = options.globalState;
     this.overscaling = options.overscaling;
     this.layers = options.layers;
     this.layerIds = this.layers.map(layer => layer.id);
@@ -90,7 +91,10 @@ class LineBucket {
     this.hasPattern = hasPattern('line', this.layers, options);
 
     for (const { feature, index, sourceLayerIndex } of features) {
-      if (!this.layers[0]._featureFilter(new EvaluationParameters(this.zoom), feature)) continue;
+      if (
+        !this.layers[0]._featureFilter(new EvaluationParameters(this.zoom, { globalState: this.globalState }), feature)
+      )
+        continue;
 
       const geometry = loadGeometry(feature);
 
diff --git a/src/data/bucket/symbol_bucket.js b/src/data/bucket/symbol_bucket.js
@@ -176,6 +176,7 @@ class SymbolBucket {
   constructor(options) {
     this.collisionBoxArray = options.collisionBoxArray;
     this.zoom = options.zoom;
+    this.globalState = options.globalState;
     this.overscaling = options.overscaling;
     this.layers = options.layers;
     this.layerIds = this.layers.map(layer => layer.id);
@@ -258,7 +259,7 @@ class SymbolBucket {
 
     const icons = options.iconDependencies;
     const stacks = options.glyphDependencies;
-    const globalProperties = new EvaluationParameters(this.zoom);
+    const globalProperties = new EvaluationParameters(this.zoom, { globalState: this.globalState });
 
     for (const { feature, index, sourceLayerIndex } of features) {
       if (!layer._featureFilter(globalProperties, feature)) {
diff --git a/src/source/geojson_source.js b/src/source/geojson_source.js
@@ -184,7 +184,8 @@ class GeoJSONSource extends Evented {
       tileSize: this.tileSize,
       source: this.id,
       pixelRatio: browser.devicePixelRatio,
-      showCollisionBoxes: this.map.showCollisionBoxes
+      showCollisionBoxes: this.map.showCollisionBoxes,
+      globalState: this.map.getGlobalState()
     };
 
     const justReloaded = tile.workerID != null;
diff --git a/src/source/vector_tile_source.js b/src/source/vector_tile_source.js
@@ -94,7 +94,8 @@ class VectorTileSource extends Evented {
         type: this.type,
         source: this.id,
         pixelRatio: browser.devicePixelRatio,
-        showCollisionBoxes: this.map.showCollisionBoxes
+        showCollisionBoxes: this.map.showCollisionBoxes,
+        globalState: this.map.getGlobalState()
       };
       tile.workerID ??= this.dispatcher.nextWorkerId();
       const data = await this.dispatcher.send('loadTile', params, tile.workerID);
diff --git a/src/source/vector_tile_worker_source.js b/src/source/vector_tile_worker_source.js
@@ -49,6 +49,7 @@ class VectorTileWorkerSource {
     }
     const { vectorTile, rawData } = response;
     const workerTile = new WorkerTile(params);
+    workerTile.globalState = params.globalState;
     workerTile.vectorTile = vectorTile;
     const result = await workerTile.parse(vectorTile, this.layerIndex, this.resources);
     if (rawData) {
diff --git a/src/source/worker_tile.js b/src/source/worker_tile.js
@@ -31,6 +31,7 @@ class WorkerTile {
     this.source = params.source;
     this.overscaling = this.tileID.overscaleFactor();
     this.showCollisionBoxes = params.showCollisionBoxes;
+    this.globalState = params.globalState;
   }
 
   async parse(data, layerIndex, resources) {
@@ -91,7 +92,8 @@ class WorkerTile {
           overscaling: this.overscaling,
           collisionBoxArray: this.collisionBoxArray,
           sourceLayerIndex: sourceLayerIndex,
-          sourceID: this.source
+          sourceID: this.source,
+          globalState: this.globalState
         }));
 
         bucket.populate(features, options);
diff --git a/src/style/evaluation_parameters.js b/src/style/evaluation_parameters.js
@@ -8,15 +8,17 @@ class EvaluationParameters {
     this.zoom = zoom;
 
     if (options) {
-      this.now = options.now;
-      this.fadeDuration = options.fadeDuration;
-      this.zoomHistory = options.zoomHistory;
-      this.transition = options.transition;
+      this.now = options.now || 0;
+      this.fadeDuration = options.fadeDuration || 0;
+      this.zoomHistory = options.zoomHistory || new ZoomHistory();
+      this.transition = options.transition || {};
+      this.globalState = options.globalState || {};
     } else {
       this.now = 0;
       this.fadeDuration = 0;
       this.zoomHistory = new ZoomHistory();
       this.transition = {};
+      this.globalState = {};
     }
   }
 
diff --git a/src/style/properties.js b/src/style/properties.js
@@ -75,6 +75,10 @@ class PropertyValue {
     return this.expression.kind === 'source' || this.expression.kind === 'composite';
   }
 
+  getGlobalStateRefs() {
+    return this.expression.globalStateRefs ?? new Set();
+  }
+
   possiblyEvaluate(parameters) {
     return this.property.possiblyEvaluate(this, parameters);
   }
diff --git a/src/style/style.js b/src/style/style.js
@@ -41,6 +41,7 @@ class Style extends Evented {
     this.sourceCaches = {};
     this.zoomHistory = new ZoomHistory();
     this._loaded = false;
+    this._globalState = {};
 
     this._resetUpdates();
 
@@ -78,6 +79,80 @@ class Style extends Evented {
     });
   }
 
+  setGlobalStateProperty(name, value) {
+    this._checkLoaded();
+
+    const newValue = value === null ? (this.stylesheet.state?.[name]?.default ?? null) : value;
+
+    if (deepEqual(newValue, this._globalState[name])) {
+      return this;
+    }
+
+    this._globalState[name] = newValue;
+
+    const sourceIdsToReload = this._findGlobalStateAffectedSources([name]);
+
+    for (const id in this.sourceCaches) {
+      if (sourceIdsToReload.has(id)) {
+        this._reloadSource(id);
+        this._changed = true;
+      }
+    }
+  }
+
+  getGlobalState() {
+    return this._globalState;
+  }
+
+  setGlobalState(newStylesheetState) {
+    this._checkLoaded();
+
+    const changedGlobalStateRefs = [];
+
+    for (const propertyName in newStylesheetState) {
+      const didChange = !deepEqual(this._globalState[propertyName], newStylesheetState[propertyName].default);
+
+      if (didChange) {
+        changedGlobalStateRefs.push(propertyName);
+        this._globalState[propertyName] = newStylesheetState[propertyName].default;
+      }
+    }
+
+    const sourceIdsToReload = this._findGlobalStateAffectedSources(changedGlobalStateRefs);
+
+    for (const id in this.sourceCaches) {
+      if (sourceIdsToReload.has(id)) {
+        this._reloadSource(id);
+        this._changed = true;
+      }
+    }
+  }
+
+  /**
+   * Find all sources that are affected by the global state changes.
+   * For example, if a layer filter uses global-state expression, this function will return the source id of that layer.
+   */
+  _findGlobalStateAffectedSources(globalStateRefs) {
+    if (globalStateRefs.length === 0) {
+      return new Set();
+    }
+
+    const sourceIdsToReload = new Set();
+
+    for (const layerId in this._layers) {
+      const layer = this._layers[layerId];
+      const layoutAffectingGlobalStateRefs = layer.getLayoutAffectingGlobalStateRefs();
+
+      for (const ref of globalStateRefs) {
+        if (layoutAffectingGlobalStateRefs.has(ref)) {
+          sourceIdsToReload.add(layer.source);
+        }
+      }
+    }
+
+    return sourceIdsToReload;
+  }
+
   loadJSON(json) {
     this.fire(new Event('dataloading', { dataType: 'style' }));
 
@@ -128,6 +203,8 @@ class Style extends Evented {
 
     this.light = new Light(this.stylesheet.light);
 
+    this.setGlobalState(this.stylesheet.state ?? null);
+
     this.fire(new Event('data', { dataType: 'style' }));
     this.fire(new Event('style.load'));
   }
@@ -547,12 +624,12 @@ class Style extends Evented {
     }
 
     if (filter === null || filter === undefined) {
-      layer.filter = undefined;
+      layer.setFilter(undefined);
       this._updateLayer(layer);
       return;
     }
 
-    layer.filter = clone(filter);
+    layer.setFilter(clone(filter));
     this._updateLayer(layer);
   }
 
diff --git a/src/style/style_layer.js b/src/style/style_layer.js
@@ -3,6 +3,7 @@ const { filterObject } = require('../util/object');
 const { Evented } = require('@mapwhit/events');
 const { Layout, Transitionable, PossiblyEvaluatedPropertyValue } = require('./properties');
 const { supportsPropertyExpression } = require('@mapwhit/style-expressions');
+const featureFilter = require('../style-spec/feature_filter');
 
 const TRANSITION_SUFFIX = '-transition';
 
@@ -23,9 +24,10 @@ class StyleLayer extends Evented {
       this.source = layer.source;
       this.sourceLayer = layer['source-layer'];
       this.filter = layer.filter;
+      this._featureFilter = featureFilter(layer.filter);
     }
 
-    this._featureFilter = () => true;
+    this._featureFilter ??= featureFilter.addGlobalStateRefs(() => true);
 
     if (properties.layout) {
       this._unevaluatedLayout = new Layout(properties.layout);
@@ -43,6 +45,11 @@ class StyleLayer extends Evented {
     this._transitioningPaint = this._transitionablePaint.untransitioned();
   }
 
+  setFilter(filter) {
+    this.filter = filter;
+    this._featureFilter = featureFilter(filter);
+  }
+
   getCrossfadeParameters() {
     return this._crossfadeParameters;
   }
@@ -55,6 +62,31 @@ class StyleLayer extends Evented {
     return this._unevaluatedLayout.getValue(name);
   }
 
+  /**
+   * Get list of global state references that are used within layout or filter properties.
+   * This is used to determine if layer source need to be reloaded when global state property changes.
+   *
+   */
+  getLayoutAffectingGlobalStateRefs() {
+    const globalStateRefs = new Set();
+
+    if (this._unevaluatedLayout) {
+      for (const propertyName in this._unevaluatedLayout._values) {
+        const value = this._unevaluatedLayout._values[propertyName];
+
+        for (const globalStateRef of value.getGlobalStateRefs()) {
+          globalStateRefs.add(globalStateRef);
+        }
+      }
+    }
+
+    for (const globalStateRef of this._featureFilter.getGlobalStateRefs()) {
+      globalStateRefs.add(globalStateRef);
+    }
+
+    return globalStateRefs;
+  }
+
   setLayoutProperty(name, value) {
     if (name === 'visibility') {
       this.visibility = value === 'none' ? value : 'visible';
diff --git a/src/ui/map.js b/src/ui/map.js
@@ -201,6 +201,29 @@ class Map extends Camera {
     this.on('dataloading', this._onDataLoading);
   }
 
+  /**
+   * Sets a global state property that can be retrieved with the [`global-state` expression](https://maplibre.org/maplibre-style-spec/expressions/#global-state).
+   * If the value is null, it resets the property to its default value defined in the [`state` style property](https://maplibre.org/maplibre-style-spec/root/#state).
+   *
+   * Note that changing `global-state` values defined in layout properties is not supported, and will be ignored.
+   *
+   * @param propertyName - The name of the state property to set.
+   * @param value - The value of the state property to set.
+   */
+  setGlobalStateProperty(propertyName, value) {
+    this.style.setGlobalStateProperty(propertyName, value);
+    return this._update(true);
+  }
+
+  /**
+   * Returns the global map state
+   *
+   * @returns The map state object.
+   */
+  getGlobalState() {
+    return this.style.getGlobalState();
+  }
+
   /**
    * Adds a {@link IControl} to the map, calling `control.onAdd(this)`.
    *
@@ -1248,7 +1271,8 @@ class Map extends Camera {
         now,
         fadeDuration: this._fadeDuration,
         zoomHistory: this.style.zoomHistory,
-        transition: this.style.getTransition()
+        transition: this.style.getTransition(),
+        globalState: this.style.getGlobalState()
       });
 
       const factor = parameters.crossFadingFactor();
diff --git a/src/util/transfer_registry.js b/src/util/transfer_registry.js
@@ -27,6 +27,7 @@ function register(name, klass, { omit, shallow } = {}) {
 }
 
 register('Object', Object);
+register('Set', Set);
 
 /**
  * Serialize the given object for transfer to or from a web worker.
diff --git a/test/unit/source/geojson_source.test.js b/test/unit/source/geojson_source.test.js
diff --git a/test/unit/source/vector_tile_source.test.js b/test/unit/source/vector_tile_source.test.js
diff --git a/test/unit/style/style.test.js b/test/unit/style/style.test.js
diff --git a/test/unit/style/style_layer.test.js b/test/unit/style/style_layer.test.js
diff --git a/test/unit/ui/map/global_state.test.js b/test/unit/ui/map/global_state.test.js

Original file line number	Diff line number	Diff line change
`@@ -49,6 +49,7 @@ class VectorTileWorkerSource {`
`49`	`49`	`}`
`50`	`50`	`const { vectorTile, rawData } = response;`
`51`	`51`	`const workerTile = new WorkerTile(params);`
	`52`	`+ workerTile.globalState = params.globalState;`
`52`	`53`	`workerTile.vectorTile = vectorTile;`
`53`	`54`	`const result = await workerTile.parse(vectorTile, this.layerIndex, this.resources);`
`54`	`55`	`if (rawData) {`