[css-animations-2, css-transitions-2] Entry and exit animations for top-layer elements

[chrishtr]

Animating an element into and out of the top layer provides context to the user for a more useful and pleasant interaction. Currently, developers have no way to do so in a way that preserves top-layer status during the animation, and as a result, demos like this one won’t work in cases where exiting the top layer causes a visible change of positioning or z-index. Let's fix that.

TL;DR of proposal

Introduce a new CSS property called top-layer that can be targeted by web developers in their CSS transitions and animations.

This CSS property is not generally available to web developers and will always be set with an !important UA style sheet rule. It’s defined as a CSS property for the purpose of a layered definition that fits within existing animations APIs and concepts, and as a result is easy for developers to use with existing animation APIs.

Example: a <dialog> remaining in the top layer during a 200ms opacity animation during close. The part marked as "New!" is the only addition needed for the developer to delay top-layer removal until the end of the animation.

@keyframes open {
  from { opacity: 0; }
  /* Ending at opacity: 1 is implicit, per existing CSS animations spec */
}
dialog:closed {
  opacity: 1; /* UA default */
  animation: open 200ms;
  transition: top-layer 200ms; /* New! */
}
@keyframes close {
  from { display: block; }
 /* Starting from opacity 1 is implicit, per existing CSS animations spec */ 
  to { opacity: 0; }
}
dialog {
  animation: close 200ms;
}

(full demo except for top-layer here)

Details

Use case

This feature enables support for animation when entering or leaving the top layer. Such animations often wish to preserve top-layer rendering during the course of an “exit” or "entry" animation. Without this feature, it is impossible to perform such an animation.

Top-layer APIs: <dialog>, fullscreen, and popover.

Note: The demo in the TL;DR uses CSS animations, but a CSS transition would additionally require this issue to be resolved to be usable for entry transition animations. We also need to support animating display:none for top layer animations that need it, such as <dialog> (tracked here).

Background on the top layer

The top layer is defined here. It is currently accessed only via the Fullscreen API (here) and the <dialog> element’s showModal method (here). When opening a fullscreen element, the fullscreen spec says “add it to its node document’s top layer”. When closing fullscreen, it says “remove it from its node document’s top layer”.

When calling showModal, the <dialog> spec says “add subject [the dialog element] to subject's node document's top layer”. When closing a dialog, it says “If subject is in its Document's top layer, then remove it”. If an element is already in the top layer, re-adding it to the top layer moves it to the top of the top layer.

Proposed Definition of the top-layer CSS property

The top-layer CSS property determines whether an element is in the top layer. It has two values:

top-layer: browser; /* element is in the top layer */
top-layer: none; /* element is not in the top layer */

• Default: none
• Animatable: yes
• Discrete: yes
• Accessible to developers: only via transition CSS property values

When an element is “added to the top layer” (see previous section), it is placed in the ordered set of top-layer elements, but the rendering effect of the top layer (putting it in the top-layer stacking context and obeying the rendering order of the ordered set) only applies when top-layer is set.

The element is only removed from the ordered set once top-layer’s computed style has evaluated to none (at the end of the transition, if any). However, the “moved to the top of the top layer” behavior still occurs if the element is “added to the top layer” while animating out (see previous section).

The following UA style rules are added:

dialog {
 top-layer: none !important;
}

dialog:modal:open {
  top-layer: browser !important;
}

:fullscreen {
  top-layer: browser !important;
}

Why shouldn't developers be able to change top-layer outside of transitions?

It’s important to restrict direct developer access because the top layer is a UA-managed resource. Not giving developers direct access guarantees that the UA is able to show top layer content on top of other content, and control eviction from the top layer when needed. This point has been discussed in #6965. If in the future a "developer" top layer is added below the browser one, we could potentially add a third value to top-layer.

[andruud]

I thought the concept of "UA-private except for transitions" seemed odd at first, but I suppose it could be expressed as adding a UA rule (before the other rules):

* {
  top-layer: initial !important;
}

[chrishtr]

I thought the concept of "UA-private except for transitions" seemed odd at first, but I suppose it could be expressed as adding a UA rule (before the other rules):

Good idea! I think this should work, because transitions are at the highest priority of the cascade. It would also avoid introducing a new "UA private" concept, which is a plus.

[chrishtr]

Good idea! I think this should work, because transitions are at the highest priority of the cascade. It would also avoid introducing a new "UA private" concept, which is a plus.

I went ahead and edited the original proposal to remove "UA private" and replace with !important UA style sheet rules. I tested in Chromium and found that transition animations work as expected.

[tabatkins]

...huh. This seems like an incredibly clever hack. I'm not opposed to it!

[khushalsagar]

When an element is “added to the top layer” (see previous section), it is placed in the ordered set of top-layer elements, but the rendering effect of the top layer (putting it in the top-layer stacking context and obeying the rendering order of the ordered set) only applies when top-layer is set.

I'm unclear on the exact effect of adding this element to the the ordered set but not changing its rendering order. There is a set of rules defined here, the change in rendering order (by updating the element's parent stacking context) is part of it. But isn't all of this deferred by the transition property which delays updating the top-layer value?

[LeaVerou]

I thought the concept of "UA-private except for transitions" seemed odd at first, but I suppose it could be expressed as adding a UA rule (before the other rules):

Good idea! I think this should work, because transitions are at the highest priority of the cascade. It would also avoid introducing a new "UA private" concept, which is a plus.

What prevents developers from applying an animation like:

@keyframes foo {
	from, to { top-layer: browser }
}

.foo {
	animation: foo 1s infinite paused both; /* actually any of these keywords by itself works too */
}

to put elements in the top-layer?

[emilio]

@LeaVerou that'd be in the animations, not transition origin.

[LeaVerou]

@emilio Then transition: 999999999s top-layer to make it last forever after a given trigger 🤷🏽‍♀️

My point is that this is a clever hack, but a hack nevertheless, and can be worked around to at least some degree.

[css-meeting-bot]

The CSS Working Group just discussed Entry and Exit Animations for top-layer elements.

The full IRC log of that discussion

<fantasai> Topic: Entry and Exit Animations for top-layer elements
<fantasai> github: https://github.com//issues/8189
<fantasai> flackr: When certain elements go in/out of top layer
<fantasai> flackr: if devs want to have an naimation on the, they need the element to remain in the top layer for duration of the animation
<fantasai> flackr: so proposal is that we allow specifying top layer in the transition properties
<fantasai> flackr: but that it's otherwise not a developer-stylable property
<fantasai> flackr: essentially, you can specify transition: top-layer
<fantasai> flackr: and give it a duratoin
<fantasai> flackr: and this is the duration during which the element stays in the top layer
<Rossen_> q?
<ntim> q+
<Rossen_> ack ntim
<fantasai> ntim: I've always been against the top-layer CSS property concept
<fantasai> ntim: The concept should really stay abstracted away from the developer
<fantasai> ntim: even just introducing this property is a bad first step, I think
<lea> q?
<lea> q+
<emilio> q+
<fantasai> lea: I wanted to as ntim why he thinks this concept should be abstracted away from the developer
<fantasai> lea: there's a lot of reasons it should controllable in CSS
<Rossen_> ack lea
<fantasai> lea: we keep seeing use cases that could be solved if could be controlled in CSS
<fantasai> ntim: If you allow controlling top layer with CSS, you end up with same issues as z-index
<fantasai> ntim: the appeal of top layer right now is that it's controlled by order of JS API calls
<lea> q?
<flackr> q+
<fantasai> ntim: but once you start allowing random elements to put top-layer, then what order is actually used in the end?
<fantasai> lea: I think that depends on how we design the feature
<fantasai> lea: maybe it's a property that just the UA controls
<fantasai> lea: though I hope to avoid that
<fantasai> ntim: I think it needs a real design
<fantasai> ntim: just exposing this concept...
<chrishtr> Note that the proposal is not incompatible with ntim's concern. I agree with his concern.
<fantasai> lea: yes, absolutely, does need design work to do it properly to not have problems of z-index
<fantasai> lea: total +1 to that
<lea> q?
<Rossen_> ack emilio
<fantasai> emilio: I don't think I have a strong feeling wrt top layer property
<fantasai> emilio: but basically the use case seems to be transitioning modal dialogs and so on when opening and closing
<fantasai> emilio: and I assume other elements in the top layer
<fantasai> emilio: to me that seems like a use case that non-modal dialogs also need
<fantasai> emilio: there are dialogs that may not be in the top layer
<fantasai> emilio: so feels to me that this is a clever hack to avoid having closing/closed state on the dialog and fullscreen things
<fantasai> emilio: not sure if that's been considered
<fantasai> emilio: so why is this property better
<fantasai> emilio: why not say that it goes from open to non-open, have an intermediate state, and define that intermediat state transition as when all its transitions have finished
<Rossen_> ack flackr
<fantasai> flackr: Wrt tim's concern about exposing top-layer to the user, we have these stackign questions
<fantasai> flackr: this proposal nicely avoids, because things remain in their current stacking position
<fantasai> flackr: so we don't have to change any of that or figure out those definitions yet
<fantasai> flackr: I don't understand what non-modal dialogs have a problem, they can continue to apply their desired z-index
<fantasai> emilio: but you still have the issue of if you want a close animation on a dialog, you need to do it manuall
<Rossen_> q?
<fantasai> flackr: dialog element, which is top-layer?
<fantasai> emilio: dialog may or may not be top layer depending on show vs showModal
<masonf> If the dialog isn't modal, it isn't in the top layer, and you don't need this.
<fantasai> flackr: It would maintain its top layer state during transition, but still have to define the animation
<chrishtr> q+
<fantasai> emilio: idea is you can do opacity or transform or whatever to hide the dialog, right?
<fantasai> emilio: right now that's not easy to do with non-modal dialogs either
<fantasai> emilio: why not have ...
<fantasai> emilio: Firefox has all its panels as well, we have animations when you use menus
<fantasai> emilio: and those are just web elements
<fantasai> emilio: internally we have 5 states
<fantasai> emilio: open, opening, closing, closed
<fantasai> emilio: we ahve intermediate states so that the front end can actually use transitions for this stuff
<fantasai> emilio: my question is, why is this specific to top-layer and not to elements that pop in and out
<fantasai> flackr: you can't reasonably establish entry animations is resolved by setting inital styles
<fantasai> flackr: with that, should be possible to do on non-modal dialogs
<fantasai> flackr: top-layer is the only thing they don't have access to
<fantasai> flackr: the model is consistent with other things taht have a state change trigger an animation
<fantasai> flackr: state changes immediately, even though animation continues to run
<masonf> non-modal dialogs need the ability to animate to/from display:none, but that's a separate issue.
<fantasai> emilio: when non-modal dialog closes, you want to ?? animation to displaY:none
<fantasai> emilio: you transitoin display, which we resolved to do but don't yet do
<fantasai> emilio: so your proposeal would be to animation display directly and also transition opacity
<fantasai> flackr: I have proof of concept for Chrome
<lea> q?
<fantasai> emilio: so this proposal is to explicitly allow z-order to remain while transitioning
<lea> q+
<fantasai> emilio: like transitioning display
<fantasai> emilio: on one hand, I thin it would be less weird to have these intermediate states
<fantasai> emilio: when you open dialog, you transition to opening state
<fantasai> emilio: when you update style and don't have transitions running you're open
<fantasai> emilio: etc.
<fantasai> emilio: when no pending ransitions transition to closed
<fantasai> emilio: only targetted to dialogs/popovers/etc. but I think that's the main use case
<fantasai> emilio: I think that would be slightly less weird for authors
<fantasai> emilio: rather than transitioning display ...
<fantasai> emilio: having magic property seems weird
<fantasai> emilio: I guess this proposal weird, but I think maybe having intermediate pseudo-classes could be more elegant and usable for authors
<fantasai> flackr: I think this is more consistent with other state changes for the Web
<Rossen_> ack fantasai
<fantasai> fantasai: why not have things just stay in the top layer until their transitions are done automatically?
<fantasai> ntim: That seems to make sense
<fantasai> chrishtr: Having a transitioning state and this automatically detect what they're happening and preserve top layer during UA was thoroughly explored during popover design
<fantasai> chrishtr: and prototyped in Chromium
<fantasai> chrishtr: was specific to popover and dialog, and why not have a generic mechanism in animations
<fantasai> chrishtr: this is what lead to these proposals for display:none animations and specifying top-layer duration
<fantasai> chrishtr: without specifying UA magic to detect length of animations
<Rossen_> ack chrishtr
<ntim> q+
<fantasai> chrishtr: discussed at length in popover API proposal
<Rossen_> ack lea
<fantasai> lea: firstly, it seems weird to have a property that only works in transitions
<fantasai> lea: if devs want to put things in the top layer, what prevents them from adding an animation that puts them in the top layer?
<fantasai> emilio: ....
<fantasai> lea: so only available in transitions?
<fantasai> lea: what prevents having a transition that lasts 999999s?
<fantasai> emilio: you'd need to call modal
<fantasai> lea: trying to prevent devs by adding only to transitions, it's a hack and can be worked around
<fantasai> emilio: I agree
<Rossen_> q?
<fantasai> emilio: internally, how we implement top layer
<fantasai> emilio: I'm not sure how I feel about this
<flackr> q+
<fantasai> [missed]
<fantasai> Rossen_: let's end this topic right here
<fantasai> Rossen_: we coered quite a bit, but this doesn't seem ready for resolution
<fantasai> Rossen_: was well articulated and proposed, and good path forward for addressing some of the TAG review comments
<fantasai> Rossen_: shoudl take conversation back to GH, and should bring it back when it's more developed
<flackr> q-

[flackr]

@emilio Then transition: 999999999s top-layer to make it last forever after a given trigger 🤷🏽‍♀️

My point is that this is a clever hack, but a hack nevertheless, and can be worked around to at least some degree.

The browser is still in control of what is in the top layer and its order, which isn't true if exposed as a generic css property. While your example is a hint to the browser that once in the top layer the element should remain in the top layer basically forever, the browser is allowed to still evict it in certain circumstances and can also guarantee that new content shows above the old content (e.g. a new fullscreen element or top layer dialog will go above).

[khushalsagar]

@emilio @LeaVerou I think that problem is gonna stay no matter what solution we take if we acknowledge the use-case. We want developers to be able to keep elements in top layer for the duration of an animation, the length of which should be in developer's control. Whether that happens via :open/:closed pseudo-classes or transition: top-layer, the author is going to be able to keep elements in top layer indefinitely. We could carve out a special duration cap for transitions involving top-layer to address this if needed.

[nt1m]

@chrishtr mentioned that was objection around appending things to top layer during the transition. I believe the objection was more around the :top-layer pseudo and the interactions around it regarding transition (e.g. :top-layer would be matching even when the popup isn't open). Now that the pseudo-class is named :open/:closed, I think this approach can potentially be revisited. (Although feel free to correct me if I'm missing something)

cc @fantasai who brought this up during the call.

[nt1m]

Also, I'd like to re-iterate my objection to exposing the name "top layer" explicitly to the web platform.

These are the reasons why:

• There is general confusion with the name "top layer", e.g. is it the "topmost" element in the top-layer, or is this every element in the top layer? (In the specs, it refers to the the whole stack of elements).
• Top layer was meant as an UA implementation detail to alleviate z-index issues. It's OK to document it, just like we document UA presentational hints, but I believe it's generally a bad pattern to expose this vocabulary to the language itself.

If we want to consider exposing top layer to random elements, I think that's a discussion that needs to happen independently, with a proper discussion around naming, before exposing it to the language.