Add :focusring selector (#709)

* Add :focusring selector

* Rewrite to make the normative parts a little clearer, and rearrange the non-normatives into advisements and examples.

Author: robdodson

selectors/Overview.bs

@@ -272,14 +272,21 @@ Selectors Overview</h2>
 			<tr>
 				<td><code>E:hover</code>
 				<td>an E element that is under the cursor,
-						or that has a descendant under the cursor
+					or that has a descendant under the cursor
 				<td>[[#useraction-pseudos]]
 				<td>2
 			<tr>
 				<td><code>E:focus</code>
 				<td>an E element that has user input focus
 				<td>[[#useraction-pseudos]]
 				<td>2
+			<tr>
+				<td><code>E:focus-ring</code>
+				<td>an E element that has user input focus, 
+					and the UA has determined that a focus ring or other indicator 
+					should be drawn for that element
+				<td>[[#useraction-pseudos]]
+				<td>4
 			<tr>
 				<td><code>E:drop</code>
 				<td>an E element that can possibly receive a drop
@@ -2019,9 +2026,9 @@ The Activation Pseudo-class: '':active''</h3>
 <h3 id="the-focus-pseudo">
 The Input Focus Pseudo-class: '':focus''</h3>
 
-	The <dfn id='focus-pseudo'>:focus</dfn> pseudo-class applies while an element
-	has the focus (accepts keyboard or mouse events, or other forms of
-	input).
+	The <dfn id='focus-pseudo'>:focus</dfn> pseudo-class applies 
+	while an element has the focus 
+	(accepts keyboard or mouse events, or other forms of input).
 
 	There may be document language or implementation specific limits on
 	which elements can acquire '':focus''.
@@ -2031,6 +2038,68 @@ The Input Focus Pseudo-class: '':focus''</h3>
 	the same ways must apply to elements matching '':focus'' as well,
 	except that the parent of an element that matches '':focus'' must not match '':focus''.
 
+<h3 id="the-focusring-pseudo">
+The Input Focus-Ring Pseudo-class: '':focus-ring''</h3>
+
+	The <dfn id='focus-ring-pseudo'>:focus-ring</dfn> pseudo-class applies
+	while an element matches the '':focus'' pseudo-class,
+	<em>and</em> the UA determines via heuristics
+	that the focus should be specially indicated on the element
+	(typically via a "focus ring").
+	
+	<div class=example>
+		For example, UAs typically display focus indicators on text elements
+		<em>whenever</em> they're focused,
+		to draw attention to the fact that keyboard input will affect their contents.
+		
+		On the other hand, they typically only display focus indicators on buttons
+		when they were focused by a keyboard interaction
+		(such as tabbing thru the document), 
+		because it's not always immediately obvious where the focus will move
+		after such an interaction,
+		but not when they were focused by more "obvious" interactions,
+		like clicking on the button with a mouse pointer.
+	</div>
+	
+	<div class=advisement>
+		Page authors should follow these guidelines
+		when deciding whether to use '':focus'' or '':focus-ring''
+		to style the focused state of an element:
+		
+		* If the element has "native" focus indicator behavior
+			(such as text fields or buttons),
+			use '':focus-ring''.
+		* Otherwise, if the element is emulating a text input,
+			or something else that is <em>intended</em> to receive keyboard interaction,
+			use '':focus''.
+		* Otherwise,
+			use '':focus-ring''.
+	</div>
+	
+	When UAs choose to specially indicate focus on an element,
+	or whether they specially indicate focus at all,
+	is UA-dependent.
+	Different UAs,
+	the same UA on different operating systems,
+	or the same UA on the same OS,
+	but with different user settings,
+	can make different choices as to when an element matches '':focus-ring''.
+	
+	<div class=example>
+		The following guidelines are suggested heuristics
+		for choosing when to apply '':focus-ring'' 
+		to elements without "native" focus ring behavior:
+		
+		* If the element received focus via a keyboard interaction,
+			including indirectly,
+			such as triggering a dialog
+			by pressing a button using the keyboard,
+			apply '':focus-ring''.
+		* If a keyboard event occurs while an element is focused,
+			even if the element wasn't focused by a keyboard interaction,
+			apply '':focus-ring''.
+	</div>
+
 <h3 id="the-focus-within-pseudo">
 The Generalized Input Focus Pseudo-class: '':focus-within''</h3>