[macos, ios] Insert layer above

[frederoni]

WIP
Insert layer above another layer

[mention-bot]

@frederoni, thanks for your PR! By analyzing the history of the files in this pull request, we identified @incanus, @1ec5 and @jfirebaugh to be potential reviewers.

[frederoni]

should I remove the optional beforeLayerID and combine beforeOrAfter in the insert method?

[jfirebaugh]

I don't think an additional variant of addLayer is necessary; this should use the beforeLayerID parameter of the existing addLayer method to accomplish the desired result. If this requires calculating which layer is currently immediately after a given layer, you may need #6097 to land first.

[jfirebaugh]

In fact, I question whether the SDKs themselves should have another variant. Typically array-like datastructures offer only an "insert before" operation. In cases where "insert after" is desired, you increment your index by one.

[frederoni]

I think you're right about addLayer being sufficient and waiting for #6097 but it does make sense to support this in the SDK. -[UIView insertSubview:aboveSubview:] -[CALayer insertSublayer:above:] is convenient and used quite frequently. Adding a navigation line on top of all roads makes more sense than adding it under symbol layers for example.

[incanus]

Another vote here for the Cocoa API-like above variant as well. It's a common pattern on iOS.

[jfirebaugh]

As a cartographic convention, it's much more common to say "add a layer beneath labels" than "add a layer above X", for some value of X. We can of course support both in an SDK for a platform where "above" is common in other contexts, I'm just not really convinced it makes sense for map layers.

[frederoni]

Not sure we should confuse cartographers with app developers. One of the most common use cases will likely be to find a road or a park and insert a layer on top of it. If we don't support this, you'll have to find an arbitrary layer above the layer you're working with and insert it beneath it. Doesn't sound very intuitive to me.

[1ec5]

For comparison, MapKit only allows you to insert an overlay at one of two preset levels: aboveRoads (above roads; below labels, shields, and POIs) and aboveLabels (above labels, shields, and POIs; below annotations and 3D buildings).

[frederoni]

@1ec5 Excellent solution. Let's do something along those lines adapted for custom styles when #6097 lands.

[1ec5]

I only pointed out MapKit's overlay levels for comparison, as a window into the most common use cases. Since our SDK is much more freeform, allowing arbitrary styles with arbitrary layers, an equivalent set of options would necessarily be limited to a certain set of Mapbox styles, something we haven't done in the SDK to date.