Explicit "horizontal" and "vertical" aliases for alignment properties

[mhsmith]

I had a chat with @ntoll this afternoon about our approach to naming style properties. In general, we agreed that it's better to match the CSS names, because many users will already be familiar with them. And even if they're not, matching the names will make it easier for users to find help and examples from sources ike MDN or ChatGPT.

However, the CSS names for the "align" and "justify" properties are a bit difficult to learn and remember, especially when it comes to whether they refer to the horizontal or vertical dimension. So I'd like to add some aliases for these properties.

CSS has 6 of these properties in total. Toga and Invent currently implement slightly different subsets, but it's likely we'll add more in the future. So it's important that whatever alias pattern we choose can be extended to the full set. Here's what we settled on:

CSS	Alias (Row and Grid)	Alias (Column)	Single-line flexbox	Multi-line flexbox	Grid
align_self	vertical_align	horizontal_align	x	x	x
align_content	vertical_align_content	horizontal_align_content		x	x
align_items	vertical_align_items	horizontal_align_items	x	x	x
justify_self	horizontal_align (Grid only)	N/A			x
justify_content	horizontal_align_content	vertical_align_content	x	x	x
justify_items	horizontal_align_items (Grid only)	N/A			x

The content and items aliases can be implemented in Toga using a similar mechanism to the alignment/align_items alias (#3033).

The self aliases are a bit more awkward because during initialization, we don’t know what the parent will be yet. But we don't support these properties yet anyway (#3126).

[HalfWhitt]

Seems reasonable to me. To avoid a collision of complexity, I'd recommend waiting to implement this until the aforementioned alignment/align_items alias is old enough to retire.

[mhsmith]

I agree that would be preferable, but we're trying to close the syntax gap with Invent as quickly as possible, so we don't have time to wait for a reasonable deprecation period.

However, since these aliases have no existing behavior to preserve, I'm using the simpler of the two options we discussed in #3033 – i.e., convert the alias to a CSS name at the time it's accessed, rather than storing it persistently in a separate property.

[freakboy3742]

Now that I'm looking at an actual implementation in #3113 - and more specifically, the documentation for the new aliases - I'm questioning whether this is a good idea, or at least whether we're missing something significant in Pack before it makes sense.

Here's the acid test:

Without looking at the docs - will `horizontal_align_content = START" move content up, or to the left?

Can you provide an intuitive explanation for why that is the case?

Even the question is ill posed, because you need to know you're in a ROW box before you even know that horizontal_align_content is even legal as a style directive (in the current implementation, anyway).

In a way, the alias mapping described here almost goes the "wrong way". My understanding of the intention of this change is to remove the need to understand "main axis" and "cross axis", so that a user can say "horizontal = START" and know that a box/widget will move in the horizontal axis. This proposed change doesn't alter the user's need to understand the main axis or cross axis - you still need to know whether you want the main or cross axis to know whether you need to use "content" or "items" to get the direction you intend. And it's not all intuitive (to me, at least) which one is which.

The core of the problem might actually be that we've mapped the wrong properties in Pack. We recently deprecated alignment to map to align-items... but should that actually be align-content? Or... should justify-content actually be justify-items? I've tied myself in knots looking at the MDN pages for these properties...

[mhsmith]

The core of the problem might actually be that we've mapped the wrong properties in Pack. We recently deprecated alignment to map to align-items... but should that actually be align-content? Or... should justify-content actually be justify-items? I've tied myself in knots looking at the MDN pages for these properties...

The mapping is correct, but I agree it seems more complex than necessary in the context of single-line flexboxes. It starts to make more sense when you extend it to multi-line flexboxes and grids. I've added some columns to the table above indicating where each property is supported in CSS.

In summary:

• "justify" refers to the main axis (horizontal in a grid), and "align" the cross axis (vertical in a grid).
• "self" is set on the child, and moves it within its containing cell.
• "items" is set on the parent, and sets the default "self" value for all its children.
• "content" is set on the parent, and moves entire rows and columns at once.

This then explains the situations where properties are not available:

• justify-self and justify-items aren't available on any flexboxes, because their cells are always shrink-to-fit in the main axis.
• align-content is only available on multi-line flexboxes (those where flex-wrap is enabled), because single-line flexboxes always use the full cross-axis size.

We don't currently support multi-line flexboxes, but this feature has some good uses, so we might add it in the future. For example, GitHub uses it to display an issue's label list – see this issue for how it wraps when there are many labels.

Without looking at the docs - will `horizontal_align_content = START" move content up, or to the left?

It has to be left, because that's a horizontal direction. That's the advantage the alias has over the CSS name – it makes the direction clear when you're reading the code.

As you say, it doesn't help so much with writing the code for a single-line flexbox, because you still need to remember whether to use "items" or "content". But when you extend it to multi-line flexboxes and grids, you'll have a larger set of properties available, with both "items" and "content" in the same axis. So I don't see any way to make it simpler without losing consistency.

Unlike the other Pack changes I've made recently, I don't think we should necessarily be updating the examples to encourage people to use these aliases, at least not in a single-line flexbox. The main motivation is compatibility with Invent, where the naming issue is more immediate because they've already added grids.

[freakboy3742]

The core of the problem might actually be that we've mapped the wrong properties in Pack. We recently deprecated alignment to map to align-items... but should that actually be align-content? Or... should justify-content actually be justify-items? I've tied myself in knots looking at the MDN pages for these properties...

The mapping is correct, but I agree it seems more complex than necessary in the context of single-line flexboxes. It starts to make more sense when you extend it to multi-line flexboxes and grids. I've added some columns to the table above indicating where each property is supported in CSS.

Ok - I think that's set me straight. I was definitely getting myself tied in knots trying to work out the difference between items and content in particular, given the examples on MDN - and I think it's the lack of a grid layout (and the resultant lack of significance of the justify-items case) that was throwing me.

Without looking at the docs - will `horizontal_align_content = START" move content up, or to the left?

It has to be left, because that's a horizontal direction. That's the advantage the alias has over the CSS name – it makes the direction clear when you're reading the code.

As you say, it doesn't help so much with writing the code for a single-line flexbox, because you still need to remember whether to use "items" or "content". But when you extend it to multi-line flexboxes and grids, you'll have a larger set of properties available, with both "items" and "content" in the same axis. So I don't see any way to make it simpler without losing consistency.

Yeah - my "gotcha" question wasn't well posed. It's obviously "left", because of horizontal. I think I was aiming more for the confusion around whether horizontal_align_content would raise an error or not - because on a column box, it will, and it won't necessarily be obvious why.

However, I agree that there's no way to simplify this any further without introducing ambiguities; and it does remove the need to understand the difference between "alignment" and "justification".

Unlike the other Pack changes I've made recently, I don't think we should necessarily be updating the examples to encourage people to use these aliases, at least not in a single-line flexbox. The main motivation is compatibility with Invent, where the naming issue is more immediate because they've already added grids.

Agreed.