├── README.md
├── demo
    └── index.html
├── docs
    ├── modality-mq.md
    └── modality-pseudo.md
└── src
    └── keyboard-modality.js


/README.md:
--------------------------------------------------------------------------------
 1 | **Deprecated:** Please look at https://github.com/wicg/focus-ring/ instead.
 2 | 
 3 | Archived content below.
 4 | 
 5 | ---
 6 | 
 7 | Based on a conversation between Alice Boxhall, Brian Kardell and Marcy Sutton, this prototype attaches/manages metadata in the form of a `modality` attribute to the body, as a way to allow authors to experiment with adapting style based on the user's _active_ input modality (i.e., how they are interacting with the UI _right now_).
 8 | 
 9 | [Demo](https://alice.github.io/modality/demo)
10 | 
11 | ## Rationale
12 | 
13 | There are many instances in which it would be useful for authors to understand the user's current interaction modality and be able to adapt the UI with better accomodations. The motivating example is `:focus` where the status quo is quite problematic:
14 | 
15 | - The default focus ring is not based on a single :focus rule as some might expect, not all things which can receive focus receive a ring in all cases. Adding such a rule is always currently problematic, but it's also exceptionally common.
16 | - Many developers disable the default focus ring in their CSS styles, others attempt to style it in concert with their design. The former often seems to be a result of finding the default focus ring both aesthetically unpleasant and confusing to users when applied after a mouse or touch event and introduces accessibility problems.  The latter inevitably creates considerably more of the kind of problem that the former was trying to solve.
17 | 
18 | To deal with this:
19 | - It seems evident that a visual indication of what has focus is only interesting to a user who is using the keyboard to interact with the page. A user using any kind of pointing device would only be interested in what is in focus if they were _just about_ to use the keyboard - otherwise, it is irrelevant and potentially confusing.
20 | - Thus, if we only show the focus ring when relevant, we can avoid user confusion and avoid creating incentives for developers to disable it.  
21 | - A mechanism for exposing focus ring styles only when the keyboard is the user's current input modality gives us this opportunity.
22 | 
23 | ## Implementation Prototype
24 | 
25 | At this stage, we're only looking at keyboard modality.  
26 | 
27 | The tiny [keyboard-modality.js](http://alice.github.io/modality/src/keyboard-modality.js) provides a prototype intended to achieve the goals we are proposing with technology that exists today in order for developers to be able to try it out, understand it and provide feedback.  Simply speaking, it sets a `modality=keyboard` attribute on `body` if the script determines that the keyboard is being used. Similarly, the attribute is removed if the script determines that the user is no longer using the keyboard. This allows authors to write rules which consider the input modality and style appropriately.   
28 | 
29 | It also simulates how the default UA styles would be adjusted by appending the following style as the first rule in the page, which disables the focus ring _unless_ `modality` is set to `keyboard`:
30 | 
31 | ```html
32 | body:not([modality=keyboard]) :focus {
33 |     outline: none;
34 | }
35 | ```
36 | 
37 | (This is added in a `<style>` element with the ID `"disable-focus-ring"`, to allow easy removal if different behaviour is desired.)
38 | 
39 | 
40 | ### How it works
41 | The script uses two heuristics to determine whether the keyboard is being used:
42 | 
43 | - a `focus` event immediately following a `keydown` event
44 | - focus moves into an element which requires keyboard interaction, such as a text field
45 | - _TODO: ideally, we also trigger keyboard modality following a keyboard event which activates an element or causes a mutation; this still needs to be implemented._
46 | 
47 | Custom elements may use the `supports-modality` attribute to provide a whitelist of supported modalities; any element without this whitelist is considered to support all modalities. Only elements which only support keyboard modality will trigger the `modality=keyboard` attribute on `<body>`.
48 | 


--------------------------------------------------------------------------------
/demo/index.html:
--------------------------------------------------------------------------------
  1 | <html><head>
  2 |     <!-- Original test page written by Dominic Mazzoni -->
  3 |     <title>modality attribute demo</title>
  4 |     <meta name="viewport" content="width=device-width,initial-scale=1">
  5 |     <style>
  6 |       div,input,textarea,h1,h2 {
  7 |       font-family: arial, sans-serif;
  8 |       }
  9 |       div { margin: 1em 0; }
 10 |       div[role="textbox"] {
 11 |       width: 10em;
 12 |       min-height: 2em;
 13 |       padding: 0.2em;
 14 |       border: 1px solid #000;
 15 |       }
 16 |       label {
 17 |       display: block;
 18 |       margin: 1em 0;
 19 |       }
 20 |       select {
 21 |       width: 10em;
 22 |       }
 23 |     </style>
 24 |     <script src="../src/keyboard-modality.js"></script>
 25 |     <style>
 26 |         body[modality=keyboard] :focus {
 27 |           outline: 2px solid green;
 28 |         }
 29 |     </style>
 30 |   </head>
 31 |   <body>
 32 |     <h1>Keyboard-only focus test</h1>
 33 |     <p>
 34 |       This page contains various html controls and demonstrates a proposal for only drawing a focus ring when the keyboard is being used. 
 35 |       Navigate through the interactive elements various ways (using mouse, switch to keyboard, try it on a touch device). You should see a green focus indicator (or comment out green focus ring style to see default focus ring) on elements below differently based on whether you interact with them via keyboard or mouse.  If you are using the mouse and get lost, at any time you can tab/shift-tab to find your focus indicator.
 36 |     </p>
 37 |     <h2>Editable text</h2>
 38 |     <div>
 39 |       <input placeholder="Single line">
 40 |     </div>
 41 |     <div>
 42 |       <textarea placeholder="Multi line"></textarea>
 43 |     </div>
 44 |     <div>
 45 |       <div id="s" role="textbox" tabindex="0" contenteditable="true">Contenteditable with textbox role</div>
 46 |     </div>
 47 |     <h2>Buttons</h2>
 48 |     <div>
 49 |       <button>Button</button>
 50 |     </div>
 51 |     <div>
 52 |       <button supports-modality=keyboard>Button with <code>supports-modality=keyboard</code></button>
 53 |     </div>
 54 |     <div>
 55 |       <input type="submit" value="Submit button">
 56 |     </div>
 57 |     <div>
 58 |       <label><input type="checkbox">Checkbox</label>
 59 |     </div>
 60 |     <div>
 61 |       <label><input name="a" type="radio">Radio 1</label>
 62 |       <label><input name="a" type="radio">Radio 2</label>
 63 |     </div>
 64 |     <h2>Selects</h2>
 65 |     <label>Select one from drop-down:<br>
 66 |       <select>
 67 |         <option>Apple</option>
 68 |         <option>Orange</option>
 69 |         <option>Banana</option>
 70 |       </select>
 71 |     </label>
 72 |     <label>Select one from list:<br>
 73 |       <select size="5">
 74 |         <option>Apple</option>
 75 |         <option>Orange</option>
 76 |         <option>Banana</option>
 77 |       </select>
 78 |     </label>
 79 |     <label>Select multiple:<br>
 80 |       <select multiple="">
 81 |         <option>Apple</option>
 82 |         <option>Orange</option>
 83 |         <option>Banana</option>
 84 |       </select>
 85 |     </label>
 86 |     <h2>Other</h2>
 87 |     <label>Process nice score from -20 to +20:<br>
 88 |       <input type="range" min="-20" max="20" value="0">
 89 |     </label>
 90 |     <label>Bowling score from 0 to 300:<br>
 91 |       <input type="range" min="0" max="300" value="0">
 92 |     </label>
 93 |     <div>
 94 |       <input type="date" value="2008-09-01">
 95 |     </div>
 96 |     <div>
 97 |       <input type="time" value="00:00:00">
 98 |     </div>
 99 |     <div>
100 |       <input type="number" placeholder="Number">
101 |     </div>
102 |     <div>
103 |       <input type="color" title="Color" value="#00ff00">
104 |     </div>
105 |     <div>
106 |       <input type="file" title="File">
107 |     </div>
108 | 
109 | 
110 |   </body>
111 | </html>
112 | 


--------------------------------------------------------------------------------
/docs/modality-mq.md:
--------------------------------------------------------------------------------
 1 | # `modality` media query proposal
 2 | 
 3 | ## Introduction
 4 | 
 5 | There are many instances in which it would be useful for authors to understand the user's current interaction modality and be able to adapt the UI with better accomodations.
 6 | 
 7 | As the user interacts with the UI, it can be said to have an active modality in the same way it has an active element or a current size.  Browsers, [since at least IE7](https://bugzilla.mozilla.org/show_bug.cgi?id=377320) have experimented with ideas around how the default focus ring works, for example, based on how the user has acted thusfar.  With 8 years worth of experience (as of the time of this writing), implementers have a lot of feedback and data which definitely seems to indicate that such accomodations are necessary.  However, there are no standards in this space and none of this is exposed to authors. Any author change to the default focus ring is unable to consult the same sources of truth and invariably trades off this work leading to problems which have been written about exhaustively and leave the author with one of three bad choices: 
 8 |  * Nothing gets the focus ring because a large number of users use a pointing device and find it confusing or asthetically displeasing, thereby creating accessibility problems for keyboard users and confusion for people who use both
 9 |  * Everything focusable gets the focus ring for accessibility sake and the designer and large number of users are left unhappy and confused a majority of the time.
10 |  * Authors write very specific rules about what does and doesn't get the focus indicator regardless of how the user is interacting.  This can be tremendously confusing for keyboard users and cause accessibility problems on its own and it isn't very forward compatible - as new elements are added to the page, or HTML introduces new elements (or authors import custom-elements), each needs custom focus rules or they will work differently.
11 | 
12 | We propose that lying beneath implementations is already an observable concept of modality and that explaining it as a `modality` primitive (`<input type="text">` for example supports only keyboard as a modality for input and therefore always receives a default focus ring, whereas button `<button>` supports many modalities and it often depends on how you got there).  We propose that defining this and exposing it via a `MediaQuery` would allow appropriate accomodations in the same ways that Responsive Design and Adaptive Design allow authors to create a better experience for all users. The example below shows an example in which users could simply and safely remove the default focus outline when the user isn't using a keyboard and provide one when they are.  As a savvy user switches modalities from touch/point to keys, the active modality changes and the focus ring appears. 
13 | 
14 | ```html
15 | :focus { outline: none; }
16 | @media (modality: keyboard) {
17 |  :focus {
18 |     outline: 2px solid blue;
19 |   }
20 | }
21 | ```
22 | 
23 | Likewise, if necessary, script can easily respond to such a change given `matchMedia` and `MediaQueryListener`.
24 | 
25 | ```js
26 | window.matchMedia("(modality: keyboard)").addListener(function (evt) {
27 |    // The modality has changed to keyboard
28 | });
29 | 
30 | window.matchMedia("not (modality: keyboard)").addListener(function (evt) {
31 |    // The modality has changed, it's not keyboard
32 | });
33 | ```
34 | 
35 | ## Modalities
36 | At this stage, we are only considering keyboard modality (and not keyboard), motivated by the focus ring issue. However, as this proposal evolves, we will likely add other modalities.
37 | 
38 | Each modality consists of:
39 | - a name,
40 | - a series of trigger situations which will cause modality to reevaluate (see below)
41 | - an algorythmic means of evaluating the resulting modality
42 | 
43 | ### Keyboard modality
44 | 
45 | The named 'keyboard' modality triggers modality reevaluation immediately after:
46 | 
47 | - a `focus` event triggered from the keyboard, or
48 | - focus moves into an element, or
49 | - a user uses the keyboard to interact with an element which was focused via another means,
50 | - any blur event not immediately followed by one of the above
51 | 
52 | Evaluation of the modality (boolean) is determined by evaluating the event that happened above combined with what the element it occurred on supports for input modality.  For example, focusing on an `<input type="text">` will always evaluate to a keyboard modality because this is the only modality it supports, whereas focusing on a `<input type="button">` will evaluate based purely on which event triggered it (keyboard or pointer, for example).
53 | 
54 | 
55 | 


--------------------------------------------------------------------------------
/docs/modality-pseudo.md:
--------------------------------------------------------------------------------
 1 | # `modality` pseudo-class proposal
 2 | 
 3 | ## Introduction
 4 | 
 5 | There are many instances in which it would be useful for authors to understand the user's current interaction modality and be able to adapt the UI with better accomodations.
 6 | 
 7 | As the user interacts with the UI, it can be said to have an active modality in the same way it has an active element or a current size.  Browsers, [since at least IE7](https://bugzilla.mozilla.org/show_bug.cgi?id=377320) have experimented with ideas around how the default focus ring works, for example, based on how the user has acted thusfar.  With 8 years worth of experience (as of the time of this writing), implementers have a lot of feedback and data which definitely seems to indicate that such accomodations are necessary.  However, there are no standards in this space and none of this is exposed to authors. Any author change to the default focus ring is unable to consult the same sources of truth and invariably trades off this work leading to problems which have been written about exhaustively and leave the author with one of three bad choices:
 8 |  * Nothing gets the focus ring because a large number of users use a pointing device and find it confusing or asthetically displeasing, thereby creating accessibility problems for keyboard users and confusion for people who use both
 9 |  * Everything focusable gets the focus ring for accessibility sake and the designer and large number of users are left unhappy and confused a majority of the time.
10 |  * Authors write very specific rules about what does and doesn't get the focus indicator regardless of how the user is interacting.  This can be tremendously confusing for keyboard users and cause accessibility problems on its own and it isn't very forward compatible - as new elements are added to the page, or HTML introduces new elements (or authors import custom-elements), each needs custom focus rules or they will work differently.
11 | 
12 | We propose that lying beneath implementations is already an observable concept of modality and that explaining it as a `modality` primitive (`<input type="text">` for example supports only keyboard as a modality for input and therefore always receives a default focus ring, whereas button `<button>` supports many modalities and it often depends on how you got there).  We propose that defining this and exposing it via a `pseudo-class` would allow appropriate accomodations in the same ways that Responsive Design and Adaptive Design allow authors to create a better experience for all users. The example below shows an example in which users could simply and safely remove the default focus outline when the user isn't using a keyboard and provide one when they are.  As a savvy user switches modalities from touch/point to keys (and the target of such action is consulted), the active modality may change and, as appropriate, the focus ring appears.
13 | 
14 | The modality is a document-wide property about which state the user-context is in which can be consulted via the `:modality()` pseudo-class filter.
15 | 
16 | ```html
17 | :focus {
18 |    outline: 2px solid blue;
19 | }
20 | :not(:modality(keyboard)):focus { outline: none; }
21 | ```
22 | 
23 | This is exposed through a `modality` observably in that changes to the document's known modalitity state will raise a `modalitychange` event (fired on animation frame) and script can easily respond to account accordingly.
24 | 
25 | ```js
26 | document.addEventListener("modalitychange", function () {
27 |    /* authors can use document.matchesSelector(":modality(...)"") to determine state */
28 | }, true);
29 | ```
30 | 
31 | ## Modalities
32 | At this stage, we are only considering keyboard modality (and :not keyboard), motivated by the focus ring issue. However, as this proposal evolves, we will likely add other modalities.
33 | 
34 | Each modality consists of:
35 | - a name,
36 | - a series of trigger situations which will cause modality to reevaluate (see below)
37 | - an algorythmic means of evaluating the resulting modality
38 | 
39 | ### Keyboard modality
40 | 
41 | The named 'keyboard' modality triggers modality reevaluation immediately after:
42 | 
43 | - a `focus` event triggered from the keyboard, or
44 | - focus moves into an element, or
45 | - a user uses the keyboard to interact with an element which was focused via another means,
46 | - any blur event not immediately followed by one of the above
47 | 
48 | Evaluation of the modality (boolean) is determined by evaluating the event that happened above combined with what the element it occurred on supports for input modality.  For example, focusing on an `<input type="text">` will always evaluate to a keyboard modality because this is the only modality it supports, whereas focusing on a `<input type="button">` will evaluate based purely on which event triggered it (keyboard or pointer, for example).
49 | 


--------------------------------------------------------------------------------
/src/keyboard-modality.js:
--------------------------------------------------------------------------------
 1 | /* https://github.com/alice/modality v1.0.2 */
 2 | document.addEventListener("DOMContentLoaded", function() {
 3 |     var hadKeyboardEvent = false,
 4 |         keyboardModalityWhitelist = [ "input:not([type])",
 5 |                                       "input[type=email]",
 6 |                                       "input[type=text]",
 7 |                                       "input[type=password]",
 8 |                                       "input[type=number]",
 9 |                                       "input[type=date]",
10 |                                       "input[type=time]",
11 |                                       "input[type=datetime]",
12 |                                       "textarea",
13 |                                       "[role=textbox]",
14 |                                       "[supports-modality=keyboard]"].join(","),
15 |         isHandlingKeyboardThrottle,
16 |         matcher = (function () {
17 | 			var el = document.body;
18 | 			if (el.matchesSelector)
19 | 				return el.matchesSelector;
20 | 			if (el.webkitMatchesSelector)
21 | 				return el.webkitMatchesSelector;
22 | 			if (el.mozMatchesSelector)
23 | 				return el.mozMatchesSelector;
24 | 			if (el.msMatchesSelector)
25 | 				return el.msMatchesSelector;
26 | 			console.error("Couldn't find any matchesSelector method on document.body.");
27 | 		}()),
28 |         disableFocusRingByDefault = function () {
29 | 			var css = "body:not([modality=keyboard]) :focus { outline: none; }",
30 | 				head = document.head || document.getElementsByTagName("head")[0],
31 | 				style = document.createElement("style");
32 | 
33 | 			style.type = "text/css";
34 | 			style.id = "disable-focus-ring";
35 | 			if (style.styleSheet) {
36 | 				style.styleSheet.cssText = css;
37 | 			} else {
38 | 				style.appendChild(document.createTextNode(css));
39 | 			}
40 | 
41 | 			head.insertBefore(style, head.firstChild);
42 | 		},
43 | 		focusTriggersKeyboardModality = function (el) {
44 | 			var triggers = false;
45 | 			if (matcher) {
46 | 				triggers = matcher.call(el, keyboardModalityWhitelist) && matcher.call(el, ":not([readonly])");
47 | 			}
48 | 		        return triggers;
49 | 		};
50 | 
51 |     disableFocusRingByDefault();
52 | 
53 |     document.body.addEventListener("keydown", function() {
54 |         hadKeyboardEvent = true;
55 |         if (isHandlingKeyboardThrottle) {
56 |             clearTimeout(isHandlingKeyboardThrottle);
57 |         }
58 |         isHandlingKeyboardThrottle = setTimeout(function() {
59 |             hadKeyboardEvent = false;
60 |         }, 100);
61 |     }, true);
62 | 
63 |     document.body.addEventListener("focus", function(e) {
64 |         if (hadKeyboardEvent || focusTriggersKeyboardModality(e.target))
65 |             document.body.setAttribute("modality", "keyboard");
66 |     }, true);
67 | 
68 |     document.body.addEventListener("blur", function() {
69 |         document.body.removeAttribute("modality");
70 |     }, true);
71 | });
72 | 


--------------------------------------------------------------------------------