Add symbol-z-order symbol layout property to style spec

[ryanhamley]

Launch Checklist

• briefly describe the changes in this PR
  • Adds symbol-sort-by-y symbol layout property to style spec
  • closes Style spec: add option to disable y-position sort for symbol features #7076
  • Native port: [core] Port symbol-z-order symbol layout style spec property mapbox-gl-native#12783
• write tests for all new functionality
• document any changes to public APIs
• manually test the debug page
• tagged @mapbox/studio and/or @mapbox/maps-design if this PR includes style spec changes

[ryanhamley]

See #7076 for background on this PR.

I can think of two alternatives to adding a new style spec property.

1. We can make this a runtime setting.

   • Downside: I don't think it makes much sense semantically and organizationally since the sorting only applies to symbols, not all layers on a map. Disabling this sorting is closely linked to the existing style spec symbol layout properties *-allow-overlap and *-ignore-placement so it's logical to include this as another style spec property.

2. We could push forward with adding a mechanism such as some expression syntax to allow for generalized manual sorting of all feature types as discussed in Style spec: Add ability to sort features #4361.

   • Downside: This is significantly more work and possibly overkill for this particular use case.

The downside of this PR's approach obviously is a new property on the style-spec which is something we have to be prepared to maintain for awhile. If/when #4361 is implemented, does this feature become obsolete? I feel like symbol sorting by y is a specialized case that users may want a simple way to disable even if they plan on doing further sorting. And of course this concern assumes we eventually implement general sorting.

Two further thoughts/questions:

1. Is symbol-sort-by-y an appropriate name or would we prefer something more descriptive like sort-overlapping-symbols (which doesn't specify how the symbols are sorted).

2. Is the description of the property in v8.json accurate and informative enough for users? And is it true that non-skeumorphic icons won't benefit from symbol sorting and are therefore good candidates for symbol-sort-by-y: false?

Tagging Carto and Studio into this discussion: @nickidlugash @samanpwbb

[ryanhamley]

Overlapping icons with default sorting behavior

Overlapping icons with symbol-sort-by-y: false (note that because the building icon is the first feature in the source data it is below the other two icons now that sorting by y is disabled)

[samanpwbb]

Overall approach looks good to me. I think it's fine to make this a new spec property since it's a straightforward boolean. if/when we take on #4361 we can deprecate or de-emphasize the property.

Is symbol-sort-by-y an appropriate name or would we prefer something more descriptive like sort-overlapping-symbols (which doesn't specify how the symbols are sorted).

What about sort-relative-to-viewport (or sort-by-viewport)? I find sort-by-y a little unclear - I needed to read the description to understand what it meant.

[ryanhamley]

Renamed symbol-sort-by-y to more descriptive symbol-sort-relative-to-viewport and edited description of property in docs

[ryanhamley]

[jfirebaugh]

Let's make this symbol-z-order, an enum-valued property with possible values "viewport-y" and "source". That gives us the flexibility to extend the property with other options. (I can imagine a request for "map-y" for example.)

[samanpwbb]

Let's make this symbol-z-order, an enum-valued property with possible values "viewport-y" and "source". That gives us the flexibility to extend the property with other options. (I can imagine a request for "map-y" for example.)

I like this option 👍. Why viewport-y instead of just viewport though?

[ryanhamley]

Yep. Makes sense. I'll change this and the native PR over to symbol-z-order.

[ChrisLoer]

This looks right to me! 🚀

"z-order" threw me off at first because it's not controlling z in the GL coordinate sense, but I came around to it as a pretty natural description of what this does.

[ryanhamley]

Ah yeah. I think most front end developers will understand it pretty intuitively as being analogous to the CSS z-index property though.