add mac compatibility mode

README.md

@@ -128,7 +128,7 @@ 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()`
+If you’re using overrides, pass the same override config both to `hotkeyKeyUX()`
 and `getHotKeyHint()` for accurate hints:
 
 ```js
@@ -431,3 +431,26 @@ startKeyUX(window, [
   hiddenKeyUX()
 ])
 ```
+
+
+### Mac Compatibility Mode
+
+It’s common to use the <kbd>Meta</kbd> (or <kbd>⌘</kbd>) modifier for hotkeys
+on Mac, while Window and Linux usually favor the <kbd>Ctrl</kbd> key. To provide
+familiar experience on all platforms, enable the Mac compatibility transform:
+
+```js
+import {
+  hotkeyMacCompat,
+  hotkeyKeyUX,
+  startKeyUX,
+  getHotKeyHint
+} from 'keyux'
+
+const macCompat = hotkeyMacCompat();
+startKeyUX(window, [hotkeyKeyUX([macCompat])])
+getHotKeyHint(window, 'ctrl+b', [macCompat])
+```
+
+Hotkeys pressed with the <kbd>Meta</kbd> modifier will work as if the <kbd>Ctrl</kbd>
+modifier was pressed.

compat.js

@@ -0,0 +1,16 @@
+function maybeApplyCompat(code, window, from, to) {
+  if (
+    window.navigator.platform.indexOf('Mac') === 0 &&
+    !code.includes('meta+ctrl')
+  ) {
+    return code.replace(from, to)
+  }
+  return code
+}
+
+export function hotkeyMacCompat() {
+  return [
+    (code, window) => maybeApplyCompat(code, window, 'meta', 'ctrl'),
+    (code, window) => maybeApplyCompat(code, window, 'ctrl', 'meta')
+  ]
+}

index.d.ts

@@ -186,3 +186,9 @@ export function getHotKeyHint(
  * ```
  */
 export function hotkeyOverrides(overrides: HotkeyOverride): Transformer
+
+/**
+ * Provides a transformer for Mac compatibility mode that can be used
+ * with `hotkeyKeyUX()` and `getHotKeyHint()`.
+ */
+export function hotkeyMacCompat(): Transformer

index.js

@@ -4,6 +4,7 @@ export * from './hidden.js'
 export * from './press.js'
 export * from './jump.js'
 export * from './overrides.js'
+export * from './compat.js'
 
 export function startKeyUX(window, plugins) {
   let unbinds = plugins.map(plugin => plugin(window))

package.json

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

test/compat.test.ts

@@ -0,0 +1,30 @@
+import { JSDOM } from 'jsdom'
+import { equal } from 'node:assert'
+import { test } from 'node:test'
+
+import { hotkeyMacCompat } from '../compat.js'
+import type { MinimalWindow } from '../index.js'
+
+const MAC_WINDOW = {
+  navigator: {
+    platform: 'Mac',
+    userAgent: 'Mac'
+  }
+} as MinimalWindow
+
+const [tranformForward, transformReverse] = hotkeyMacCompat()
+
+test('applies hotkey compatibility for Mac platform', () => {
+  equal(tranformForward('meta+shift+b', MAC_WINDOW), 'ctrl+shift+b')
+  equal(tranformForward('meta+ctrl+shift+b', MAC_WINDOW), 'meta+ctrl+shift+b')
+})
+
+test('applies hint compatibility for Mac platform', () => {
+  equal(transformReverse('ctrl+shift+b', MAC_WINDOW), 'meta+shift+b')
+  equal(transformReverse('meta+ctrl+shift+b', MAC_WINDOW), 'meta+ctrl+shift+b')
+})
+
+test('does nothing for non-Mac platform', () => {
+  equal(tranformForward('meta+shift+b', new JSDOM().window), 'meta+shift+b')
+  equal(transformReverse('ctrl+shift+b', new JSDOM().window), 'ctrl+shift+b')
+})

test/demo/index.tsx

@@ -7,6 +7,7 @@ import {
   getHotKeyHint,
   hiddenKeyUX,
   hotkeyKeyUX,
+  hotkeyMacCompat,
   hotkeyOverrides,
   jumpKeyUX,
   likelyWithKeyboard,
@@ -15,10 +16,11 @@ import {
 } from '../../index.js'
 
 let overrides: HotkeyOverride = {}
-let overridesTransformer = hotkeyOverrides(overrides);
+let overridesTransformer = hotkeyOverrides(overrides)
+let macCompatTransformer = hotkeyMacCompat()
 
 startKeyUX(window, [
-  hotkeyKeyUX([overridesTransformer]),
+  hotkeyKeyUX([macCompatTransformer, overridesTransformer]),
   focusGroupKeyUX(),
   pressKeyUX('is-pressed'),
   jumpKeyUX(),
@@ -27,7 +29,12 @@ startKeyUX(window, [
 
 const HotKeyHint: FC<{ hotkey: string }> = ({ hotkey }) => {
   return likelyWithKeyboard(window) ? (
-    <kbd>{getHotKeyHint(window, hotkey, [overridesTransformer])}</kbd>
+    <kbd>
+      {getHotKeyHint(window, hotkey, [
+        overridesTransformer,
+        macCompatTransformer
+      ])}
+    </kbd>
   ) : null
 }
 
@@ -343,15 +350,15 @@ const Tabs: FC = () => {
 const Toolbar: FC = () => {
   return (
     <>
-      <div className='toolbar' role="toolbar">
+      <div className="toolbar" role="toolbar">
         <div className="toolbar_group">
           <button className="toolbar_button" type="button">Copy</button>
           <button className="toolbar_button" type="button">Paste</button>
           <button className="toolbar_button" type="button">Cut</button>
         </div>
         <div className="toolbar_group">
           <label className="toolbar_label">
-            <input type="checkbox"/>
+            <input type="checkbox" />
             Night Mode
           </label>
         </div>