[css-grid-1][editorial] Rearrange the grid layout algo a little for c…

…larity, making a new top-level algo. #3418 (#9540)
w3c · Nov 3, 2023 · 600c743 · 600c743
1 parent 8c619cf
commit 600c743
Show file tree

Hide file tree

Showing 2 changed files with 109 additions and 55 deletions.
diff --git a/css-grid-1/Overview.bs b/css-grid-1/Overview.bs
@@ -3540,7 +3540,7 @@ Gutters: the 'row-gap', 'column-gap', and 'gap' properties</h3>
 
 	Note: Additional spacing may be added between tracks
 	due to 'justify-content'/'align-content'.
-	See [[#algo-overview]].
+	See [[#algo-grid-sizing]].
 	This space effectively increases the size of the <a>gutters</a>.
 
 	If a <a>grid</a> is <a>fragmented</a> between tracks,
@@ -3773,10 +3773,44 @@ Grid Container Baselines</h3>
  ██████  ████ ████████ ████ ██    ██  ██████
 -->
 
-<h2 id='layout-algorithm'>
-Grid Sizing</h2>
+<h2 id='layout-algorithm' oldids="algo-overview" dfn export>
+Grid Layout Algorithm</h2>
 
-	This section defines the <dfn export>grid sizing algorithm</dfn>,
+	This section defines the <b>grid layout algorithm</b>,
+	which sizes the [=grid container=],
+	sizes and positions all the [=grid tracks=],
+	and lays out the [=grid items=]
+	which have been [=grid item placement algorithm|placed=] into its [=grid areas=].
+
+	1. First, find the size of the [=grid container=],
+		per [[#intrinsic-sizes]].
+
+		Note: During this phase,
+		cyclic <<percentage>>s in track sizes are treated as ''grid-template-columns/auto''.
+
+	2. Given the resulting [=grid container=] size,
+		run the [=Grid Sizing Algorithm=]
+		to size the [=grid=].
+
+		Note: During this phase,
+		<<percentage>>s in track sizes are resolved
+		against the [=grid container=] size.
+
+	3. Lay out the [=grid items=] into their respective containing blocks.
+		Each [=grid area's=] width and height
+		are considered [=definite=] for this purpose.
+
+		Note: Since formulas calculated using only definite sizes,
+		such as the [=stretch fit=] formula,
+		are also definite,
+		the size of a grid item which is stretched
+		is also considered definite.
+
+
+<h3 id="algo-grid-sizing" dfn export>
+Grid Sizing Algorithm</h3>
+
+	This section defines the <b>grid sizing algorithm</b>,
 	which determines the size of all <a>grid tracks</a>
 	and, by extension, the entire grid.
 
@@ -3793,9 +3827,6 @@ Grid Sizing</h2>
 
 	The <a>grid sizing algorithm</a> defines how to resolve these sizing constraints into used track sizes.
 
-<h3 id="algo-overview">
-Grid Sizing Algorithm</h3>
-
 	<ol>
 		<li>
 			First, the <a>track sizing algorithm</a> is used to resolve the sizes of the <a>grid columns</a>.
@@ -3889,26 +3920,14 @@ Grid Sizing Algorithm</h3>
 			to account for the effective column gap sizes.
 
 		<li>
-			Finally, the <a>grid container</a> is sized
-			using the resulting size of the <a>grid</a> as its content size,
-			and the tracks are aligned within the <a>grid container</a>
+			Finally, align the tracks within the <a>grid container</a>
 			according to the 'align-content' and 'justify-content' properties.
 
 			Note: This can introduce extra space between tracks,
 			potentially enlarging the grid area of any grid items spanning the gaps
 			beyond the space allotted to during track sizing.
 	</ol>
 
-	Once the size of each <a>grid area</a> is thus established,
-	the <a>grid items</a> are laid out into their respective containing blocks.
-	The <a>grid area’s</a> width and height are considered <a>definite</a> for this purpose.
-
-	Note: Since formulas calculated using only definite sizes,
-	such as the <a>stretch fit</a> formula,
-	are also definite,
-	the size of a grid item which is stretched
-	is also considered definite.
-
 <h3 id='algo-terms'>
 Track Sizing Terminology</h3>
 
@@ -4887,6 +4906,13 @@ Changes since the <a href="https://www.w3.org/TR/2020/CRD-css-grid-1-20201218/">
 				instead use the <a>grid area</a> determined in [[#abspos-items]].</del>
 			</blockquote>
 
+		<li id="change-2020-rearrange-layout-algo">
+			Rearranged the Grid Sizing Algorithm overview
+			to better convey the relationship
+			between grid container sizing
+			and grid track sizing.
+			See [[#layout-algorithm]].
+			(<a href="https://github.com/w3c/csswg-drafts/issues/3418">Issue 3418</a>)
 	</ul>
 
 <h3 id="changes-202008">

diff --git a/css-grid-2/Overview.bs b/css-grid-2/Overview.bs
@@ -4092,7 +4092,7 @@ Gutters: the 'row-gap', 'column-gap', and 'gap' properties</h3>
 
 	Note: Additional spacing may be added between tracks
 	due to 'justify-content'/'align-content'.
-	See [[#algo-overview]].
+	See [[#algo-grid-sizing]].
 	This space effectively increases the size of the <a>gutters</a>.
 
 	If a <a>grid</a> is <a>fragmented</a> between tracks,
@@ -4325,10 +4325,48 @@ Grid Container Baselines</h3>
  ██████  ████ ████████ ████ ██    ██  ██████
 -->
 
-<h2 id='layout-algorithm'>
-Grid Sizing</h2>
+<h2 id='layout-algorithm' oldids="algo-overview" dfn export>
+Grid Layout Algorithm</h2>
 
-	This section defines the <dfn export>grid sizing algorithm</dfn>,
+	This section defines the <b>grid layout algorithm</b>,
+	which sizes the [=grid container=],
+	sizes and positions all the [=grid tracks=],
+	and lays out the [=grid items=]
+	which have been [=grid item placement algorithm|placed=] into its [=grid areas=].
+
+	1. First, find the size of the [=grid container=],
+		per [[#intrinsic-sizes]].
+
+		Note: During this phase,
+		cyclic <<percentage>>s in track sizes are treated as ''grid-template-columns/auto''.
+
+	2. Given the resulting [=grid container=] size,
+		run the [=Grid Sizing Algorithm=]
+		to size the [=grid=].
+
+		Note: During this phase,
+		<<percentage>>s in track sizes are resolved
+		against the [=grid container=] size.
+
+	3. Lay out the [=grid items=] into their respective containing blocks.
+		Each [=grid area's=] width and height
+		are considered [=definite=] for this purpose.
+
+		Note: Since formulas calculated using only definite sizes,
+		such as the [=stretch fit=] formula,
+		are also definite,
+		the size of a grid item which is stretched
+		is also considered definite.
+
+	Note: Placement of all [=grid items=],
+	including [=subgrids=] and their sub-items,
+	occurs before sizing.
+
+
+<h3 id="algo-grid-sizing" dfn export>
+Grid Sizing Algorithm</h3>
+
+	This section defines the <b>grid sizing algorithm</b>,
 	which determines the size of all <a>grid tracks</a>
 	and, by extension, the entire grid.
 
@@ -4345,13 +4383,6 @@ Grid Sizing</h2>
 
 	The <a>grid sizing algorithm</a> defines how to resolve these sizing constraints into used track sizes.
 
-<h3 id="algo-overview">
-Grid Sizing Algorithm</h3>
-
-	Note: Placement of all [=grid items=],
-	including [=subgrids=] and their sub-items,
-	occurs before sizing.
-
 	<ol>
 		<li>
 			First, the <a>track sizing algorithm</a> is used to resolve the sizes of the <a>grid columns</a>.
@@ -4462,9 +4493,7 @@ Grid Sizing Algorithm</h3>
 			to account for the effective column gap sizes.
 
 		<li>
-			Finally, the <a>grid container</a> is sized
-			using the resulting size of the <a>grid</a> as its content size,
-			and the tracks are aligned within the <a>grid container</a>
+			Finally, align the tracks within the <a>grid container</a>
 			according to the 'align-content' and 'justify-content' properties.
 
 			Note: This can introduce extra space between tracks,
@@ -4481,16 +4510,6 @@ Grid Sizing Algorithm</h3>
 	Note this means that a [=subgrid=] establishing an [=orthogonal flow=]
 	would have the order of its track sizing inverted compared to a nested grid.
 
-	Once the size of each <a>grid area</a> is thus established,
-	the <a>grid items</a> are laid out into their respective containing blocks.
-	The <a>grid area’s</a> width and height are considered <a>definite</a> for this purpose.
-
-	Note: Since formulas calculated using only definite sizes,
-	such as the <a>stretch fit</a> formula,
-	are also definite,
-	the size of a grid item which is stretched
-	is also considered definite.
-
 	<div class="example">
 		The following example illustrates how per-axis subgrids are sized:
 
@@ -5391,17 +5410,18 @@ Changes</h2>
 Changes since the <a href="https://www.w3.org/TR/2020/CRD-css-grid-2-20201218/">18 December 2020 CR</a></h3>
 
 	<ul class="non-normative">
-		Clarified how [=relative positioning=] applies to [=subgrids=].
-		(<a href="https://github.com/w3c/csswg-drafts/issues/7123">Issue 7123</a>)
-		<blockquote>
-			<ul>
-				<li>
-					<ins>[=Relative positioning=] applies to <a>subgrids</a> as normal,
-					and shifts the box and its content together as usual.
-					(Note: Relative positioning takes place after alignment,
-					and does not affect track sizing.)</ins>
-			</ul>
-		</blockquote>
+		<li>
+			Clarified how [=relative positioning=] applies to [=subgrids=].
+			(<a href="https://github.com/w3c/csswg-drafts/issues/7123">Issue 7123</a>)
+			<blockquote>
+				<ul>
+					<li>
+						<ins>[=Relative positioning=] applies to <a>subgrids</a> as normal,
+						and shifts the box and its content together as usual.
+						(Note: Relative positioning takes place after alignment,
+						and does not affect track sizing.)</ins>
+				</ul>
+			</blockquote>
 
 		<li id="change-2020-flex-intrinsic-ratios">
 			Changed intrinsic track space distribution <a href="#algo-spanning-flex-items">across flexible tracks</a>
@@ -5499,6 +5519,14 @@ Changes since the <a href="https://www.w3.org/TR/2020/CRD-css-grid-2-20201218/">
 				<del>However, if the <a>grid container</a> parent is also the generator of the absolutely positioned element's <a>containing block</a>,
 				instead use the <a>grid area</a> determined in [[#abspos-items]].</del>
 			</blockquote>
+
+		<li id="change-2020-rearrange-layout-algo">
+			Rearranged the Grid Sizing Algorithm overview
+			to better convey the relationship
+			between grid container sizing
+			and grid track sizing.
+			See [[#layout-algorithm]].
+			(<a href="https://github.com/w3c/csswg-drafts/issues/3418">Issue 3418</a>)
 	</ul>
 
 <h3 id="changes-202008">