@pyreon/hotkeys 0.24.5 → 0.25.0

package/src/tests/manifest-snapshot.test.ts

@@ -1,69 +0,0 @@
-import {
-  renderApiReferenceEntries,
-  renderLlmsFullSection,
-  renderLlmsTxtLine,
-} from '@pyreon/manifest'
-import manifest from '../manifest'
-
-describe('gen-docs — hotkeys snapshot', () => {
-  it('renders to llms.txt bullet', () => {
-    expect(renderLlmsTxtLine(manifest)).toMatchInlineSnapshot(`"- @pyreon/hotkeys — Keyboard shortcut management — scope-aware, modifier keys, conflict detection. 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."`)
-  })
-
-  it('renders to llms-full.txt section', () => {
-    expect(renderLlmsFullSection(manifest)).toMatchInlineSnapshot(`
-      "## @pyreon/hotkeys — Keyboard Shortcuts
-
-      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.
-
-      \`\`\`typescript
-      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 })
-      \`\`\`
-
-      > **Note**: 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.
-      >
-      > **mod alias**: \`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.
-      >
-      > **Scopes**: 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.
-      "
-    `)
-  })
-
-  it('renders to MCP api-reference entries', () => {
-    const record = renderApiReferenceEntries(manifest)
-    expect(Object.keys(record).length).toBe(3)
-  })
-})

package/src/types.ts

@@ -1,50 +0,0 @@
-// ─── Hotkey Types ────────────────────────────────────────────────────────────
-
-/**
- * A parsed key combination.
- * Example: 'ctrl+shift+s' → { ctrl: true, shift: true, alt: false, meta: false, key: 's' }
- */
-export interface KeyCombo {
-  ctrl: boolean
-  shift: boolean
-  alt: boolean
-  meta: boolean
-  key: string
-}
-
-/**
- * Options for registering a hotkey.
- */
-export interface HotkeyOptions {
-  /** Scope for the hotkey — only active when this scope is active. Default: 'global' */
-  scope?: string
-  /** Whether to prevent default browser behavior — default: true */
-  preventDefault?: boolean
-  /** Whether to stop event propagation — default: false */
-  stopPropagation?: boolean
-  /** Whether the hotkey fires when an input/textarea/contenteditable is focused — default: false */
-  enableOnInputs?: boolean
-  /** Description of what this hotkey does — useful for help dialogs */
-  description?: string
-  /** Whether the hotkey is enabled — default: true */
-  enabled?: boolean | (() => boolean)
-}
-
-/**
- * A registered hotkey entry.
- */
-export interface HotkeyEntry {
-  /** The original shortcut string (e.g. 'ctrl+s') */
-  shortcut: string
-  /** Parsed key combination */
-  combo: KeyCombo
-  /** The callback to invoke */
-  handler: (event: KeyboardEvent) => void
-  /** Options */
-  options: Required<
-    Pick<
-      HotkeyOptions,
-      'scope' | 'preventDefault' | 'stopPropagation' | 'enableOnInputs' | 'enabled'
-    >
-  > & { description?: string }
-}

package/src/use-hotkey-scope.ts

@@ -1,20 +0,0 @@
-import { onUnmount } from '@pyreon/core'
-import { disableScope, enableScope } from './registry'
-
-/**
- * Activate a hotkey scope for the lifetime of a component.
- * When the component unmounts, the scope is deactivated.
- *
- * @example
- * ```tsx
- * function Modal() {
- *   useHotkeyScope('modal')
- *   useHotkey('escape', () => closeModal(), { scope: 'modal' })
- *   // ...
- * }
- * ```
- */
-export function useHotkeyScope(scope: string): void {
-  enableScope(scope)
-  onUnmount(() => disableScope(scope))
-}

package/src/use-hotkey.ts

@@ -1,26 +0,0 @@
-import { onUnmount } from '@pyreon/core'
-import { registerHotkey } from './registry'
-import type { HotkeyOptions } from './types'
-
-/**
- * Register a keyboard shortcut scoped to a component's lifecycle.
- * Automatically unregisters when the component unmounts.
- *
- * @example
- * ```ts
- * function Editor() {
- *   useHotkey('ctrl+s', () => save(), { description: 'Save document' })
- *   useHotkey('ctrl+z', () => undo())
- *   useHotkey('ctrl+shift+z', () => redo())
- *   // ...
- * }
- * ```
- */
-export function useHotkey(
-  shortcut: string,
-  handler: (event: KeyboardEvent) => void,
-  options?: HotkeyOptions,
-): void {
-  const unregister = registerHotkey(shortcut, handler, options)
-  onUnmount(unregister)
-}