feat: implement polyfill

Signed-off-by: Till Sanders <mail@till-sanders.de>
tillsanders · Jan 9, 2021 · 4d85959 · 4d85959
1 parent e94b768
commit 4d85959
Show file tree

Hide file tree

Showing 15 changed files with 11,686 additions and 0 deletions.
diff --git a/.editorconfig b/.editorconfig
@@ -0,0 +1,13 @@
+# editorconfig.org
+root = true
+
+[*]
+indent_style = space
+indent_size = 2
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.md]
+trim_trailing_whitespace = false
diff --git a/.eslintrc.json b/.eslintrc.json
@@ -0,0 +1,39 @@
+{
+    "root": true,
+    "env": {
+        "browser": true,
+        "es2021": true
+    },
+    "extends": [
+        "airbnb-base"
+    ],
+    "parser": "@typescript-eslint/parser",
+    "parserOptions": {
+        "ecmaVersion": 12,
+        "sourceType": "module"
+    },
+    "plugins": [
+        "@typescript-eslint"
+    ],
+    "settings": {
+        "import/resolver": {
+            "node": {
+                "extensions": [".js", ".ts"]
+            }
+        }
+    },
+    "rules": {
+        "import/extensions": "off"
+    },
+    "overrides": [
+        {
+            "files": ["test/**/*.spec.{js,ts}"],
+            "env": {
+                "jest": true
+            },
+            "rules": {
+                "@typescript-eslint/no-explicit-any": "off"
+            }
+        }
+    ]
+}
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1,9 @@
+/logs
+*.log
+npm-debug.log*
+coverage
+node_modules/
+.npm
+.eslintcache
+dist
+.DS_Store
diff --git a/README.md b/README.md
@@ -0,0 +1,84 @@
+# AccessKeyLabelPolyfill
+
+> Polyfills the accessKeyLabel property to improve discoverability of native keyboard shortcuts for
+> your website. Tiny (< 1KB) and dependency-free.
+
+With the [`accesskey` HTML property](https://developer.mozilla.org/de/docs/Web/HTML/Globale_Attribute/accesskey),
+you can easily provide keyboard shortcuts for the buttons of your web application.
+
+```html
+<button accesskey="D">Do crazy stuff</button>
+<!-- Can be activated using Ctrl + Alt + D -->
+```
+
+Sadly, most users don't even know these shortcuts can be used, even if the web developer provided
+them. To make these shortcuts more discoverable you might decide to use the `title` property, a
+tooltip or some other UI element to display the keyboard shortcut.
+
+```html
+<button accesskey="D">Do crazy stuff</button>
+<small>Hint: Use Ctrl + Alt + D to quickly access this button!</small>
+```
+
+A good idea, but browsers use different combinations of modifier keys. But thanks to the
+[`accessKeyLabel` property](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/accessKeyLabel),
+we can easily get a string representation of the keyboard shortcut assigned by the browser. Sooo,
+we're good, right? Alas, not quite. Though the API has been around for years,
+[browser support](https://caniuse.com/?search=accessKeyLabel) isn't good enough. Especially, since
+Chrome is still missing out. To help bridge the gap, you can use this polyfill and finally let your
+users benefit from the keyboard shortcuts you provide!
+
+## Usage
+
+### NPM
+
+Simply install the polyfill:
+
+```sh
+npm i access-key-label-polyfill
+# or
+yarn add access-key-label-polyfill
+```
+
+And the import and run the install function:
+
+```javascript
+import installAccessKeyLabelPolyfill from 'access-key-label-polyfill';
+installAccessKeyLabelPolyfill();
+```
+
+Note: CJS, UMD and ESM are available, just take a look in the package.
+
+### Browser
+
+You can also use this polyfill 'oldschool'. Simply download the demo files and add the
+`AccessKeyLabelPolyfill.umd.js` file to your body:
+
+```html
+<body>
+  <!-- ... -->
+  <script src="path/to/AccessKeyLabelPolyfill.umd.js"></script>
+  <script>
+    accessKeyLabelPolyfill(); // lowerCamelCase!
+  </script>
+```
+
+## How does it work?
+
+First, the polyfill will try to detect wether the browser already supports `accessKeyLabel`. If it
+does, it will exit immediately. If the browser doesn't support this API, the polyfill will add a
+small function to fill the gap. This function will try to detect the browser / operating system and
+return the correct label. You can then use `accessKeyLabel` as expected.
+
+### Caveats
+
+- To return the correct label, the polyfill needs to determine the correct operating system, browser
+  and sometimes even the browser version. This is done with a very lightweight script and based on
+  the user-agent. While this has been tested successfully and should work reliably, wrong
+  user-agents can still mess it up, of course.
+- The polyfill currently supports the major browsers on macOS (including Firefox < v14), namely
+  Chrome. As well as Internet Explorer, Edge and Safari on iOS / iPadOS. There might be more
+  browsers, that need this polyfill, but there is surprisingly little information regarding support,
+  so please feel free to open an issue if you come across an unsupported case.
+- Chrome on Android does not seem to support `accessKey`, or at least, I was unable to guess (why
+  is this not documented anywhere?!) the correct modifier keys. Would love to get help with this!
diff --git a/babel.config.js b/babel.config.js
@@ -0,0 +1,6 @@
+module.exports = {
+  presets: [
+    ['@babel/preset-env', { targets: { node: 'current' } }],
+    '@babel/preset-typescript',
+  ],
+};
diff --git a/demo/AccessKeyLabelPolyfill.umd.js b/demo/AccessKeyLabelPolyfill.umd.js
diff --git a/demo/AccessKeyLabelPolyfill.umd.js.map b/demo/AccessKeyLabelPolyfill.umd.js.map
diff --git a/demo/index.html b/demo/index.html
@@ -0,0 +1,93 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>AccessKeyLabelPolyfill, Demo</title>
+  <style>
+    html {
+      font-family: sans-serif;
+      color: #333;
+      line-height: 1.4;
+    }
+    main {
+      display: flex;
+      flex-direction: column;
+      justify-content: center;
+      align-items: center;
+      height: 100vh;
+      padding: 1em;
+    }
+    button {
+      font-size: 2em;
+      padding: 0.875em 1em;
+      appearance: none;
+      border: 1px solid #EEE;
+      border-radius: 5px;
+    }
+    span {
+      display: block;
+      padding: 1em;
+    }
+    p {
+      position: absolute;
+      top: 1rem;
+      left: 1rem;
+      border-radius: 5px;
+      padding: 0.75em;
+      max-width: 30rem;
+      color: #FFF;
+      margin: 0;
+    }
+    p.supported {
+      background-color: #2ECC71;
+    }
+    p.unsupported {
+      background-color: #E67E22;
+    }
+  </style>
+</head>
+<body>
+  <main>
+    <button accesskey="p" onclick="alert('Geronimooooo!')"><u>P</u>ress me</button>
+    <p></p>
+  </main>
+  <script>
+    var button = document.querySelector('button');
+
+    function displayAccessKeyHint() {
+      // Display accesskey hint below button
+      var hint = document.createElement('span');
+      hint.innerText = button.accessKeyLabel
+      button.parentNode.insertBefore(hint, button.nextSibling);
+    }
+
+    // Check for browser support
+    var support = document.createElement('p');
+    var supported = !!Object.getOwnPropertyDescriptor(HTMLElement.prototype, 'accessKeyLabel')
+    if (supported) {
+      support.classList = 'supported'
+      support.innerText = 'Your browser already supports the accessKeyLabel property, so this polyfill will not do anything here.'
+    } else {
+      support.classList = 'unsupported'
+      support.innerText = 'Your browser does not support the accessKeyLabel property, so this polyfill will take action.'
+    }
+    button.parentNode.insertBefore(support, button.nextSibling);
+
+    if (!supported) {
+      // Load polyfill
+      var polyfill = document.createElement('script');
+      polyfill.src = './AccessKeyLabelPolyfill.umd.js';
+      polyfill.async = false;
+      polyfill.onload = function () {
+        accessKeyLabelPolyfill();
+        displayAccessKeyHint();
+      }
+      var head = document.head || document.getElementsByTagName('head')[0];
+      head.insertBefore(polyfill, head.firstChild);
+    } else {
+      displayAccessKeyHint();
+    }
+  </script>
+</body>
+</html>
diff --git a/jest.config.ts b/jest.config.ts
@@ -0,0 +1,8 @@
+export default {
+  clearMocks: true,
+  coverageDirectory: 'coverage',
+  coveragePathIgnorePatterns: [
+    '/node_modules/',
+  ],
+  coverageProvider: 'v8',
+};