[selectors] Initial rewrite of the Pseudo-Elements section.

Author: tabatkins

selectors/Overview.bs

@@ -20,7 +20,7 @@ Abstract: <b>Selectors</b> are patterns that match against elements in a tree, a
 Abstract: Selectors Level 4 describes the selectors that already exist in [[!SELECT]], and further introduces new selectors for CSS and other languages that may need them.
 At Risk: the column combinator
 At Risk: The '':drop()'' pseudo-class
-Ignored Terms: DocumentFragment, math, h1
+Ignored Terms: DocumentFragment, math, h1, host element, shadow tree, box tree
 Link Defaults: html5 (element) a
 </pre>
 <style>
@@ -645,6 +645,23 @@ Data Model</h3>
 			but can be used in the matching of pseudo-classes and pseudo-elements.
 	</ul>
 
+	The first four bullet points in the list above are referred to as <dfn export title="feature">features</dfn>.
+	The <a>simple selectors</a> which are keyed off of them
+	(<a>universal selector</a>, <a>type selectors</a>, <a>ID selectors</a>, <a>class selectors</a>, and <a>attribute selectors</a>)
+	are called <dfn export title="feature selector">feature selectors</dfn>.
+
+	While elements may lack any of the individual <a>features</a>,
+	some elements are <dfn export>featureless</dfn>,
+	which means that not only do they lack any <a>features</a>
+	(and thus will never match a <a>feature selector</a>),
+	but any selectors that reference <a>features</a>,
+	such as '':not(div)'',
+	also never match them.
+	Thus, only <a>pseudo-classes</a> or <a>pseudo-elements</a> can be used to select them.
+	Individual <a>featureless</a> elements may define additional restrictions on what kinds of selectors can match them.
+	(For example, the <a>host element</a> in a <a>shadow tree</a> is <a>featureless</a>,
+	and can't be matched by <em>any</em> <a>pseudo-class</a> except for '':host'' and '':host-context()''.)
+
 	In HTML,
 	the DOM is used as the <a>element tree</a>.
 	Each DOM element is an element in the <a>element tree</a>,
@@ -800,56 +817,68 @@ Pseudo-classes</h3>
 
 <h3 id="pseudo-elements">Pseudo-elements</h3>
 
-	<dfn id='pseudo-element' title="pseudo-element" export>Pseudo-elements</dfn> create abstractions about the document tree
+	Similar to how <a>pseudo-classes</a> represent additional information
+	not directly present in the document tree
+	(or that is inconvenient to use),
+	a <dfn export>pseudo-element</dfn> is an <em>element</em>
+	not directly present in the document tree,
+	used to create abstractions about the document tree
 	beyond those specified by the document language.
-	For instance, document languages do not offer mechanisms to access
-	the first letter or first line of an element's content.
-	<a>Pseudo-elements</a> allow authors to refer
-	to this otherwise inaccessible information.
-	<a>Pseudo-elements</a> may also provide authors a way
-	to refer to content that does not exist in the source document
-	(e.g., the ''::before'' and ''::after'' <a>pseudo-elements</a>
-	give access to generated content in CSS [[CSS21]]).
+
+	<div class="example">
+		For instance, document languages do not offer mechanisms to access
+		the first letter or first line of an element's content,
+		but there exist <a>pseudo-elements</a>
+		(''::first-letter'' and ''::first-line'')
+		that allow those things to be styled.
+
+		<a>Pseudo-elements</a> can also represent content that doesn't exist in the source document at all,
+		such as the ''::before'' and ''::after'' pseudo-elements
+		which allow additional content to be inserted before or after the contents of any element.
+	</div>
 
 	The syntax of a <a>pseudo-element</a>
 	is "::" (two U+003A COLON characters)
 	followed by the name of the <a>pseudo-element</a> as an <a>identifier</a>.
 	<a>Pseudo-element</a> names are <a href="#case-sensitive">ASCII case-insensitive</a>.
 	No <a>white space</a> is allowed between the two colons, or between the colons and the name.
 
-	This <code>::</code> notation was chosen in order to establish
-	a discrimination between <a>pseudo-classes</a> (which subclass existing elements)
-	and <a>pseudo-elements</a> (which are elements not represented in the document tree).
-	However, for compatibility with existing style sheets,
-	user agents must also accept the previous one-colon notation
-	for <a>pseudo-elements</a> introduced in CSS levels 1 and 2
-	(namely, '':first-line'', '':first-letter'',
-	'':before'' and '':after'').
-	This compatibility notation is not allowed any other <a>pseudo-elements</a>.
+	Due to legacy constraints,
+	user agents must allow ''::before'', ''::after'', ''::first-line'', and ''::first-letter'' pseudo-elements
+	to be written with a single colon rather than two,
+	similar to <a>pseudo-class</a> syntax.
+	Authors must always use the double-colon syntax for these <a>pseudo-elements</a>.
+
+	<a>Pseudo-elements</a> do not exist independently;
+	they belong to another element on the page,
+	called their <dfn export>originating element</dfn>.
+	When a <a>pseudo-element</a> is encountered in a selector as part of a <a>compound selector</a>,
+	the part of the selector to the left of the <a>pseudo-element</a> selects the <a>originating element</a> for the <a>pseudo-element</a>;
+	the part of the selector to the right, if any, applies to the <a>pseudo-element</a> itself.
+	If a <a>pseudo-element</a> <em>starts</em> a <a>compound selector</a>,
+	it's treated as if the selector to its left was the <a>universal selector</a>.
 
-	Note: A future version of this specification may allow
-	multiple pseudo-elements per selector.
+	<div class='example'>
+		For example, in the selector ''div a::before'',
+		the ''a'' elements matched by the selector are the <a>originating elements</a>
+		for the ''::before'' pseudo-elements attached to them.
 
-	Syntactically, a <a>pseudo-element</a> immediately follows
-	the <a>compound selector</a> representing its <dfn export>originating element</dfn>,
-	i.e. the element to which it is associated.
-	Unless otherwise overridden by the definition of the <a>pseudo-element</a>:
+		The selector ''::first-line'' is equivalent to ''*::first-line'',
+		which selects the ''::first-line'' pseudo-element on <em>every</em> element in the document.
+	</div>
 
-	<ul>
-		<li>only one <a>pseudo-element</a> may appear per <a>complex selector</a>
-		<li>the <a>pseudo-element</a> must appear after the <a>compound selector</a>
-			that represents the <a href="#subject">subjects</a> of the selector
-		<li>the <a>pseudo-element</a> may appear only if the subject of the selector
-			is the last <a>compound selector</a> in the selector.
-	</ul>
+	<a>Pseudo-elements</a> are <a>featureless</a>,
+	and so can't be matched by any <a>feature selector</a>.
+	They also do not affect the interpretation of <a>structural pseudo-classes</a>,
+	which are evaluated based solely on real elements.
+	Other <a>pseudo-classes</a> <em>can</em> match <a>pseudo-elements</a>,
+	unless otherwise specified.
 
-	A <a>pseudo-element</a> may be immediately followed
-	by any combination of the <a href="#useraction-pseudos">user action pseudo-classes</a>,
-	in which case the <a>pseudo-element</a> is represented only when it is in the corresponding state.
-	Whether these pseudo-classes can match on the <a>pseudo-element</a>
-	depends on the <a>pseudo-class</a> and <a>pseudo-element</a>&rdquo;s definitions:
-	unless otherwise-specified, none of these <a>pseudo-classes</a>
-	will match on the <a>pseudo-element</a>.
+	<p class='issue'>
+		I've switched over to defaulting to allowing.
+		Is that okay,
+		or should we stick with defaulting to *not* allowing,
+		and requiring individual pseudo-classes to specify that they work on pseudo-elements?
 
 	<div class="example">
 		For example, the '':hover'' pseudo-class specifies that it
@@ -860,8 +889,79 @@ Pseudo-classes</h3>
 		the selector ''::first-line:focus'' will never match anything.
 	</div>
 
+	<a>Pseudo-elements</a> may have children,
+	as defined by the specification defining them.
+	Their children can be children of other elements, too,
+	turning the <a>element tree</a> into a directed acyclic graph,
+	but their rendering must be defined so as to maintain the tree-ness of the <a>box tree</a>.
+
+	<div class='example'>
+		For example,
+		the ''::content'' pseudo-element treats elements distributed to it as its children.
+		This means that, given the following fragment:
+
+		<pre>
+		&lt;div>
+			&lt;span>foo&lt;/span>
+			&lt;"shadow root">
+				&lt;content>&lt;/content>
+			&lt;/"shadow root">
+		&lt;/div>
+		</pre>
+
+		the selectors ''div > span'' and ''div::shadow ::content > span'' select the same element via different paths.
+
+		However, when rendered,
+		the <code>&lt;span></code> element generates boxes as if it were the child of the <code>&lt;content></code> element,
+		rather than the <code>&lt;div></code> element,
+		so the tree structure of the <a>box tree</a> is maintained.
+	</div>
+
 	The host language defines which pseudo-elements exist and their meaning.
-	For CSS, [[CSS21]] defines the ::before, ::after, ::first-line and ::first-letter pseudo-elements.
+	[[CSS21]] defines the ''::before'', ''::after'', ''::first-line'' and ''::first-letter'' pseudo-elements
+	which exist in all document languages.
+
+<h4 id='pseudo-element-types'>
+Types of Pseudo-Elements</h4>
+
+	<a>Pseudo-elements</a> are divided into two categories:
+	<a>content pseudo-elements</a>,
+	<a>text pseudo-elements</a>,
+
+	A <dfn export>content pseudo-element</dfn>
+	“acts like an element”.
+	It might be able to generate boxes
+	(though it probably doesn't by default),
+	and all properties are valid on it.
+	While it is ignored by <a>structural pseudo-classes</a>,
+	it's otherwise treated exactly like an element inserted in its place.
+
+	<div class='example'>
+		For example, the ''::before'' <a>pseudo-element</a> is a <a>content pseudo-element</a>,
+		as it can be styled like any other element
+		(as long as its 'content' property is set to a non-''content/none'' value).
+
+		The ''::shadow'' <a>pseudo-element</a> is also a <a>content pseudo-element</a>,
+		even though it never generates boxes.
+		It does, however,
+		act as the parent of the top-level elements in its <a>shadow tree</a>.
+	</div>
+
+	A <dfn export>text pseudo-element</dfn>,
+	on the other hand,
+	never generates boxes.
+	Instead, it generates fragments
+	within the boxes generated by its <a>originating element</a>.
+	Further, the fragments generated by a <a>text pseudo-element</a>
+	can cross content boundaries of elements within the <a>originating element</a>.
+	For these reasons,
+	the properties that apply to <a>text pseudo-elements</a> are extremely restricted.
+	<span class='issue'>Explain this better.</span>
+
+	<div class='example'>
+		The ''::first-line'' and ''::first-letter'' <a>pseudo-elements</a>
+		are both <a>text pseudo-elements</a>.
+	</div>
 
 <h3 id="case-sensitive">
 Characters and case sensitivity</h3>