[css-position-4] Make 'rendered in the top layer' depend on 'overlay' as well, to allow for entry animations as well. w3c#8730

Author: tabatkins

css-position-4/Overview.bs

@@ -488,7 +488,8 @@ Top Layer Manipulation {#top-manip}
 <div algorithm>
 	An element |el| is <dfn export lt="render in the top layer">rendered in the top layer</dfn>
 	of an optional {{Document}} |doc|
-	if |el| is [=list/contained=] in |doc|'s [=Document/top layer=].
+	if |el| is [=list/contained=] in |doc|'s [=Document/top layer=],
+	and |el| has ''overlay: auto''.
 
 	If |doc| is not passed,
 	it's [=rendered in the top layer=]
@@ -596,43 +597,36 @@ Inherited: no
 Animation Type: (see prose)
 </pre>
 
-The 'overlay' property is used to help determine
-whether an element should be in the [=Document/top layer=] or not.
+The 'overlay' property determines
+whether an element is [=rendered in the top layer=] or not.
 
 <dl dfn-type=value dfn-for=overlay>
 	: <dfn>none</dfn>
-	:: The element shouldn't be in the [=Document/top layer=].
+	:: The element isn't [=rendered in the top layer=].
 
 	: <dfn>auto</dfn>
-	:: The element should be in the [=Document/top layer=].
+	:: The element is [=rendered in the top layer=].
 		Rather than generating boxes as part of its normal position in the document,
-		it generates boxes as a sibling of the root element.
+		it generates boxes as a sibling of the root element,
+		rendered "above" it.
 </dl>
 
 <div class=note id=overlay-guidance>
-	Note: 'overlay' is a somewhat unusual property:
-	it is <em>only</em> set by the user agent,
+	Note: 'overlay' is a somewhat unusual property,
+	as it is <em>only</em> set by the user agent,
 	and can't be set by authors <em>at all</em>.
-	As well, it has almost no effect:
-	an element is [=rendered in the top layer=]
-	as soon as it's [=in the top layer=]
-	and stops as soon as it's not;
-	the 'overlay' property doesn't affect this.
-
-	However, when the user agent wants to remove an element from the [=Document/top layer=],
-	it checks 'overlay' first;
-	if it's still ''overlay/auto'',
-	it delays the removal until it's ''overlay/none''.
-	The user agent is in control of when it goes from ''overlay/auto'' to ''overlay/none'',
-	but authors <em>can</em> set a 'transition' on 'overlay',
-	delaying its change.
-
-	This delay period can then be paired with other animations or transitions
-	to create an "exit animation"--
-	animating the element leaving the top layer,
-	for example by fading its 'opacity'--
-	without it <em>also</em> immediately rendering back in the normal document
-	and possibly becoming obscured.
+
+	However, authors <em>do</em> have the ability to affect
+	<em>when</em> 'overlay' changes its value,
+	by setting a 'transition' on the property.
+	This allows an author to align an animation
+	with the transition,
+	with the element moving in or out of the top layer
+	only at the desired point in the animation.
+	This allows, for example,
+	an animation that causes an element to fade out of its normal position on the page,
+	then fade in at its new top-layer position,
+	or vice versa.
 </div>
 
 For animation,
@@ -643,6 +637,12 @@ and other values of p map to the closer endpoint;
 if neither value is ''overlay/auto'' then discrete animation is used.
 
 Note: This is similar to how 'visibility' animates.
+With most [=easing functions=],
+this will keep the element [=rendered in the top layer=]
+for the entire duration of the transition,
+whether it's entering or leaving the top layer.
+''step-start''/''step-end''/''linear()''
+can be used to control when the value flips more precisely.
 
 User agents must have the following rule in their UA stylesheet: