Merge pull request w3c#4190 from frivoal/fix4189

[css-contain] Be more rigorous about box vs element

Author: tabatkins

css-contain-1/Overview.bs

@@ -144,7 +144,7 @@ Strong Containment: the 'contain' property</h2>
 		<dt><dfn>size</dfn>
 		<dd>
 			The value turns on <a>size containment</a> for the element.
-			This ensures that the containing element can be laid out
+			This ensures that the containing box can be laid out
 			without needing to examine its descendants.
 
 			<wpt>
@@ -208,7 +208,7 @@ Strong Containment: the 'contain' property</h2>
 		<dt><dfn>layout</dfn>
 		<dd>
 			This value turns on <a>layout containment</a> for the element.
-			This ensures that the containing element is <em>totally opaque</em> for layout purposes;
+			This ensures that the containing box is <em>totally opaque</em> for layout purposes;
 			nothing outside can affect its internal layout,
 			and vice versa.
 
@@ -262,7 +262,7 @@ Strong Containment: the 'contain' property</h2>
 			This value turns on <a>style containment</a> for the element.
 			This ensures that,
 			for properties which can have effects on more than just an element and its descendants,
-			those effects don't escape the containing element.
+			those effects don't escape the element.
 
 			<wpt>
 				contain-style-baseline-001.html
@@ -289,7 +289,7 @@ Strong Containment: the 'contain' property</h2>
 		<dt><dfn>paint</dfn>
 		<dd>
 			This value turns on <a>paint containment</a> for the element.
-			This ensures that the descendants of the containing element don't display outside its bounds,
+			This ensures that the descendants of the containing box don't display outside its bounds,
 			so if an element is off-screen or otherwise not visible,
 			its descendants are also guaranteed to be not visible.
 
@@ -402,12 +402,14 @@ Types of Containment</h2>
 Size Containment</h3>
 
 	If the element does not generate a <a>principal box</a> (as is the case with ''display: contents'' or ''display: none''),
-	or if the element is a ''display/table'',
-	or if the element is an <a spec="css-display-3">internal table element</a>,
-	or if the element is an <a spec="css-display-3">internal ruby element</a>,
-	or if the element's <a>principal box</a> is a <a spec="css-display-3" lt="atomic inline">non-atomic</a> <a spec="css-display-3">inline-level</a> box,
+	or its [=inner display type=] is ''display/table'',
+	or its principal box is an <a spec="css-display-3">internal table box</a>,
+	or an <a spec="css-display-3">internal ruby box</a>,
+	or a <a spec="css-display-3" lt="atomic inline">non-atomic</a> <a spec="css-display-3">inline-level</a> box,
 	size containment has no effect.
-	Otherwise, giving an element <dfn export>size containment</dfn> has the following effects:
+	Otherwise, giving an element <dfn export>size containment</dfn>
+	makes its [=principal box=] a <dfn for=size-containment>containing box</dfn> for [=size containment=]
+	and has the following effects:
 
 	<wpt>
 	contain-size-001.html
@@ -425,11 +427,11 @@ Size Containment</h3>
 	contain-size-052.html
 	</wpt>
 
-	Note: Internal table elements,
+	Note: Internal table boxes,
 	which do not include table captions,
 	are excluded,
 	because the table layout algorithm
-	does not allow elements to become smaller than their inflow content.
+	does not allow boxes to become smaller than their inflow content.
 	Sizing a table cell as if it was empty and then layout out its content inside without changing the size
 	is effectively an undefined operation.
 	Manually setting the 'width' or 'height' properties to ''0''
@@ -443,7 +445,7 @@ Size Containment</h3>
 	contain-size-056.html
 	</wpt>
 
-	1. When calculating the size of the containing element,
+	1. When calculating the size of the [=size-containment/containing box=],
 		it must be treated as having no contents.
 
 		<wpt>
@@ -482,7 +484,7 @@ Size Containment</h3>
 		</wpt>
 
 		Then,
-		its contents must then be laid out into the containing element's resolved size.
+		its contents must then be laid out into the [=size-containment/containing box=]'s resolved size.
 
 		Note: [=size containment=] does not suppress baseline alignment.
 		See [=layout containment=] for that.
@@ -506,44 +508,46 @@ Size Containment</h3>
 		contain-size-replaced-005.html
 		contain-size-replaced-006.html
 		</wpt>
-	2. Elements with <a>size containment</a> are <a spec=css-break-3>monolithic</a> (See [[CSS-BREAK-3#possible-breaks]]).
+	2. [=size-containment/Containing boxes=] for <a>size containment</a> are <a spec=css-break-3>monolithic</a> (See [[CSS-BREAK-3#possible-breaks]]).
 
 		<wpt>
 		contain-size-breaks-001.html
 		contain-size-monolithic-001.html
 		</wpt>
 
 	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 containing element's contents
-	based on the containing element's size
+	Its primary benefit on its own is that tools which want to lay out the containing box's contents
+	based on the containing box's size
 	(such as a JS library implementing the "container query" concept)
 	can do so without fear of "infinite loops",
-	where having a child's size respond to the size of the containing element
-	causes the containing element's size to change as well,
+	where having a child's size respond to the size of the containing box
+	causes the containing box's size to change as well,
 	possibly triggering <em>further</em> changes in how the child sizes itself
-	and possibly thus more changes to the containing element's size,
+	and possibly thus more changes to the containing box's size,
 	ad infinitum.
 
 	When paired with <a>layout containment</a>, though,
 	possible optimizations that can be enabled include (but are not limited to):
 
-	1. When the style or contents of a descendant of the containing element is changed,
+	1. When the style or contents of a descendant of the containing box is changed,
 		calculating what part of the DOM tree is "dirtied" and might need to be re-laid out
-		can stop at the containing element.
+		can stop at the containing box.
 
 	2. When laying out the page,
-		if the containing element is off-screen or obscured,
+		if the containing box is off-screen or obscured,
 		the layout of its contents can be delayed or done at a lower priority.
 
 <h3 id='containment-layout'>
 Layout Containment</h3>
 
 	If the element does not generate a <a>principal box</a> (as is the case with 'display' values of ''display/contents'' or ''display/none''),
-	or if the element is an <a spec="css-display-3">internal table element</a> other than ''display/table-cell'',
-	or if the element is an <a spec="css-display-3">internal ruby element</a>,
-	or if the element's <a>principal box</a> is a <a spec="css-display-3" lt="atomic inline">non-atomic</a> <a spec="css-display-3">inline-level</a> box,
+	or its [=principal box=] is an <a spec="css-display-3">internal table box</a> other than ''display/table-cell'',
+	or an <a spec="css-display-3">internal ruby box</a>,
+	or a <a spec="css-display-3" lt="atomic inline">non-atomic</a> <a spec="css-display-3">inline-level</a> box,
 	layout containment has no effect.
-	Otherwise, giving an element <dfn export>layout containment</dfn> has the following effects:
+	Otherwise, giving an element <dfn export>layout containment</dfn>
+	makes its [=principal box=] a <dfn for=layout-containment>containing box</dfn> for [=layout containment=]
+	and has the following effects:
 
 	<wpt>
 	contain-layout-001.html
@@ -560,7 +564,7 @@ Layout Containment</h3>
 	contain-layout-independent-formatting-context-003.html
 	</wpt>
 
-	1. The element [=establishes an independent formatting context=].
+	1. The [=layout-containment/containing box=] [=establishes an independent formatting context=].
 
 		<wpt>
 		contain-layout-ifc-022.html
@@ -570,10 +574,10 @@ Layout Containment</h3>
 		</wpt>
 
 	2. If at least one [=fragmentation container=] of a [=fragmentation context=] has [=layout containment=],
-		or if at least one [=fragmentation container=] of a [=fragmentation context=] is a descendant of an element with layout containment
+		or if at least one [=fragmentation container=] of a [=fragmentation context=] is a descendant of [=layout-containment/containing box=] for layout containment
 		<strong>and</strong> at least one subsequent [=fragmentation container=] of the same [=fragmentation context=]
 		is not a descendant of that same element with layout containment,
-		then the first element with [=layout containment=]
+		then the first [=layout-containment/containing box=] for [=layout containment=]
 		which is either a [=fragmentation container=] itself
 		or is an ancestor of a [=fragmentation container=]
 		must “trap” the remainder of the [=fragmented flow=]:
@@ -626,7 +630,7 @@ Layout Containment</h3>
 			In this [[CSS-REGIONS-1]] example,
 			content can flow from <code>#a</code> to <code>#b</code>,
 			from <code>#b</code> to <code>#c</code>.
-			However as <code>#c</code> is the last fragment container in the first layout-contained element,
+			However as <code>#c</code> is the last fragment container in the first containing box for layout containment,
 			it traps all the remaining content,
 			and nothing gets flowed into <code>#d</code>, <code>#e</code>, or <code>#f</code>.
 		</div>
@@ -646,7 +650,7 @@ Layout Containment</h3>
 		contain-layout-ink-overflow-020.html
 		</wpt>
 
-	4. The element acts as a containing block for absolutely positioned and fixed positioned descendants.
+	4. The [=layout-containment/containing box=] acts as a containing block for absolutely positioned and fixed positioned descendants.
 
 		<wpt>
 		contain-layout-006.html
@@ -655,15 +659,15 @@ Layout Containment</h3>
 		contain-layout-cell-002.html
 		</wpt>
 
-	5. The element creates a <a>stacking context</a>.
+	5. The [=layout-containment/containing box=] creates a <a>stacking context</a>.
 
 		<wpt>
 		contain-layout-016.html
 		contain-layout-017.html
 		contain-layout-018.html
 		</wpt>
 
-	6. [=Forced breaks=] are allowed within elements with [=layout containment=],
+	6. [=Forced breaks=] are allowed within [=layout-containment/containing boxes=] for [=layout containment=],
 		but do not propagate to the parent as otherwise described in [[CSS-BREAK-3#break-between]].
 
 		<wpt>
@@ -676,9 +680,9 @@ Layout Containment</h3>
 
 	7. For the purpose of the 'vertical-align' property,
 		or any other property whose effects
-		need to relate the position of the containing element's baseline
+		need to relate the position of the [=layout-containment/containing box=]'s baseline
 		to something other than its descendants,
-		the containing element is treated as having no baseline.
+		the [=layout-containment/containing box=] is treated as having no baseline.
 
 		<wpt>
 		contain-layout-baseline-001.html
@@ -694,16 +698,16 @@ Layout Containment</h3>
 	Possible optimizations that can be enabled by <a>layout containment</a> include (but are not limited to):
 
 	1. When laying out the page,
-		the contents of separate containing elements
+		the contents of separate containing boxes
 		can be laid out in parallel,
 		as they're guaranteed not to affect each other.
 
 	2. When laying out the page,
-		if the containing element is off-screen or obscured
-		and the layout of the visible parts of the screen do not depend on the size of the containing element
-		(for example, if the containing element is near the end of a block container,
+		if the containing box is off-screen or obscured
+		and the layout of the visible parts of the screen do not depend on the size of the containing box
+		(for example, if the containing box is near the end of a block container,
 		and you're viewing the beginning of the block container),
-		the layout of the containing elements' contents can be delayed or done at a lower priority.
+		the layout of the containing box' contents can be delayed or done at a lower priority.
 
 		(When paired with <a>size containment</a>,
 		this optimization can be applied more liberally.)
@@ -713,7 +717,8 @@ Style Containment</h3>
 
 	Note: Style Containment is at-risk.
 
-	Giving an element <dfn export>style containment</dfn> has the following effects:
+	Giving an element <dfn export>style containment</dfn>
+	and has the following effects:
 
 	1. The 'counter-increment' and 'counter-set' properties
 	    must be <a for=property>scoped to the element's sub-tree</a>
@@ -804,19 +809,21 @@ Style Containment</h3>
 
 	Possible optimizations that can be enabled by <a>style containment</a> include (but are not limited to):
 
-	1. Whenever a property is changed on a descendant of the containing element,
+	1. Whenever a property is changed on a descendant of an element with [=style containment=],
 		calculating what part of the DOM tree is "dirtied" and might need to have its style recalculated
-		can stop at the containing element.
+		can stop at the containing box.
 
 <h3 id='containment-paint'>
 Paint Containment</h3>
 
 	If the element does not generate a <a>principal box</a> (as is the case with 'display' values of ''display/contents'' or ''display/none''),
-	or if the element is an <a spec="css-display-3">internal table element</a> other than ''display/table-cell'',
-	or if the element is an <a spec="css-display-3">internal ruby element</a>,
-	or if the element's <a>principal box</a> is a <a spec="css-display-3" lt="atomic inline">non-atomic</a> <a spec="css-display-3">inline-level</a> box,
+	or its [=principal box=] is an <a spec="css-display-3">internal table box</a> other than ''display/table-cell'',
+	or an <a spec="css-display-3">internal ruby box</a>,
+	or a <a spec="css-display-3" lt="atomic inline">non-atomic</a> <a spec="css-display-3">inline-level</a> box,
 	paint containment has no effect.
-	Otherwise, giving an element <dfn export>paint containment</dfn> has the following effects:
+	Otherwise, giving an element <dfn export>paint containment</dfn>
+	makes its [=principal box=] a <dfn for=paint-containment>containing box</dfn> for [=paint containment=]
+	and has the following effects:
 
 	<wpt>
 	contain-paint-002.html
@@ -837,7 +844,7 @@ Paint Containment</h3>
 
 	1. The contents of the element
 		including both the paint of the descendants and their geometry
-		must be clipped to the <a>padding edge</a> of the element's <a>principal box</a>,
+		must be clipped to the <a>padding edge</a> of the [=paint-containment/containing box=],
 		taking <a>corner clipping</a> into account.
 		This does not include the creation of any mechanism
 		to access or indicate the presence of the clipped content;
@@ -864,7 +871,7 @@ Paint Containment</h3>
 		contain-paint-table-001.html
 		contain-paint-table-002.html
 		</wpt>
-	2. The element acts as a containing block for absolutely positioned and fixed positioned descendants.
+	2. The [=paint-containment/containing box=] acts as a containing block for absolutely positioned and fixed positioned descendants.
 
 		<wpt>
 		contain-paint-009.html
@@ -873,15 +880,15 @@ Paint Containment</h3>
 		contain-paint-023.html
 		contain-paint-024.html
 		</wpt>
-	3. The element creates a <a>stacking context</a>.
+	3. The [=paint-containment/containing box=] creates a <a>stacking context</a>.
 
 		<wpt>
 		contain-paint-020.html
 		contain-paint-021.html
 		contain-paint-025.html
 		contain-subgrid-001.html
 		</wpt>
-	4. The element [=establishes an independent formatting context=].
+	4. The [=paint-containment/containing box=] [=establishes an independent formatting context=].
 
 		<wpt>
 		contain-paint-ifc-011.html
@@ -896,13 +903,13 @@ Paint Containment</h3>
 <div class=informative>
 	Possible optimizations that can be enabled by <a>paint containment</a> include (but are not limited to):
 
-	1. If the containing element is off-screen or obscured,
+	1. If the containing box is off-screen or obscured,
 		the UA can directly skip trying to paint its contents,
 		as they're guaranteed to be off-screen/obscured as well.
 
 	2. Unless the clipped content is made accessible via a separate mechanism
 		such as the 'overflow', 'resize', or 'text-overflow' properties,
-		the UA can reserve "canvas" space for the element exactly the element's size.
+		the UA can reserve "canvas" space for the box exactly the box's size.
 		(In similar, scrollable, situations, like ''overflow: hidden'',
 		it's possible to scroll to the currently-clipped content,
 		so UAs often predictively overpaint somewhat