1335106 - Documentation for the CSS Box Alignment properties

Status: RESOLVED WONTFIX

(Developer Documentation Graveyard :: CSS, defect)

Description

[Mats Palmgren (inactive)]

Spawning this off from bug 1235922 comment 53:


> Mats Palmgren (:mats) 2017-01-30 09:43:44 PST

The authoritative spec for all the align-/justify- properties is css-align now.
These properties originated in the flexbox spec and only applied there, but were
later generalized to apply to Grid, Block, Table, and Column layout and thus
were moved into the dedicated spec (css-align) that specifies the behavior for all
layout modes (we only support them in Flexbox and Grid layout so far though).

It seems these properties are not listed at all for Grid:
https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Grid_Layout

'justify-self' is missing (presumably b/c it doesn't apply to Flexbox, but
it does apply to Grid though):
https://developer.mozilla.org/en-US/docs/Web/CSS/justify-self

Also, the 'first baseline' / 'last baseline' values are missing.

I'm not sure how to organize this best in MDN.  I'm guessing the most
convenient for the reader is to list them in each layout mode, but that
means some duplication.  The landing page for each property though, needs
to describe the behavior for all layout modes (or at least the ones we
support).  For example,
https://developer.mozilla.org/en-US/docs/Web/CSS/align-self
talks about flex items and flex lines, which only makes sense for flexbox
layout and would be rather confusing for someone that wants to know what
the property does in a grid layout.

You could also look at how css-align is organized to solve this problem.
It basically describes the behavior using abstract concepts, like "alignment
context / alignment subject", and then documents what a "context" and
"subject" is in each mode.  See for example:
https://drafts.csswg.org/css-align-3/#self-alignment

Comment 1

[Mats Palmgren (inactive)]

I also note that the 'align-self' "Formal Syntax" in MDN is obsolete, compare:
https://developer.mozilla.org/en-US/docs/Web/CSS/align-self#Formal_syntax
with:
https://drafts.csswg.org/css-align-3/#align-self-property
The new <overflow-position>? bit is missing.  And some values are missing.
(ditto for 'align-items' / 'justify-items')

and for 'align-content' / 'justify-content':
https://developer.mozilla.org/en-US/docs/Web/CSS/align-content#Formal_syntax
vs
https://drafts.csswg.org/css-align-3/#content-distribution
The new <overflow-position>? bit is missing.  And some values are missing.
And the <content-position> part is missing.

Comment 2

[Mats Palmgren (inactive)]

FYI, the 'place-content', 'place-self', and 'place-items' shorthand properties
from the same spec are not documented yet. (implemented in bug 1319958)

Comment 3

[Mats Palmgren (inactive)]

The landing page for Flexbox:
https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Flexible_Box_Layout
lists these properties but only references the Flexbox spec.

This is rather unfortunate because the definitions in the Flexbox spec
are obsolete.  We should probably add a link to the css-align spec
there with the text "for the align-content, align-items, ... properties,
see the CSS Box Alignment spec".

Comment 4

[Jean-Yves Perrier [:teoli]]

Hi!

Yes, I think it is time to tackle this problem. We have delayed it as the spec was quite in flux, but with the release of CSS Grids very soon, and work ongoing on bug 1105571, we need to have a coherent and consistent descriptions of these properties. 

If I have well understood the spec, we are speaking about 6 longhands properties, and 3 shorthands: 
- Content distribution: justify-content (LH), align-content (LH), place-content (SH)
- Self alignment: justify-self (LH), align-self (LH), place-self (SH)
- Default alignment: justify-items (LH), align-items (LH), place-items (SH)


We clearly need to:
1) Correct the syntax of the existing ones 
2) Add the missing ones
3) Update the existing ones by separating on the page the behavior for block/flexbox/grids layouts (when different)



Before thinking about how to document these perfectly, I will need to understand some concepts. These are fundamentals concepts, but I just want to be sure that I understand them well. More concretely, I want to be sure to understand correctly the different concepts listed in the 'Applies to' section of each properties.


So here is my understanding:

- flex containers
"A flex container is the box generated by an element with a computed display of flex or inline-flex"
In layman words: Any element's box with display:flex or display: inline-flex

(For: justify-content, align-content, place-content, align-items)


- grid containers
Any element's box with display: grid (a block-level grid container), display: inline-grid (an inline-level grid container), and in the future display: subgrid (that will create a subgrid grid container, that is a special grid container, or a block-level grid container, depending if the element is grid-item or not)

In layman words: Any element's box with display: grid, display: inline-grid [And in the future display: subgrid]

(For: justify-content, align-content, place-content, justify-items, align-items)



- block containers
"A box whose contents participate in a block formatting context. A block container does not necessarily establish a new block formatting context if its parent formatting context is also a block formatting context. " [CSS Display 3, linked for CSS Box Align 3]

In layman words: everything that contains blocks 
[That is any element with display:block, inline-block, table-cell, table-caption, flow-root, as well as any element with a float different than none, any element with  position: static or position: fixed), or any element with an overflow value that is not 'visible']
I think grid and flex containers are technically block containers too, but this is not important in our case here (as they are singled out)

(For: justify-content, align-content, place-content)

- flex items
"In-flow children of a flex container are called flex items and are laid out using the flex layout model."

In layman words: every children of a flex container that is not absolutely positioned, or floated.

(For: align-self)

- grid items
"Loosely speaking, the grid items of a grid container are boxes representing its in-flow contents: each in-flow child of a grid container becomes a grid item."

In layman words: every children of a grid container that is not absolutely positioned or floated.
(As far as I underdant, this simplified definition doesn't account for subgrid items, while the official definition does).

(For: justify-self, align-self)


- block-level elements
"Block-level elements are those elements of the source document that are formatted visually as blocks (e.g., paragraphs). The following values of the 'display' property make an element block-level: 'block', 'list-item', and 'table'."

In layman words: every element that has display:block, display:list-item, or display:table.

(For: justify-self)


Is my understand correct? If so, I think we need glossaries entries to describe this terminology so that we can link the articles to them.

Comment 5

[Mats Palmgren (inactive)]

(In reply to Jean-Yves Perrier [:teoli] from comment #4)
> If I have well understood the spec, we are speaking about 6 longhands
> properties, and 3 shorthands: 

Correct, there is a Property Index at the end (most CSS specs have it):
https://drafts.csswg.org/css-align-3/#property-index

> "A flex container is the box generated by an element with a computed display
> of flex or inline-flex"
> In layman words: Any element's box with display:flex or display: inline-flex

Correct.

> In layman words: Any element's box with display: grid, display: inline-grid
> [And in the future display: subgrid]

Correct, but I think you can forget subgrid exists in this first round
of documentation.  No browser implements it yet, and the spec is very
likely to change.

> (For: justify-content, align-content, place-content, justify-items,
> align-items)

and place-items.  IOW, all properties except align/justify-self.

> In layman words: everything that contains blocks 
> [That is any element with display:block, inline-block, table-cell,
> table-caption, flow-root, as well as any element with a float different than
> none, any element with  position: static or position: fixed), or any element
> with an overflow value that is not 'visible']

Yes, but note that "Absolutely-Positioned Boxes" have special rules
in some places in css-align.
Also, it's probably a good idea to not to get to deep into what
a "block container" is on MDN and instead link to the specs.  E.g.
https://drafts.csswg.org/css-display/#propdef-display
https://drafts.csswg.org/css-display/#block-container
I suspect most web deveopers knows the concept.

> I think grid and flex containers are technically block containers too, but
> this is not important in our case here (as they are singled out)

No, not really.  They are block-level boxes if they have display:grid/flex
or inline-level boxes if they have display:inline-grid/inline-flex which
means they'll layout as "blocks" or "inlines" in a block formatting context.
"block container" however refers to the interior of the box, and a grid
container establishes a "grid formatting context" for its contents, and
grid items are "grid-level" boxes.
https://drafts.csswg.org/css-grid/#grid-level
https://drafts.csswg.org/css-grid/#grid-formatting-context
Compare "block container" / "block formatting context" / "block-level" boxes,
vs "grid container" / "grid formatting context" / "grid-level" boxes.

> - flex items
> "In-flow children of a flex container are called flex items and are laid out
> using the flex layout model."
> 
> In layman words: every children of a flex container that is not absolutely
> positioned, or floated.

The 'float' property is ignored for flex and grid items.  So it's all children
that isn't absolutely positioned.

> - grid items
> "Loosely speaking, the grid items of a grid container are boxes representing
> its in-flow contents: each in-flow child of a grid container becomes a grid
> item."
> 
> In layman words: every children of a grid container that is not absolutely
> positioned or floated.

Ditto.  (The rules for flex/grid are exactly the same here.)

> (As far as I underdant, this simplified definition doesn't account for
> subgrid items, while the official definition does).

A subgrid is also a grid item in itself, but for css-align documentation
purposes I think we can just leave it out completely for now.

> - block-level elements
> "Block-level elements are those elements of the source document that are
> formatted visually as blocks (e.g., paragraphs). The following values of the
> 'display' property make an element block-level: 'block', 'list-item', and
> 'table'."
> 
> In layman words: every element that has display:block, display:list-item, or
> display:table.

Also display:grid, display:flex when they are inside a block formatting context.
"block-level" refers to how the box behaves externally, in the context its
parent establish.  E.g. a display:grid box can also be a grid-level box if its
parent is another grid container, or it can be a flex-level box if its parent
is a flex container (which establish a flex formatting context).
https://drafts.csswg.org/css-flexbox/#flex-containers

So, loosely, the *-self properties specifies how the box should align inside
its surrounding alignment context (e.g. in a row, a line etc).  The *-items are
simply a placeholder value for items that have *-self:auto.  It's a way
for a container to conveniently specify a default *-self value for all items
that doesn't explicitly set it.  *-content specifies how a container's content
should be distributed inside it (e.g. if the rows in a grid doesn't fill its
block-size, should they stack at the start or be evenly distributed etc).

Comment 6

[Mats Palmgren (inactive)]

> Yes, but note that "Absolutely-Positioned Boxes" have special rules
> in some places in css-align.

E.g. https://drafts.csswg.org/css-align-3/#justify-abspos

Comment 7

[Mats Palmgren (inactive)]

I should I have said "alignment container" instead of "alignment context" above.

The key concepts with which css-align describes the behavior abstractly is
"alignment container" and "alignment subject".  Then it says what these are
for each type of box, e.g. *-self for a grid item it's the grid area
and the item's margin-box:
https://drafts.csswg.org/css-align-3/#justify-grid
https://drafts.csswg.org/css-align-3/#align-grid

for *-content it's the tracks (rows and columns) inside the grid container's
content-box:
https://drafts.csswg.org/css-align-3/#distribution-grid

Comment 8

[Rachel Andrew]

I've now documented a lot of these as part of the Grid, Flexbox, Box Alignment docs I've been writing, would be very happy to make any additions people think are missing, and we have also been splitting up the browser support data to make it more clear when alignment is implemented in which contexts.

It would possibly be easier to create individual bugs for places where things are still strange, as I think the general direction of this issue is what we have been working to over the last few months, but there are definitely things that will fall out of that.

Comment 9

[BMO Automation]

MDN Web Docs' bug reporting has now moved to GitHub. From now on, please file content bugs at https://github.com/mdn/sprints/issues/ and platform bugs at https://github.com/mdn/kuma/issues/.