Layout Transition Primitives

1. Introduction

[CSS3-TRANSITIONS] provide web authors with the ability to generate smooth transitioning effects when mutating the CSS of their web pages. However, the transitions that can be generated in this manner are limited in important ways, which make it difficult or impossible to use them in some cases.

In particular, CSS Transitions only operate on computed style values, such as between 100px and 200px; values that rely on layout, such as width: auto, can’t be used as the start or end of a transition.

Furthermore, CSS Transitions only work over actual CSS property values, but some of aspects of an element one might wish to transition are derived from other properties rather than being directly specified. For example, the position and size of an element positioned with Grid Layout is derived from its grid-placement properties, rather than being directly specified. An author can transition the grid-placement properties, but that will merely cause the element to "skip" from cell to cell as its grid-row-start and similar properties transition as integers; it won’t have the desired effect of making the element smoothly move between its start and end position. Relatedly, there is no reasonable way to express a transition when an element enters or leaves the document.

These shortcomings make [CSS3-TRANSITIONS] unsuitable for specifying transitions between laid out states of a web page. This specification provides a set of primitive JavaScript methods to enable transition-like graphical effects for complex layout changes.

1.1. Motivating Examples

Layout transition primitives can be used to programmatically control transitions between layout states. For example:

myDiv.suspendPainting();
CSS.elementSources.myDivSnapshot = myDiv.snapshot();
var div = document.createElement('div');
div.style.position = 'absolute';
div.style.left = myDiv.offsetLeft + 'px';
// ...
div.style.backgroundImage = 'element(myDivSnapshot)';
document.body.appendChild(div);
// perform layout
div.animate({left: myDiv.offsetLeft, ... }, 1).source.onEnd(function() {
  myDiv.resumePainting();
  div.remove();
});

container.suspendPainting();
CSS.elementSources.afterDivSnapshot = afterDiv.snapshot();
// .. create and insert snapshot element (see previous example)
container.appendBefore(afterDiv, newDiv);
var bounds = newDiv.recastElement();
new ParGroup([
  bounds.animate([{height: 0}, {height: bounds.height}], 1),
  div.animate({top: afterDiv.top}, 1)
]).source.onEnd(function() {
  myDiv.resumePainting();
  div.remove();
});

myDiv.suspendPainting();
CSS.elementSources.before = myDiv.snapshot();
// .. create and insert snapshot element (see previous example)
// perform layout
CSS.elementSources.after = myDiv.snapshot();
div.style.transition = 'background-image 1s';
div.style.backgroundImage = 'element(after)';
setTimeout(function() {
  myDiv.resumePainting();
  div.remove();
}, 1000);

2. IDL

partial interface Element {
  void suspendPainting();
  void resumePainting();
  Promise<OpaqueImageSnapshot> snapshot();
  ElementBounds recastElement();
  void cancelRecast();
};

interface OpaqueImageSnapshot {
};

interface ElementBounds {
  attribute DOMString left;
  attribute DOMString top;
  attribute DOMString width;
  attribute DOMString height;
  attribute DOMString transform;
  attribute DOMString transformOrigin;
  attribute DOMString opacity;
  attribute DOMString overflow;
};

Ensure that ElementBounds implements Animatable, assuming that this idea makes it into the Web Animations specification.

3. Suspending Painting - the suspendPainting() and resumePainting() methods

The suspendPainting() and resumePainting() methods on elements allow an author to control whether an element "paints", or is displayed on the screen. This is similar to using the visibility property, but more explicit and slightly more powerful. Like visibility and unlike other properties such as display, the element is still laid out and takes up space on the page as normal even if it’s not being painted.

Note: Suspending the painting of an element is commonly used with the other methods in this specification, to get the original element "out of the way" while script is simulating a transition of the element with snapshots and recastings.

When suspendPainting() is called on an element, the element’s painting suspended flag must be set. When resumePainting() is called on an element, the element’s painting suspended flag must be unset.

When an element’s painting suspended flag is toggled from unset to set, its subtree must be repainted.

This is actually trying to introduce the notion that suspendPainting() is an entry in the style updates queue. How should this be worded?

An element is suspended if its painting suspended flag is set, or if it has a parent element and that parent element is suspended.

Whether the painting suspended flag is set or unset must not change if the element is added or removed from the document.

When an element is suspended, its generated box is invisible (fully transparent, nothing is drawn), but still affects layout. This is similar to the effects of visibility: hidden

Note: Calling resumePainting() on an element which is suspended due to an ancestor having its painting suspended flag set will do nothing; the element’s painting suspended flag is already unset.

4. Snapshotting Elements - The snapshot() method

The snapshot() method takes a "snapshot" of an element, returning an image of the element at that time (even if the element is currently suspended) which is useful in implementing layout transitions, as described in the Examples section of this document.

When snapshot() is called on an element el, the user agent must perform the following steps:

1. Let snapshot be a newly-created OpaqueImageSnapshot object. Return snapshot, and complete the rest of these steps asynchronously.
2. Create a new style-dependent action action which, when executed, captures the current rendering of el, associates the rendering with snapshot, and resolves snapshot’s ready promise with undefined.
3. Push action onto el’s style updates queue.

Rewrite this to return a promise for a snapshot, rather than sync-returning a snapshot that then has a ready promise.

When asked to capture the current rendering of an element el, the user agent must produce the image that would be represented by an element() function referencing el at that moment, with the image having the same width and height as el does at that moment. If el is currently suspended, for the purposes of generating this image it is treated as being not suspended.

Note: Only the current element’s suspended state is altered for the purposes of generating a snapshot image. If descendant elements are also marked as suspended, then those elements will remain transparent in the snapshot.

Note: The image does not necessarily have to be a raster bitmap, as the actual image data is never directly exposed to the page. For example, some user agents use an intermediate vector-like representation of an element before the rasterization step; this alternative representation may be produced instead, so that the image can be rendered accurately at any target size without scaling artifacts.

Note: Due to the way the style updates queue works, if an author generates a snapshot before creating a new element and assigning the snapshot as a background image, it’s guaranteed that there will be no FOUC (flash of unstyled content). Any other order might generate a FOUC, depending on timing and user-agent-specific behavior.

Note: Snapshots never "expire" or otherwise become unusable, even if the element they are snapshotting is removed or deleted.

4.1. Snapshots: the OpaqueImageSnapshot object

OpaqueImageSnapshot objects are returned by the snapshot() method, and represent the rendering of an element at the time that snapshot() is called.

For security reasons, the image data represented by an OpaqueImageSnapshot object is not obtainable by any means; the image can only be displayed indirectly, by using the OpaqueImageSnapshot object in conjunction with CSS’s element() function and the elementSources map.

An OpaqueImageSnapshot object might represent an image. If it does, it provides a paint source, with the width, height, and appearance of the image it represents.

When the ready() method of an OpaqueImageSnapshot snapshot is called, user agents must perform the following steps:

1. Let ready promise be a newly-created Promise. Return it, and perform the rest of these steps asynchronously.
2. When snapshot represents an image, resolve ready promise with undefined.

Is there any way for a snapshot to fail? Deleting the element before it’s rendered?

5. Recasting Painting - The recastElement() and cancelRecast() methods

While snapshotting elements into static images is appropriate for many layout transitions, sometimes it is necessary to continuously lay out the element and its contents as it changes size and shape. However, the actual element can’t be used for this purpose, as it’s busy occupying space in the layout. Instead, a suspended element can have its painting recasted, rendering it at an explicitly-set size and position without moving it in the layout as far as the outer page is concerned.

When the recastElement() method is called on an element el, the user agent must perform the following steps:

1. If the element is not currently suspended, throw a ??? error and exit this algorithm.
2. If the element already has an associated ElementBounds object, return that object and exit this algorithm.
3. Create a new ElementBounds object bounds associated with el. Initialize the element bounds. Return bounds.

While an element has an associated ElementBounds object, it is recast.

If an element is recast, and stops being suspended for any reason, it must cancel recast, which causes its associated ElementBounds object to no longer be associated with it.

While an element is recast, it must be laid out twice. The first is as normal for a suspended element, to establish the space that the element takes up in the page.

The second treats the element as absolutely positioned with the initial containing block as its containing block, and the element’s width, height, left, top, opacity, and transform properties set to the corresponding values from the element’s associated ElementBounds object rather than the values obtained from the cascade. Additionally, the element’s right and bottom properties must be treated as auto for this layout. The element must then render as normal based on the results of this layout.

Modifying the element’s associated ElementBounds object must cause the element to perform its second layout with the new values, as if this were an ordinary style change.

Querying the style of any properties on the element must return the results of the first layout, not the second.

Note: Note that while an element is recast, any additional calls to recastElement() will return the same ElementBounds object.

When the cancelRecast() method is called on an element, the user agent must cancel recast on it.

Removing a recast element from the document causes that element to cancel recast. However, atomic moves within the same document do not cancel recast.

Note: recasting an element does not alter the suspended state of descendents of that element.

5.1. The ElementBounds Object

The ElementBounds object controls the position and size of a recast element’s rendering. It is returned by calling recastElement() on an element.

When asked to initialize the element bounds for an element el and an ElementBounds object eb, user agents must perform the following steps:

1. Lay out the element as normal.
2. Set the width, height, opacity, and transform attributes of eb to the used values of the corresponding properties from el.
3. Set the left and top attributes of eb to the offsets of el’s left and top edges, respectively, relative to the top left corner of the initial containing block.

6. Appendix A: The Style Updates Queue

Note: This section probably isn’t best placed here, but I need some terms defined that aren’t currently defined.

Each element in a document is associated with a style updates queue, containing style updates and style-dependent actions. A style update is a pending currently-unapplied change made to the style of an element on the page which might have an effect on the style, layout, or rendering of the element. A style-dependent action is an operation which relies on the element’s style, layout, and/or rendering being fully up-to-date.

Whenever a change is made to the page’s style that may affect an element, a style update must be pushed onto the element’s style updates queue. The element’s style, layout, and/or rendering must not be updated unless a corresponding style update is at the front of the style updates queue. When a style update is applied, it must be popped from the queue.

Similarly, style-dependent actions must not be executed unless they are at the front of the style updates queue. When they are executed, they must be popped from the queue.

User agents may delay applying style updates as long as they consider reasonable so as to batch any work caused by updating styles, layout, and rendering. User agents should prioritize applying style updates that precede a style-dependent action when a style-dependent action is in the queue.