Add vertical-align in format expression

[stanislawpuda-tomtom]

Related issue #832.

This PR introduces vertical align property to format expression. It enables to specify how each section should be positioned in relation to biggest element in line. There are three possible options:

• "bottom" default: text baseline or image bottom are in line - this is current behaviour.
• "center": image center or text center are in line.
• "top": image top and text top are in line

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.
• Include before/after visuals or gifs if this PR includes visual changes.
• Write tests for all new functionality.
• Document any changes to public APIs.
• Post benchmark scores.
• Add an entry to CHANGELOG.md under the ## main section.

[codecov-commenter]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 92.80%. Comparing base (c6fd205) to head (37e1178).
Report is 11 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #900      +/-   ##
==========================================
+ Coverage   92.78%   92.80%   +0.01%     
==========================================
  Files         107      107              
  Lines        4739     4752      +13     
  Branches     1346     1352       +6     
==========================================
+ Hits         4397     4410      +13     
  Misses        342      342              

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

[stanislawpuda-tomtom]

I would like to cover questions from the meeting on Nov 13th:

Using HTML

I did check, and it is possible to use HTML to display vertically aligned labels. This approach works for MapLibre GL JS, however it does not cover multiple platforms. There are more advantages of using format expression over custom HTML layer:

• much easier to use
• HTML markers don't support collision detection, as far as I know, which makes the implementation even more difficult
• better performance
• defined once in the style spec for multiple platforms

Format expression already gives possibility to create rich labels on the map, easily, without having to implement own custom solution. Having the possibility to align elements vertically in my opinion is good supplement to format expression. In some cases necessary to make full benefit from it.

Sample use case

Our team created a sample mock how the labels look like with and without vertical alignment.

Before:

After:

[lseelenbinder]

Thanks for taking the time to work through these pieces @stanislawpuda-tomtom!

In my opinion, those advantages are sufficient to merit including in the spec—especially for collision detection and performance reasons.

[stanislawpuda-tomtom]

I have changed baseline to bottom.
I also modified one test to check if vertical-align is recognised for image section.

[HarelM]

Are you sure about the places where you added the code?
It seems that equivalent format related code does not look the same.
I know this is an enum while the others are string, or number, but I find the code a bit weird...

[stanislawpuda-tomtom]

I've added vertical-align to SDK support table.

For the code, let me try to explain:

let verticalAlign = null;
if (arg['vertical-align']) { 
    // covers case, when `vertical-align` is defined with plain string, then we can check if matches enum
    if (typeof arg['vertical-align'] === 'string' && !VERTICAL_ALIGN_OPTIONS.includes(arg['vertical-align'] as VerticalAlign)) {
        return context.error(`\`vertical-align\` must be one of: 'bottom', 'center', 'top' but found '${arg['vertical-align']}' instead.`) as null;
    }

    // in this case it returns expression, so we can't check if it matches enum, only if it is string
    verticalAlign = context.parse(arg['vertical-align'], 1, StringType);
    if (!verticalAlign) return null;
}

[stanislawpuda-tomtom]

@HarelM @lseelenbinder
Is it possible to proceed with this PR? Is there something I can do, clarify, or is there any blocker?

[HarelM]

Can this if be moved to the parse code to keep this as clean as the other if statements?

[stanislawpuda-tomtom]

I did try to move it to parse - however then it shouldn't be placed in parse fn itself, but I found that it is better to add enum validation, like for array in other places.

However, to make it possible there are multiple changes that has to be made. Moreover the validation for enum is a bit different, because other validations are based on types, and enum validation requires access to the value, so it is possible to compare with enum values.

You can see how it looks here: tomtom-forks#2

After making this try I actually think that having it in format.ts, as it is now, is better and much simpler. Also in similar fashion the validation is implemented for interpolate expression (link to the file).

[HarelM]

How is this different than other properties? Why not passing null here?

[stanislawpuda-tomtom]

This is the instantiation of FormattedSection for image. All other properties are null, because they only applies to text (font etc.), but vertical-align can be applied to both image and text section.

[HarelM]

Shouldn't this be defined in the v8 spec file and not here?

[HarelM]

Can we put enum possible values instead of string? Not sure how the handled in different places...

[HarelM]

I've added details on my concerns regarding the current code. Let me know if this is clearer now.

[stanislawpuda-tomtom]

@HarelM It is clear - I'll cover them. Thank you!