global-state expression (#1044)

* add global-state expression

* self review

* code hygiene

* add integration tests

* add unit tests

* update sdk-support

* use getOwn

* add state root property

* state property validation

* validate state keys existance when global-state is used

* improve expression parsing

* refactor

* temporarily build for testing purposes

* improve docs

* schema support

* cleanout

* export schema validator

* minor fix

* cleanout

* update types

* docs

* minor fixes

* add schema ts types

* cleanout

* fixes + increase test coverage

* review fixes

* make default optional in the ts types

* docs update

* docs fixes

* review fixes

* minor fix

* review fixes

* remove annotations section

* remove validation

* cleanout

* add changelog

* Review fix: update src/reference/v8.json

Co-authored-by: Bart Louwers <[email protected]>

* Review fix: update src/reference/v8.json

Co-authored-by: Bart Louwers <[email protected]>

* fix links

---------

Co-authored-by: stanislawpuda-tomtom <[email protected]>
Co-authored-by: Bart Louwers <[email protected]>
Co-authored-by: Stanislaw Puda <[email protected]>

Author: 3 people

CHANGELOG.md

@@ -3,6 +3,7 @@
 ### ✨ Features and improvements
 - `glyphs` is now optional even if a symbol layer specifies `text-field`; if it is unset, `text-font` is interpreted as a fallback font list ([#1068](https://github.com/maplibre/maplibre-style-spec/pull/1068))
 - `hillshade` layer now supports multiple methods, and the `multidirectional` method supports array values for illumination properties ([#1088](https://github.com/maplibre/maplibre-style-spec/pull/1088))
+- Add `global-state` expression and `state` root property ([#1044](https://github.com/maplibre/maplibre-style-spec/pull/1044)).
 
 ### 🐞 Bug fixes
 - Fix RuntimeError class, make it inherited from Error ([#983](https://github.com/maplibre/maplibre-style-spec/issues/983))

build/generate-docs.ts

@@ -20,7 +20,7 @@ type JsonSdkSupport = {
 type JsonObject = {
     required?: boolean;
     units?: string;
-    default?: string | number | boolean;
+    default?: string | number | boolean | {};
     type: string;
     doc: string;
     requires?: any[];
@@ -58,7 +58,6 @@ function topicElement(key: string, value: JsonObject): boolean {
         key !== 'sprite' &&
         key !== 'layers' &&
         key !== 'sources';
-
 }
 
 /**
@@ -233,7 +232,7 @@ function convertPropertyToMarkdown(key: string, value: JsonObject, keyPrefix = '
         markdown += `Units in ${value.units}. `;
     }
     if (value.default !== undefined) {
-        markdown += `Defaults to \`${value.default}\`. `;
+        markdown += `Defaults to \`${JSON.stringify(value.default)}\`. `;
     }
     if (value.requires) {
         markdown += requiresToMarkdown(value.requires);

build/generate-style-spec.ts

@@ -39,6 +39,8 @@ function propertyType(property) {
                 return '{[_: string]: SourceSpecification}';
             case 'projection:':
                 return 'ProjectionSpecification';
+            case 'state':
+                return 'StateSpecification';
             case 'numberArray':
                 return 'NumberArraySpecification';
             case 'colorArray':
@@ -321,6 +323,13 @@ export type DataDrivenPropertyValueSpecification<T> =
     | CompositeFunctionSpecification<T>
     | ExpressionSpecification;
 
+export type SchemaSpecification = {
+    default?: unknown
+};
+
+// State
+export type StateSpecification = Record<string, SchemaSpecification>;
+
 ${objectDeclaration('StyleSpecification', spec.$root)}
 
 ${objectDeclaration('LightSpecification', spec.light)}

src/diff.test.ts

@@ -262,6 +262,16 @@ describe('diff', () => {
         } as StyleSpecification)).toEqual([]);
     });
 
+    test('set state', () => {
+        expect(diff({
+            state: {foo: 1}
+        } as any as StyleSpecification, {
+            state: {foo: 2}
+        } as any as StyleSpecification)).toEqual([
+            {command: 'setGlobalState', args: [{foo: 2}]}
+        ]);
+    });
+
     test('set center', () => {
         expect(diff({
             center: [0, 0]

src/diff.ts

@@ -1,5 +1,5 @@
 
-import {GeoJSONSourceSpecification, LayerSpecification, LightSpecification, ProjectionSpecification, SkySpecification, SourceSpecification, SpriteSpecification, StyleSpecification, TerrainSpecification, TransitionSpecification} from './types.g';
+import {GeoJSONSourceSpecification, LayerSpecification, LightSpecification, ProjectionSpecification, SkySpecification, SourceSpecification, SpriteSpecification, StyleSpecification, TerrainSpecification, TransitionSpecification, StateSpecification} from './types.g';
 import {deepEqual} from './util/deep_equal';
 
 /**
@@ -31,6 +31,7 @@ export type DiffOperationsMap = {
     'setTerrain': [TerrainSpecification];
     'setSky': [SkySpecification];
     'setProjection': [ProjectionSpecification];
+    'setGlobalState': [StateSpecification];
 }
 
 export type DiffOperations = keyof DiffOperationsMap;
@@ -280,6 +281,9 @@ export function diff(before: StyleSpecification, after: StyleSpecification): Dif
         if (!deepEqual(before.center, after.center)) {
             commands.push({command: 'setCenter', args: [after.center]});
         }
+        if (!deepEqual(before.state, after.state)) {
+            commands.push({command: 'setGlobalState', args: [after.state]});
+        }
         if (!deepEqual(before.centerAltitude, after.centerAltitude)) {
             commands.push({command: 'setCenterAltitude', args: [after.centerAltitude]});
         }

src/expression/compound_expression.ts

@@ -21,6 +21,7 @@ import {Assertion} from './definitions/assertion';
 import {Coercion} from './definitions/coercion';
 import {Var} from './definitions/var';
 import {Distance} from './definitions/distance';
+import {GlobalState} from './definitions/global_state';
 
 import type {Expression, ExpressionRegistry} from './expression';
 import type {Value} from './values';
@@ -666,6 +667,8 @@ function isExpressionConstant(expression: Expression) {
         return false;
     } else if (expression instanceof Distance) {
         return false;
+    } else if (expression instanceof GlobalState) {
+        return false;
     }
 
     const isTypeAnnotation = expression instanceof Coercion ||

src/expression/definitions/global_state.ts

@@ -0,0 +1,47 @@
+import {Type, ValueType} from '../types';
+import type {Expression} from '../expression';
+import {ParsingContext} from '../parsing_context';
+import {EvaluationContext} from '../evaluation_context';
+import {getOwn} from '../../util/get_own';
+
+export class GlobalState implements Expression {
+    type: Type;
+    key: string;
+
+    constructor(key: string) {
+        this.type = ValueType;
+        this.key = key;
+    }
+
+    static parse(args: ReadonlyArray<unknown>, context: ParsingContext): Expression {
+        if (args.length !== 2) {
+            return context.error(`Expected 1 argument, but found ${args.length - 1} instead.`) as null;
+        }
+
+        const key = args[1];
+
+        if (key === undefined || key === null) {
+            return context.error('Global state property must be defined.') as null;
+        }
+
+        if (typeof key !== 'string') {
+            return context.error(`Global state property must be string, but found ${typeof args[1]} instead.`) as null;
+        }
+
+        return new GlobalState(key);
+    }
+
+    evaluate(ctx: EvaluationContext) {
+        const globalState = ctx.globals?.globalState;
+
+        if (!globalState || Object.keys(globalState).length === 0) return null;
+
+        return getOwn(globalState, this.key);
+    }
+
+    eachChild() {}
+
+    outputDefined() {
+        return false;
+    }
+}

src/expression/definitions/index.ts

@@ -28,6 +28,7 @@ import {ImageExpression} from './image';
 import {Length} from './length';
 import {Within} from './within';
 import {Distance} from './distance';
+import {GlobalState} from './global_state';
 
 import type {ExpressionRegistry} from '../expression';
 
@@ -68,5 +69,6 @@ export const expressions: ExpressionRegistry = {
     'to-string': Coercion,
     'var': Var,
     'within': Within,
-    'distance': Distance
+    'distance': Distance,
+    'global-state': GlobalState
 };

src/expression/expression.test.ts

@@ -632,7 +632,6 @@ describe('slice expression', () => {
 });
 
 describe('projection expression', () => {
-
     test('step', () => {
         const response = createExpression(['step', ['zoom'], 'vertical-perspective', 10, 'mercator']);
 
@@ -643,7 +642,7 @@ describe('projection expression', () => {
         } else {
             throw new Error('Failed to parse Step expression');
         }
-    })
+    });
 
     test('step array', () => {
         const response = createExpression(['step', ['zoom'], ['literal', ['vertical-perspective', 'mercator', 0.5]], 10, 'mercator'], v8.projection.type as StylePropertySpecification);
@@ -655,7 +654,7 @@ describe('projection expression', () => {
         } else {
             throw new Error('Failed to parse Step expression');
         }
-    })
+    });
 
     test('interpolate', () => {
         const response = createExpression(['interpolate', ['linear'], ['zoom'], 8, 'vertical-perspective', 10, 'mercator'], v8.projection.type as StylePropertySpecification);
@@ -667,7 +666,7 @@ describe('projection expression', () => {
         } else {
             throw new Error('Failed to parse Interpolate expression');
         }
-    })
+    });
 
     test('interpolate numberArray', () => {
         const response = createExpression(['interpolate', ['linear'], ['zoom'], 8, ['literal', [2,3]], 10, ['literal', [4,5]]],  {
@@ -753,6 +752,34 @@ describe('projection expression', () => {
         } else {
             throw new Error('Failed to parse Interpolate expression');
         }
-    })
+    });
+});
 
+describe('global-state expression', () => {
+    test('requires a property argument', () => {
+        const response = createExpression(['global-state']);
+        expect(response.result).toBe('error');
+        expect(response.value[0]).toBeInstanceOf(ExpressionParsingError);
+        expect((response.value[0] as ExpressionParsingError).message).toBe('Expected 1 argument, but found 0 instead.');
+    });
+    test('requires a string as the property argument', () => {
+        const response = createExpression(['global-state', true]);
+        expect(response.result).toBe('error');
+        expect(response.value[0]).toBeInstanceOf(ExpressionParsingError);
+        expect((response.value[0] as ExpressionParsingError).message).toBe('Global state property must be string, but found boolean instead.');
+    });
+    test('rejects a second argument', () => {
+        const response = createExpression(['global-state', 'foo', 'bar']);
+        expect(response.result).toBe('error');
+        expect(response.value[0]).toBeInstanceOf(ExpressionParsingError);
+        expect((response.value[0] as ExpressionParsingError).message).toBe('Expected 1 argument, but found 2 instead.');
+    });
+    test('evaluates a global state property', () => {
+        const response = createExpression(['global-state', 'foo']);
+        if (response.result === 'success') {
+            expect(response.value.evaluate({globalState: {foo: 'bar'}, zoom: 0}, {} as Feature)).toBe('bar');
+        } else {
+            throw new Error('Failed to parse GlobalState expression');
+        }
+    });
 });

src/expression/index.ts

@@ -61,6 +61,7 @@ export type GlobalProperties = Readonly<{
     lineProgress?: number;
     isSupportedScript?: (_: string) => boolean;
     accumulated?: Value;
+    globalState?: Record<string, any>;
 }>;
 
 export class StyleExpression {