[Design Proposal] Allow global state expressions in layer visibility

[hiddewie]

Design Proposal: Allow global state expressions in layer visibility

Motivation

See the original issue for Maplibre GL JS in maplibre/maplibre-gl-js#6495

Since the introduction of global-state in expressions, creating a dynamic map in a single style became a lot easier and user friendly.

However, the visibility field currently does not support any other values than visible or none. Making such layers visible / invisible requires client-side code to toggle the layer visibility in sync with changing the global-state values. Most importantly, this requires client-side code to have knowledge of the naming an structure of the style layers.

Proposed Change

The change has been implemented in #1359.

Allow the visibility field to support an expression, instead of just the string values visible and none. Support global-state as part of the expression. Do not support feature-state as part of the expression.

API Modifications

The field visibility for a layer will support expressions, including global-state. Currently only the string values visible and none are supported.

Note that feature-state is not included, because it has no meaning in a visibility field which is "global" to a layer.

Migration Plan and Compatibility

This proposal is backwards compatible. Users who do not want/need this feature do not need to use it.

Users who want/need this feature can start using it by configuring an expression, possibly including global-state, into their layer definitions for the visibility field.

Rejected Alternatives

No change

To create a dynamic map which is configurable for the user, there must be client-side logic to call imperative funcitons on the map to toggle visibility of layers. Additionally, on the initial map load, the same layers need to be modified to support the "initial" client configuration.

Without global-state expressions in the visibility field, it is difficult to keep dynamic style changes that impact how the layers are painted (for example colors), in sync with the visibility of layers.

Use filter

In a layer, the filter field supports expressions including global-state. An expression which evaluates do false for all features will visually give the same results as making the entire layer invisible.

However, there is a performance impact, because the source of the invisible layer will still be fetched, and the filter is still evaluated for every feature.

For large data sets with many invisible layers (due to expressions evaluating to false), this approach is infeasible.

[HarelM]

Thanks for taking the time to write up this proposal!
My main concern about it is around limiting the expression to not be feature related.
The expression system relies deeply on features, the need to interpret the expression to make sure it is not feature related seems like a can of worms.

Another alternative which I believe was not added here is using the layer's metadata to decide which layer to hide and which to show (since you need to change the global state from the code anyway, you can go over the layers and toggle them as needed). I admit it's not the cleanest solution, but I think it's a lot simpler than adding expression that must not be feature related.

[melitele]

My main concern about it is around limiting the expression to not be feature related.
The expression system relies deeply on features, the need to interpret the expression to make sure it is not feature related seems like a can of worms.

It's actually quite simple. evaluate for visibility expression doesn't take any parameters, so there is no way it'll get the feature (neither feature-state nor zoom). This is possible because global-state is passed when creating expression, not when evaluating it (use global-state added to expression in constructor instead of the one passed as a parameter to evaluate function #1267 was the change).

This is the relevant line in the PR:
expression.evaluate = () => compiled.value.evaluate({} as GlobalProperties);

I added the unit test that shows that neither feature nor other parameters are used when evaluating visibility.

[HarelM]

Thanks for info! This helps reduce anxiety :-)
The spec types support enum as much as I can see here is visibility different in any way that it should be noted somehow?

[melitele]

Visibility continues to be defined as enum. property-type changes from constant to data-constant with following expression spec:

"expression": {
    "interpolated": false,
    "parameters": [
          "global-state"
    ]
}

[HarelM]

I've posted a message on slack to get a bit more traction on this issue, but I think this proposal is solid. Thanks for all work on this!