Rewrite of flex-align.

Author: tabatkins

css3-flexbox/Overview.html

@@ -16,12 +16,12 @@
 
    <h1 id=head-box-flexible>CSS Flexible Box Layout Module</h1>
 
-   <h2 class="no-num no-toc" id=w3c-working>Editor's Draft, 25 August 2011</h2>
+   <h2 class="no-num no-toc" id=w3c-working>Editor's Draft, 27 August 2011</h2>
 
    <dl>
     <dt>This version:
 
-    <dd><!-- <a href="http://www.w3.org/TR/2011/WD-css3-flexbox-20110825/">http://www.w3.org/TR/2011/WD-css3-flexbox-20110825/</a></dd> -->
+    <dd><!-- <a href="http://www.w3.org/TR/2011/WD-css3-flexbox-20110827/">http://www.w3.org/TR/2011/WD-css3-flexbox-20110827/</a></dd> -->
      <a
      href="http://dev.w3.org/csswg/css3-flexbox/">http://dev.w3.org/csswg/css3-flexbox/</a>
 
@@ -281,7 +281,12 @@ <h2 id=box-model><span class=secno>2. </span> The Flexbox Box Model</h2>
    side of the flexbox, and go toward the <dfn id=main-end>main-end</dfn>
    side. A <a href="#flexbox-item"><i>flexbox item's</i></a> width or height,
    whichever is in the <a href="#main-axis"><i>main axis</i></a>, is the
-   item's <dfn id=main-size>main size</dfn>. These terms are mapped to
+   item's <dfn id=main-size>main size</dfn>. The <a
+   href="#flexbox-item"><i>flexbox item's</i></a> &lsquo;<code
+   class=property>width</code>&rsquo; or &lsquo;<code
+   class=property>height</code>&rsquo; property, specifically, that is in the
+   <a href="#main-axis"><i>main axis</i></a> is the item's <dfn
+   id=main-size-property>main size property</dfn>. These terms are mapped to
    physical directions based on the first keyword in the &lsquo;<a
    href="#flex-flow0"><code class=property>flex-flow</code></a>&rsquo;
    property.
@@ -292,11 +297,15 @@ <h2 id=box-model><span class=secno>2. </span> The Flexbox Box Model</h2>
    directions and sides defined. The width or height of a <a
    href="#flexbox-item"><i>flexbox item</i></a>, whichever is in the <a
    href="#cross-axis"><i>cross axis</i></a>, is the item's <dfn
-   id=cross-size>cross size</dfn>. These terms are mapped to physical
-   directions based on the orientation of the <a href="#main-axis"><i>main
-   axis</i></a> and the second keyword in the &lsquo;<a
-   href="#flex-flow0"><code class=property>flex-flow</code></a>&rsquo;
-   property.
+   id=cross-size>cross size</dfn>, and similarly the actual &lsquo;<code
+   class=property>width</code>&rsquo; or &lsquo;<code
+   class=property>height</code>&rsquo; property, whichever is in the <a
+   href="#cross-axis"><i>cross axis</i></a>, is the item's <dfn
+   id=cross-size-property>cross size property</dfn>. These terms are mapped
+   to physical directions based on the orientation of the <a
+   href="#main-axis"><i>main axis</i></a> and the second keyword in the
+   &lsquo;<a href="#flex-flow0"><code
+   class=property>flex-flow</code></a>&rsquo; property.
 
   <p>The contents of a flexbox can be easily and powerfully manipulated with
    a handful of properties. Most significantly, <a
@@ -1109,12 +1118,12 @@ <h3 id=flex-pack><span class=secno>5.1. </span> Main Axis Alignment: the
 
   <p>Between and around <a href="#flexbox-item"><i>flexbox items</i></a>
    there are additional flexible lengths called <dfn id=packing-space
-   title="packing space|packing spaces">packing spaces</dfn>. <a
-   href="#packing-space"><i>Packing spaces</i></a> can absorb leftover free
-   space in a flexbox line if there aren't any other <a
-   href="#flexible-length0"><i>flexible lengths</i></a>, or if all the <a
-   href="#flexible-length0"><i>flexible lengths</i></a> have reached their
-   maximum size. The &lsquo;<a href="#flex-pack0"><code
+   title="packing space|packing spaces">packing spaces</dfn>. After the
+   flexbox items have a chance <a href="#packing-space"><i>Packing
+   spaces</i></a> can absorb leftover free space in a flexbox line if there
+   aren't any other <a href="#flexible-length0"><i>flexible lengths</i></a>,
+   or if all the <a href="#flexible-length0"><i>flexible lengths</i></a> have
+   reached their maximum size. The &lsquo;<a href="#flex-pack0"><code
    class=property>flex-pack</code></a>&rsquo; property defines the
    flexibility of <a href="#packing-space"><i>packing spaces</i></a>:
 
@@ -1185,7 +1194,7 @@ <h3 id=flex-align><span class=secno>5.2. </span> Cross Axis Alignment: the
     <tr>
      <th>Value:
 
-     <td>before | after | middle | stretch | baseline
+     <td>start | end | center | baseline | stretch
 
     <tr>
      <th>Initial:
@@ -1195,7 +1204,7 @@ <h3 id=flex-align><span class=secno>5.2. </span> Cross Axis Alignment: the
     <tr>
      <th>Applies to:
 
-     <td>flexbox items
+     <td><a href="#flexbox-item"><i>flexbox items</i></a>
 
     <tr>
      <th>Inherited:
@@ -1213,216 +1222,92 @@ <h3 id=flex-align><span class=secno>5.2. </span> Cross Axis Alignment: the
      <td>visual
   </table>
 
-  <p>When the size of the containing box along <a href="#cross-axis"><i>cross
-   axis</i></a> is larger than the size of a child, extra space will be
-   available. The &lsquo;<a href="#flex-align0"><code
-   class=property>flex-align</code></a>&rsquo; property specifies how flexbox
-   item is placed along the <a href="#cross-axis"><i>cross axis</i></a>, and
-   where the extra space, if any, is positioned.
-
-  <p>The values of this property have the following meanings. See text for
-   more specifics as to how children are positioned.
+  <p>The &lsquo;<a href="#flex-align0"><code
+   class=property>flex-align</code></a>&rsquo; property aligns <a
+   href="#flexbox-item"><i>flexbox items</i></a> within the current line of
+   the flexbox &mdash; essentially the same thing as &lsquo;<a
+   href="#flex-pack0"><code class=property>flex-pack</code></a>&rsquo;, only
+   in the <a href="#cross-axis"><i>cross axis</i></a>.
 
   <dl>
    <dt><dfn id=flex-align-before>before</dfn>
 
-   <dd>The &lsquo;<a href="#flex-line-pack-before"><code
-    class=property>before</code></a>&rsquo; edge of the child box along <a
-    href="#cross-axis"><i>cross axis</i></a>is aligned with &lsquo;<a
-    href="#flex-line-pack-before"><code
-    class=property>before</code></a>&rsquo; edge of the flexbox content box.
-    See text for explanation of how direction of <a
-    href="#cross-axis"><i>cross axis</i></a> is determined.
+   <dd>The <a href="#cross-start"><i>cross-start</i></a> margin edge of the
+    <a href="#flexbox-item"><i>flexbox item</i></a> is placed flush with the
+    <a href="#cross-start"><i>cross-start</i></a> edge of the line.
 
    <dt><dfn id=flex-align-after>after</dfn>
 
-   <dd>The &lsquo;<a href="#flex-line-pack-after"><code
-    class=property>after</code></a>&rsquo; edge of the child box along <a
-    href="#cross-axis"><i>cross axis</i></a>is aligned with &lsquo;<a
-    href="#flex-line-pack-after"><code class=property>after</code></a>&rsquo;
-    edge of the flexbox content box. See text for explanation of how
-    direction of <a href="#cross-axis"><i>cross axis</i></a> is determined.
+   <dd>The <a href="#cross-end"><i>cross-end</i></a> margin edge of the <a
+    href="#flexbox-item"><i>flexbox item</i></a> is placed flush with the <a
+    href="#cross-end"><i>cross-end</i></a> edge of the line.
 
    <dt><dfn id=flex-align-middle>middle</dfn>
 
-   <dd>Any extra space along the <a href="#cross-axis"><i>cross axis</i></a>
-    is divided evenly, with half placed before the child and the other half
-    placed after the child.
+   <dd>The <a href="#flexbox-item"><i>flexbox item's</i></a> margin box is
+    centered in the <a href="#cross-axis"><i>cross axis</i></a> within the
+    line.
 
    <dt><dfn id=flex-align-baseline>baseline</dfn>
 
    <dd>
-    <p>If this child's inline axis is parallel to <a
-     href="#main-axis"><i>main axis</i></a> of the flexbox, the baseline of
-     the child box is aligned with baselined of all other child boxes that
-     meet the same criteria. Baseline of each child box is determined in the
-     same way as when it is placed inline (as inline-block, inline-table,
-     etc.).</p>
-
-    <p>The children participating in baseline alignment, once aligned on
-     their baselines, should then be placed into the box so that the child
-     with the earliest extent margin has its &lsquo;<a
-     href="#flex-line-pack-before"><code
-     class=property>before</code></a>&rsquo; margin edge flush with the
-     &lsquo;<a href="#flex-line-pack-before"><code
-     class=property>before</code></a>&rsquo; edge of flexbox's content area.
-     If the flexbox does not have an &lsquo;<code
-     class=css>auto</code>&rsquo; height, overflow will always be on the
-     &lsquo;<a href="#flex-line-pack-after"><code
-     class=property>after</code></a>&rsquo; edge.
-
-    <p>If the child box <i>inline axis</i> is orthogonal to flexbox <a
-     href="#main-axis"><i>main axis</i></a>, then &lsquo;<a
-     href="#flex-align-baseline"><code class=css>baseline</code></a>&rsquo;
-     acts identically to &lsquo;<a href="#flex-pack-center"><code
-     class=css>center</code></a>&rsquo;.</p>
+    <p>If the <a href="#flexbox-item"><i>flexbox item's</i></a> inline axis
+     is the same as the <a href="#cross-axis"><i>cross axis</i></a>, this
+     value is identical to &lsquo;<a href="#flex-pack-start"><code
+     class=css>start</code></a>&rsquo;.</p>
+
+    <p>Otherwise, all <a href="#flexbox-item"><i>flexbox items</i></a> on the
+     line with &lsquo;<code class=css>flex-align:baseline</code>&rsquo; that
+     don't run afoul of the previous paragraph are aligned such that their
+     baselines align, and the item with the largest distance between its
+     baseline and its <a href="#cross-start"><i>cross-start</i></a> margin
+     edge is placed flush against the <a
+     href="#cross-start"><i>cross-start</i></a> edge of the line.</p>
 
    <dt><dfn id=flex-align-stretch>stretch</dfn>
 
-   <dd>The height of each child is adjusted to that of the containing block.
-    However, note the text below.
+   <dd>
+    <p>If the <a href="#cross-size-property"><i>cross size property</i></a>
+     of the <a href="#flexbox-item"><i>flexbox item</i></a> is anything other
+     than &lsquo;<code class=css>auto</code>&rsquo;, this value is identical
+     to &lsquo;<a href="#flex-pack-start"><code
+     class=css>start</code></a>&rsquo;.</p>
+
+    <p>Otherwise, this value causes the <a
+     href="#cross-size-property"><i>cross size property</i></a> of the <a
+     href="#flexbox-item"><i>flexbox item</i></a> to resolve to the length
+     necessary to make the <a href="#cross-size"><i>cross size</i></a> of the
+     item's margin box the same size as the line.</p>
   </dl>
 
-  <p>Direction of the <a href="#cross-axis"><i>cross axis</i></a> is
-   determined as follows:
-
-  <p>In multi-line flexbox, <a href="#cross-axis"><i>cross axis</i></a>
-   points in the direction of wrapping (the side where lines are added)
-
-  <p>In single-line flexbox, the direction of <a href="#cross-axis"><i>cross
-   axis</i></a> is determined by the computed value of writing mode of the
-   flexbox element.
-
-  <ul>
-   <li> If flexbox's <a href="#main-axis"><i>main axis</i></a> is parallel to
-    inline axis of the writing mode, <a href="#cross-axis"><i>cross
-    axis</i></a> points in the direction of block flow.
-
-   <li> If flexbox's <a href="#main-axis"><i>main axis</i></a> is parallel to
-    block flow axis of the writing mode, <a href="#cross-axis"><i>cross
-    axis</i></a> points in the direction of inline flow
-  </ul>
-
-  <p>The following rules should be applied when determining the size of child
-   boxes along the <a href="#cross-axis"><i> cross axis</i></a>. Exceptions
-   to these rules are noted under each of the possible values of &lsquo;<a
-   href="#flex-align0"><code class=property>flex-align</code></a>&rsquo;
-   below.
-
-  <p>First, the <a href="#cross-axis"><i>cross axis</i></a> size of content
-   box of the flexbox has to be calculated. If computed value of flexbox's
-   width or height (whichever is along the <a href="#cross-axis"><i>cross
-   axis</i></a>), that value is used. If it is &lsquo;<code
-   class=property>auto</code>&rsquo;, the size is determined by flexbox
-   items, as follows:
-
-  <ol>
-   <li><i>Cross-axis</i> sizes of margin boxes of all children in are checked
-    and the biggest is selected.
-
-   <li>If there are any children with baseline alignemnt, biggest ascent
-    (including its margin-before) and biggest descent (including its
-    margin-after) are found.
-
-   <li>Flexbox's content box size is the size its biggest child or the sum of
-    the biggest ascent and biggest descent, whichever is larger.
-  </ol>
-
-  <p>All normal flow children of boxes will attempt to satisfy the following
-   sizing equation when placed inside vertical boxes if and only if at least
-   one of the specified values is auto:
-
-  <p>&lsquo;<code class=property>margin-left</code>&rsquo; + &lsquo;<code
-   class=property>border-left-width</code>&rsquo; + &lsquo;<code
-   class=property>padding-left</code>&rsquo; + &lsquo;<code
-   class=property>width</code>&rsquo; + &lsquo;<code
-   class=property>padding-right</code>&rsquo; + &lsquo;<code
-   class=property>border-right-width</code>&rsquo; + &lsquo;<code
-   class=property>margin-right</code>&rsquo; = width of containing box
-
-  <p>and a similar equation for height when placed inside horizontal boxes:
-
-  <p>&lsquo;<code class=property>margin-top</code>&rsquo; + &lsquo;<code
-   class=property>border-top-width</code>&rsquo; + &lsquo;<code
-   class=property>padding-top</code>&rsquo; + &lsquo;<code
-   class=property>height</code>&rsquo; + &lsquo;<code
-   class=property>padding-bottom</code>&rsquo; + &lsquo;<code
-   class=property>border-bottom-width</code>&rsquo; + &lsquo;<code
-   class=property>margin-bottom</code>&rsquo; = height of containing box
-
-  <p>If all the values in the equation are specified (i.e., if there are no
-   auto values), then the equation above does not apply, and the specified
-   values should be used. If applying the equation results in a negative
-   value for width/height, then that value is set to 0, and those values
-   should be used.
-
-  <p>If the value of &lsquo;<a href="#flex-align0"><code
-   class=property>flex-align</code></a>&rsquo; is &lsquo;<a
-   href="#flex-align-stretch"><code class=css>stretch</code></a>&rsquo;, then
-   elements obey the sizing rules specified above. This is the default value.
-   If both width/height and one or both margin values are &lsquo;<code
-   class=property>auto</code>&rsquo;, the &lsquo;<code
-   class=property>auto</code>&rsquo; margins are set to 0 and the equation is
-   used to find a value for width/height. Otherwise, if both margins are
-   &lsquo;<code class=property>auto</code>&rsquo;, then the equation is
-   solved under the additional constraint that the two margins must get the
-   same value. If neither the width/height or either margin is auto, then the
-   extra space is positioned as if flex-align was &lsquo;<a
-   href="#flex-line-pack-before"><code
-   class=property>before</code></a>&rsquo;.
-
-  <p>If the value of &lsquo;<a href="#flex-align0"><code
-   class=property>flex-align</code></a>&rsquo; is &lsquo;<a
-   href="#flex-line-pack-before"><code class=css>before</code></a>&rsquo;,
-   &lsquo;<a href="#flex-line-pack-after"><code
-   class=css>after</code></a>&rsquo;, &lsquo;<a
-   href="#flex-line-pack-middle"><code class=css>middle</code></a>&rsquo;, or
-   &lsquo;<a href="#flex-align-baseline"><code
-   class=css>baseline</code></a>&rsquo;, and a value of &lsquo;<code
-   class=css>auto</code>&rsquo; is specified for width/height, then the
-   intrinsic size (or shrink to fit size) of the element should be used. If
-   one margin has the value of auto, then the equations above should be used.
-   If both margins have a value of auto then the above equations should be
-   used, with the space being divided evenly between the two margins. These
-   rules are similar to the rules for replaced elements inside blocks.
-
-  <p>If the above would cause the width or height to greater than the
-   computed maximum width or height, then the width or height is set to the
-   maximum width or height, and the auto margins increased by the extra
-   amount left over. If both margins are auto, they should both be increased
-   by the same amount. If neither margin is auto, the extra space is placed
-   as necessary depending on the flex-align value.
-
-  <p>Once the sizes are computed, the margin boxes of the elements should be
-   aligned at the before, middle, baseline or after edge of the box.
-
   <div class=example>
-   <p>A vertical flexbox can be used to emulate the functionality of HTML's
-    <code>&lt;center></code> element:</p>
+   <p>By using a vertical flexbox and &lsquo;<a href="#flex-align0"><code
+    class=property>flex-align</code></a>&rsquo;, we can emulate the
+    functionality of HTML's <code>&lt;center></code> element:</p>
 
    <pre>&lt;div>
-	&lt;span>foo foo foo foo&lt;/span>
-	&lt;span>bar bar&lt;br>bar bar&lt;/span>
-	&lt;span>foo foo foo foo foo foo foo foo foo foo foo foo&lt;/span>
+	&lt;div>foo foo foo foo&lt;/div>
+	&lt;div>bar bar&lt;br>bar bar&lt;/div>
+	&lt;div>foo foo foo foo foo foo foo foo foo foo foo foo&lt;/div>
 &lt;/div>
 &lt;style>
 	div {
 		display: flexbox;
-		flex-direction: tb;
+		flex-flow: column;
 		width: 200px;
 	}
-	span {/* /*  */ */
-		margin: 0 auto;
+	div > div {
+		flex-align: center;
 	}
 &lt;/style></pre>
 
    <p><img alt="" src="images/basic-vertical-flexbox.png"></p>
   </div>
 
-  <p class=issue>TODO: examples, with pictures
+  <p class=issue>More examples for the other alignment values!
 
-  <p class=issue>TODO: alignment rules should be compatible with
-   css3-grid-layout, if possible
+  <p>The precise effects of this property are articulated in the <a
+   href="#layout-algorithm">Layout Algorithm</a> section.
 
   <h2 id=multiline><span class=secno>6. </span> Multi-line flexbox</h2>
 
@@ -2229,7 +2114,7 @@ <h2 class=no-num id=property>Property index</h2>
     <tr>
      <th><a class=property href="#flex-align0">flex-align</a>
 
-     <td>before | after | middle | stretch | baseline
+     <td>start | end | center | baseline | stretch
 
      <td>stretch
 
@@ -2343,6 +2228,9 @@ <h2 class=no-num id=index>Index</h2>
    <li>cross size, <a href="#cross-size" title="cross
     size"><strong>2.</strong></a>
 
+   <li>cross size property, <a href="#cross-size-property" title="cross size
+    property"><strong>2.</strong></a>
+
    <li>cross-start, <a href="#cross-start"
     title=cross-start><strong>2.</strong></a>
 
@@ -2428,6 +2316,9 @@ <h2 class=no-num id=index>Index</h2>
    <li>main size, <a href="#main-size" title="main
     size"><strong>2.</strong></a>
 
+   <li>main size property, <a href="#main-size-property" title="main size
+    property"><strong>2.</strong></a>
+
    <li>main-start, <a href="#main-start"
     title=main-start><strong>2.</strong></a>