third_party/polymer/v1_0/components-chromium/iron-a11y-keys-behavior/iron-a11y-keys-behavior-extracted.js

   1
   2   (function() {
   3     'use strict';
   4
   5     /**
   6      * Chrome uses an older version of DOM Level 3 Keyboard Events
   7      *
   8      * Most keys are labeled as text, but some are Unicode codepoints.
   9      * Values taken from: http://www.w3.org/TR/2007/WD-DOM-Level-3-Events-20071221/keyset.html#KeySet-Set
  10      */
  11     var KEY_IDENTIFIER = {
  12       'U+0009': 'tab',
  13       'U+001B': 'esc',
  14       'U+0020': 'space',
  15       'U+002A': '*',
  16       'U+0030': '0',
  17       'U+0031': '1',
  18       'U+0032': '2',
  19       'U+0033': '3',
  20       'U+0034': '4',
  21       'U+0035': '5',
  22       'U+0036': '6',
  23       'U+0037': '7',
  24       'U+0038': '8',
  25       'U+0039': '9',
  26       'U+0041': 'a',
  27       'U+0042': 'b',
  28       'U+0043': 'c',
  29       'U+0044': 'd',
  30       'U+0045': 'e',
  31       'U+0046': 'f',
  32       'U+0047': 'g',
  33       'U+0048': 'h',
  34       'U+0049': 'i',
  35       'U+004A': 'j',
  36       'U+004B': 'k',
  37       'U+004C': 'l',
  38       'U+004D': 'm',
  39       'U+004E': 'n',
  40       'U+004F': 'o',
  41       'U+0050': 'p',
  42       'U+0051': 'q',
  43       'U+0052': 'r',
  44       'U+0053': 's',
  45       'U+0054': 't',
  46       'U+0055': 'u',
  47       'U+0056': 'v',
  48       'U+0057': 'w',
  49       'U+0058': 'x',
  50       'U+0059': 'y',
  51       'U+005A': 'z',
  52       'U+007F': 'del'
  53     };
  54
  55     /**
  56      * Special table for KeyboardEvent.keyCode.
  57      * KeyboardEvent.keyIdentifier is better, and KeyBoardEvent.key is even better
  58      * than that.
  59      *
  60      * Values from: https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent.keyCode#Value_of_keyCode
  61      */
  62     var KEY_CODE = {
  63       9: 'tab',
  64       13: 'enter',
  65       27: 'esc',
  66       33: 'pageup',
  67       34: 'pagedown',
  68       35: 'end',
  69       36: 'home',
  70       32: 'space',
  71       37: 'left',
  72       38: 'up',
  73       39: 'right',
  74       40: 'down',
  75       46: 'del',
  76       106: '*'
  77     };
  78
  79     /**
  80      * MODIFIER_KEYS maps the short name for modifier keys used in a key
  81      * combo string to the property name that references those same keys
  82      * in a KeyboardEvent instance.
  83      */
  84     var MODIFIER_KEYS = {
  85       'shift': 'shiftKey',
  86       'ctrl': 'ctrlKey',
  87       'alt': 'altKey',
  88       'meta': 'metaKey'
  89     };
  90
  91     /**
  92      * KeyboardEvent.key is mostly represented by printable character made by
  93      * the keyboard, with unprintable keys labeled nicely.
  94      *
  95      * However, on OS X, Alt+char can make a Unicode character that follows an
  96      * Apple-specific mapping. In this case, we
  97      * fall back to .keyCode.
  98      */
  99     var KEY_CHAR = /[a-z0-9*]/;
 100
 101     /**
 102      * Matches a keyIdentifier string.
 103      */
 104     var IDENT_CHAR = /U\+/;
 105
 106     /**
 107      * Matches arrow keys in Gecko 27.0+
 108      */
 109     var ARROW_KEY = /^arrow/;
 110
 111     /**
 112      * Matches space keys everywhere (notably including IE10's exceptional name
 113      * `spacebar`).
 114      */
 115     var SPACE_KEY = /^space(bar)?/;
 116
 117     function transformKey(key) {
 118       var validKey = '';
 119       if (key) {
 120         var lKey = key.toLowerCase();
 121         if (lKey.length == 1) {
 122           if (KEY_CHAR.test(lKey)) {
 123             validKey = lKey;
 124           }
 125         } else if (ARROW_KEY.test(lKey)) {
 126           validKey = lKey.replace('arrow', '');
 127         } else if (SPACE_KEY.test(lKey)) {
 128           validKey = 'space';
 129         } else if (lKey == 'multiply') {
 130           // numpad '*' can map to Multiply on IE/Windows
 131           validKey = '*';
 132         } else {
 133           validKey = lKey;
 134         }
 135       }
 136       return validKey;
 137     }
 138
 139     function transformKeyIdentifier(keyIdent) {
 140       var validKey = '';
 141       if (keyIdent) {
 142         if (IDENT_CHAR.test(keyIdent)) {
 143           validKey = KEY_IDENTIFIER[keyIdent];
 144         } else {
 145           validKey = keyIdent.toLowerCase();
 146         }
 147       }
 148       return validKey;
 149     }
 150
 151     function transformKeyCode(keyCode) {
 152       var validKey = '';
 153       if (Number(keyCode)) {
 154         if (keyCode >= 65 && keyCode <= 90) {
 155           // ascii a-z
 156           // lowercase is 32 offset from uppercase
 157           validKey = String.fromCharCode(32 + keyCode);
 158         } else if (keyCode >= 112 && keyCode <= 123) {
 159           // function keys f1-f12
 160           validKey = 'f' + (keyCode - 112);
 161         } else if (keyCode >= 48 && keyCode <= 57) {
 162           // top 0-9 keys
 163           validKey = String(48 - keyCode);
 164         } else if (keyCode >= 96 && keyCode <= 105) {
 165           // num pad 0-9
 166           validKey = String(96 - keyCode);
 167         } else {
 168           validKey = KEY_CODE[keyCode];
 169         }
 170       }
 171       return validKey;
 172     }
 173
 174     function normalizedKeyForEvent(keyEvent) {
 175       // fall back from .key, to .keyIdentifier, to .keyCode, and then to
 176       // .detail.key to support artificial keyboard events
 177       return transformKey(keyEvent.key) ||
 178         transformKeyIdentifier(keyEvent.keyIdentifier) ||
 179         transformKeyCode(keyEvent.keyCode) ||
 180         transformKey(keyEvent.detail.key) || '';
 181     }
 182
 183     function keyComboMatchesEvent(keyCombo, keyEvent) {
 184       return normalizedKeyForEvent(keyEvent) === keyCombo.key &&
 185         !!keyEvent.shiftKey === !!keyCombo.shiftKey &&
 186         !!keyEvent.ctrlKey === !!keyCombo.ctrlKey &&
 187         !!keyEvent.altKey === !!keyCombo.altKey &&
 188         !!keyEvent.metaKey === !!keyCombo.metaKey;
 189     }
 190
 191     function parseKeyComboString(keyComboString) {
 192       return keyComboString.split('+').reduce(function(parsedKeyCombo, keyComboPart) {
 193         var eventParts = keyComboPart.split(':');
 194         var keyName = eventParts[0];
 195         var event = eventParts[1];
 196
 197         if (keyName in MODIFIER_KEYS) {
 198           parsedKeyCombo[MODIFIER_KEYS[keyName]] = true;
 199         } else {
 200           parsedKeyCombo.key = keyName;
 201           parsedKeyCombo.event = event || 'keydown';
 202         }
 203
 204         return parsedKeyCombo;
 205       }, {
 206         combo: keyComboString.split(':').shift()
 207       });
 208     }
 209
 210     function parseEventString(eventString) {
 211       return eventString.split(' ').map(function(keyComboString) {
 212         return parseKeyComboString(keyComboString);
 213       });
 214     }
 215
 216
 217     /**
 218      * `Polymer.IronA11yKeysBehavior` provides a normalized interface for processing
 219      * keyboard commands that pertain to [WAI-ARIA best practices](http://www.w3.org/TR/wai-aria-practices/#kbd_general_binding).
 220      * The element takes care of browser differences with respect to Keyboard events
 221      * and uses an expressive syntax to filter key presses.
 222      *
 223      * Use the `keyBindings` prototype property to express what combination of keys
 224      * will trigger the event to fire.
 225      *
 226      * Use the `key-event-target` attribute to set up event handlers on a specific
 227      * node.
 228      * The `keys-pressed` event will fire when one of the key combinations set with the
 229      * `keys` property is pressed.
 230      *
 231      * @demo demo/index.html
 232      * @polymerBehavior IronA11yKeysBehavior
 233      */
 234     Polymer.IronA11yKeysBehavior = {
 235       properties: {
 236         /**
 237          * The HTMLElement that will be firing relevant KeyboardEvents.
 238          */
 239         keyEventTarget: {
 240           type: Object,
 241           value: function() {
 242             return this;
 243           }
 244         },
 245
 246         _boundKeyHandlers: {
 247           type: Array,
 248           value: function() {
 249             return [];
 250           }
 251         },
 252
 253         // We use this due to a limitation in IE10 where instances will have
 254         // own properties of everything on the "prototype".
 255         _imperativeKeyBindings: {
 256           type: Object,
 257           value: function() {
 258             return {};
 259           }
 260         }
 261       },
 262
 263       observers: [
 264         '_resetKeyEventListeners(keyEventTarget, _boundKeyHandlers)'
 265       ],
 266
 267       keyBindings: {},
 268
 269       registered: function() {
 270         this._prepKeyBindings();
 271       },
 272
 273       attached: function() {
 274         this._listenKeyEventListeners();
 275       },
 276
 277       detached: function() {
 278         this._unlistenKeyEventListeners();
 279       },
 280
 281       /**
 282        * Can be used to imperatively add a key binding to the implementing
 283        * element. This is the imperative equivalent of declaring a keybinding
 284        * in the `keyBindings` prototype property.
 285        */
 286       addOwnKeyBinding: function(eventString, handlerName) {
 287         this._imperativeKeyBindings[eventString] = handlerName;
 288         this._prepKeyBindings();
 289         this._resetKeyEventListeners();
 290       },
 291
 292       /**
 293        * When called, will remove all imperatively-added key bindings.
 294        */
 295       removeOwnKeyBindings: function() {
 296         this._imperativeKeyBindings = {};
 297         this._prepKeyBindings();
 298         this._resetKeyEventListeners();
 299       },
 300
 301       keyboardEventMatchesKeys: function(event, eventString) {
 302         var keyCombos = parseEventString(eventString);
 303         var index;
 304
 305         for (index = 0; index < keyCombos.length; ++index) {
 306           if (keyComboMatchesEvent(keyCombos[index], event)) {
 307             return true;
 308           }
 309         }
 310
 311         return false;
 312       },
 313
 314       _collectKeyBindings: function() {
 315         var keyBindings = this.behaviors.map(function(behavior) {
 316           return behavior.keyBindings;
 317         });
 318
 319         if (keyBindings.indexOf(this.keyBindings) === -1) {
 320           keyBindings.push(this.keyBindings);
 321         }
 322
 323         return keyBindings;
 324       },
 325
 326       _prepKeyBindings: function() {
 327         this._keyBindings = {};
 328
 329         this._collectKeyBindings().forEach(function(keyBindings) {
 330           for (var eventString in keyBindings) {
 331             this._addKeyBinding(eventString, keyBindings[eventString]);
 332           }
 333         }, this);
 334
 335         for (var eventString in this._imperativeKeyBindings) {
 336           this._addKeyBinding(eventString, this._imperativeKeyBindings[eventString]);
 337         }
 338       },
 339
 340       _addKeyBinding: function(eventString, handlerName) {
 341         parseEventString(eventString).forEach(function(keyCombo) {
 342           this._keyBindings[keyCombo.event] =
 343             this._keyBindings[keyCombo.event] || [];
 344
 345           this._keyBindings[keyCombo.event].push([
 346             keyCombo,
 347             handlerName
 348           ]);
 349         }, this);
 350       },
 351
 352       _resetKeyEventListeners: function() {
 353         this._unlistenKeyEventListeners();
 354
 355         if (this.isAttached) {
 356           this._listenKeyEventListeners();
 357         }
 358       },
 359
 360       _listenKeyEventListeners: function() {
 361         Object.keys(this._keyBindings).forEach(function(eventName) {
 362           var keyBindings = this._keyBindings[eventName];
 363           var boundKeyHandler = this._onKeyBindingEvent.bind(this, keyBindings);
 364
 365           this._boundKeyHandlers.push([this.keyEventTarget, eventName, boundKeyHandler]);
 366
 367           this.keyEventTarget.addEventListener(eventName, boundKeyHandler);
 368         }, this);
 369       },
 370
 371       _unlistenKeyEventListeners: function() {
 372         var keyHandlerTuple;
 373         var keyEventTarget;
 374         var eventName;
 375         var boundKeyHandler;
 376
 377         while (this._boundKeyHandlers.length) {
 378           // My kingdom for block-scope binding and destructuring assignment..
 379           keyHandlerTuple = this._boundKeyHandlers.pop();
 380           keyEventTarget = keyHandlerTuple[0];
 381           eventName = keyHandlerTuple[1];
 382           boundKeyHandler = keyHandlerTuple[2];
 383
 384           keyEventTarget.removeEventListener(eventName, boundKeyHandler);
 385         }
 386       },
 387
 388       _onKeyBindingEvent: function(keyBindings, event) {
 389         keyBindings.forEach(function(keyBinding) {
 390           var keyCombo = keyBinding[0];
 391           var handlerName = keyBinding[1];
 392
 393           if (!event.defaultPrevented && keyComboMatchesEvent(keyCombo, event)) {
 394             this._triggerKeyHandler(keyCombo, handlerName, event);
 395           }
 396         }, this);
 397       },
 398
 399       _triggerKeyHandler: function(keyCombo, handlerName, keyboardEvent) {
 400         var detail = Object.create(keyCombo);
 401         detail.keyboardEvent = keyboardEvent;
 402
 403         this[handlerName].call(this, new CustomEvent(keyCombo.event, {
 404           detail: detail
 405         }));
 406       }
 407     };
 408   })();