[css-contain-2] Add in the a11y and examples sections. Clarify the observable behavior by saying "painting". Add Vlad as a co-editor, per WG resolution.

Author: tabatkins

css-contain-2/Overview.bs

@@ -10,6 +10,7 @@ Previous Version: https://www.w3.org/TR/2019/WD-css-contain-2-20191015/
 TR: https://www.w3.org/TR/css-contain-2/
 Editor: Tab Atkins, Google, http://xanthir.com/contact/, w3cid 42199
 Editor: Florian Rivoal, On behalf of Bloomberg, https://florian.rivoal.net/, w3cid 43241
+Editor: Vladimir Levin, Google, vmpstr@google.com, w3cid 75295
 Abstract: This CSS module describes the 'contain' property, which indicates that the element's subtree is independent of the rest of the page. This enables heavy optimizations by user agents when used well.
 Test Suite: https://test.csswg.org/harness/results/css-contain-1_dev/
 WPT Path Prefix: css/css-contain/
@@ -678,7 +679,7 @@ Layout Containment</h3>
 		contain-layout-ink-overflow-020.html
 		</wpt>
 
-	4. The [=layout-containment/containing box=] establishes an [=absolute positioning containing block=] and a [=fixed positioning containing block=].
+	4. The [=layout containment/containing box=] establishes an [=absolute positioning containing block=] and a [=fixed positioning containing block=].
 
 		<wpt>
 		contain-layout-006.html
@@ -905,7 +906,7 @@ Paint Containment</h3>
 		contain-paint-table-001.html
 		contain-paint-table-002.html
 		</wpt>
-	2. The [=paint-containment/containing box=] establishes an [=absolute positioning containing block=] and a [=fixed positioning containing block=].
+	2. The [=paint containment/containing box=] establishes an [=absolute positioning containing block=] and a [=fixed positioning containing block=].
 
 		<wpt>
 		contain-paint-009.html
@@ -1013,12 +1014,12 @@ Suppressing An Element's Contents Entirely: the 'content-visibility' property {#
 		(the [=flat tree=] descendants of the element,
 		including both text and elements,
 		or the replaced content of a [=replaced element=])
-		are not rendered
+		are not painted
 		(as if they had ''visibility: hidden'')
 		and do not respond to hit-testing
 		(as if they had ''pointer-events: none'').
 
-		The user agent <em>should</em> avoid as much layout and rendering work as possible
+		The user agent <em>should</em> additionally avoid as much layout/rendering work as possible
 		for [=skipped contents=];
 		the combination of heavy [=containment=]
 		and making the contents invisible and untouchable
@@ -1050,7 +1051,10 @@ Suppressing An Element's Contents Entirely: the 'content-visibility' property {#
 				since the results of such layouts
 				will not affect the container element’s size.
 
-			Note that in the ''content-visibility: auto'' case, layout containment, style containment, and paint containment persist even if the element is not skipped. This is done to prevent layout changes that would be incurred by containment changes as a result element entering and exiting the skipped state.
+			Note that in the ''content-visibility: auto'' case,
+			[=layout containment=], [=style containment=], and [=paint containment=] persist even if the element is not [=skipped=].
+			This is done to prevent layout changes that would be incurred by [=containment=] changes
+			as a result of an element entering and exiting the [=skipped=] state.
 		</div>
 	</div>
 
@@ -1244,7 +1248,7 @@ Restrictions and Clarifications {#cv-notes}
 
 1. From the perspective of an {{IntersectionObserver}},
 	the [=skipped contents=] of an element
-	are never intersecting the {{IntersectionObserver/root}}.
+	are never intersecting the [=intersection root=].
     This is true even if both the root and the target elements
     are in the [=skipped contents=].
 
@@ -1263,19 +1267,23 @@ Restrictions and Clarifications {#cv-notes}
 	Specifically, such changes will take effect right after
 	step 11 of <a href="https://html.spec.whatwg.org/multipage/webappapis.html#update-the-rendering">Update the Rendering</a> step of the Processing Model.
 
-    <div class=note>
-      Determining the viewport intersection of the element can be done with an
-      internal version of an IntersectionObserver. However, since the
-      observations from this are dispatched at step 12 of Update the
-      Rendering, any changes to the [=skipped=] (and thus painted) state will
-      not be visible to the user until the next frame's processing. For this
-      reason, updating the [=skipped=] state, including containment
-      adjustments, is deferred to that frame as well. This ensures that script
-      accessing, for example, the containment value of the element between
-      these two events (internal intersection observation and [=skipped=] state
-      update) will retrieve values consistent with current painted state and
-      not cause any forced layouts.
-    </div>
+	<div class=note>
+		Determining the viewport intersection of the element
+		can be done with an internal version of an IntersectionObserver.
+		However, since the observations from this are dispatched at
+		step 12 of Update the Rendering,
+		any changes to the [=skipped contents|skipped=] (and thus painted) state
+		will not be visible to the user until the next frame's processing.
+		For this reason, updating the [=skipped contents|skipped=] state,
+		including containment adjustments,
+		is deferred to that frame as well.
+		This ensures that script accessing,
+		for example,
+		the containment value of the element between these two events
+		(internal intersection observation and [=skipped contents|skipped=] state update)
+		will retrieve values consistent with current painted state
+		and not cause any forced layouts.
+	</div>
 
 4. For the purposes of scrolling operations,
 	such as {{Element/scrollIntoView()}},
@@ -1314,6 +1322,144 @@ Restrictions and Clarifications {#cv-notes}
 
 7. [=Skipped contents=] do not contribute to the result of {{HTMLElement/innerText}}.
 
+Accessibility Implications {#cv-a11y}
+-------------------------------------
+
+If a user agent exposes some form of "accessibility tree",
+akin to the DOM tree but specialized for accessibility use-cases such as screen-readers
+(thus providing the positions/etc of elements relevant to accessibility APIs,
+such as focusable elements),
+then the [=skipped contents=] of ''content-visibility: hidden'' elements
+must similarly be "skipped" (omitted) in the accessibility tree
+(similar to how ''display: none'' elements
+are omitted in all views of the document).
+
+[=Skipped contents=] of ''content-visibility: auto'' elements
+must not expose the fact that a user is interacting with the page via the accessibility tree,
+rather than via rendering visually to the screen.
+In particular, if a user agent uses ''content-visibility: auto''
+to avoid doing layout and painting work on off-screen content
+for displaying to the screen,
+it must similarly avoid doing that work on off-screen content
+for representing in the accessibility tree.
+If this is not possible
+(for example, if the user agent's representation of a focusable element in the accessibility tree
+requires knowledge of its exact position,
+and thus requires a full layout to be done on it and surrounding contents),
+then the user agent <em>must</em> omit the [=skipped contents=] from the accessibility tree entirely.
+
+Note: This requirement is intended to protect users utilizing accessibility tooling
+from being identified and profiled as such
+via observation of timing channels;
+if a user agent can skip significant amounts of work
+when rendering visually,
+but has to do all of the work when rendering to an accessibility tree,
+then an author can tell how a user is interacting with the page
+by observing the timing of layout operations.
+
+Examples {#cv-examples}
+-----------------------
+
+<div class=example>
+	<xmp highlight=markup>
+		<style>
+		.sv {
+			content-visibility: auto;
+			min-height: 50px;
+		}
+		</style>
+
+		<div class=sv>
+			... some content goes here ...
+		</div>
+	</xmp>
+
+	The .sv element's ''content-visibility: auto'' value
+	lets the user-agent manage whether the element is [=skipped=].
+	Specifically when this element is near the viewport,
+	the user-agent will begin painting the element.
+	When the element moves away from the viewport,
+	it will stop being painted.
+	In addition, the user-agent should skip as much of the rendering work as possible
+	when the element is [=skipped=].
+</div>
+
+<div class=example>
+	<xmp highlight=markup>
+		<style>
+		.sv {
+			content-visibility: hidden;
+		}
+		</style>
+
+		<div class=sv>
+			... some content goes here ...
+		</div>
+	</xmp>
+
+	In this case, the element is [=skipped=] regardless of viewport intersection.
+	This means that the only way to have the [=contents=] painted
+	is via script updating the value to remove 'content-visibility' or change its value.
+	As before, the user-agent should skip as much of the rendering in the [=contents=] as possible.
+
+	An additional effect of skipping rendering
+	is that the layout state of the [=contents=] can be preserved by the user-agent,
+	so that removing the 'content-visibility' property in the future
+	will cause the [=contents=] to be rendered quicker
+	than if they were hidden with ''display: none'' or similar.
+</div>
+
+<div class=example>
+	<xmp highlight=markup>
+	<style>
+	body {
+		margin: 0;
+	}
+	.sv {
+		content-visibility: hidden;
+		position: relative;
+		left: 10px;
+		top: 20px;
+	}
+	#child {
+		position: relative;
+		left: 1px;
+		top: 2px;
+		width: 100px;
+		height: 200px;
+	}
+	</style>
+
+	<div id=target class=sv>
+		<div id=child></div>
+		... some other content goes here ...
+	</div>
+	<script>
+		...
+		// This will force rendering work, including layout,
+		// if the UA previously avoided it.
+		target.firstElementChild.getBoundingClientRect();
+		...
+	</script>
+	</xmp>
+
+	Similarly to the last example, the element is [=skipped=].
+	The user-agent should avoid as much rendering work as possible.
+	However, in this example, at some point script accesses a layout value in the element's [=contents=].
+	In this situation, the user-agent cannot avoid rendering work
+	and has to process any previously skipped rendering work
+	in order to return a correct value to the caller.
+	In this example, the result of {{Element/getBoundingClientRect()}}
+	is a rect positioned at (11, 22) with a size 100x200.
+
+	Note that repeated calls to the same layout value
+	should not cause any additional rendering work,
+	since the user-agent should retain the last updated rendering state.
+
+	Also note that this situation in which rendering work is required is not unique.
+	There may be other situations in which the user-agent cannot avoid rendering work.
+</div>
+