global-state expression

[zbigniewmatysek-tomtom]

This PR introduces:

• new expression global-state that retrieves a property value from the new root property state.
• new root property state , where the default value can be set. This eliminates need to put coalesce in all places where global-state is used.

The expression is similar to get and such be interpreted by renderers as such:

• when referenced property is not set, it must return null
• referenced property values are treated as primitives, so there is no need to wrap global-state in literal if it returns an array.

Renderer implementations can expose methods such as setGlobalStateProperty(name, value) for changing the state properties at runtime.

Use cases enabled or simplified by this extension:

• Setting map language (without a plugin or SDK wrapper code)
• POI categories filtering (without using layer.setFilter() that relies on the filter content to work)
• Single style with multiple variants (light/dark mode, browsing/navigation) instead of multiple styles.

Related issues:
#886
maplibre/maplibre-gl-js#4964

Launch Checklist

• Confirm your changes do not include backports from Mapbox projects (unless with compliant license) - if you are not sure about this, please ask!
• Briefly describe the changes in this PR.
• Link to related issues.
• Write tests for all new functionality.
• Document any changes to public APIs.
• Add an entry to CHANGELOG.md under the ## main section.

[HarelM]

Looks good! Thanks!
CC: @louwers.

[codecov-commenter]

Codecov Report

Attention: Patch coverage is 92.50000% with 3 lines in your changes missing coverage. Please review.

Project coverage is 93.66%. Comparing base (e48ac7a) to head (2a27194).

Files with missing lines	Patch %	Lines
src/expression/definitions/global_state.ts	86.36%	3 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1044      +/-   ##
==========================================
- Coverage   93.67%   93.66%   -0.01%     
==========================================
  Files         112      115       +3     
  Lines        4888     4928      +40     
  Branches     1392     1401       +9     
==========================================
+ Hits         4579     4616      +37     
- Misses        309      312       +3     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[zbigniewmatysek-tomtom]

@HarelM @louwers Please take another look 😉

As discussed on the call:

• Removed "types"
• Removed requirement that property must be defined in state if it's referenced by the global-state
• Kept state with optional default
• Updated docs
• I am going to move the "types" and validations to a separate proposal, once this one is merged

PR description and the changelog were updated to reflect the changes.

[HarelM]

LGTM, THANKS!

[HarelM]

I think the last comment that was not addressed is the following:
#1044 (comment)
Around making the native issue self-descriptive.

[zbigniewmatysek-tomtom]

@HarelM updated native issue: maplibre/maplibre-native#3302

[louwers]

Please see my comments for suggestions on slightly rewording the documentation for clarity.

Otherwise LGTM.

[hiddewie]

@zbigniewmatysek-tomtom Incredible work! Much appreciated how you move the proposal from maplibre/maplibre-gl-js#4964 forward!

[HarelM]

@zbigniewmatysek-tomtom can you please address the last few comments, so I'll be able to release a new version of the style-spec package?

[stanislawpuda-tomtom]

@louwers @HarelM
As @zbigniewmatysek-tomtom is off I have included fixes from two last comments.
Unfortunately CI fails with relative links, I changed them back to absolute (with https://maplibre.org).

[HarelM]

@louwers feel free to push the merge button once you finish the review.
LGTM.