Vertical alignment in format expression

[stanislawpuda-tomtom]

Design Proposal: Add vertical alignment to format expression

Motivation

Format expression can facilitate multiple text and image elements of different sizes. At the moment all of them are aligned to the font baseline. It is not possible to change the vertical alignment. Having a possibility to change the alignment, eg. center, would allow us to create rich labels.

If following design would be accepted I would like to make contributions to this repo and MapLibre GL JS with the implementation.

Proposed Change

We would like to introduce vertical-align property to style override in format expression. vertical-align property can take three options:

• baseline (default)
• center
• top

Examples

Center

"text-field": [
  "format",
  ["image", "image"], 
  { "vertical-align": "center" },
  " ",
  {},
  "BIG yg",
  { "font-scale": 1.2, "vertical-align": "center" },
  " ",
  {},
  "SMALL",
  { "font-scale": 0.8, "vertical-align": "center" }
],

Top

"text-field": [
  "format",
  ["image", "image"], 
  { "vertical-align": "top" },
  " ",
  {},
  "BIG yg",
  { "font-scale": 1.2, "vertical-align": "top" },
  " ",
  {},
  "SMALL",
  { "font-scale": 0.8, "vertical-align": "top" }
],

Baseline (default, current behaviour)

"text-field": [
  "format",
  ["image", "image"], 
  {},
  " ",
  {},
  "BIG yg",
  { "font-scale": 1.2 },
  " ",
  {},
  "SMALL",
  { "font-scale": 0.8 }
],

Mixed

"text-field": [
  "format",
  ["image", "image"], 
  {},
  " ",
  {},
  "BIG yg",
  { "font-scale": 1.2 },
  " ",
  {},
  "SMALL",
  { "font-scale": 0.8, "vertical-align": "center" }
],

API Modifications

Add new property to style override object of format expression:

vertical-align:

• type: enum
• default: baseline
• possible values: baseline, center, top
• effect: change vertical alignment of format expression element

Behaviour

• baseline default: text baseline and image bottom are in line (current behaviour)
• center: image center and text center (line between baseline and top) are in line with center of the highest element in the row
• top: image top and text top (line determined by the highest character in the font) are in line

It is possible to set vertical-align for each element in format expression separately.

Migration Plan and Compatibility

There is no breaking change. Rendering of existing styles is unchanged. Only if style has new property vertical-align with non-default value, there is a difference in label rendering.

[HarelM]

Thanks for taking the time to open the proposal!
What are the current alternatives available?
My concern is the this is a bit two simplistic. What about if I want to move a single word two pixels upwards? What about padding between words?
This might get very complex...

[stanislawpuda-tomtom]

I understand your concern. I believe what you've mention can be achieved by combining together additional property.

If we want to move single word a few pixels, we could add vertical-offset. Examples:

• element aligned to the top and shifted two pixels down: { "vertical-align": "top", "vertical-offset": "-2px" }
• element aligned to the center and shifted two pixels up: { "vertical-align": "center", "vertical-offset": "2px" }
  "offset" property maybe could take also relative values, but it should be well thought out to make it intuitive.

For the padding between words the easiest solution is to use spaces. I'm not sure if this requires another solution.

For the alternatives, we did think of numeric based approach, where value moves element up and down. There are two possibilities:

• where numeric value stands for relation between baseline of the row and element vertical position. Eg. 0 - baseline of the element = baseline of the row, 0.5 - element shifted 50% of its height up, -0.5 or center, middle of the element in line with row baseline. However, this approach is not working when elements (especially images) can have various height.
• similar to vertical-align but with numbers: 0 for baseline, 0.5 for middle and 1 for top - but enum variant is in my opinion easier to understand

[zbigniewmatysek-tomtom]

I propose to rename this property, because it suggests it works like https://developer.mozilla.org/en-US/docs/Web/CSS/vertical-align, but in reality is similar to the https://developer.mozilla.org/en-US/docs/Web/CSS/align-self.

I belive showing the analogy to CSS properties can be helpful. It is easier to explain and adopt trough using existing terminology.

Regarding the @HarelM concern on the extendibility of this proposal. I think it's pretty extensible. One solution is having relative offset property that @stanislawpuda-tomtom explained or a different set of properties altogether that may or may not be combained with the vertical-align.

[HarelM]

I would advise to bring this up in the monthly meeting to discuss this.

[stanislawpuda-tomtom]

Will do!

Regarding the name, I went through few possible options:

• row-align,
• align-vertical,
• vertical-placement,
• y-align?

But to be honest, vertical-align still sounds for me like the best option. I'm not sure if the connotations with CSS property is so significant.