[css-contain-2] Clarify how sizing containment works (#5643)

Author: frivoal

css-contain-2/Overview.bs

@@ -46,6 +46,10 @@ spec:css-sizing-4; type:property; text:contain-intrinsic-size
 spec:css-sizing-4; type:property; text:aspect-ratio
 spec:intersection-observer; type:dfn; text:intersection root
 spec:css-sizing-3; type:value; for:height; text:auto
+spec:css-sizing-3; type:property; text:width
+spec:css-sizing-3; type:property; text:height
+spec:css-sizing-3; type:value; for:width; text:min-content
+spec:css-sizing-3; type:value; for:width; text:max-content
 </pre>
 
 <h2 id='intro'>
@@ -476,59 +480,15 @@ Size Containment</h3>
 	contain-size-056.html
 	</wpt>
 
-	1. When calculating the size of the [=size containment box=],
-		including when computing its [=intrinsic size=],
-		it must be treated as having no contents.
+	1.
+		The [=intrinsic sizes=] of the [=size containment box=]
+		are determined as if the element had no content,
+		following the same logic as when [=sizing as if empty=].
 
-		<wpt>
-		contain-size-021.html
-		contain-size-023.html
-		contain-size-025.html
-		contain-size-027.html
-		contain-size-061.html
-		contain-size-062.html
-		contain-size-063.html
-		contain-size-borders.html
-		contain-size-fieldset-001.html
-		contain-size-fieldset-002.html
-		contain-size-select-001.html
-		contain-size-select-002.html
-		contain-size-scrollbars-001.html
-		contain-size-scrollbars-002.html
-		contain-size-scrollbars-003.html
-		contain-size-scrollbars-004.html
-
-		contain-size-button-001.html
-		contain-size-flexbox-001.html
-		contain-size-flexbox-002.html
-		contain-size-grid-001.html
-		</wpt>
-
-		Note: Even when the element's [=sizing properties=] are ''height/auto''
-		this does not necessarily make the element zero-sized:
-		properties set on the element itself,
-		such as the 'columns' property or the 'grid' property,
-		continue to be taken into account.
-
-		<wpt>
-		contain-size-grid-002.html
-		contain-size-grid-003.html
-		contain-size-multicol-001.html
-		contain-size-multicol-as-flex-item.html
-		</wpt>
-
-		Then,
-		its contents must then be laid out into the [=size containment box=]'s resolved size normally (including any pseudo-elements),
-		i.e. [=size containment=] has no effect in this phase.
-
-		Note: [=size containment=] does not suppress baseline alignment.
-		See [=layout containment=] for that.
-
-		<wpt>
-		contain-size-baseline-001.html
-		</wpt>
-
-		<a>Replaced elements</a> must be treated as having an intrinsic width and height of 0.
+		Note: This affects explicit invocations of the ''min-content'' or ''max-content'' keywords,
+		as well as any calculation that depends on these measurement,
+		such as sizing <span class=informative>[=grid tracks=]</span> into which a size contained item is placed,
+		or if [=fit-content sizing=] the containment box's parent.
 
 		<wpt>
 		contain-size-013.html
@@ -544,38 +504,98 @@ Size Containment</h3>
 		contain-size-replaced-006.html
 		</wpt>
 
-	2. [=Size containment boxes=] must be treated
-		as if they had no [=intrinsic aspect ratio=].
+	2. Laying out a [=size containment box=] and its content is conceptually done in two phases:
+		<dl>
+			<dt><dfn>Sizing as if empty</dfn>
+			<dd>
+				The [=used value|used=] 'width' and 'height' of the [=size containment box|containment box=]
+				are determined as if performing a normal layout of the box,
+				except that it is treated as having no content--
+				not even through pseudo elements such as ''::before'', ''::after'', or ''::marker''.
 
-		Note: Size containment only suppresses the [=intrinsic aspect ratio=],
-		not [=preferred aspect ratio=],
-		so properties like 'aspect-ratio' which affect that [=preferred aspect ratio=] directly
-		are honored.
+				<wpt>
+				contain-size-021.html
+				contain-size-023.html
+				contain-size-025.html
+				contain-size-027.html
+				contain-size-061.html
+				contain-size-062.html
+				contain-size-063.html
+				contain-size-borders.html
+				contain-size-fieldset-001.html
+				contain-size-fieldset-002.html
+				contain-size-select-001.html
+				contain-size-select-002.html
+				contain-size-scrollbars-001.html
+				contain-size-scrollbars-002.html
+				contain-size-scrollbars-003.html
+				contain-size-scrollbars-004.html
 
-		<wpt pathprefix=css/css-sizing/aspect-ratio/>
-		replaced-element-023.html
-		replaced-element-025.html
-		replaced-element-027.html
-		</wpt>
+				contain-size-button-001.html
+				contain-size-flexbox-001.html
+				contain-size-flexbox-002.html
+				contain-size-grid-001.html
+				</wpt>
 
-		<div class=example>
-			Given the following markup and style, the image would be sized to 100px by 100px,
-			as the aspect ratio set by the 'aspect-ratio' property takes effect.
-			<pre><code class=lang-css>
-			img {
-				width: 100px;
-				aspect-ratio: 1/1;
-				contain: size;
-			}
-			</code><code class=lang-html>
-			&lt;img src="https://www.example.com/300x100.jpg">
-			</code></pre>
+				<a>Replaced elements</a> must be treated as having an intrinsic width and height of 0
+				and no [=intrinsic aspect ratio=].
 
-			If the 'aspect-ratio' property had not been declared,
-			the image would have been 100px by 0px,
-			as its intrinsic aspect ratio is suppressed,
-			and its intrinsic height is treated as 0.
-		</div>
+				Note: Size containment only suppresses the [=intrinsic aspect ratio=],
+				so properties like 'aspect-ratio' which affect that [=preferred aspect ratio=] directly
+				are honored.
+
+				<wpt>
+				contain-size-013.html
+				contain-size-041.html
+				contain-size-042.html
+				contain-size-replaced-001.html
+				contain-size-replaced-002.html
+				contain-size-replaced-003a.html
+				contain-size-replaced-003b.html
+				contain-size-replaced-003c.html
+				contain-size-replaced-004.html
+				contain-size-replaced-005.html
+				</wpt>
+				<wpt pathprefix=css/css-sizing/aspect-ratio/>
+				replaced-element-023.html
+				replaced-element-025.html
+				replaced-element-027.html
+				</wpt>
+
+				All CSS properties of the [=size containment box=] are taken into account
+				as they would be when performing layout normally.
+				Other specifications may make specific exemptions.
+
+				<wpt>
+				contain-size-replaced-006.html
+				</wpt>
+
+				Note: Even when the element's [=sizing properties=] specify an intrinsic size,
+				this does not necessarily make the element zero-sized:
+				properties set on the element itself
+				continue to be taken into account,
+				which can cause it to be larger.
+
+				<wpt>
+				contain-size-grid-002.html
+				contain-size-grid-003.html
+				contain-size-multicol-001.html
+				contain-size-multicol-as-flex-item.html
+				</wpt>
+
+			<dt><dfn>Laying out in-place</dfn>
+			<dd>
+				The [=size containment box|containment box=]'s content
+				(including any pseudo-elements)
+				must then be laid out into the now fixed-size [=size containment box|containment box=] normally.
+		</dl>
+
+		Note: [=Size containment=] does not suppress baseline alignment.
+		See [=layout containment=] for that.
+
+		<wpt>
+		contain-size-baseline-001.html
+		</wpt>
 
 	3. [=Size containment boxes=] are <a spec=css-break-3>monolithic</a> (See [[CSS-BREAK-3#possible-breaks]]).
 
@@ -584,6 +604,25 @@ Size Containment</h3>
 		contain-size-monolithic-001.html
 		</wpt>
 
+	<div class=example>
+		Given the following markup and style, the image would be sized to 100px by 100px,
+		as the aspect ratio set by the 'aspect-ratio' property takes effect.
+		<pre><code class=lang-css>
+		img {
+			width: 100px;
+			aspect-ratio: 1/1;
+			contain: size;
+		}
+		</code><code class=lang-html>
+		&lt;img src="https://www.example.com/300x100.jpg">
+		</code></pre>
+
+		If the 'aspect-ratio' property had not been declared,
+		the image would have been 100px by 0px,
+		as its intrinsic aspect ratio is suppressed,
+		and its intrinsic height is treated as 0.
+	</div>
+
 	By itself, <a>size containment</a> does not offer much optimization opportunity.
 	Its primary benefit on its own is that tools which want to lay out the [=size containment box|containment box=]'s contents
 	based on the [=size containment box|containment box=]'s size
@@ -604,7 +643,7 @@ Size Containment</h3>
 
 	2. When laying out the page,
 		if the [=size containment box|containment box=] is off-screen or obscured,
-		the layout of its contents can be delayed or done at a lower priority.
+		the layout of its contents (i.e. "[=laying out in-place=]") can be delayed or done at a lower priority.
 
 <h3 id='containment-layout'>
 Layout Containment</h3>