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.77%. Comparing base (594ab7d) to head (65be105).
Report is 7 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #900      +/-   ##
==========================================
+ Coverage   92.75%   92.77%   +0.01%     
==========================================
  Files         107      107              
  Lines        4706     4719      +13     
  Branches     1337     1343       +6     
==========================================
+ Hits         4365     4378      +13     
  Misses        341      341              

☔ 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]

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!

[stanislawpuda-tomtom]

@HarelM

I answered your comments.

[HarelM]

Thanks, I'll look into it in the coming days.

[HarelM]

@louwers can you please review the v8 changes to make sure this is acceptable by you as well?

[louwers]

@HarelM Will have a look.

[louwers]

Left two comments. LGTM otherwise.

Also thanks for asking the MapLibre Native community for their feedback. Appreciate it!

[stanislawpuda-tomtom]

@louwers

Answered. Thank you for your comments.

[zbigniewmatysek-tomtom]

@HarelM @louwers Could you take the last look? Once this is merged, we will be able to continue the work on the implementation PR ;)

[HarelM]

@louwers need to approve this as he had some code review comments, I have approved it.

[louwers]

Thanks for the changes.

LGTM, but I still think some images would do the docs good. :)

[stanislawpuda-tomtom]

@louwers @HarelM
For the images we can do something like this:

Let me know if this is fine for you, I'll make a commit.

Btw I'm not sure where I should put images. I can place them in /docs/assets. Those images which are in docs already one is in some fork branch, and other hosted under maplibre.org domain.

[louwers]

Looks great!

I personally prefer using GitHub for image hosting. We can replace the images with examples from actual maps when this is implemented.

[stanislawpuda-tomtom]

Done!

[louwers]

@HarelM If you think it's better with the images, could you merge?