feat(keyboard): apply modifier state (#815)

src/keyboard/index.ts

@@ -20,11 +20,19 @@ export function createKeyboardState(): keyboardState {
     pressed: [],
     carryChar: '',
     modifiers: {
-      alt: false,
-      caps: false,
-      ctrl: false,
-      meta: false,
-      shift: false,
+      Alt: false,
+      AltGraph: false,
+      Control: false,
+      CapsLock: false,
+      Fn: false,
+      FnLock: false,
+      Meta: false,
+      NumLock: false,
+      ScrollLock: false,
+      Shift: false,
+      Symbol: false,
+      SymbolLock: false,
     },
+    modifierPhase: {},
   }
 }

src/keyboard/keyMap.ts

@@ -72,5 +72,10 @@ export const defaultKeyMap: keyboardKey[] = [
   {code: 'PageUp', key: 'PageUp'},
   {code: 'PageDown', key: 'PageDown'},
 
+  // Special keys that are not part of a default US-layout but included for specific behavior
+  {code: 'Fn', key: 'Fn'},
+  {code: 'Symbol', key: 'Symbol'},
+  {code: 'AltRight', key: 'AltGraph'},
+
   // TODO: add mappings
 ]

src/keyboard/keyboardAction.ts

@@ -1,9 +1,8 @@
 import {fireEvent} from '@testing-library/dom'
 import {Config} from '../setup'
-import {getActiveElement, wait} from '../utils'
+import {getActiveElement, getKeyEventProps, wait} from '../utils'
 import {behaviorPlugin, keyboardKey} from './types'
 import * as plugins from './plugins'
-import {getKeyEventProps} from './getEventProps'
 
 export interface KeyboardAction {
   keyDef: keyboardKey
@@ -162,7 +161,7 @@ function applyPlugins(
 function hasKeyPress(keyDef: keyboardKey, config: Config) {
   return (
     (keyDef.key?.length === 1 || keyDef.key === 'Enter') &&
-    !config.keyboardState.modifiers.ctrl &&
-    !config.keyboardState.modifiers.alt
+    !config.keyboardState.modifiers.Control &&
+    !config.keyboardState.modifiers.Alt
   )
 }

src/keyboard/plugins/character.ts

@@ -171,7 +171,7 @@ export const keypressBehavior: behaviorPlugin[] = [
       prepareInput(
         '\n',
         element,
-        isContentEditable(element) && !keyboardState.modifiers.shift
+        isContentEditable(element) && !keyboardState.modifiers.Shift
           ? 'insertParagraph'
           : 'insertLineBreak',
       )?.commit()

src/keyboard/plugins/combination.ts

@@ -8,7 +8,7 @@ import {selectAll} from '../../utils'
 export const keydownBehavior: behaviorPlugin[] = [
   {
     matches: (keyDef, element, {keyboardState}) =>
-      keyDef.code === 'KeyA' && keyboardState.modifiers.ctrl,
+      keyDef.code === 'KeyA' && keyboardState.modifiers.Control,
     handle: (keyDef, element) => selectAll(element),
   },
 ]

src/keyboard/plugins/functional.ts

@@ -9,53 +9,16 @@ import {
   blur,
   focus,
   getTabDestination,
+  getUIEventModifiers,
   hasFormSubmit,
   isClickableInput,
   isEditable,
   isElementType,
   prepareInput,
 } from '../../utils'
-import {getKeyEventProps, getMouseEventProps} from '../getEventProps'
 import {behaviorPlugin} from '../types'
 
-const modifierKeys = {
-  Alt: 'alt',
-  Control: 'ctrl',
-  Shift: 'shift',
-  Meta: 'meta',
-} as const
-
-export const preKeydownBehavior: behaviorPlugin[] = [
-  // modifierKeys switch on the modifier BEFORE the keydown event
-  ...Object.entries(modifierKeys).map(
-    ([key, modKey]): behaviorPlugin => ({
-      matches: keyDef => keyDef.key === key,
-      handle: (keyDef, element, {keyboardState}) => {
-        keyboardState.modifiers[modKey] = true
-      },
-    }),
-  ),
-
-  // AltGraph produces an extra keydown for Control
-  // The modifier does not change
-  {
-    matches: keyDef => keyDef.key === 'AltGraph',
-    handle: (keyDef, element, {keyboardMap, keyboardState}) => {
-      const ctrlKeyDef = keyboardMap.find(
-        k => k.key === 'Control',
-      ) ?? /* istanbul ignore next */ {key: 'Control', code: 'Control'}
-      fireEvent.keyDown(element, getKeyEventProps(ctrlKeyDef, keyboardState))
-    },
-  },
-]
-
 export const keydownBehavior: behaviorPlugin[] = [
-  {
-    matches: keyDef => keyDef.key === 'CapsLock',
-    handle: (keyDef, element, {keyboardState}) => {
-      keyboardState.modifiers.caps = !keyboardState.modifiers.caps
-    },
-  },
   {
     matches: (keyDef, element) =>
       keyDef.key === 'Backspace' && isEditable(element),
@@ -66,7 +29,7 @@ export const keydownBehavior: behaviorPlugin[] = [
   {
     matches: keyDef => keyDef.key === 'Tab',
     handle: (keyDef, element, {keyboardState}) => {
-      const dest = getTabDestination(element, keyboardState.modifiers.shift)
+      const dest = getTabDestination(element, keyboardState.modifiers.Shift)
       if (dest === element.ownerDocument.body) {
         blur(element)
       } else {
@@ -103,7 +66,7 @@ export const keypressBehavior: behaviorPlugin[] = [
         // Links with href defined should handle Enter the same as a click
         (isElementType(element, 'a') && Boolean(element.href))),
     handle: (keyDef, element, {keyboardState}) => {
-      fireEvent.click(element, getMouseEventProps(keyboardState))
+      fireEvent.click(element, getUIEventModifiers(keyboardState))
     },
   },
   {
@@ -122,38 +85,12 @@ export const keypressBehavior: behaviorPlugin[] = [
   },
 ]
 
-export const preKeyupBehavior: behaviorPlugin[] = [
-  // modifierKeys switch off the modifier BEFORE the keyup event
-  ...Object.entries(modifierKeys).map(
-    ([key, modKey]): behaviorPlugin => ({
-      matches: keyDef => keyDef.key === key,
-      handle: (keyDef, element, {keyboardState}) => {
-        keyboardState.modifiers[modKey] = false
-      },
-    }),
-  ),
-]
-
 export const keyupBehavior: behaviorPlugin[] = [
   {
     matches: (keyDef, element) =>
       keyDef.key === ' ' && isClickableInput(element),
     handle: (keyDef, element, {keyboardState}) => {
-      fireEvent.click(element, getMouseEventProps(keyboardState))
-    },
-  },
-]
-
-export const postKeyupBehavior: behaviorPlugin[] = [
-  // AltGraph produces an extra keyup for Control
-  // The modifier does not change
-  {
-    matches: keyDef => keyDef.key === 'AltGraph',
-    handle: (keyDef, element, {keyboardMap, keyboardState}) => {
-      const ctrlKeyDef = keyboardMap.find(
-        k => k.key === 'Control',
-      ) ?? /* istanbul ignore next */ {key: 'Control', code: 'Control'}
-      fireEvent.keyUp(element, getKeyEventProps(ctrlKeyDef, keyboardState))
+      fireEvent.click(element, getUIEventModifiers(keyboardState))
     },
   },
 ]

src/keyboard/plugins/index.ts

@@ -4,9 +4,10 @@ import * as controlKeys from './control'
 import * as characterKeys from './character'
 import * as functionalKeys from './functional'
 import * as combination from './combination'
+import * as modifiers from './modifiers'
 
 export const preKeydownBehavior: behaviorPlugin[] = [
-  ...functionalKeys.preKeydownBehavior,
+  ...modifiers.preKeydownBehavior,
 ]
 
 export const keydownBehavior: behaviorPlugin[] = [
@@ -22,11 +23,11 @@ export const keypressBehavior: behaviorPlugin[] = [
 ]
 
 export const preKeyupBehavior: behaviorPlugin[] = [
-  ...functionalKeys.preKeyupBehavior,
+  ...modifiers.preKeyupBehavior,
 ]
 
 export const keyupBehavior: behaviorPlugin[] = [...functionalKeys.keyupBehavior]
 
 export const postKeyupBehavior: behaviorPlugin[] = [
-  ...functionalKeys.postKeyupBehavior,
+  ...modifiers.postKeyupBehavior,
 ]

src/keyboard/plugins/modifiers.ts

@@ -0,0 +1,92 @@
+/**
+ * This file should contain behavior for modifier keys:
+ * https://www.w3.org/TR/uievents-key/#keys-modifier
+ */
+
+import {fireEvent} from '@testing-library/dom'
+import {getKeyEventProps} from '../../utils'
+import {behaviorPlugin} from '../types'
+
+const modifierKeys = [
+  'Alt',
+  'AltGraph',
+  'Control',
+  'Fn',
+  'Meta',
+  'Shift',
+  'Symbol',
+] as const
+type ModififierKey = typeof modifierKeys[number]
+
+const modifierLocks = [
+  'CapsLock',
+  'FnLock',
+  'NumLock',
+  'ScrollLock',
+  'SymbolLock',
+] as const
+type ModififierLockKey = typeof modifierLocks[number]
+
+// modifierKeys switch on the modifier BEFORE the keydown event
+export const preKeydownBehavior: behaviorPlugin[] = [
+  {
+    matches: keyDef => modifierKeys.includes(keyDef.key as ModififierKey),
+    handle: (keyDef, element, {keyboardMap, keyboardState}) => {
+      keyboardState.modifiers[keyDef.key as ModififierKey] = true
+
+      // AltGraph produces an extra keydown for Control
+      // The modifier does not change
+      if (keyDef.key === 'AltGraph') {
+        const ctrlKeyDef = keyboardMap.find(
+          k => k.key === 'Control',
+        ) ?? /* istanbul ignore next */ {key: 'Control', code: 'Control'}
+        fireEvent.keyDown(element, getKeyEventProps(ctrlKeyDef, keyboardState))
+      }
+    },
+  },
+  {
+    matches: keyDef => modifierLocks.includes(keyDef.key as ModififierLockKey),
+    handle: (keyDef, element, {keyboardState}) => {
+      const key = keyDef.key as ModififierLockKey
+      keyboardState.modifierPhase[key] = keyboardState.modifiers[key]
+
+      if (!keyboardState.modifierPhase[key]) {
+        keyboardState.modifiers[key] = true
+      }
+    },
+  },
+]
+
+// modifierKeys switch off the modifier BEFORE the keyup event
+export const preKeyupBehavior: behaviorPlugin[] = [
+  {
+    matches: keyDef => modifierKeys.includes(keyDef.key as ModififierKey),
+    handle: (keyDef, element, {keyboardState}) => {
+      keyboardState.modifiers[keyDef.key as ModififierKey] = false
+    },
+  },
+  {
+    matches: keyDef => modifierLocks.includes(keyDef.key as ModififierLockKey),
+    handle: (keyDef, element, {keyboardState}) => {
+      const key = keyDef.key as ModififierLockKey
+
+      if (keyboardState.modifierPhase[key]) {
+        keyboardState.modifiers[key] = false
+      }
+    },
+  },
+]
+
+export const postKeyupBehavior: behaviorPlugin[] = [
+  // AltGraph produces an extra keyup for Control
+  // The modifier does not change
+  {
+    matches: keyDef => keyDef.key === 'AltGraph',
+    handle: (keyDef, element, {keyboardMap, keyboardState}) => {
+      const ctrlKeyDef = keyboardMap.find(
+        k => k.key === 'Control',
+      ) ?? /* istanbul ignore next */ {key: 'Control', code: 'Control'}
+      fireEvent.keyUp(element, getKeyEventProps(ctrlKeyDef, keyboardState))
+    },
+  },
+]

src/keyboard/types.ts

@@ -13,11 +13,25 @@ export type keyboardState = {
       Active modifiers
     */
   modifiers: {
-    alt: boolean
-    caps: boolean
-    ctrl: boolean
-    meta: boolean
-    shift: boolean
+    Alt: boolean
+    AltGraph: boolean
+    CapsLock: boolean
+    Control: boolean
+    Fn: boolean
+    FnLock: boolean
+    Meta: boolean
+    NumLock: boolean
+    ScrollLock: boolean
+    Shift: boolean
+    Symbol: boolean
+    SymbolLock: boolean
+  }
+  modifierPhase: {
+    CapsLock?: boolean
+    FnLock?: boolean
+    NumLock?: boolean
+    ScrollLock?: boolean
+    SymbolLock?: boolean
   }
 
   /**

src/utils/index.ts

@@ -27,6 +27,9 @@ export * from './focus/selectAll'
 export * from './focus/selection'
 export * from './focus/selector'
 
+export * from './keyboard/getKeyEventProps'
+export * from './keyboard/getUIEventModifiers'
+
 export * from './keyDef/readNextDescriptor'
 
 export * from './misc/eventWrapper'

src/utils/keyboard/getKeyEventProps.ts

@@ -0,0 +1,10 @@
+import {keyboardKey, keyboardState} from '../../keyboard/types'
+import {getUIEventModifiers} from './getUIEventModifiers'
+
+export function getKeyEventProps(keyDef: keyboardKey, state: keyboardState) {
+  return {
+    key: keyDef.key,
+    code: keyDef.code,
+    ...getUIEventModifiers(state),
+  }
+}

src/utils/keyboard/getUIEventModifiers.ts

@@ -0,0 +1,18 @@
+import type {keyboardState} from '../../keyboard'
+
+export function getUIEventModifiers(keyboardState: keyboardState) {
+  return {
+    altKey: keyboardState.modifiers.Alt,
+    ctrlKey: keyboardState.modifiers.Control,
+    metaKey: keyboardState.modifiers.Meta,
+    shiftKey: keyboardState.modifiers.Shift,
+    modifierAltGraph: keyboardState.modifiers.AltGraph,
+    modifierCapsLock: keyboardState.modifiers.CapsLock,
+    modifierFn: keyboardState.modifiers.Fn,
+    modifierFnLock: keyboardState.modifiers.FnLock,
+    modifierNumLock: keyboardState.modifiers.NumLock,
+    modifierScrollLock: keyboardState.modifiers.ScrollLock,
+    modifierSymbol: keyboardState.modifiers.Symbol,
+    modifierSymbolLock: keyboardState.modifiers.SymbolLock,
+  }
+}