@pyreon/hotkeys 0.6.0

package/src/index.ts

@@ -0,0 +1,49 @@
+/**
+ * @pyreon/hotkeys — Reactive keyboard shortcut management for Pyreon.
+ *
+ * Register global or scoped keyboard shortcuts with automatic lifecycle
+ * management. Supports modifier keys, aliases, input filtering, and
+ * scope-based activation.
+ *
+ * @example
+ * ```ts
+ * import { useHotkey, useHotkeyScope } from '@pyreon/hotkeys'
+ *
+ * // Global shortcut
+ * useHotkey('ctrl+s', () => save(), { description: 'Save' })
+ *
+ * // Scoped shortcut — only active when scope is enabled
+ * useHotkeyScope('editor')
+ * useHotkey('ctrl+z', () => undo(), { scope: 'editor' })
+ *
+ * // Platform-aware — mod = ⌘ on Mac, Ctrl elsewhere
+ * useHotkey('mod+k', () => openCommandPalette())
+ * ```
+ */
+
+// ─── Hooks ───────────────────────────────────────────────────────────────────
+
+export { useHotkey } from './use-hotkey'
+export { useHotkeyScope } from './use-hotkey-scope'
+
+// ─── Imperative API ──────────────────────────────────────────────────────────
+
+export {
+  disableScope,
+  enableScope,
+  getActiveScopes,
+  getRegisteredHotkeys,
+  registerHotkey,
+} from './registry'
+
+// ─── Utilities ───────────────────────────────────────────────────────────────
+
+export { formatCombo, matchesCombo, parseShortcut } from './parse'
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export type { HotkeyEntry, HotkeyOptions, KeyCombo } from './types'
+
+// ─── Testing ─────────────────────────────────────────────────────────────────
+
+export { _resetHotkeys } from './registry'

package/src/parse.ts

@@ -0,0 +1,93 @@
+import type { KeyCombo } from './types'
+
+// ─── Key aliases ─────────────────────────────────────────────────────────────
+
+const KEY_ALIASES: Record<string, string> = {
+  esc: 'escape',
+  return: 'enter',
+  del: 'delete',
+  ins: 'insert',
+  space: ' ',
+  spacebar: ' ',
+  up: 'arrowup',
+  down: 'arrowdown',
+  left: 'arrowleft',
+  right: 'arrowright',
+  plus: '+',
+}
+
+/**
+ * Parse a shortcut string like 'ctrl+shift+s' into a KeyCombo.
+ * Supports aliases (esc, del, space, etc.) and mod (ctrl on Windows/Linux, meta on Mac).
+ */
+export function parseShortcut(shortcut: string): KeyCombo {
+  const parts = shortcut.toLowerCase().trim().split('+')
+  const combo: KeyCombo = {
+    ctrl: false,
+    shift: false,
+    alt: false,
+    meta: false,
+    key: '',
+  }
+
+  for (const part of parts) {
+    const p = part.trim()
+    if (p === 'ctrl' || p === 'control') {
+      combo.ctrl = true
+    } else if (p === 'shift') {
+      combo.shift = true
+    } else if (p === 'alt') {
+      combo.alt = true
+    } else if (p === 'meta' || p === 'cmd' || p === 'command') {
+      combo.meta = true
+    } else if (p === 'mod') {
+      // mod = meta on Mac, ctrl elsewhere
+      if (isMac()) {
+        combo.meta = true
+      } else {
+        combo.ctrl = true
+      }
+    } else {
+      combo.key = KEY_ALIASES[p] ?? p
+    }
+  }
+
+  return combo
+}
+
+/**
+ * Check if a KeyboardEvent matches a KeyCombo.
+ */
+export function matchesCombo(event: KeyboardEvent, combo: KeyCombo): boolean {
+  if (event.ctrlKey !== combo.ctrl) return false
+  if (event.shiftKey !== combo.shift) return false
+  if (event.altKey !== combo.alt) return false
+  if (event.metaKey !== combo.meta) return false
+
+  const eventKey = event.key.toLowerCase()
+  return eventKey === combo.key
+}
+
+/**
+ * Format a KeyCombo back to a human-readable string.
+ */
+export function formatCombo(combo: KeyCombo): string {
+  const parts: string[] = []
+  if (combo.ctrl) parts.push('Ctrl')
+  if (combo.shift) parts.push('Shift')
+  if (combo.alt) parts.push('Alt')
+  if (combo.meta) parts.push(isMac() ? '⌘' : 'Meta')
+  parts.push(
+    combo.key.length === 1 ? combo.key.toUpperCase() : capitalize(combo.key),
+  )
+  return parts.join('+')
+}
+
+function capitalize(s: string): string {
+  return s.charAt(0).toUpperCase() + s.slice(1)
+}
+
+function isMac(): boolean {
+  if (typeof navigator === 'undefined') return false
+  return /mac|iphone|ipad|ipod/i.test(navigator.userAgent)
+}

package/src/registry.ts

@@ -0,0 +1,151 @@
+import type { Signal } from '@pyreon/reactivity'
+import { signal } from '@pyreon/reactivity'
+import { matchesCombo, parseShortcut } from './parse'
+import type { HotkeyEntry, HotkeyOptions } from './types'
+
+// ─── State ───────────────────────────────────────────────────────────────────
+
+const entries: HotkeyEntry[] = []
+const activeScopes = signal<Set<string>>(new Set(['global']))
+let listenerAttached = false
+
+// ─── Input detection ─────────────────────────────────────────────────────────
+
+const INPUT_TAGS = new Set(['INPUT', 'TEXTAREA', 'SELECT'])
+
+function isInputFocused(event: KeyboardEvent): boolean {
+  const target = event.target as HTMLElement | null
+  if (!target) return false
+  if (INPUT_TAGS.has(target.tagName)) return true
+  if (target.isContentEditable) return true
+  return false
+}
+
+// ─── Global listener ─────────────────────────────────────────────────────────
+
+function attachListener(): void {
+  if (listenerAttached) return
+  if (typeof window === 'undefined') return
+  listenerAttached = true
+
+  window.addEventListener('keydown', (event) => {
+    const scopes = activeScopes.peek()
+
+    for (const entry of entries) {
+      // Check scope
+      if (!scopes.has(entry.options.scope)) continue
+
+      // Check enabled
+      const enabled =
+        typeof entry.options.enabled === 'function'
+          ? entry.options.enabled()
+          : entry.options.enabled
+      if (!enabled) continue
+
+      // Check input focus
+      if (!entry.options.enableOnInputs && isInputFocused(event)) continue
+
+      // Check key match
+      if (!matchesCombo(event, entry.combo)) continue
+
+      // Match found
+      if (entry.options.preventDefault) event.preventDefault()
+      if (entry.options.stopPropagation) event.stopPropagation()
+      entry.handler(event)
+    }
+  })
+}
+
+// ─── Registration ────────────────────────────────────────────────────────────
+
+/**
+ * Register a keyboard shortcut. Returns an unregister function.
+ *
+ * @example
+ * ```ts
+ * const unregister = registerHotkey('ctrl+s', (e) => save(), { description: 'Save' })
+ * // later: unregister()
+ * ```
+ */
+export function registerHotkey(
+  shortcut: string,
+  handler: (event: KeyboardEvent) => void,
+  options?: HotkeyOptions,
+): () => void {
+  attachListener()
+
+  const entry: HotkeyEntry = {
+    shortcut,
+    combo: parseShortcut(shortcut),
+    handler,
+    options: {
+      scope: options?.scope ?? 'global',
+      preventDefault: options?.preventDefault !== false,
+      stopPropagation: options?.stopPropagation === true,
+      enableOnInputs: options?.enableOnInputs === true,
+      enabled: options?.enabled ?? true,
+      description: options?.description,
+    },
+  }
+
+  entries.push(entry)
+
+  return () => {
+    const idx = entries.indexOf(entry)
+    if (idx !== -1) entries.splice(idx, 1)
+  }
+}
+
+// ─── Scope management ────────────────────────────────────────────────────────
+
+/**
+ * Activate a hotkey scope. 'global' is always active.
+ */
+export function enableScope(scope: string): void {
+  const current = activeScopes.peek()
+  if (current.has(scope)) return
+  const next = new Set(current)
+  next.add(scope)
+  activeScopes.set(next)
+}
+
+/**
+ * Deactivate a hotkey scope. Cannot deactivate 'global'.
+ */
+export function disableScope(scope: string): void {
+  if (scope === 'global') return
+  const current = activeScopes.peek()
+  if (!current.has(scope)) return
+  const next = new Set(current)
+  next.delete(scope)
+  activeScopes.set(next)
+}
+
+/**
+ * Get the currently active scopes as a reactive signal.
+ */
+export function getActiveScopes(): Signal<Set<string>> {
+  return activeScopes
+}
+
+/**
+ * Get all registered hotkeys (for building help dialogs).
+ */
+export function getRegisteredHotkeys(): ReadonlyArray<{
+  shortcut: string
+  scope: string
+  description?: string
+}> {
+  return entries.map((e) => ({
+    shortcut: e.shortcut,
+    scope: e.options.scope,
+    description: e.options.description,
+  }))
+}
+
+// ─── Reset (for testing) ────────────────────────────────────────────────────
+
+export function _resetHotkeys(): void {
+  entries.length = 0
+  activeScopes.set(new Set(['global']))
+}