Support union types in style spec

[drwestco]

Per the conversation in #1832, addressing a similar issue as I encountered in #1289, I've come across the need to extend the type signatures for existing style properties to support union types. i.e., for backwards compatibility, a style property keeps its original type A, but for future expansion, may alternatively be of type B.

In #1289, icon-padding may either be a plain number (representing equal padding on all sides), or an array of numbers (supporting CSS-style padding shorthand). To accomplish this, I introduced a new 'padding' type to the style spec.

For #1832, text-offset may either be a 2-element array, representing a single [x, y] offset, or (new extension) an array of such 2-element arrays. I could follow the same pattern as icon-padding, and introduce yet another new type (offsetCollection?) to represent the alternate types this value can take. Instead, I'm proposing a more generic solution, and explicitly listing the alternate forms directly:

"text-offset": {
  "specs": [
    {
      "type": "array",
      "value": "number",
      "units": "ems",
      "length": 2,
      "doc": "Offset distance of text from its anchor. Positive values indicate right and down, while negative values indicate left and up. If used with text-variable-anchor, input values will be taken as absolute values. Offsets along the x- and y-axis will be applied automatically based on the anchor position."
    },
    {
      "type": "array",
      "min-length": 1,
      "value": {
        "type": "array",
        "value": "number",
        "units": "ems",
        "length": 2,
        "doc": "Offset distance of text from its anchor. Positive values indicate right and down, while negative values indicate left and up."
      },
      "doc": "List of offset distances of text from its anchor. The order the individual offsets appear matches the set of possible anchors listed in text-variable-anchor."
    }
  ],
  "default": [
    0,
    0
  ],
  ...
}

Here, the new 'specs' property provides a list of alternate property value specifications. generate-style-spec and generate-style-code are updated to produce the corresponding union types:

/* types.g.ts */
"text-offset"?: DataDrivenPropertyValueSpecification<[number, number] | Array<[number, number]>>,

/* symbol_style_layer_properties.g.ts */
"text-offset": PossiblyEvaluatedPropertyValue<[number, number] | Array<[number, number]>>,

Thoughts on this approach? Per the whole #1851 discussion, the style spec format and validation process may entirely change in the near future.

[HarelM]

The problem is that if you add this support to js you'll need to write it in native as well and this is all proprietary code which is prone to errors, I think we should invest in something more future proof. IDK...
We can also try and only support this small increment and see what the next item that requires changes, but this feels a bit "we are already invested in so let's continue in that wrong direction" approach, which I personally don't like much...

[drwestco]

So you'd suggest going with a 1-off for text-offset, as I did with icon-padding?

[HarelM]

Sure... Least evil I guess...