Merge pull request #20 from myandrienko/transformers

add transformers api

README.md

@@ -59,16 +59,17 @@ Then add the `startKeyUX` call with the necessary features to the main JS file.
 import {
   hiddenKeyUX,
   hotkeyKeyUX,
+  hotkeyOverrides,
   jumpKeyUX,
   focusGroupKeyUX,
   pressKeyUX,
   startKeyUX
 } from 'keyux'
 
-const overrides = {}
+const overrides = hotkeyOverrides({})
 
 startKeyUX(window, [
-  hotkeyKeyUX(overrides),
+  hotkeyKeyUX([overrides]),
   focusGroupKeyUX(),
   pressKeyUX('is-pressed'),
   jumpKeyUX(),
@@ -127,6 +128,24 @@ external keyboard).
 For instance, for `alt+b` it will return `Alt + B` on Windows/Linux or `⌥ B`
 on Mac.
 
+If you're using overrides, pass the same override config both to `hotkeyKeyUX()`
+and `getHotKeyHint()` for accurate hints:
+
+```js
+import {
+  getHotKeyHint,
+  hotkeyOverrides,
+  hotkeyKeyUX,
+  startKeyUX
+} from 'keyux'
+
+let config = { 'alt+b': 'b' }
+
+startKeyUX(window, [
+  hotkeyKeyUX([hotkeyOverrides(config)]) // Override B to Alt + B
+])
+getHotKeyHint(window, 'b', [hotkeyOverrides(config)]) // Alt + B
+```
 
 ### Pressed State
 
@@ -161,8 +180,8 @@ to automatically add class for every `:active` state in your CSS.
 Many users want to override hotkeys because your hotkeys can conflict with
 their browser’s extensions, system, or screen reader.
 
-KeyUX allows overriding hotkeys using the `overrides` object.
-Both `hotkeyKeyUX()` and `getHotKeyHint()` accept it as an argument.
+KeyUX allows to override hotkeys using tranforms. Use the `hotkeyOverrides()` tranformer
+with `hotkeyKeyUX()` and `getHotKeyHint()`.
 
 You will need to create some UI for users to fill this object like:
 
@@ -172,10 +191,9 @@ const overrides = {
 }
 ```
 
-Then KeyUX will click on `aria-keyshortcuts="b"` when
-<kbd>Alt</kbd>+<kbd>B</kbd> is pressed, and
-`getHotKeyHint(window, 'b', overrides)` will return `Alt + B`/`⌥ B`.
-
+Then KeyUX will click on `aria-keyshortcuts="b"` when <kbd>Alt</kbd>+<kbd>B</kbd>
+is pressed, and `getHotKeyHint(window, 'b', [hotkeyOverrides(overrides)])`
+will return `Alt + B`/`⌥ B`.
 
 ### Hotkeys for List
 

hotkey.js

@@ -31,35 +31,38 @@ function findNonIgnored(activeElement, elements) {
   }
 }
 
-function checkHotkey(where, code, overrides) {
-  let codeOverride = overrides[code]
-  if (Object.values(overrides).includes(code) && !codeOverride) return false
+function checkHotkey(window, code, transformers) {
+  let realCode = code
+  for (let [transform] of transformers) {
+    realCode = transform(realCode, window)
+    if (!realCode) return false
+  }
 
+  let where = window.document
   let activeElement = where.activeElement
-  let actualCode = codeOverride || code
 
   let areaId = activeElement.getAttribute('data-keyux-hotkeys')
   if (areaId) {
     let area = where.querySelector(`#${areaId}`)
     if (area) {
-      let element = area.querySelector(`[aria-keyshortcuts="${actualCode}" i]`)
+      let element = area.querySelector(`[aria-keyshortcuts="${realCode}" i]`)
       if (element) return element
     }
   }
 
   return (
     findNonIgnored(
       activeElement,
-      activeElement.querySelectorAll(`[aria-keyshortcuts="${actualCode}" i]`)
+      activeElement.querySelectorAll(`[aria-keyshortcuts="${realCode}" i]`)
     ) ||
     findNonIgnored(
       where,
-      where.querySelectorAll(`[aria-keyshortcuts="${actualCode}" i]`)
+      where.querySelectorAll(`[aria-keyshortcuts="${realCode}" i]`)
     )
   )
 }
 
-function findHotKey(event, where, overrides) {
+function findHotKey(event, window, transformers) {
   let prefix = ''
   if (event.metaKey) prefix += 'meta+'
   if (event.ctrlKey) prefix += 'ctrl+'
@@ -73,24 +76,24 @@ function findHotKey(event, where, overrides) {
     code += event.key.toLowerCase()
   }
 
-  let hotkey = checkHotkey(where, code, overrides)
+  let hotkey = checkHotkey(window, code, transformers)
   if (
     !hotkey &&
     NON_ENGLISH_LAYOUT.test(event.key) &&
     /^Key.$/.test(event.code)
   ) {
     let enKey = event.code.replace(/^Key/, '').toLowerCase()
-    hotkey = checkHotkey(where, prefix + enKey, overrides)
+    hotkey = checkHotkey(window, prefix + enKey, transformers)
   }
 
   return hotkey
 }
 
-export function hotkeyKeyUX(overrides = {}) {
+export function hotkeyKeyUX(transformers = []) {
   return window => {
     function keyDown(event) {
       if (ignoreHotkeysIn(event.target)) return
-      let press = findHotKey(event, window.document, overrides)
+      let press = findHotKey(event, window, transformers)
       if (press) press.click()
     }
 

index.d.ts

@@ -38,6 +38,16 @@ export interface FocusGroupKeyUXOptions {
 
 export type HotkeyOverride = Record<string, string>
 
+type SingleDirectionTransformer = (
+  code: string,
+  window: MinimalWindow
+) => false | string
+
+export type Transformer = [
+  tranformForward: SingleDirectionTransformer,
+  transformReverse: SingleDirectionTransformer
+]
+
 /**
  * Press button/a according to `aria-keyshortcuts`.
  *
@@ -49,7 +59,7 @@ export type HotkeyOverride = Record<string, string>
  * ])
  * ```
  */
-export function hotkeyKeyUX(overrides?: HotkeyOverride): KeyUXModule
+export function hotkeyKeyUX(transformers?: Transformer[]): KeyUXModule
 
 /**
  * Add arrow-navigation on `role="menu"`.
@@ -142,7 +152,7 @@ export function likelyWithKeyboard(window: MinimalWindow): boolean
 /**
  * Return text for `<kbd>` element with hint for hot key.
  *
- * It replaced `Ctrl` with `⌘` on Mac and respects overrides.
+ * It replaces `Meta` with `⌘` etc on Mac.
  *
  * ```js
  * import { getHotKeyHint, likelyWithKeyboard } from 'keyux'
@@ -158,5 +168,21 @@ export function likelyWithKeyboard(window: MinimalWindow): boolean
 export function getHotKeyHint(
   window: MinimalWindow,
   code: string,
-  overrides?: HotkeyOverride
+  transformers?: Transformer[]
 ): string
+
+/**
+ * Provides a transformer for hotkey overrides that can be used
+ * with `hotkeyKeyUX()` and `getHotKeyHint()`.
+ *
+ * ```js
+ * import { getHotKeyHint, hotkeyKeyUX, hotkeyOverrides } from "keyux"
+ *
+ * let overrides = hotkeyOverrides({ 'alt+b': 'b' })
+ * startKeyUX(window, [
+ *   hotkeyKeyUX([overrides])
+ * ])
+ * getHotKeyHint(window, 'b', [overrides])
+ * ```
+ */
+export function hotkeyOverrides(overrides: HotkeyOverride): Transformer

index.js

@@ -3,6 +3,7 @@ export * from './hotkey.js'
 export * from './hidden.js'
 export * from './press.js'
 export * from './jump.js'
+export * from './overrides.js'
 
 export function startKeyUX(window, plugins) {
   let unbinds = plugins.map(plugin => plugin(window))
@@ -16,13 +17,10 @@ export function likelyWithKeyboard(window = globalThis) {
   return !['iphone', 'ipad', 'android'].some(device => agent.includes(device))
 }
 
-export function getHotKeyHint(window, code, overrides = {}) {
+export function getHotKeyHint(window, code, transformers = []) {
   let realCode = code
-  for (let i in overrides) {
-    if (overrides[i] === code) {
-      realCode = i
-      break
-    }
+  for (let transformer of transformers) {
+    realCode = transformer[1](realCode, window, 'r')
   }
   let prettyParts = realCode
     .split('+')

overrides.js

@@ -0,0 +1,18 @@
+export function hotkeyOverrides(overrides) {
+  return [
+    code => {
+      let realCode = overrides[code]
+      if (Object.values(overrides).includes(code) && !realCode) return false
+      return realCode || code
+    },
+
+    code => {
+      for (let i in overrides) {
+        if (overrides[i] === code) {
+          return i
+        }
+      }
+      return code
+    }
+  ]
+}

package.json

@@ -83,9 +83,9 @@
     {
       "name": "All modules",
       "import": {
-        "./index.js": "{ startKeyUX, hotkeyKeyUX, pressKeyUX, focusGroupKeyUX, jumpKeyUX, hiddenKeyUX, likelyWithKeyboard, getHotKeyHint }"
+        "./index.js": "{ startKeyUX, hotkeyKeyUX, pressKeyUX, focusGroupKeyUX, jumpKeyUX, hiddenKeyUX, likelyWithKeyboard, getHotKeyHint, hotkeyOverrides }"
       },
-      "limit": "1967 B"
+      "limit": "1996 B"
     }
   ],
   "clean-publish": {

test/demo/index.tsx

@@ -7,16 +7,18 @@ import {
   getHotKeyHint,
   hiddenKeyUX,
   hotkeyKeyUX,
+  hotkeyOverrides,
   jumpKeyUX,
   likelyWithKeyboard,
   pressKeyUX,
   startKeyUX
 } from '../../index.js'
 
 let overrides: HotkeyOverride = {}
+let overridesTransformer = hotkeyOverrides(overrides);
 
 startKeyUX(window, [
-  hotkeyKeyUX(overrides),
+  hotkeyKeyUX([overridesTransformer]),
   focusGroupKeyUX(),
   pressKeyUX('is-pressed'),
   jumpKeyUX(),
@@ -25,7 +27,7 @@ startKeyUX(window, [
 
 const HotKeyHint: FC<{ hotkey: string }> = ({ hotkey }) => {
   return likelyWithKeyboard(window) ? (
-    <kbd>{getHotKeyHint(window, hotkey, overrides)}</kbd>
+    <kbd>{getHotKeyHint(window, hotkey, [overridesTransformer])}</kbd>
   ) : null
 }
 

test/hotkey.test.ts

@@ -3,7 +3,7 @@ import { equal } from 'node:assert'
 import { test } from 'node:test'
 
 import type { HotkeyOverride } from '../index.js'
-import { hotkeyKeyUX, startKeyUX } from '../index.js'
+import { hotkeyKeyUX, hotkeyOverrides, startKeyUX } from '../index.js'
 
 function press(
   window: DOMWindow,
@@ -125,7 +125,7 @@ test('supports non-English keyboard layouts', () => {
 test('allows to override hotkeys', () => {
   let window = new JSDOM().window
   let overrides: HotkeyOverride = {}
-  startKeyUX(window, [hotkeyKeyUX(overrides)])
+  startKeyUX(window, [hotkeyKeyUX([hotkeyOverrides(overrides)])])
   window.document.body.innerHTML =
     '<button aria-keyshortcuts="b"></button>' +
     '<button aria-keyshortcuts="q"></button>'

test/index.test.ts

@@ -4,6 +4,7 @@ import { test } from 'node:test'
 
 import {
   getHotKeyHint,
+  hotkeyOverrides,
   likelyWithKeyboard,
   type MinimalWindow
 } from '../index.js'
@@ -34,7 +35,8 @@ test('makes hotkey hint prettier', () => {
     getHotKeyHint(window, 'meta+ctrl+shift+alt+b'),
     'Meta + Ctrl + Shift + Alt + B'
   )
-  equal(getHotKeyHint(window, 'alt+b', { b: 'alt+b' }), 'B')
+  equal(getHotKeyHint(window, 'alt+b', [hotkeyOverrides({ b: 'alt+b' })]), 'B')
+  equal(getHotKeyHint(window, 'q', [hotkeyOverrides({ b: 'alt+b' })]), 'Q')
 })
 
 test('makes mac hotkey hint prettier', () => {