Overview.bs

<pre class='metadata'>
Title: CSS Flexible Box Layout Module Level 2
Shortname: css-flexbox
Level: 2
Status: ED
Work Status: Exploring
Group: csswg
ED: https://drafts.csswg.org/css-flexbox-2/
Abstract: The specification describes a CSS box model optimized for user interface design. In the flex layout model, the children of a flex container can be laid out in any direction, and can “flex” their sizes, either growing to fill unused space or shrinking to avoid overflowing the parent. Both horizontal and vertical alignment of the children can be easily manipulated. Nesting of these boxes (horizontal inside vertical, or vertical inside horizontal) can be used to build layouts in two dimensions.
Editor: Tab Atkins Jr., Google, http://xanthir.com/contact/, w3cid 42199
Editor: Elika J. Etemad / fantasai, Apple, http://fantasai.inkedblade.net/contact, w3cid 35400
Editor: Rossen Atanassov, Microsoft, ratan@microsoft.com, w3cid 49885
</pre>

<h2 id="intro">
Introduction</h2>

	<em>This section is not normative.</em>

	This module is currently a diff spec over [[CSS-FLEXBOX-1]].
	It defines a new flex wrapping mode, ''flex-wrap: balance'',
	which attempts to find linebreak locations
	which make the size of each flex line
	as similar as possible.

<h2 id='flow-order'>
Ordering and Orientation</h2>

...

<h3 id='flex-wrap-property'>
Flex Line Wrapping: the 'flex-wrap' property</h3>

	<pre class='propdef'>
	Name: flex-wrap
	Value: nowrap | [ wrap | wrap-reverse ] || balance
	Initial: nowrap
	Applies to: <a>flex containers</a>
	Inherited: no
	Computed value: specified keyword
	Animation type: discrete
	</pre>

	The 'flex-wrap' property controls whether the flex container is <a>single-line</a> or <a>multi-line</a>,
	and the direction of the <a>cross-axis</a>,
	which determines the direction new lines are stacked in.

	<dl dfn-type=value dfn-for=flex-wrap>
		<dt><dfn>nowrap</dfn>
		<dd>
			The flex container is <a>single-line</a>.

		<dt><dfn>wrap</dfn>
		<dd>
			The flex container is <a>multi-line</a>.

		<dt><dfn>wrap-reverse</dfn>
		<dd>
			The flex container is [=multi-line=],
			but the lines are stacked "in reverse" (see below).

		<dt><dfn>balance</dfn>
		<dd>
			The flex container is [=multi-line=],
			and attempts to "balance" the lengths of the [=flex lines=]
			to be as similar as possible.
			See [[#flex-balance=]].

			''balance'' can be combined with ''wrap'' or ''wrap-reverse''
			to dictate which direction the [=flex lines=] are stacked in.
			If neither are specified,
			it behaves as if ''wrap'' was specified.
	</dl>

	By default, the [=cross-start=] direction of the [=flex container=]
	is either the <a>inline-start</a> or <a>block-start</a> direction
	of the [=flex container's=] <a>writing mode</a>
	(whichever is in the <a>cross axis</a>)
	and the <a>cross-end</a> direction is the opposite direction of <a>cross-start</a>.
	If ''wrap-reverse'' is specified,
	the <a>cross-start</a> and <a>cross-end</a> directions
	are swapped.

	Note: Depending on the value of 'align-content',
	the ''wrap-reverse'' value of 'flex-wrap' can alter the initial scroll position
	on [=flex containers=] that are also [=scroll containers=].
	See [[css-align-3#overflow-scroll-position]].


<h2 id='flex-lines'>
Flex Lines</h2>

...

<h3 id='flex-line-count-property'>
Minimum Flex Lines: the 'flex-line-count' property</h3>

	<pre class='propdef'>
	Name: flex-line-count
	Value: <<integer [1, infinity]>>
	Initial: 1
	Applies to: [=multi-line=] [=flex containers=]
	Inherited: no
	Computed value: the specified integer, computed
	Animation type: as integer
	</pre>

	By default, a ''balance'' flexbox
	will create as many lines as a normal [=multi-line=] flexbox,
	then rebalance how the flex items are assigned across that many lines.
	In some situations,
	an author might want to ensure there are always a certain number of lines,
	or might be using a flexbox in a way where there is no limit to the line length
	(the standard for a [=column flexbox=])
	and so the "default" line number calculation is useless.
	The 'flex-line-count' property specifies a minimum number of [=flex lines=]
	that the [=flex container=] should create
	to balance the items across.

	If the [=flex container=] has less [=flex items=] than the 'flex-line-count' value,
	it will only create as many lines as there are [=flex items=].
	If the [=flex lines=] are limited in length
	and the [=flex items=] will fill more than the specified number of lines,
	the actual [=flex line=] count can be higher than what is specified.

	Unused lines (ones with no [=flex items=] assigned to them)
	are discarded and do not affect layout.
	<span class=note>This only affects non-''balance'' flexboxes.
	A ''balance'' flexbox will always assign at least one [=flex item=] to each line,
	and if it has less items than 'flex-line-count',
	that's handled specially, above.</span>

	In addition to setting a minimum number of lines that are used by ''balance'',
	'flex-line-count' changes the [=available space=] in the [=cross axis=] for [=flex items=]:
	subtracting the size of N-1 gaps from the normal [=available space=],
	then dividing the leftover by N,
	where N is the 'flex-line-count' value.
	This uses the actual 'flex-line-count' value,
	not the number of lines produced
	(which can be higher or lower than what is specified).

	Note: This [=available space=] adjustment is the only effect 'flex-line-count' has
	on non-''balance'' flexboxes.

	Percentages continue to resolve as normal,
	unaffected by this [=available space=] adjustment.
	(To have a [=flex item=] fill the [=cross-axis=] [=available space=],
	use ''width/height: stretch''.)

	If the [=flex container=] is [=single-line=]
	(aka, ''flex-wrap: nowrap''),
	this property has no effect.

<h2 id=layout-algorithm>
Flex Layout Algorithm</h2>

...

<div class=issues>

	TODO fill in the details of how balancing works.

	In short, do flex layout up to the linebreaking part.
	Linebreak as normal
	(but with the floor-at-0 thing, below)
	to discover how many lines are needed;
	if 'flex-line-count' is higher
	(and there are at least that many flex items),
	use that line count instead.

	Then do balanced line-breaking,
	using a well-known algorithm I forget the name of right this moment.

	For the purpose of the balancing algorithm,
	hypothetical sizes are floored at 0,
	so it can be done efficiently.
	(Negative margins can make the hypothetical size negative,
	which <em>does</em> affect line-breaking.)
</div>