feat: support cleanup handler shortcut api (#27)

* add tsdoc about handler cleanup api in `KbsDefinition`
* add shift+b example with cleanup method in dashboard

Closes: #26

Author: tpoisseau

src/app/Dashboard.tsx

@@ -1,17 +1,36 @@
+import { useState } from 'react';
+
 import { useKbsGlobal } from '../component/index.ts';
 
 import Playground from './Playground.tsx';
 import { useCounter } from './useCounter.ts';
 
 export default function Dashboard() {
   const [counter, shortcuts] = useCounter({ maxFrequency: 2 });
-  useKbsGlobal(shortcuts);
+  const [color, setColor] = useState('white');
+  useKbsGlobal([
+    ...shortcuts,
+    {
+      shortcut: { key: 'b', shift: true },
+      handler() {
+        setColor('black');
+
+        return () => setColor('white');
+      },
+    },
+  ]);
   return (
-    <div className="p-4 space-y-8">
+    <div
+      className={`p-4 space-y-8 ${color === 'white' ? 'bg-white text-black' : 'bg-black text-white'}`}
+    >
       <p>
         Dashboard counter: {counter}. Press I or C to increment (max 2 per
         second if held down) and D to decrement.
       </p>
+      <p>
+        Press <kbd>Shift+B</kbd> to invert the background color of the page.
+        Release <kbd>Shift</kbd> or <kbd>B</kbd> to reset.
+      </p>
       <Playground />
     </div>
   );

src/component/types.ts

@@ -16,9 +16,12 @@ export interface KbsKeyDefinitionCode extends KbsKeyDefinitionModifiers {
 
 export type KbsKeyDefinition = KbsKeyDefinitionKey | KbsKeyDefinitionCode;
 
-export type KbsHandler = (
+export type KbsHandlerCleaner = (
   event: KeyboardEvent<HTMLDivElement> | globalThis.KeyboardEvent,
 ) => void;
+export type KbsHandler = (
+  event: KeyboardEvent<HTMLDivElement> | globalThis.KeyboardEvent,
+) => KbsHandlerCleaner | void;
 
 /**
  * Extend this interface to customize the metadata type.
@@ -36,6 +39,8 @@ export interface KbsDefinition {
     | ReadonlyArray<string | KbsKeyDefinition>;
   /**
    * The handler function to call when the shortcut is triggered.
+   * If the handler returns a cleanup method (`KbsHandlerCleaner`),
+   * it will listen for keyup events and call the cleanup method once a key related to the shortcut is released.
    */
   handler: KbsHandler;
   /**

src/component/utils/get_key_down_handler.ts

@@ -18,6 +18,24 @@ export function useLastTriggerRef() {
   return useRef<LastTriggerData>({ keyOrCode: '', timestamp: 0 });
 }
 
+function parseEvent(
+  event: KeyboardEvent | ReactKeyboardEvent<HTMLDivElement>,
+  combinedShortcuts: Record<string, KbsInternalShortcut>,
+) {
+  const { key, code } = eventToKeyOrCode(event);
+  let keyOrCode;
+  let shortcut;
+  if (combinedShortcuts[key]) {
+    shortcut = combinedShortcuts[key];
+    keyOrCode = key;
+  } else {
+    shortcut = combinedShortcuts[code];
+    keyOrCode = code;
+  }
+
+  return { key, code, keyOrCode, shortcut };
+}
+
 export function getKeyDownHandler(
   lastTrigger: MutableRefObject<LastTriggerData>,
   combinedShortcuts: Record<string, KbsInternalShortcut>,
@@ -28,33 +46,41 @@ export function getKeyDownHandler(
     if (shouldIgnoreElement(event.target as HTMLElement)) {
       return;
     }
-    const { key, code } = eventToKeyOrCode(event);
-    let keyOrCode;
-    let shortcut;
-    if (combinedShortcuts[key]) {
-      shortcut = combinedShortcuts[key];
-      keyOrCode = key;
-    } else {
-      shortcut = combinedShortcuts[code];
-      keyOrCode = code;
-    }
-    if (shortcut) {
-      event.stopPropagation();
-      event.preventDefault();
-
-      if (shortcut.maxFrequency > 0) {
-        const now = performance.now();
-        if (
-          event.repeat &&
-          lastTrigger.current.keyOrCode === keyOrCode &&
-          now - lastTrigger.current.timestamp < 1000 / shortcut.maxFrequency
-        ) {
-          return;
-        }
-        lastTrigger.current = { keyOrCode, timestamp: now };
-      }
 
-      shortcut.handler(event);
+    const { key, keyOrCode, shortcut } = parseEvent(event, combinedShortcuts);
+    if (!shortcut) return;
+    const initialKeys = new Set(key.split(']_'));
+
+    event.stopPropagation();
+    event.preventDefault();
+
+    if (shortcut.maxFrequency > 0) {
+      const now = performance.now();
+      if (
+        event.repeat &&
+        lastTrigger.current.keyOrCode === keyOrCode &&
+        now - lastTrigger.current.timestamp < 1000 / shortcut.maxFrequency
+      ) {
+        return;
+      }
+      lastTrigger.current = { keyOrCode, timestamp: now };
     }
+
+    const cleanup = shortcut.handler(event);
+    if (!cleanup) return;
+
+    const handleKeyUp = (
+      event: KeyboardEvent | ReactKeyboardEvent<HTMLDivElement>,
+    ) => {
+      if (shouldIgnoreElement(event.target as HTMLElement)) return;
+      const { key } = parseEvent(event, combinedShortcuts);
+      const releasedKeys = key.split(']_');
+      if (!releasedKeys.some((key) => initialKeys.has(key))) return;
+
+      document.body.removeEventListener('keyup', handleKeyUp);
+      cleanup(event);
+    };
+
+    document.body.addEventListener('keyup', handleKeyUp);
   };
 }