| OLD | NEW |
| (Empty) |
| 1 <!-- | |
| 2 @license | |
| 3 Copyright (c) 2014 The Polymer Project Authors. All rights reserved. | |
| 4 This code may only be used under the BSD style license found at http://polym
er.github.io/LICENSE.txt | |
| 5 The complete set of authors may be found at http://polymer.github.io/AUTHORS
.txt | |
| 6 The complete set of contributors may be found at http://polymer.github.io/CO
NTRIBUTORS.txt | |
| 7 Code distributed by Google as part of the polymer project is also | |
| 8 subject to an additional IP rights grant found at http://polymer.github.io/P
ATENTS.txt | |
| 9 --> | |
| 10 | |
| 11 <!-- | |
| 12 `core-a11y-keys` provides a normalized interface for processing keyboard command
s that pertain to [WAI-ARIA best | |
| 13 practices](http://www.w3.org/TR/wai-aria-practices/#kbd_general_binding). The el
ement takes care of browser differences | |
| 14 with respect to Keyboard events and uses an expressive syntax to filter key pres
ses. | |
| 15 | |
| 16 Use the `keys` attribute to express what combination of keys will trigger the ev
ent to fire. | |
| 17 | |
| 18 Use the `target` attribute to set up event handlers on a specific node. | |
| 19 The `keys-pressed` event will fire when one of the key combinations set with the
`keys` attribute is pressed. | |
| 20 | |
| 21 Example: | |
| 22 | |
| 23 This element will call `arrowHandler` on all arrow keys: | |
| 24 | |
| 25 <core-a11y-keys target="{{}}" keys="up down left right" on-keys-pressed="{{a
rrowHandler}}"></core-a11y-keys> | |
| 26 | |
| 27 Keys Syntax: | |
| 28 | |
| 29 The `keys` attribute can accepts a space seprated, `+` concatenated set of modif
ier keys and some common keyboard keys. | |
| 30 | |
| 31 The common keys are `a-z`, `0-9` (top row and number pad), `*` (shift 8 and numb
er pad), `F1-F12`, `Page Up`, `Page | |
| 32 Down`, `Left Arrow`, `Right Arrow`, `Down Arrow`, `Up Arrow`, `Home`, `End`, `Es
cape`, `Space`, `Tab`, and `Enter` keys. | |
| 33 | |
| 34 The modifier keys are `Shift`, `Control`, and `Alt`. | |
| 35 | |
| 36 All keys are expected to be lowercase and shortened: | |
| 37 `Left Arrow` is `left`, `Page Down` is `pagedown`, `Control` is `ctrl`, `F1` is
`f1`, `Escape` is `esc` etc. | |
| 38 | |
| 39 Keys Syntax Example: | |
| 40 | |
| 41 Given the `keys` attribute value "ctrl+shift+f7 up pagedown esc space alt+m", th
e `<core-a11y-keys>` element will send | |
| 42 the `keys-pressed` event if any of the follow key combos are pressed: Control an
d Shift and F7 keys, Up Arrow key, Page | |
| 43 Down key, Escape key, Space key, Alt and M key. | |
| 44 | |
| 45 Slider Example: | |
| 46 | |
| 47 The following is an example of the set of keys that fulfil the WAI-ARIA "slider"
role [best | |
| 48 practices](http://www.w3.org/TR/wai-aria-practices/#slider): | |
| 49 | |
| 50 <core-a11y-keys target="{{}}" keys="left pagedown down" on-keys-pressed="{{d
ecrement}}"></core-a11y-keys> | |
| 51 <core-a11y-keys target="{{}}" keys="right pageup up" on-keys-pressed="{{incr
ement}}"></core-a11y-keys> | |
| 52 <core-a11y-keys target="{{}}" keys="home" on-keys-pressed="{{setMin}}"></cor
e-a11y-keys> | |
| 53 <core-a11y-keys target="{{}}" keys="end" on-keys-pressed="{{setMax}}"></core
-a11y-keys> | |
| 54 | |
| 55 The `increment` function will move the slider a set amount toward the maximum va
lue. | |
| 56 The `decrement` function will move the slider a set amount toward the minimum va
lue. | |
| 57 The `setMin` function will move the slider to the minimum value. | |
| 58 The `setMax` function will move the slider to the maximum value. | |
| 59 | |
| 60 Keys Syntax Grammar: | |
| 61 | |
| 62 [EBNF](http://en.wikipedia.org/wiki/Extended_Backus%E2%80%93Naur_Form) Grammar o
f the `keys` attribute. | |
| 63 | |
| 64 modifier = "shift" | "ctrl" | "alt"; | |
| 65 ascii = ? /[a-z0-9]/ ? ; | |
| 66 fnkey = ? f1 through f12 ? ; | |
| 67 arrow = "up" | "down" | "left" | "right" ; | |
| 68 key = "tab" | "esc" | "space" | "*" | "pageup" | "pagedown" | "home" | "end"
| arrow | ascii | fnkey ; | |
| 69 keycombo = { modifier, "+" }, key ; | |
| 70 keys = keycombo, { " ", keycombo } ; | |
| 71 | |
| 72 @group Core Elements | |
| 73 @element core-a11y-keys | |
| 74 @homepage github.io | |
| 75 --> | |
| 76 | |
| 77 <link rel="import" href="../polymer/polymer.html"> | |
| 78 | |
| 79 <style shim-shadowdom> | |
| 80 html /deep/ core-a11y-keys { | |
| 81 display: none; | |
| 82 } | |
| 83 </style> | |
| 84 | |
| 85 <polymer-element name="core-a11y-keys"> | |
| 86 <script> | |
| 87 (function() { | |
| 88 /* | |
| 89 * Chrome uses an older version of DOM Level 3 Keyboard Events | |
| 90 * | |
| 91 * Most keys are labeled as text, but some are Unicode codepoints. | |
| 92 * Values taken from: http://www.w3.org/TR/2007/WD-DOM-Level-3-Events-200712
21/keyset.html#KeySet-Set | |
| 93 */ | |
| 94 var KEY_IDENTIFIER = { | |
| 95 'U+0009': 'tab', | |
| 96 'U+001B': 'esc', | |
| 97 'U+0020': 'space', | |
| 98 'U+002A': '*', | |
| 99 'U+0030': '0', | |
| 100 'U+0031': '1', | |
| 101 'U+0032': '2', | |
| 102 'U+0033': '3', | |
| 103 'U+0034': '4', | |
| 104 'U+0035': '5', | |
| 105 'U+0036': '6', | |
| 106 'U+0037': '7', | |
| 107 'U+0038': '8', | |
| 108 'U+0039': '9', | |
| 109 'U+0041': 'a', | |
| 110 'U+0042': 'b', | |
| 111 'U+0043': 'c', | |
| 112 'U+0044': 'd', | |
| 113 'U+0045': 'e', | |
| 114 'U+0046': 'f', | |
| 115 'U+0047': 'g', | |
| 116 'U+0048': 'h', | |
| 117 'U+0049': 'i', | |
| 118 'U+004A': 'j', | |
| 119 'U+004B': 'k', | |
| 120 'U+004C': 'l', | |
| 121 'U+004D': 'm', | |
| 122 'U+004E': 'n', | |
| 123 'U+004F': 'o', | |
| 124 'U+0050': 'p', | |
| 125 'U+0051': 'q', | |
| 126 'U+0052': 'r', | |
| 127 'U+0053': 's', | |
| 128 'U+0054': 't', | |
| 129 'U+0055': 'u', | |
| 130 'U+0056': 'v', | |
| 131 'U+0057': 'w', | |
| 132 'U+0058': 'x', | |
| 133 'U+0059': 'y', | |
| 134 'U+005A': 'z', | |
| 135 'U+007F': 'del' | |
| 136 }; | |
| 137 | |
| 138 /* | |
| 139 * Special table for KeyboardEvent.keyCode. | |
| 140 * KeyboardEvent.keyIdentifier is better, and KeyBoardEvent.key is even bett
er than that | |
| 141 * | |
| 142 * Values from: https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEve
nt.keyCode#Value_of_keyCode | |
| 143 */ | |
| 144 var KEY_CODE = { | |
| 145 9: 'tab', | |
| 146 13: 'enter', | |
| 147 27: 'esc', | |
| 148 33: 'pageup', | |
| 149 34: 'pagedown', | |
| 150 35: 'end', | |
| 151 36: 'home', | |
| 152 32: 'space', | |
| 153 37: 'left', | |
| 154 38: 'up', | |
| 155 39: 'right', | |
| 156 40: 'down', | |
| 157 46: 'del', | |
| 158 106: '*' | |
| 159 }; | |
| 160 | |
| 161 /* | |
| 162 * KeyboardEvent.key is mostly represented by printable character made by th
e keyboard, with unprintable keys labeled | |
| 163 * nicely. | |
| 164 * | |
| 165 * However, on OS X, Alt+char can make a Unicode character that follows an A
pple-specific mapping. In this case, we | |
| 166 * fall back to .keyCode. | |
| 167 */ | |
| 168 var KEY_CHAR = /[a-z0-9*]/; | |
| 169 | |
| 170 function transformKey(key) { | |
| 171 var validKey = ''; | |
| 172 if (key) { | |
| 173 var lKey = key.toLowerCase(); | |
| 174 if (lKey.length == 1) { | |
| 175 if (KEY_CHAR.test(lKey)) { | |
| 176 validKey = lKey; | |
| 177 } | |
| 178 } else if (lKey == 'multiply') { | |
| 179 // numpad '*' can map to Multiply on IE/Windows | |
| 180 validKey = '*'; | |
| 181 } else { | |
| 182 validKey = lKey; | |
| 183 } | |
| 184 } | |
| 185 return validKey; | |
| 186 } | |
| 187 | |
| 188 var IDENT_CHAR = /U\+/; | |
| 189 function transformKeyIdentifier(keyIdent) { | |
| 190 var validKey = ''; | |
| 191 if (keyIdent) { | |
| 192 if (IDENT_CHAR.test(keyIdent)) { | |
| 193 validKey = KEY_IDENTIFIER[keyIdent]; | |
| 194 } else { | |
| 195 validKey = keyIdent.toLowerCase(); | |
| 196 } | |
| 197 } | |
| 198 return validKey; | |
| 199 } | |
| 200 | |
| 201 function transformKeyCode(keyCode) { | |
| 202 var validKey = ''; | |
| 203 if (Number(keyCode)) { | |
| 204 if (keyCode >= 65 && keyCode <= 90) { | |
| 205 // ascii a-z | |
| 206 // lowercase is 32 offset from uppercase | |
| 207 validKey = String.fromCharCode(32 + keyCode); | |
| 208 } else if (keyCode >= 112 && keyCode <= 123) { | |
| 209 // function keys f1-f12 | |
| 210 validKey = 'f' + (keyCode - 112); | |
| 211 } else if (keyCode >= 48 && keyCode <= 57) { | |
| 212 // top 0-9 keys | |
| 213 validKey = String(48 - keyCode); | |
| 214 } else if (keyCode >= 96 && keyCode <= 105) { | |
| 215 // num pad 0-9 | |
| 216 validKey = String(96 - keyCode); | |
| 217 } else { | |
| 218 validKey = KEY_CODE[keyCode]; | |
| 219 } | |
| 220 } | |
| 221 return validKey; | |
| 222 } | |
| 223 | |
| 224 function keyboardEventToKey(ev) { | |
| 225 // fall back from .key, to .keyIdentifier, to .keyCode, and then to .detai
l.key to support artificial keyboard events | |
| 226 var normalizedKey = transformKey(ev.key) || transformKeyIdentifier(ev.keyI
dentifier) || transformKeyCode(ev.keyCode) || transformKey(ev.detail.key) || ''; | |
| 227 return { | |
| 228 shift: ev.shiftKey, | |
| 229 ctrl: ev.ctrlKey, | |
| 230 meta: ev.metaKey, | |
| 231 alt: ev.altKey, | |
| 232 key: normalizedKey | |
| 233 }; | |
| 234 } | |
| 235 | |
| 236 /* | |
| 237 * Input: ctrl+shift+f7 => {ctrl: true, shift: true, key: 'f7'} | |
| 238 * ctrl/space => {ctrl: true} || {key: space} | |
| 239 */ | |
| 240 function stringToKey(keyCombo) { | |
| 241 var keys = keyCombo.split('+'); | |
| 242 var keyObj = Object.create(null); | |
| 243 keys.forEach(function(key) { | |
| 244 if (key == 'shift') { | |
| 245 keyObj.shift = true; | |
| 246 } else if (key == 'ctrl') { | |
| 247 keyObj.ctrl = true; | |
| 248 } else if (key == 'alt') { | |
| 249 keyObj.alt = true; | |
| 250 } else { | |
| 251 keyObj.key = key; | |
| 252 } | |
| 253 }); | |
| 254 return keyObj; | |
| 255 } | |
| 256 | |
| 257 function keyMatches(a, b) { | |
| 258 return Boolean(a.alt) == Boolean(b.alt) && Boolean(a.ctrl) == Boolean(b.ct
rl) && Boolean(a.shift) == Boolean(b.shift) && a.key === b.key; | |
| 259 } | |
| 260 | |
| 261 /** | |
| 262 * Fired when a keycombo in `keys` is pressed. | |
| 263 * | |
| 264 * @event keys-pressed | |
| 265 */ | |
| 266 function processKeys(ev) { | |
| 267 var current = keyboardEventToKey(ev); | |
| 268 for (var i = 0, dk; i < this._desiredKeys.length; i++) { | |
| 269 dk = this._desiredKeys[i]; | |
| 270 if (keyMatches(dk, current)) { | |
| 271 ev.preventDefault(); | |
| 272 ev.stopPropagation(); | |
| 273 this.fire('keys-pressed', current, this, false); | |
| 274 break; | |
| 275 } | |
| 276 } | |
| 277 } | |
| 278 | |
| 279 function listen(node, handler) { | |
| 280 if (node && node.addEventListener) { | |
| 281 node.addEventListener('keydown', handler); | |
| 282 } | |
| 283 } | |
| 284 | |
| 285 function unlisten(node, handler) { | |
| 286 if (node && node.removeEventListener) { | |
| 287 node.removeEventListener('keydown', handler); | |
| 288 } | |
| 289 } | |
| 290 | |
| 291 Polymer('core-a11y-keys', { | |
| 292 created: function() { | |
| 293 this._keyHandler = processKeys.bind(this); | |
| 294 }, | |
| 295 attached: function() { | |
| 296 if (!this.target) { | |
| 297 this.target = this.parentNode; | |
| 298 } | |
| 299 listen(this.target, this._keyHandler); | |
| 300 }, | |
| 301 detached: function() { | |
| 302 unlisten(this.target, this._keyHandler); | |
| 303 }, | |
| 304 publish: { | |
| 305 /** | |
| 306 * The set of key combinations to listen for. | |
| 307 * | |
| 308 * @attribute keys | |
| 309 * @type string (keys syntax) | |
| 310 * @default '' | |
| 311 */ | |
| 312 keys: '', | |
| 313 /** | |
| 314 * The node that will fire keyboard events. | |
| 315 * Default to this element's parentNode unless one is assigned | |
| 316 * | |
| 317 * @attribute target | |
| 318 * @type Node | |
| 319 * @default this.parentNode | |
| 320 */ | |
| 321 target: null | |
| 322 }, | |
| 323 keysChanged: function() { | |
| 324 // * can have multiple mappings: shift+8, * on numpad or Multiply on num
pad | |
| 325 var normalized = this.keys.replace('*', '* shift+*'); | |
| 326 this._desiredKeys = normalized.toLowerCase().split(' ').map(stringToKey)
; | |
| 327 }, | |
| 328 targetChanged: function(oldTarget) { | |
| 329 unlisten(oldTarget, this._keyHandler); | |
| 330 listen(this.target, this._keyHandler); | |
| 331 } | |
| 332 }); | |
| 333 })(); | |
| 334 </script> | |
| 335 </polymer-element> | |
| OLD | NEW |