@pyreon/hotkeys 0.24.5 → 0.24.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyreon/hotkeys",
-  "version": "0.24.5",
+  "version": "0.24.6",
   "description": "Reactive keyboard shortcut management for Pyreon — scope-aware, conflict detection",
   "homepage": "https://github.com/pyreon/pyreon/tree/main/packages/hotkeys#readme",
   "bugs": {
@@ -15,7 +15,6 @@
   "files": [
     "lib",
     "!lib/**/*.map",
-    "src",
     "README.md",
     "LICENSE"
   ],
@@ -26,7 +25,6 @@
   "types": "./lib/types/index.d.ts",
   "exports": {
     ".": {
-      "bun": "./src/index.ts",
       "import": "./lib/index.js",
       "types": "./lib/types/index.d.ts"
     }
@@ -43,13 +41,13 @@
   },
   "devDependencies": {
     "@happy-dom/global-registrator": "^20.8.9",
-    "@pyreon/core": "^0.24.5",
+    "@pyreon/core": "^0.24.6",
     "@pyreon/manifest": "0.13.1",
-    "@pyreon/reactivity": "^0.24.5",
+    "@pyreon/reactivity": "^0.24.6",
     "@vitus-labs/tools-lint": "^2.4.0"
   },
   "dependencies": {
-    "@pyreon/core": "^0.24.5",
-    "@pyreon/reactivity": "^0.24.5"
+    "@pyreon/core": "^0.24.6",
+    "@pyreon/reactivity": "^0.24.6"
   }
 }

package/src/index.ts

@@ -1,49 +0,0 @@
-/**
- * @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/manifest.ts

@@ -1,119 +0,0 @@
-import { defineManifest } from '@pyreon/manifest'
-
-export default defineManifest({
-  name: '@pyreon/hotkeys',
-  title: 'Keyboard Shortcuts',
-  tagline:
-    'Keyboard shortcut management — scope-aware, modifier keys, conflict detection',
-  description:
-    'Reactive keyboard shortcut management for Pyreon. Register global or scoped shortcuts with automatic lifecycle management. Supports `mod` alias (Command on Mac, Ctrl elsewhere), multi-key combos, scope-based activation for context-aware shortcuts, and conflict detection. Component-scoped hooks auto-unregister on unmount. Imperative API available for non-component contexts.',
-  category: 'universal',
-  longExample: `import { useHotkey, useHotkeyScope, registerHotkey, getRegisteredHotkeys, enableScope, disableScope } from '@pyreon/hotkeys'
-
-// Global shortcut — auto-unregisters on unmount
-useHotkey('mod+s', (e) => {
-  e.preventDefault()  // prevent browser save dialog
-  save()
-}, { description: 'Save document' })
-
-// Platform-aware: mod = ⌘ on Mac, Ctrl on Windows/Linux
-useHotkey('mod+k', () => openCommandPalette())
-
-// Multi-key combo
-useHotkey('ctrl+shift+p', () => openPreferences())
-
-// Scoped shortcuts — only active when scope is enabled
-useHotkeyScope('editor')  // activates 'editor' scope for this component's lifetime
-
-useHotkey('ctrl+z', () => undo(), { scope: 'editor', description: 'Undo' })
-useHotkey('ctrl+shift+z', () => redo(), { scope: 'editor', description: 'Redo' })
-useHotkey('ctrl+d', () => duplicateLine(), { scope: 'editor' })
-
-// Imperative API — for non-component contexts (stores, middleware)
-const unregister = registerHotkey('ctrl+q', () => quit(), { scope: 'global' })
-// unregister() when done
-
-// Introspection
-const hotkeys = getRegisteredHotkeys()  // all registered shortcuts
-enableScope('modal')                     // programmatically enable a scope
-disableScope('editor')                   // programmatically disable a scope
-
-// Shortcuts can filter input elements — by default, shortcuts
-// don't fire when focused on <input>, <textarea>, <select>.
-// Override with:
-useHotkey('escape', () => closeModal(), { enableOnFormElements: true })`,
-  features: [
-    'useHotkey(shortcut, handler, options?) — component-scoped, auto-unregisters on unmount',
-    'useHotkeyScope(scope) — activate a scope for a component\'s lifetime',
-    'mod alias — Command on Mac, Ctrl elsewhere',
-    'Scope-based activation for context-aware shortcuts',
-    'Imperative API: registerHotkey, enableScope, disableScope, getRegisteredHotkeys',
-    'parseShortcut / matchesCombo / formatCombo utilities',
-  ],
-  api: [
-    {
-      name: 'useHotkey',
-      kind: 'hook',
-      signature:
-        '(shortcut: string, handler: (e: KeyboardEvent) => void, options?: HotkeyOptions) => void',
-      summary:
-        'Register a keyboard shortcut that auto-unregisters when the component unmounts. Shortcut format: `mod+s`, `ctrl+shift+p`, `escape`, etc. `mod` is Command on Mac, Ctrl elsewhere. By default, shortcuts don\'t fire when focused on form elements (input, textarea, select) — override with `enableOnFormElements: true`. Supports `scope` option for context-aware activation and `description` for introspection.',
-      example: `useHotkey('mod+s', (e) => {
-  e.preventDefault()
-  save()
-}, { description: 'Save' })
-
-useHotkey('ctrl+z', () => undo(), { scope: 'editor' })
-useHotkey('escape', () => close(), { enableOnFormElements: true })`,
-      mistakes: [
-        'Forgetting e.preventDefault() for browser-reserved shortcuts (mod+s, mod+p) — the browser dialog fires alongside your handler',
-        'Registering the same shortcut in overlapping scopes without priority — both handlers fire; use scope isolation to prevent conflicts',
-        'Using useHotkey outside a component body — the onUnmount cleanup requires an active component setup context',
-        'Not activating the scope — useHotkey with a scope option does nothing unless useHotkeyScope(scope) is called or enableScope(scope) is invoked',
-      ],
-      seeAlso: ['useHotkeyScope', 'registerHotkey'],
-    },
-    {
-      name: 'useHotkeyScope',
-      kind: 'hook',
-      signature: '(scope: string) => void',
-      summary:
-        'Activate a hotkey scope for the lifetime of the current component. When the component mounts, the scope is enabled; when it unmounts, the scope is disabled. Shortcuts registered with a matching `scope` option only fire when the scope is active. Multiple components can activate the same scope — it stays active until the last one unmounts.',
-      example: `// In an editor component:
-useHotkeyScope('editor')
-useHotkey('ctrl+z', () => undo(), { scope: 'editor' })
-
-// In a modal component:
-useHotkeyScope('modal')
-useHotkey('escape', () => close(), { scope: 'modal' })`,
-      mistakes: [
-        'Using useHotkeyScope outside a component body — the lifecycle hooks require an active setup context',
-        'Assuming scope deactivation is immediate on unmount — if another component also activated the scope, it stays active',
-      ],
-      seeAlso: ['useHotkey', 'enableScope', 'disableScope'],
-    },
-    {
-      name: 'registerHotkey',
-      kind: 'function',
-      signature:
-        '(shortcut: string, handler: (e: KeyboardEvent) => void, options?: HotkeyOptions) => () => void',
-      summary:
-        'Imperative hotkey registration for non-component contexts (stores, global setup). Returns an unregister function. Unlike useHotkey, this does NOT auto-cleanup on unmount — caller is responsible for calling the returned unregister function.',
-      example: `const unregister = registerHotkey('ctrl+q', () => quit(), { scope: 'global' })
-// Later:
-unregister()`,
-      seeAlso: ['useHotkey'],
-    },
-  ],
-  gotchas: [
-    'By default, shortcuts do NOT fire when focused on form elements (input, textarea, select). Pass `enableOnFormElements: true` in options to override. Escape is a common candidate for this override.',
-    {
-      label: 'mod alias',
-      note: '`mod` maps to Command on macOS, Ctrl on Windows/Linux. Write `mod+s` instead of platform-specific `ctrl+s` / `cmd+s` for cross-platform shortcuts.',
-    },
-    {
-      label: 'Scopes',
-      note: 'Scoped shortcuts only fire when their scope is active. Activate with `useHotkeyScope(scope)` (component-scoped) or `enableScope(scope)` (imperative). Without activation, scoped handlers are silently dormant.',
-    },
-  ],
-})

package/src/parse.ts

@@ -1,91 +0,0 @@
-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

@@ -1,176 +0,0 @@
-import type { Signal } from '@pyreon/reactivity'
-import { signal } from '@pyreon/reactivity'
-import { matchesCombo, parseShortcut } from './parse'
-import type { HotkeyEntry, HotkeyOptions } from './types'
-
-// ─── State ───────────────────────────────────────────────────────────────────
-
-// Linear array on purpose. Per-keystroke dispatch (line 35) iterates entries
-// in registration order — O(n) where n = registered hotkeys. For real apps
-// (single-digit to low-tens) the cost is sub-microsecond and well under the
-// 16ms frame budget. Switching to a Map<comboKey, entries[]> would help only
-// past ~5,000 hotkeys, which is unrealistic. The array also preserves
-// registration order for the rare case where two hotkeys match the same
-// combo on different scopes — first-registered wins. Don't replace with a
-// Map without confirming a real app actually hits the perf wall.
-const entries: HotkeyEntry[] = []
-const activeScopes = signal<Set<string>>(new Set(['global']))
-let listenerAttached = false
-let keydownHandler: ((event: KeyboardEvent) => void) | null = null
-
-// ─── 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
-
-  keydownHandler = (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)
-    }
-  }
-
-  window.addEventListener('keydown', keydownHandler)
-}
-
-function detachListener(): void {
-  if (typeof window === 'undefined') return
-  if (!listenerAttached || !keydownHandler) return
-  window.removeEventListener('keydown', keydownHandler)
-  listenerAttached = false
-  keydownHandler = null
-}
-
-// ─── 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,
-      ...(options?.description != null ? { description: options.description } : {}),
-    },
-  }
-
-  entries.push(entry)
-
-  return () => {
-    const idx = entries.indexOf(entry)
-    if (idx !== -1) entries.splice(idx, 1)
-
-    // Detach listener if no more entries
-    if (entries.length === 0) {
-      detachListener()
-    }
-  }
-}
-
-// ─── 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,
-    ...(e.options.description != null ? { description: e.options.description } : {}),
-  }))
-}
-
-// ─── Reset (for testing) ────────────────────────────────────────────────
-
-export function _resetHotkeys(): void {
-  entries.length = 0
-  activeScopes.set(new Set(['global']))
-  detachListener()
-}

package/src/tests/hooks-coverage.test.ts

@@ -1,120 +0,0 @@
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
-
-let unmountCallbacks: Array<() => void> = []
-
-vi.mock('@pyreon/core', () => ({
-  onUnmount: (fn: () => void) => {
-    unmountCallbacks.push(fn)
-  },
-}))
-
-import {
-  _resetHotkeys,
-  getActiveScopes,
-  getRegisteredHotkeys,
-} from '../registry'
-import { useHotkey } from '../use-hotkey'
-import { useHotkeyScope } from '../use-hotkey-scope'
-
-function fireKey(
-  key: string,
-  modifiers: Partial<{
-    ctrlKey: boolean
-    shiftKey: boolean
-    altKey: boolean
-    metaKey: boolean
-  }> = {},
-): void {
-  const event = new KeyboardEvent('keydown', {
-    key,
-    ctrlKey: modifiers.ctrlKey ?? false,
-    shiftKey: modifiers.shiftKey ?? false,
-    altKey: modifiers.altKey ?? false,
-    metaKey: modifiers.metaKey ?? false,
-    bubbles: true,
-    cancelable: true,
-  })
-  window.dispatchEvent(event)
-}
-
-describe('useHotkey', () => {
-  beforeEach(() => {
-    _resetHotkeys()
-    unmountCallbacks = []
-  })
-
-  afterEach(() => {
-    _resetHotkeys()
-  })
-
-  it('registers a hotkey that fires on keydown', () => {
-    let fired = false
-    useHotkey('ctrl+s', () => {
-      fired = true
-    })
-
-    fireKey('s', { ctrlKey: true })
-    expect(fired).toBe(true)
-  })
-
-  it('unregisters hotkey on unmount', () => {
-    let count = 0
-    useHotkey('ctrl+s', () => {
-      count++
-    })
-
-    fireKey('s', { ctrlKey: true })
-    expect(count).toBe(1)
-
-    // Simulate unmount
-    unmountCallbacks.forEach((fn) => fn())
-
-    fireKey('s', { ctrlKey: true })
-    expect(count).toBe(1) // should not fire after unmount
-  })
-
-  it('passes options to registerHotkey', () => {
-    useHotkey('ctrl+s', () => {}, { description: 'Save', scope: 'editor' })
-    const hotkeys = getRegisteredHotkeys()
-    expect(hotkeys).toHaveLength(1)
-    expect(hotkeys[0]!.description).toBe('Save')
-    expect(hotkeys[0]!.scope).toBe('editor')
-  })
-})
-
-describe('useHotkeyScope', () => {
-  beforeEach(() => {
-    _resetHotkeys()
-    unmountCallbacks = []
-  })
-
-  afterEach(() => {
-    _resetHotkeys()
-  })
-
-  it('enables a scope', () => {
-    useHotkeyScope('modal')
-    expect(getActiveScopes().peek().has('modal')).toBe(true)
-  })
-
-  it('disables scope on unmount', () => {
-    useHotkeyScope('modal')
-    expect(getActiveScopes().peek().has('modal')).toBe(true)
-
-    // Simulate unmount
-    unmountCallbacks.forEach((fn) => fn())
-
-    expect(getActiveScopes().peek().has('modal')).toBe(false)
-  })
-
-  it('scoped hotkey fires when scope is active', () => {
-    let fired = false
-    useHotkeyScope('editor')
-    useHotkey('escape', () => {
-      fired = true
-    }, { scope: 'editor' })
-
-    fireKey('Escape')
-    expect(fired).toBe(true)
-  })
-})