[selectors] Add API hooks for matching selectors against trees and elements, and dedup some IDs.

Author: tabatkins

selectors/Overview.bs

@@ -1410,7 +1410,7 @@ Type selectors and namespaces</h4>
 		namespace has been defined.
 	</div>
 
-<h3 id="universal-selector">
+<h3 id="the-universal-selector">
 Universal selector </h3>
 
 	The <dfn export>universal selector</dfn>, written as a
@@ -2227,7 +2227,7 @@ The drag-and-drop pseudo-class '':drop'' and '':drop()''</h3>
 	For example, in HTML the <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/dnd.html#the-dropzone-attribute"><code>dropzone</code></a> attribute
 	specified that an element is a drop target.
 
-	The <dfn>:drop()</dfn> functional pseudo-class is identical to '':drop'',
+	The <dfn id="selectordef-drop-function">:drop()</dfn> functional pseudo-class is identical to '':drop'',
 	but allows additional filters to be specified that can exclude some drop targets.
 	Its syntax is:
 
@@ -3031,7 +3031,7 @@ Grid-Structural Selectors</h2>
 	are defined.
 	In a column-primary format, these pseudo-classes match against row associations instead.
 
-<h3 id="column-combinator">
+<h3 id="the-column-combinator">
 Column combinator</h3>
 
 	The <dfn export>column combinator</dfn>, which consists of two pipes (''||'')
@@ -3306,7 +3306,7 @@ API Hooks</h2>
 	To aid in the writing of specs that use Selectors concepts,
 	this section defines several API hooks that can be invoked by other specifications.
 
-<h3 id='parse-a-selector'>
+<h3 id='parse-selector'>
 Parse A Selector</h3>
 
 	This section defines how to <dfn export>parse a selector</dfn> from a string <var>source</var>.
@@ -3331,7 +3331,7 @@ Parse A Selector</h3>
 			return <var>selector</var>.
 	</ol>
 
-<h3 id='parse-a-relative-selector'>
+<h3 id='parse-relative-selector'>
 Parse A Relative Selector</h3>
 
 	This section defines how to <dfn export>parse a relative selector</dfn> from a string <var>source</var>,
@@ -3360,6 +3360,71 @@ Parse A Relative Selector</h3>
 			Return <var>selector</var>.
 	</ol>
 
+<h3 id='match-against-tree'>
+Match a Selector Against A Tree</h3>
+
+	This section defines how to <dfn export>match a selector against a tree</dfn>.
+
+	APIs calling this algorithm must provide a <var>selector</var>,
+	and a set of <var>root elements</var> of the trees to be matched against.
+	They may optionally provide:
+
+	<ul>
+		<li>
+			A <a>scoping method</a> and <a>scoping root</a>.
+			If not specified,
+			the selector defaults to being unscoped.
+
+		<li>
+			A set of <a>:scope elements</a>,
+			which will match the '':scope'' pseudo-class.
+			If not specified,
+			then if the selector is a <a>scoped selector</a>,
+			the set of <a>:scope elements</a> default to the <a>scoping root</a>;
+			otherwise,
+			it defaults to the <var>root elements</var>.
+
+		<li>
+			Which <a>pseudo-elements</a> are allowed to show up in the match list.
+			If not specified, this defaults to allowing all pseudo-elements.
+	</ul>
+
+	This algorithm returns a (possible empty) list of elements.
+
+	<ol>
+		<li>
+			<a>Evaluate a selector</a> with the same arguments provided to this algorithm,
+			and return the result.
+	</ol>
+
+<h3 id='match-against-element'>
+Match a Selector Against an Element</h3>
+
+	This section defines how to <dfn export>match a selector against an element</dfn>.
+
+	APIs calling this algorithm must provide a <var>selector</var> and an <var>element</var>.
+	They may optionally provide the same optional arguments as described in the algorithm to <a>match a selector against a tree</a>.
+
+	This algorithm returns either success or failure.
+
+	<ol>
+		<li>
+			Let <var>root element</var> be the "root ancestor" of <var>element</var>:
+			the element found by traversing parent links from <var>element</var>
+			until an element without a parent is encountered.
+
+		<li>
+			<a>Evaluate a selector</a> with <var>selector</var> and <var>root element</var>,
+			and any optional arguments passed to this algorithm.
+			Let <var>matched elements</var> be the result.
+
+		<li>
+			If <var>element</var> is in <var>matched elements</var>,
+			return success.
+			Otherwise,
+			return failure.
+	</ol>
+
 
 <h2 id="changes">
 Changes</h2>