{"version":3,"file":"useKeyboardShortcuts.mjs","sources":["../../../src/lib/hooks/useKeyboardShortcuts.tsx"],"sourcesContent":["/**\n * @file Keyboard Shortcuts Hook\n * @description Hook for managing and documenting keyboard shortcuts\n *\n * WCAG 2.1 Reference:\n * - 2.1.1 Keyboard (Level A)\n * - 2.1.4 Character Key Shortcuts (Level A)\n * - 3.3.5 Help (Level AAA)\n */\n\n/* @refresh reset */\n/* eslint-disable react-refresh/only-export-components */\n\nimport React, { useCallback, useEffect, useMemo, useRef, useState } from 'react';\nimport { useFeatureFlag } from '../flags/useFeatureFlag';\nimport { flagKeys } from '../flags/flag-keys';\n\n/**\n * Keyboard shortcut definition\n */\nexport interface KeyboardShortcut {\n /** Unique identifier for the shortcut */\n id: string;\n /** Human-readable description of what the shortcut does */\n description: string;\n /** Key combination (e.g., 'Ctrl+S', 'Escape', 'Alt+N') */\n keys: string;\n /** Category for grouping shortcuts */\n category?: string;\n /** Whether the shortcut is enabled */\n enabled?: boolean;\n /** The handler function to execute */\n handler: (event: KeyboardEvent) => void;\n}\n\n/**\n * Parsed key combination\n */\ninterface ParsedKeys {\n ctrlKey: boolean;\n shiftKey: boolean;\n altKey: boolean;\n metaKey: boolean;\n key: string;\n}\n\n/**\n * Options for the keyboard shortcuts hook\n */\nexport interface UseKeyboardShortcutsOptions {\n /** Whether to prevent default behavior when a shortcut is triggered */\n preventDefault?: boolean;\n /** Whether to stop propagation when a shortcut is triggered */\n stopPropagation?: boolean;\n /** Scope element (defaults to document) */\n scope?: HTMLElement | null;\n /** Whether shortcuts are globally enabled */\n enabled?: boolean;\n}\n\n/**\n * Parse a key combination string into modifier flags and key\n */\nfunction parseKeyCombo(keys: string): ParsedKeys {\n const parts = keys.toLowerCase().split('+');\n const key = parts.pop() ?? '';\n\n return {\n ctrlKey: parts.includes('ctrl') || parts.includes('control'),\n shiftKey: parts.includes('shift'),\n altKey: parts.includes('alt'),\n metaKey: parts.includes('meta') || parts.includes('cmd') || parts.includes('command'),\n key: key === 'space' ? ' ' : key,\n };\n}\n\n/**\n * Check if an event matches a parsed key combination\n */\nfunction matchesKeyCombo(event: KeyboardEvent, parsed: ParsedKeys): boolean {\n const eventKey = event.key.toLowerCase();\n\n return (\n event.ctrlKey === parsed.ctrlKey &&\n event.shiftKey === parsed.shiftKey &&\n event.altKey === parsed.altKey &&\n event.metaKey === parsed.metaKey &&\n (eventKey === parsed.key || event.code.toLowerCase() === parsed.key)\n );\n}\n\n/**\n * Format a key combination for display\n */\nexport function formatKeyCombo(keys: string): string {\n const isMac = typeof navigator !== 'undefined' && /Mac|iPod|iPhone|iPad/.test(navigator.platform);\n\n return keys\n .split('+')\n .map((key) => {\n const k = key.trim().toLowerCase();\n switch (k) {\n case 'ctrl':\n case 'control':\n return isMac ? '^' : 'Ctrl';\n case 'alt':\n return isMac ? '?' : 'Alt';\n case 'shift':\n return isMac ? '?' : 'Shift';\n case 'meta':\n case 'cmd':\n case 'command':\n return isMac ? '?' : 'Win';\n case 'space':\n return 'Space';\n case 'escape':\n case 'esc':\n return 'Esc';\n case 'enter':\n case 'return':\n return isMac ? '?' : 'Enter';\n case 'backspace':\n return isMac ? '?' : 'Backspace';\n case 'delete':\n return isMac ? '?' : 'Delete';\n case 'arrowup':\n return isMac ? '?' : 'Up';\n case 'arrowdown':\n return isMac ? '?' : 'Down';\n case 'arrowleft':\n return isMac ? '?' : 'Left';\n case 'arrowright':\n return isMac ? '?' : 'Right';\n default:\n return key.toUpperCase();\n }\n })\n .join(isMac ? '' : ' + ');\n}\n\n/**\n * Hook for managing keyboard shortcuts with documentation\n *\n * @example\n * ```tsx\n * function MyComponent() {\n * const { shortcuts } = useKeyboardShortcuts([\n * {\n * id: 'save',\n * description: 'Save changes',\n * keys: 'Ctrl+S',\n * category: 'Actions',\n * handler: () => saveDocument(),\n * },\n * {\n * id: 'close',\n * description: 'Close panel',\n * keys: 'Escape',\n * category: 'Navigation',\n * handler: () => closePanel(),\n * },\n * ]);\n *\n * return (\n * \n * \n *
\n * );\n * }\n * ```\n */\nexport function useKeyboardShortcuts(\n shortcuts: KeyboardShortcut[],\n options: UseKeyboardShortcutsOptions = {}\n): {\n shortcuts: KeyboardShortcut[];\n shortcutsByCategory: Record;\n enableShortcut: (id: string) => void;\n disableShortcut: (id: string) => void;\n toggleShortcut: (id: string) => void;\n /** Whether keyboard shortcuts are globally enabled via feature flag */\n isFeatureEnabled: boolean;\n} {\n // Check if keyboard shortcuts are enabled via feature flag\n const keyboardShortcutsFeatureEnabled = useFeatureFlag(flagKeys.KEYBOARD_SHORTCUTS);\n\n const { preventDefault = true, stopPropagation = false, scope = null, enabled = true } = options;\n\n // Combine feature flag with options.enabled\n const effectivelyEnabled = enabled && keyboardShortcutsFeatureEnabled;\n\n const [enabledShortcuts, setEnabledShortcuts] = useState>(() => {\n const initial: Record = {};\n shortcuts.forEach((s) => {\n initial[s.id] = s.enabled !== false;\n });\n return initial;\n });\n\n const shortcutsRef = useRef(shortcuts);\n shortcutsRef.current = shortcuts;\n\n // Parse all key combinations once\n const parsedShortcuts = useMemo(() => {\n return shortcuts.map((shortcut) => ({\n ...shortcut,\n parsed: parseKeyCombo(shortcut.keys),\n }));\n }, [shortcuts]);\n\n // Group shortcuts by category\n const shortcutsByCategory = useMemo(() => {\n const grouped: Record = {};\n shortcuts.forEach((shortcut) => {\n const category = shortcut.category ?? 'General';\n grouped[category] ??= [];\n grouped[category].push(shortcut);\n });\n return grouped;\n }, [shortcuts]);\n\n // Handle keydown events\n useEffect(() => {\n if (!effectivelyEnabled) return;\n\n const handleKeyDown = (event: KeyboardEvent): void => {\n // Don't trigger shortcuts when typing in inputs\n const target = event.target as HTMLElement;\n if (\n target.tagName === 'INPUT' ||\n target.tagName === 'TEXTAREA' ||\n target.tagName === 'SELECT' ||\n target.isContentEditable\n ) {\n // Allow Escape to work in inputs\n if (event.key !== 'Escape') {\n return;\n }\n }\n\n for (const shortcut of parsedShortcuts) {\n if (!enabledShortcuts[shortcut.id]) continue;\n\n if (matchesKeyCombo(event, shortcut.parsed)) {\n if (preventDefault) {\n event.preventDefault();\n }\n if (stopPropagation) {\n event.stopPropagation();\n }\n shortcut.handler(event);\n return;\n }\n }\n };\n\n const element = scope ?? document;\n element.addEventListener('keydown', handleKeyDown as EventListener);\n\n return () => {\n element.removeEventListener('keydown', handleKeyDown as EventListener);\n };\n }, [\n effectivelyEnabled,\n parsedShortcuts,\n enabledShortcuts,\n preventDefault,\n stopPropagation,\n scope,\n ]);\n\n const enableShortcut = useCallback((id: string) => {\n setEnabledShortcuts((prev) => ({ ...prev, [id]: true }));\n }, []);\n\n const disableShortcut = useCallback((id: string) => {\n setEnabledShortcuts((prev) => ({ ...prev, [id]: false }));\n }, []);\n\n const toggleShortcut = useCallback((id: string) => {\n setEnabledShortcuts((prev) => ({ ...prev, [id]: !prev[id] }));\n }, []);\n\n return {\n shortcuts,\n shortcutsByCategory,\n enableShortcut,\n disableShortcut,\n toggleShortcut,\n isFeatureEnabled: keyboardShortcutsFeatureEnabled,\n };\n}\n\n/**\n * Component to display keyboard shortcuts help\n *\n * @example\n * ```tsx\n * \n * ```\n */\nexport interface KeyboardShortcutsHelpProps {\n shortcuts: KeyboardShortcut[];\n title?: string;\n className?: string;\n style?: React.CSSProperties;\n}\n\nexport function KeyboardShortcutsHelp({\n shortcuts,\n title = 'Keyboard Shortcuts',\n className,\n style,\n}: KeyboardShortcutsHelpProps): React.ReactElement {\n // Group by category\n const grouped = useMemo(() => {\n const result: Record = {};\n shortcuts.forEach((s) => {\n const cat = s.category ?? 'General';\n result[cat] ??= [];\n result[cat].push(s);\n });\n return result;\n }, [shortcuts]);\n\n return (\n \n \n {title}\n \n\n {Object.entries(grouped).map(([category, categoryShortcuts]) => (\n \n
\n {category}\n \n \n {categoryShortcuts.map((shortcut) => (\n \n - {shortcut.description}
\n - \n \n {formatKeyCombo(shortcut.keys)}\n \n
\n