[css-view-transitions-2] Add nested view transition groups spec (#13412)

* Add nested view transition groups spec

Author: vmpstr

css-view-transitions-2/Overview.bs

@@ -131,7 +131,7 @@ spec:css2; type:dfn; text:viewport
 			and more specifically based on the active view transition being of a certain type.
 		* [[#shared-style-with-vt-classes|Sharing styles between view transition pseudo-elements]], a way to declare a style once,
 			and use it for multiple view transition pseudo-elements. This includes the 'view-transition-class' property, and [[#pseudo-element-class-additions|additions to named pseudo-elements]]
-		* [[#nested-vt|Nested view transition groups]], a way to construct deeper hierarchies of view transition pseudo-elements,
+		* [[#view-transition-group-prop|Nested view transition groups]], a way to construct deeper hierarchies of view transition pseudo-elements,
 			which in turn allows relative transforms and clipping of participating elements.
 		* [[#scoped-vt|Scoped view transitions]], a way to perform view transitions within the scope of a DOM subtree.
 
@@ -1024,9 +1024,127 @@ the active view transition of an element is exposed to script via a property on
 	[=document-scoped view transition names=] don't accidentally interfere with
 	other [=scoped view transitions=] in the ancestor chain.
 
-# Nested View Transition Groups # {#nested-vt}
+## Nested View Transition Groups: The 'view-transition-group' property ## {#view-transition-group-prop}
 
-	ISSUE: This needs to be explained / specified.
+	<pre class=propdef>
+	Name: view-transition-group
+	Value: normal | contain | nearest | <<custom-ident>>
+	Initial: normal
+	Inherited: no
+	Percentages: n/a
+	Computed Value: as specified
+	Animation type: discrete
+	</pre>
+
+	The 'view-transition-group' property can be used in conjuction with 'view-transition-name' to generate a hierarchy of [=named view transition pseudo-element=].
+	This property has no effect if 'view-transition-name' is ''view-transition-name/none''.
+
+	<dl dfn-type=value dfn-for=view-transition-group>
+		: <dfn>normal</dfn>
+		:: The ''view-transition-group()'' [=pseudo-element=]
+			generated by this element
+			is a child of the ''view-transition-group-children()'' [=pseudo-element=]
+			generated by this element's nearest ''view-transition-group()'' generating
+			[=flat tree=] ancestor element
+			with a non-''view-transition-group/normal'' 'view-transition-group' value,
+			if any.
+			If no such element is present, the ''view-transition-group()'' [=pseudo-element=]
+			generated by this element
+			is a direct child of the ''::view-transition'' [=pseudo-element=]
+			associated with this view transition.
+		: <dfn>contain</dfn>
+		:: The ''view-transition-group-children()'' [=pseudo-element=]
+			generated by this element acts as a container for its descendants.
+			See ''view-transition-group/normal'' for the effect it has on other elements.
+		: <dfn>nearest</dfn>
+		:: The ''view-transition-group()'' [=pseudo-element=]
+			generated by this element
+			is a child of the ''view-transition-group-children()'' [=pseudo-element=]
+			generated by this element's nearest ''view-transition-group()'' generating
+			[=flat tree=] ancestor element,
+			if any.
+			If no such element is present, the ''view-transition-group()'' [=pseudo-element=]
+			generated by this element
+			is a direct child of the ''::view-transition'' [=pseudo-element=]
+			associated with this view transition.
+		: <dfn><<custom-ident>></dfn>
+		:: The ''view-transition-group()'' [=pseudo-element=]
+			generated by this element
+			is a child of the ''view-transition-group()'' [=pseudo-element=]
+			generated by this element's [=flat tree=] ancestor element
+			with a ''view-transition-name'' value that matches '<<custom-ident>>', if any.
+			If no such element is present, the ''view-transition-group()'' [=pseudo-element=]
+			generated by this element
+			is a direct child of the ''::view-transition'' [=pseudo-element=]
+			associated with this view transition.
+	</dl>
+
+	The ''view-transition-group-children()'' [=pseudo-element=] is generated
+	if and only if there is a ''view-transition-group()'' [=pseudo-element=] attached to it.
+
+	The [=used value=] for 'view-transition-group' resolves to a 'view-transition-name' in its ancestor chain, or to ''view-transition-name/none''. When generating the [=named view transition pseudo-element=], the ''::view-transition-group()'' with that name
+	would create a ''::view-transition-group-children()'' pseudo-element, which would be the parent of the ''::view-transition-group()'' generated for this element's 'view-transition-name'.
+
+### Nested View Transition Group Explanation ### {#nested-overview}
+
+*This section is non-normative.*
+
+By default, setting `view-transition-name` on multiple elements generates a flat [=view transition tree=], where all the ''::view-transition-group()'' pseudo-elements are children of the ''::view-transition'' pseudo-element.
+This is sufficient for many simple use-cases, but there are some styling use-cases that cannot be achieved with a flat tree.
+The most prominent use-case is clipping: with a flat tree, all pseudo-elements are clipped to the [=snapshot containing block=], so clipping elements in the normal tree would lose their clipping during the view-transition, resulting in a broken visual effect.
+The effects that have can have an unexpected visual effect in a flat tree:
+* Clipping ('overflow', 'clip-path', 'border-radius'): clipping affects the children of the element.
+* 'opacity', 'mask-image' and 'filter': These effects that are designed to work on a fully rasterized image of a tree, rather than on each item individually.
+* 3D transforms ('transform-style', 'transform', 'perspective'): to display the full range of 3D transform animations, some hierarchy needs to be kept.
+
+To enable these use cases, this specification introduces the concept of nesting view-transition pseudo-elements. By using the 'view-transition-group' CSS property,
+the author can assign a "parent group" for a generated ''::view-transition-group()'' pseudo-element, creating a hierarchy in the [=view transition tree=].
+
+### Examples ### {#nested-vt-example}
+
+<div class="example">
+This example creates a transition where the [=view transition tree=] is nested instead of flat:
+
+```html
+<section class="container">
+	<article>Content</article>
+</section>
+```
+
+```css
+.container {
+	view-transition-name: container;
+}
+
+.container,
+::view-transition-group-children(container) {
+	clip-path: circle();
+}
+
+article {
+	view-transition-name: article;
+	view-transition-group: container;
+}
+```
+
+The pseudo-element tree for this would be as follows:
+```
+	::view-transition
+	├─ ::view-transition-group(container)
+	│  ├─ ::view-transition-image-pair(container)
+	│  │  ├─ ::view-transition-old(container)
+	│  │  └─ ::view-transition-new(container)
+	│  └─ ::view-transition-group-children(container)
+	│     ├─ ::view-transition-group(article)
+	│     │  ├─ ::view-transition-old(article)
+	│     │  └─ ::view-transition-new(article)
+	│     └─ ...other nested groups...
+	└─ …other groups…
+```
+
+By applying the ''clip-path'' to both the containing element and its generated ''::view-transition-group-children()'' pseudo-element, we preserve the clip during the transition,
+and by applying ''view-transition-group'' to the internal element referencing the container, we make the tree "nested" in a way that would apply this clipping.
+</div>
 
 # Scoped View Transitions # {#scoped-vt}
 
@@ -1121,7 +1239,26 @@ the active view transition of an element is exposed to script via a property on
 		This enables full customization of the transition.
 	</div>
 
-	ISSUE: We need an example of view transition nested groups as well.
+	<div class=note>
+		When using ''view-transition-group'' property,
+		an additional ''::view-transition-group-children()'' pseudo is created
+		that allows for clipping of descendants and specifying relative transforms.
+
+		```
+		::view-transition
+		├─ ::view-transition-group(name)
+		│  ├─ ::view-transition-image-pair(name)
+		│  │  ├─ ::view-transition-old(name)
+		│  │  └─ ::view-transition-new(name)
+		│  └─ ::view-transition-group-children(name)
+		│			└─ …groups nested under 'name'…
+		└─ …other groups…
+		```
+
+		''view-transition-group-children()'' element can now be customized to add, for example, clipping with
+		'overflow: clip'. This would clip any ''view-transition-group()'' pseudo-elements along with their
+		descendants.
+	</div>
 
 ### Named View Transition Pseudo-elements ### {#named-view-transition-pseudo}
 
@@ -1247,7 +1384,20 @@ the active view transition of an element is exposed to script via a property on
 	Note: The content and [=natural dimensions=] of the image are captured in [=capture the image=],
 	then set and updated in [=setup transition pseudo-elements=] and [=update pseudo-element styles=].
 
-ISSUE: `::view-transition-group-children()` needs to be specified here.
+### View Transition Group Children: the ''::view-transition-group-children()'' pseudo-element ### {#::view-transition-group-children}
+
+	The <dfn>::view-transition-group-children()</dfn> [=pseudo-element=]
+	is created when mandated by the ''view-transition-group'' property
+	on either the element itself or on its contained element.
+	It serves as a container for descendant ''view-transition-group()'' pseudo-elements.
+	By default, it is sized to the same size as the corresponding ''view-transition-group()'' pseudo element.
+	By default, it has a transparent border that matches the size and shape of the border on the element that caused this structure to be created.
+
+	Note: The size and border setting on this pseudo element allow the developer
+	to enable clipping of the descedant pseudo elements with a simple ''overflow:
+	clip'' property. The developer needs to take care if the original element has
+	non-overscroll scrollbars, since these scrollbars change the clipping area
+	from the default provided by this element.
 
 # View Transition Layout # {#view-transition-rendering}
 
@@ -2090,101 +2240,6 @@ To resolve the [=used value=] of 'view-transition-name' for |element|:
 
 A 'view-transition-name' generated by <css>auto</css> is a [=tree-scoped name=].
 
-# Nested view-transition groups # {#nested-view-transition-groups}
-
-## Overview ## {#nested-overview}
-
-*This section is non-normative.*
-
-By default, setting `view-transition-name` on multiple elements generates a flat [=view transition tree=], where all the ''::view-transition-group()'' pseudo-elements are children of the ''::view-transition'' pseudo-element.
-This is sufficient for many simple use-cases, but there are some styling use-cases that cannot be achieved with a flat tree.
-The most prominent use-case is clipping: with a flat tree, all pseudo-elements are clipped to the [=snapshot containing block=], so clipping elements in the normal tree would lose their clipping during the view-transition, resulting in a broken visual effect.
-The effects that have can have an unexpected visual effect in a flat tree:
-* Clipping ('overflow', 'clip-path', 'border-radius'): clipping affects the children of the element.
-* 'opacity', 'mask-image' and 'filter': These effects that are designed to work on a fully rasterized image of a tree, rather than on each item individually.
-* 3D transforms ('transform-style', 'transform', 'perspective'): to display the full range of 3D transform animations, some hierarchy needs to be kept.
-
-To enable these use cases, this specification introduces the concept of nesting view-transition pseudo-elements. By using the 'view-transition-group' CSS property,
-the author can assign a "parent group" for a generated ''::view-transition-group()'' pseudo-element, creating a hierarchy in the [=view transition tree=].
-
-## Examples ## {#nested-vt-example}
-
-<div class="example">
-This example creates a transition where the [=view transition tree=] is nested instead of flat:
-
-```html
-<section class="container">
-	<article>Content</article>
-</section>
-```
-
-```css
-.container {
-	view-transition-name: container;
-}
-
-.container,
-::view-transition-group-children(container) {
-	clip-path: circle();
-}
-
-article {
-	view-transition-name: article;
-	view-transition-group: container;
-}
-```
-
-The pseudo-element tree for this would be as follows:
-```
-	::view-transition
-	├─ ::view-transition-group(container)
-	│  ├─ ::view-transition-image-pair(container)
-	│  |  ├─ ::view-transition-old(container)
-	│  |  └─ ::view-transition-new(container)
-	│  └─ ::view-transition-group-children(container)
-	│     ├─ ::view-transition-group(article)
-	│     |  ├─ ::view-transition-old(article)
-	│     |  └─ ::view-transition-new(article)
-	│     └─ ...other nested groups...
-	└─ …other groups…
-```
-
-By applying the ''clip-path'' to both the containing element and its generated ''::view-transition-group-children()'' pseudo-element, we preserve the clip during the transition,
-and by applying ''view-transition-group'' to the internal element referencing the container, we make the tree "nested" in a way that would apply this clipping.
-</div>
-
-## The 'view-transition-group' property ## {#view-transition-group-prop}
-
-	<pre class=propdef>
-	Name: view-transition-group
-	Value: normal | contain | nearest | <<custom-ident>>
-	Initial: normal
-	Inherited: no
-	Percentages: n/a
-	Computed Value: as specified
-	Animation type: discrete
-	</pre>
-
-	The 'view-transition-group' property can be used in conjuction with 'view-transition-name' to generate a hierarchy of [=named view transition pseudo-element=].
-
-	The [=used value=] for 'view-transition-group' resolves to a 'view-transition-name' in its ancestor chain, or to ''view-transition-name/none''. When generating the [=named view transition pseudo-element=], the ''::view-transition-group()'' with that name
-	would create a ''::view-transition-group-children()'' pseudo-element, which would be the parent of the ''::view-transition-group()'' generated for this element's 'view-transition-name'.
-
-### View Transition Tree Root: the ''::view-transition-group-children'' pseudo-element ### {#view-transition-group-children-pseudo}
-
-	The <dfn>::view-transition-group-children()</dfn> [=pseudo-element=]
-	is a [=named view transition pseudo-element=]
-	that represents a matching named [=view transition=] capture.
-	A ''::view-transition-group-children()'' [=pseudo-element=]
-	is generated based on the 'view-transition-group' property,
-	as a [=tree/child=] of the corresponding ''::view-transition-group()'' [=pseudo-element=],
-	and contains one or more ''::view-transition-group()'' elements, corresponding to the nested groups.
-	See the [=used group name=] and related algorithms.
-
-	The ''::view-transition-group-children()'' [=pseudo-element=] is positioned after its sibling ''view-transition-image-pair()''.
-	It is used to control effects like clipping or masking of nested children.
-
-
 # Algorithms # {#algorithms}
 
 ## Data Structures ## {#concepts}
@@ -2965,19 +3020,10 @@ To resolve the <dfn>used group name</dfn> of an {{Element}} |element|, perform t
 	1. Let |containingGroupName| be |element|'s [=nearest containing group name=] given |transition|.
 	1. Return the first matching statement, switching on |group|:
 
-	<dl dfn-type=value dfn-for=view-transition-group>
-		: <dfn>normal</dfn>
-		: <dfn>contain</dfn>
-		:: |containingGroupName|.
-
+		* ''view-transition-group/normal'', ''view-transition-group/contain'': |containingGroupName|.
 			Note: an element with ''view-transition-group/contain'' becomes the [=nearest containing group name=] for its descendants.
-
-		: <dfn>nearest</dfn>
-		:: The [=document-scoped view transition name=] of the element's nearest [=flat tree=] ancestor which participates in the |transition|.
-
-		: <dfn><<custom-ident>></dfn>
-		:: |group| if the element has a [=flat tree=] [=tree/ancestor=] whose [=document-scoped view transition name=] is |group| and participates in |transition|; Otherwise |containingGroupName|.
-	</dl>
+		* ''view-transition-group/nearest'': The [=document-scoped view transition name=] of the element's nearest [=flat tree=] ancestor which participates in the |transition|.
+		* ''view-transition-group/<custom-ident>'': |group| if the element has a [=flat tree=] [=tree/ancestor=] whose [=document-scoped view transition name=] is |group| and participates in |transition|; Otherwise |containingGroupName|.
 </div>
 
 #### Compute the old 'view-transition-group' #### {#vt-group-capture-old}
@@ -3489,6 +3535,7 @@ This appendix is <em>informative</em>.
 Changes from <a href="https://www.w3.org/TR/2024/WD-css-view-transitions-2-20240516/">2024-05-16 Working Draft</a>
 </h3>
 
+* Add description of nested view transition groups, which was partially missing.
 * Update wording to use `opacity: 0` instead of `visibility: hidden`. See <a href="https://github.com/w3c/csswg-drafts/issues/12629">issue 12629</a>.
 * Replace `contain: view-transition` with `view-transition-scope` property (<a href="https://github.com/w3c/csswg-drafts/issues/13123">pending #13123</a>)
 * Reorder sections, editorial changes, added several issues, updated scoped view transition wording.