[shadow-styling] Rearrange more sections.

Author: tabatkins

shadow-styling/Overview.bs

@@ -16,15 +16,14 @@ Introduction</h2>
 
 	...
 
+
+
 <h2 id='shadow-dom'>
-Shadow DOM CSS Concepts</h2>
+Shadow Encapsulation</h2>
 
 	The Shadow DOM spec augments the DOM with several new concepts,
 	several of which are relevant to CSS.
 
-<h3 id='shadow-trees'>
-Shadow Trees</h3>
-
 	A <dfn export>shadow tree</dfn> is a document fragment
 	that can be attached to any element in the DOM.
 	The root of the <a>shadow tree</a> is a <dfn export>shadow root</dfn>,
@@ -39,8 +38,8 @@ Shadow Trees</h3>
 
 	The descendants of a <a>shadow host</a>
 	must not generate boxes in the formatting tree.
-	Instead, the contents of the <a>active shadow tree</a> generates boxes
-	as if it were the contents of the element instead.
+	Instead, the contents of the <a>active shadow tree</a> generate boxes
+	as if they were the contents of the element instead.
 
 	In several instances in shadow DOM,
 	elements don't have element parents
@@ -50,9 +49,6 @@ Shadow Trees</h3>
 	or whose parent is not an element,
 	is called a <dfn export>top-level element</dfn>.
 
-<h3 id='distribution-lists'>
-Distribution Lists</h3>
-
 	While the children of a <a>shadow host</a> do not generate boxes normally,
 	they can be explicitly pulled into a <a>shadow tree</a> and forced to render normally.
 	This is done by assigning the elements to a <dfn export>distribution list</dfn>.
@@ -68,8 +64,8 @@ Distribution Lists</h3>
 	as if they all replaced the <a>insertion point</a> in-place.
 	<span class='note'>(Akin to the behavior of ''display-box: contents''.)</span>
 
-<h2 id='selectors-data-model'>
-Extensions to the Selectors Data Model</h2>
+<h3 id='selectors-data-model'>
+Shadow DOM Selection Model</h3>
 
 	Elements in the <a>element tree</a>
 	additionally have zero or more <a>shadow trees</a>
@@ -86,8 +82,8 @@ Extensions to the Selectors Data Model</h2>
 	and their descendants,
 	ordered by a pre-order traversal.
 
-<h3 id='host-element'>
-Host Elements in a Shadow Tree</h3>
+<h4 id='host-element'>
+Host Elements in a Shadow Tree</h4>
 
 	A <a>shadow host</a> is outside of the <a>shadow trees</a> it hosts,
 	but it is sometimes useful to be able to style it from inside the <a>shadow tree</a> context.
@@ -130,58 +126,14 @@ Host Elements in a Shadow Tree</h3>
 	</details>
 
 
-
-<h2 id='cascading'>
-Changes to the Cascading Model</h2>
-
-	To address the desired cascading behavior of rules targetting elements in shadow roots,
-	this specification extends the <a href="http://dev.w3.org/csswg/css-cascade/#cascading">cascade order</a>
-	defined in the Cascade specification. [[!CSS3CASCADE]]
-
-	An additional cascade criteria must be added,
-	between Origin and Scope,
-	called Shadow Tree.
-
-	<ul>
-		<li>
-			When comparing two declarations,
-			if one of them is in a <a>shadow tree</a>
-			and the other is in a document that contains that <a>shadow tree</a>,
-			then for normal rules the declaration from the outer document wins,
-			and for important rules the declaration from the <a>shadow tree</a> wins.
-
-			Note: This is the <em>opposite</em> of how scoped styles work.
-
-		<li>
-			When comparing two declarations,
-			if both are in <a>shadow trees</a> with the same <a>host element</a>,
-			then for normal rules the declaration from the <a>shadow tree</a> that was created most recently wins,
-			and for important rules the declaration from the <a>shadow tree</a> that was created less recently wins.
-	</ul>
-
-	When calculating <a href="http://dev.w3.org/csswg/css-cascade/#cascade-order">Order of Appearance</a>,
-	the tree of trees,
-	defined by the Shadow DOM specification,
-	is used to calculate ordering.
-
-<h3 id='inheritance'>
-Inheritance and Shadow DOM</h3>
-
-	The <a>top-level elements</a> of a <a>shadow tree</a>
-	inherit from their <a>host element</a>.
-
-	The elements in a <a>distribution list</a> inherit from the parent of the <a element>content</a> element they are ultimately distributed to,
-	rather than from their normal parent.
-
-
-<h2 id='selectors'>
-Shadow DOM Selectors</h2>
+<h3 id='selectors'>
+Shadow DOM Selectors</h3>
 
 	Shadow DOM defines a few new selectors
 	to help select elements in useful way related to Shadow DOM.
 
-<h3 id='host-selector'>
-Selecting the Host Element: the '':host'' and '':host()'' pseudo-classes</h3>
+<h4 id='host-selector'>
+Selecting Into the Light: the '':host'', '':host()'', and '':host-context()'' pseudo-classes</h4>
 
 	The <dfn selector>:host</dfn> pseudo-class,
 	when evaluated in the context of a <a>shadow tree</a>,
@@ -224,9 +176,6 @@ Selecting the Host Element: the '':host'' and '':host()'' pseudo-classes</h3>
 		</ul>
 	</div>
 
-<h3 id='ancestor-selector'>
-Selecting Based on an Ancestor Outside the Shadow Tree: the '':host-context()'' pseudo-class</h3>
-
 	Ordinary, selectors within a <a>shadow tree</a>
 	can't see elements outside the <a>shadow tree</a> at all.
 	Sometimes, however, it's useful to select an ancestor that lies somewhere outside the shadow tree,
@@ -260,8 +209,8 @@ Selecting Based on an Ancestor Outside the Shadow Tree: the '':host-context()''
 	looking for elements that match its argument,
 	until it reaches the document root.
 
-<h3 id='shadow-pseudoelement'>
-Selecting the Shadow Root Itself: the ''::shadow'' pseudo-element</h3>
+<h4 id='shadow-pseudoelement'>
+Selecting Into the Dark: the ''::shadow'' pseudo-element</h4>
 
 	If an element has at least one <a>shadow tree</a>,
 	the <dfn>::shadow</dfn> pseudo-element matches the <a>shadow roots</a> themselves.
@@ -312,8 +261,8 @@ Selecting the Shadow Root Itself: the ''::shadow'' pseudo-element</h3>
 
 
 
-<h3 id='content-combinator'>
-Selecting Distributed Elements: the ''::content'' pseudo-element</h3>
+<h4 id='content-combinator'>
+Selecting Shadow-Projected Content: the ''::content'' pseudo-element</h4>
 
 	The <dfn selector>::content</dfn> pseudo-element matches the <a>distribution list</a> itself,
 	on elements that have one.
@@ -362,8 +311,8 @@ Selecting Distributed Elements: the ''::content'' pseudo-element</h3>
 	</div>
 
 
-<h3 id='deep-combinator'>
-Selecting Through All Shadows: the ''/deep/'' combinator</h3>
+<h4 id='deep-combinator'>
+Selecting Through Shadows: the ''/deep/'' combinator</h4>
 
 	When a <dfn selector>/deep/</dfn> combinator is encountered in a selector,
 	replace every element in the <a>selector match list</a>
@@ -402,3 +351,51 @@ Selecting Through All Shadows: the ''/deep/'' combinator</h3>
 		Maybe we can give the descendant combinator a pseudonym of ''>>'',
 		as it itself is a super-child combinator?
 		Then ''/deep/'' could be spelled ''>>>''
+
+
+
+
+<h3 id='shadow-cascading'>
+Shadow Cascading & Inheritance</h3>
+
+<h4 id='cascading'>
+Cascading</h4>
+
+	To address the desired cascading behavior of rules targetting elements in shadow roots,
+	this specification extends the <a href="http://dev.w3.org/csswg/css-cascade/#cascading">cascade order</a>
+	defined in the Cascade specification. [[!CSS3CASCADE]]
+
+	An additional cascade criteria must be added,
+	between Origin and Scope,
+	called Shadow Tree.
+
+	<ul>
+		<li>
+			When comparing two declarations,
+			if one of them is in a <a>shadow tree</a>
+			and the other is in a document that contains that <a>shadow tree</a>,
+			then for normal rules the declaration from the outer document wins,
+			and for important rules the declaration from the <a>shadow tree</a> wins.
+
+			Note: This is the <em>opposite</em> of how scoped styles work.
+
+		<li>
+			When comparing two declarations,
+			if both are in <a>shadow trees</a> with the same <a>host element</a>,
+			then for normal rules the declaration from the <a>shadow tree</a> that was created most recently wins,
+			and for important rules the declaration from the <a>shadow tree</a> that was created less recently wins.
+	</ul>
+
+	When calculating <a href="http://dev.w3.org/csswg/css-cascade/#cascade-order">Order of Appearance</a>,
+	the tree of trees,
+	defined by the Shadow DOM specification,
+	is used to calculate ordering.
+
+<h4 id='inheritance'>
+Inheritance</h4>
+
+	The <a>top-level elements</a> of a <a>shadow tree</a>
+	inherit from their <a>host element</a>.
+
+	The elements in a <a>distribution list</a> inherit from the parent of the <a element>content</a> element they are ultimately distributed to,
+	rather than from their normal parent.