[css-position-4] Make 'rendered in the top layer' depend on 'overlay'…

… as well, to allow for entry animations as well. #8730

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: