[css3-flexbox] Editorial comments on ED 2012-04-20

Hi,

Here are some editorial comments on the current Editor's Draft (2012-04-20).

Issue 1:

Section 2 (The Flexbox Box Model) says:

   # The axis perpendicular to the main axis is called the cross axis,
   # and similarly has cross-start and cross-end directions and sides
   # defined. The width or height of a flexbox item, whichever is in the
   # cross axis, is the item's cross size, and similarly the cross size
   # property is whichever of ‘width’ or ‘height’ that is in the cross
   # axis.

The previous paragraph (concerning the main axis) doesn't mention the 
direction of the axis.  Either the mention of "directions" should be 
removed from the current paragraph, or else it should be mentioned in 
the previous one as well; and the mentions should be linked to 6.1 and 6.2.


Issue 2:

Section 3 (New values for ‘display’ property) says:

   # You can declare that an element is a flexbox, and thus should use
   # flexbox layout for its contents, by setting the ‘display’ property
   # on the element to the value ‘flexbox’ or ‘inline-flexbox’.

[...]

   # If an element's specified value for ‘display’ is ‘inline-flexbox’
   # and the element is floated or absolutely positioned, the computed
   # value of ‘display’ must be ‘flexbox’.

whilst Section 4 (Flexbox Items) says:

   # The computed value for ‘display’ for elements that are flexbox
   # items must be determined by applying the table in CSS 2.1 Chapter
   # 9.7.

Dodgy use of 'can', 'should' and 'must'.  It's probably best to rewrite 
the first paragraph as

   | Setting the ... declares an element to be a ... and thus flexbox
   | layout is used ...

and simply do s/must be/is/ in the second and third paragraphs.


Issue 3:

Section 3 (New values for ‘display’ property) says:

   # * ‘float’ and ‘clear’ have no effect on a flexbox item. Using
   #   ‘float’ on an element still causes that element's ‘display’
   #   property to compute to ‘block’, as normal, because that occurs
   #   before flexbox items are determined (the algorithm for wrapping
   #   children of a flexbox into flexbox items needs the computed value
   #   of ‘display’).

"wrapping children of a flexbox into flexbox items" is a bit wooly.  I 
suggest removing the parenthetical entirely.

Also, "as normal" should reference CSS21 9.7.


Issue 4:

Section 4 (New values for ‘display’ property) says:

   # * ‘vertical-align’ has no effect on the alignment of a flexbox item
   #   in the flexbox

I'm in two minds about this but I'd be tempted to remove this item. 
There's no /technical/ expectation that 'vertical-align' would have the 
effect described.  Since there may exist an author expectation, perhaps 
it could be a Note instead.


Issue 5:

Section 4 (New values for ‘display’ property) says:

   # A flexbox establishes a new flexbox formatting context for its
   # contents. This is similar to a block formatting context root:
   # floats do not intrude into the flexbox, and the flexbox's margins
   # do not collapse with the margins of its contents. Additionally,
   # each of the flexbox items establishes a new formatting context for
   # its contents.

There seems to be something grammatically amiss here.  There's a context 
and a context root; the two things are distinct and can't be compared.

I suggest:
s/contents. This is/contents,/


Issue 6:

Regarding the above paragraph from Section 4, is there narrowing of a 
flexbox next to floats, similar to narrowing of BFC roots?


Issue 7:

Regarding the above paragraph from Section 4, it's implicit from the 
alignment properties that flexbox items don't collapse their vertical 
margins with other items, but that isn't covered by the paragraph.  I 
think it's worth mentioning at that point.


Issue 8:

Section 4 (New values for ‘display’ property) says:

   # The baseline of a flexbox is:
   #
   # * If [...], the flexbox's baseline is [...]
   # [...]

s/The baseline of a flexbox is:/The baseline of a flexbox is determined 
as follows./


Issue 9:

Section 4 (Flexbox Items) says:

   # The flexbox layout algorithm operates on boxes generated by flexbox
   # items, which are elements that satisfy one of the following
   # criteria:
   #
   # [...]
   # 3. Contiguous run of non-replaced inline children, wrapped into an
   #    anonymous block element. [...]
   #
   # [...] This fixup must occur before a flexbox's contents are checked
   # to see if it's necessary to generate anonymous flexbox items.

Flexbox items are not elements, they are (possibly anonymous) boxes. 
Indeed, there's no such thing as an anonymous element.  Although this is 
an editorial hassle to get right in all the CSS3 specs, I think we 
should try hard not to perpetuate the chaos from CSS21!

(This is related to 
http://lists.w3.org/Archives/Public/www-style/2012Apr/0172.html .)


Issue 10:

A note in Section 4 (Flexbox Items) says:

   # In the future, other kinds of fixup such as ‘display:run-in’ or
   # ‘display:ruby’ should also run before flexbox fixup.

"In the future" is strange wording for a spec.  I think this needs to be 
somewhat more formal, along the lines of "Other CSS specifications may 
introduce ...".


Issue 11:

Section 4 (Flexbox Items) says:

   # Example 2
   #
   # [...]
   #
   # <!-- flexbox item: anonymous table wrapped around table-cell -->
   # <div id="item4" style="display:table-cell">table-cell</div>

Actually, the flexbox item in this case is the anonymous table /wrapper/ 
that's wrapped around the anonymous table that's wrapped around the 
anonymous table-row etc etc.


Issue 12:

Section 4 (Flexbox Items) says:

   # Example 2
   #
   # [...]
   #
   # <!-- not a flexbox item, because it's out-of-flow -->
   # <!-- however, an anonymous flexbox item is wrapped around
   #      the placeholder it leaves behind-->
   # <div id="not-an-item2" style="position: absolute;">block</div>
   #
   # [...]
   #
   # <!-- flexbox item: anonymous block around inline content -->
   # anonymous item 7.1
   # <span id="item7.1">
   #     text 7.2
   #     <div id="not-an-item7.3">block</div>
   #     text 7.4
   # </span>
   #
   # [...]
   #
   # Notice that block element "not-an-item7.3" is not a separate
   # flexbox item, because it is contained inside an inline element
   # which is being wrapped into an anonymous flexbox item. Similarly,
   # the block element "not-an-item2" is not a flexbox item, because
   # it's absolutely positioned and thus out of flow.

I would simply say that "not-an-item7.3" is not a separate flexbox item 
because it's not a child of the flexbox element.

Also, the fact that "not-an-item2" is out-of-flow is not the reason why 
it's not a flexbox item, so the prose is misleading.  Rather, the reason 
is that abspos children of flexbox are handled in a special way.  I 
would change the sentence to say "... because absolutely positioned 
elements have special treatment" (linking to 4.1), and modify the HTML 
comment by replacing
   # <!-- not a flexbox item, because it's out-of-flow -->
with
   | <!-- not a flexbox item -->


Issue 13:

Section 4 (Flexbox Items) says:

   # The computed value for ‘display’ for elements that are flexbox
   # items must be determined by applying the table in CSS 2.1 Chapter
   # 9.7.

So flexbox items are always block-level?  I think this is well worth 
stating, possibly as a Note.


Issue 14:

4.1 (Absolutely Positioned Flexbox Children) says:

   # Absolutely positioned children of a flexbox are not flexbox items,
   # but they leave behind "placeholders" in their normal position in
   # the box tree. These placeholders are anonymous inline boxes with a
   # width and height of ‘0px’, and they interact normally with the
   # flexbox layout algorithm. In particular, they'll trigger the
   # creation an anonymous flexbox item wrapper boxes, or join
   # neighboring inline elements in their anonymous flexbox item wrapper
   # boxes.

A height of 0px on the placeholder is meaningless because 'height' 
doesn't apply to non-replaced inline boxes.  I think you mean 
'line-height:0'.

[I believe that Alex questioned the use of 'height:0px' too, on the 
mailing list somewhere; but I can't find it now :-/.  No conclusion was 
reached.]


Issue 15:

Observation: I dislike that abspos children leave placeholders behind; 
but I sympathize that it's really hard to spec static position 
accurately without them.


Issue 16:

Section 5 (Multi-line Flexbox) says:

   # A flexbox can be either single-line or multi-line, depending on the
   #  ‘flex-wrap’ property. A single-line flexbox lays out all of its
   # children in a single line, even if that would cause the flexbox to
   # overflow its bounds. A multi-line flexbox breaks its flexbox items
   # across multiple lines to avoid overflowing, similar to how text is
   # broken onto a new line when it gets too wide to fit on the existing
   # line. Every line contains at least one flexbox item, unless the
   # flexbox itself is completely empty.

Does "bounds" mean "containing block"?  Actually, it's not explicit how 
overflow works for flexbox.  In a single-line flexbox, does the line 
overflow the flexbox, or does the flexbox overflow its containing box?

Also, s/avoid/attempt to avoid/ since overflow can still happen in some 
situations (eg if there is a single wide flexbox item).

Does an empty flexbox contain a line?


Issue 17:

Section 5 discusses how there's a difference between a single-line 
flexbox and a multi-line flexbox with one line: the cross size of its 
line is different.  I think the consequences of this difference are 
accounted for the by the alignment properties (and there are no 
gotchas), but it's worth a moment's thought.


Issue 18:

Example 3 in Section 5 discusses an example involving buttons with 
borders.  Unfortunately the border widths aren't taken into account in 
the calculations given.  This is largely because it's tedious and 
distracting to do so, but still...


Issue 19:

Example 3 in Section 5 says:

   # If the box was resized, the buttons may rearrange onto different
   # lines as necessary.

s/was/were/


Issue 20:

Section 6 (Ordering and Orientation) says:

   # The first level of flexbox functionality is the ability to lay out
   # a flexbox's contents in any direction and in any order. This allows
   # an author to trivially achieve effects that would previously have
   # required complex or fragile methods, such as using the ‘float’
   # property to lay out a horizontal navigation bar (which then
   # requires further effort with the ‘clear’ property or others to make
   # the elements interact nicely with the rest of the page). This
   # functionality is exposed through the ‘flex-direction’, ‘flex-wrap’,
   # and ‘flex-order’ properties.

It's not clear what this "first level" is referring to.  (I assume it 
means the first flexbox spec, ie css3-flexbox.)  I suggest rewriting 
this sentence.

I don't think it's necessary to get bogged down in the navbar example. 
Just refer to "using the 'float' property for complex layout".


Issue 21:

Example 5 in Section 6.4 (Display Order: the ‘flex-order’ property) 
describes a tabbed interface in which tab three has been moved to become 
the leftmost of four tabs.  This is a strange example!  For me, the 
typical author expectation is that tab three is brought forward visually 
but doesn't change position.  Perhaps there exists a more natural use 
case that could be presented instead.


Issue 22:

Example 5 in Section 6.4 (Display Order: the ‘flex-order’ property) says:

   # As an added bonus, the columns will all be equal-height by default,
   # [...]

I suggest linking "equal-height by default" to Section 8.2, since the 
behaviour in question hasn't been introduced yet.


Issue 23:

Section 7 (Flexibility: the ‘flex’ property) says:

   # The defining aspect of flexbox layout is the ability to make the
   # flexbox items "flex", altering their width or height to fill the
   # available space. This is done by using a ‘flex’ property. A flexbox
   # distributes free space to its items proportional to their positive
   # flexibility, or shrinks them to prevent overflow proportional to
   # their negative flexibility.

I'm not sure about "defining aspect"; after all, flexbox can be used 
quite productively without flex.

Also, s/a ‘flex’ property/the ‘flex’ property/


Issue 24:

Section 7 (Flexibility: the ‘flex’ property) says:

   # The ‘flex’ property specifies the parameters of a flexible length:
   # the positive and negative flexibility, and the preferred size. When
   # the element containing ‘flex’ is a flexbox item, ‘flex’ is
   # consulted instead of the main size property to determine the main
   # size of the element. If an element is not a flexbox item, ‘flex’
   # has no effect.

"When the element containing 'flex'" is wooly; it needs rewriting.


Issue 25:

Section 7 does not clearly define what "positive flexibility", "negative 
flexibility" and "preferred size" mean and do.  I think the first two 
are covered by the paragraph prior to the property definition where it 
talks about proportionality, but I would be tempted to move part of that 
paragraph to the part after the property definition.

I think the third one is covered by the paragraph quoted in Issue 24 
above, but if so then it should say that _the preferred size specified 
by_ ‘flex’ is consulted [...].  I also think the sentence in question 
should be moved to the third paragraph after the property definition 
where the <preferred-size? component is being discussed.


Issue 26:

Section 7 (Flexibility: the ‘flex’ property) says:

   # The <preferred-size> component sets the preferred size. It can be
   # set to any value that would be valid in the ‘width’ or ‘height’
   # property, except values that are not applicable to a component
   # value (of values defined in CSS2.1, only ‘inherit’ is not valid for
   # <preferred-size>; in the future other values may be introduced that
   # are not applicable as length component). [...]

I can't make much sense of the sentence with the parenthetical, because 
I think there's a grammatical bug!  Perhaps the parenthetical is really 
a separate sentence, in which case it should begin "Of the values ...".


Issue 27:

Section 7 (Flexibility: the ‘flex’ property) says:

   # [...] If omitted, the preferred size defaults to ‘0px’. If the
   # <preferred-size> component is ‘auto’ on a child of a flexbox, the
   # preferred size is the main size property's value.

I think it would assist the reader if there were a Note explaining the 
reason why preferred size defaults to '0px'.


Issue 28:

Example 7 in Section 7 says:

   # Here, all four paragraphs have a preferred size equal to the length
   # of their text. The leftover space (after subtracting their
   # preferred sizes and margins from the width of the flexbox) is
   # distributed evenly to the four paragraphs. [...]

I would add a clause to the last quoted sentence explaining the reason 
why the space is evenly distributed: namely that the positive 
flexibility component of the 'flex' property is 1 for each flexbox item.


Issue 29:

Section 8.1 (Axis Alignment: the ‘flex-pack’ property) says:

   # The ‘flex-pack’ property aligns flexbox items in the main axis of
   # the current line of the flexbox. This is done after any flexible
   # lengths and any auto margins have been resolved. [...]

I suggest linking "auto margins have been resolved" to 8.3.


Issue 30:

Section 8.2 (Cross Axis Alignment: the ‘flex-align’ and 
‘flex-item-align’ properties) says:

   # center
   #   The flexbox item's margin box is centered in the cross axis
   #   within the line. (If the cross size of the flexbox is less than
   #   that of the flexbox item, it will overflow equally in both
   #   directions.)

The parenthetical is false for multi-line flexboxes.  It should be 
talking about overflowing the line, not the flexbox.


Issue 31:

Section 8.2 (Cross Axis Alignment: the ‘flex-align’ and 
‘flex-item-align’ properties) says:

   # stretch
   #   If the cross size property of the flexbox item is ‘auto’, it
   #   resolves to the length necessary to make the cross size of the
   #   item's margin box the same size as the line, while still
   #   respecting ‘min/max-width/height’ constraints as normal.

s/it resolves to/the used value is/
(assuming that that's what's intended).


Issue 32:

Regarding the quoted paragraph above, I don't know what "while still 
respecting ‘min/max-width/height’ constraints as normal" is getting at, 
exactly.  I think some clarification is needed.


Issue 33:

Regarding the quoted paragraph above, I think there's an issue with 
overflow being unclear.  (cf. Issue 16.)  What happens when the line is 
not tall enough?  Does the flexbox item still end up being clamped to 
the line, and then its content overflows (as opposed to the flexbox item 
itself overflowing)?



Note that I deliberately haven't reviewed the algorithm in Section 9 
yet, since I feel that the spec should make solid sense without needing 
that algorithm and so I wanted to review it without spoilers.  (It seems 
pretty close :-)  I've review the algorithm shortly.


Cheers,
Anton Prowse
http://dev.moonhenge.net

Received on Monday, 23 April 2012 09:37:15 UTC