@remcostoeten/use-shortcut 1.3.0 → 2.0.0

package/src/runtime/conflicts.ts

@@ -0,0 +1,43 @@
+import type { ParsedShortcut, ShortcutConflict } from "../types"
+import type { ShortcutRegistry } from "./types"
+
+import { _canonicalizeParsed } from "./keys"
+
+function _isPrefix(a: string[], b: string[]): boolean {
+    if (a.length > b.length) return false
+    for (let i = 0; i < a.length; i += 1) {
+        if (a[i] !== b[i]) {
+            return false
+        }
+    }
+    return true
+}
+
+export function _detectConflict(newSteps: ParsedShortcut[], existingSteps: ParsedShortcut[]): ShortcutConflict["reason"] | null {
+    const newCanonicalSteps = newSteps.map(_canonicalizeParsed)
+    const existingCanonicalSteps = existingSteps.map(_canonicalizeParsed)
+    const newCombo = newCanonicalSteps.join(" ")
+    const existingCombo = existingCanonicalSteps.join(" ")
+
+    if (newCombo === existingCombo) return "exact"
+    if (_isPrefix(newCanonicalSteps, existingCanonicalSteps) || _isPrefix(existingCanonicalSteps, newCanonicalSteps)) {
+        return "sequence-prefix"
+    }
+
+    return null
+}
+
+export function _emitConflict(registry: ShortcutRegistry, conflict: ShortcutConflict) {
+    const conflictWarnings = registry.options.conflictWarnings ?? true
+
+    if (registry.options.onConflict) {
+        registry.options.onConflict(conflict)
+        return
+    }
+
+    if (!conflictWarnings) return
+
+    console.warn(
+        `[useShortcut] Conflict detected (${conflict.reason}) between "${conflict.combo}" and "${conflict.existingCombo}"`,
+    )
+}

package/src/runtime/debug.ts

@@ -0,0 +1,6 @@
+export function _debugLog(debug: boolean | undefined, ...args: unknown[]) {
+    if (debug) {
+        console.log("[useShortcut]", ...args)
+    }
+}
+

package/src/runtime/guards.ts

@@ -0,0 +1,82 @@
+import type { ExceptPreset, ExceptPredicate, ShortcutScope } from "../types"
+
+export const _IGNORED_TAGS = new Set(["INPUT", "TEXTAREA", "SELECT"])
+
+export const _EXCEPT_PREDICATES: Record<ExceptPreset, ExceptPredicate> = {
+    input: e => {
+        if (!(e.target instanceof HTMLElement)) return false
+        const target = e.target
+        return _IGNORED_TAGS.has(target.tagName)
+    },
+    editable: e => {
+        if (!(e.target instanceof HTMLElement)) return false
+        const target = e.target
+        return target.isContentEditable
+    },
+    typing: e => {
+        if (!(e.target instanceof HTMLElement)) return false
+        const target = e.target
+        return _IGNORED_TAGS.has(target.tagName) || target.isContentEditable
+    },
+    modal: () => {
+        if (
+            typeof document === "undefined" ||
+            typeof document.querySelector !== "function"
+        )
+            return false
+        return (
+            document.querySelector('[data-modal="true"], [role="dialog"]') !==
+            null
+        )
+    },
+    disabled: e => {
+        if (!(e.target instanceof HTMLElement)) return false
+        const target = e.target
+        return (
+            target.hasAttribute("disabled") ||
+            target.getAttribute("aria-disabled") === "true"
+        )
+    }
+}
+
+export function _shouldExcept(
+    event: KeyboardEvent,
+    except?: ExceptPreset | ExceptPreset[] | ExceptPredicate
+): boolean {
+    if (!except) return false
+
+    if (typeof except === "function") {
+        return except(event)
+    }
+
+    if (Array.isArray(except)) {
+        return except.some(preset => _EXCEPT_PREDICATES[preset]?.(event))
+    }
+
+    return _EXCEPT_PREDICATES[except]?.(event) ?? false
+}
+
+export function _normalizeScopes(scopes?: ShortcutScope): string[] {
+    if (!scopes) return []
+    return (Array.isArray(scopes) ? scopes : [scopes])
+        .map(scope => scope.trim())
+        .filter(Boolean)
+}
+
+export function _scopeMatch(
+    requiredScopes: Set<string>,
+    activeScopes: Set<string>
+): boolean {
+    if (requiredScopes.size === 0) return true
+    for (const required of requiredScopes) {
+        if (activeScopes.has(required)) return true
+    }
+    return false
+}
+
+export function _isPureModifier(event: KeyboardEvent): boolean {
+    const key = event.key.toLowerCase()
+    return (
+        key === "shift" || key === "control" || key === "alt" || key === "meta"
+    )
+}

package/src/runtime/keys.ts

@@ -0,0 +1,63 @@
+import { detectPlatform, ModifierDisplayOrder, ModifierKey } from "../constants"
+import { formatShortcut } from "../formatter"
+import type { ModifierFlags, ParsedShortcut } from "../types"
+
+export function _getActiveModifierTokens(
+    modifiers: Partial<ModifierFlags>
+): string[] {
+    const platform = detectPlatform()
+    const order = ModifierDisplayOrder[platform]
+    const tokens: string[] = []
+
+    for (const key of order) {
+        if (key === ModifierKey.CTRL && modifiers.ctrl) tokens.push("ctrl")
+        if (key === ModifierKey.ALT && modifiers.alt) tokens.push("alt")
+        if (key === ModifierKey.SHIFT && modifiers.shift) tokens.push("shift")
+        if (key === ModifierKey.META && modifiers.cmd) tokens.push("cmd")
+    }
+
+    return tokens
+}
+
+export function _buildComboString(
+    modifiers: Partial<ModifierFlags>,
+    key: string
+): string {
+    const tokens = _getActiveModifierTokens(modifiers)
+    return [...tokens, key].join("+")
+}
+
+export function _formatSequenceDisplay(steps: string[]): string {
+    return steps.map(step => formatShortcut(step)).join(" then ")
+}
+
+export function _canonicalizeParsed(parsed: ParsedShortcut): string {
+    const modifiers: string[] = []
+    if (parsed.modifiers.ctrl) modifiers.push("ctrl")
+    if (parsed.modifiers.alt) modifiers.push("alt")
+    if (parsed.modifiers.shift) modifiers.push("shift")
+    if (parsed.modifiers.meta) modifiers.push("cmd")
+    const key =
+        parsed.key === " " || parsed.key === "Spacebar"
+            ? "space"
+            : parsed.key.toLowerCase()
+    return [...modifiers, key].join("+")
+}
+
+export function _eventToCombo(event: KeyboardEvent): string {
+    const modifiers: string[] = []
+    if (event.ctrlKey) modifiers.push("ctrl")
+    if (event.altKey) modifiers.push("alt")
+    if (event.shiftKey) modifiers.push("shift")
+    if (event.metaKey) modifiers.push("cmd")
+
+    const key =
+        event.key === " " || event.key === "Spacebar"
+            ? "space"
+            : event.key.toLowerCase()
+    return [...modifiers, key].join("+")
+}
+
+export function _eventToMatchStep(event: KeyboardEvent): string {
+    return _eventToCombo(event)
+}

package/src/runtime/listener.ts

@@ -0,0 +1,142 @@
+import { matchesShortcut } from "../parser"
+
+import { _debugLog } from "./debug"
+import { _eventToMatchStep } from "./keys"
+import { _IGNORED_TAGS, _scopeMatch, _shouldExcept } from "./guards"
+import type { RegistryEntry, ShortcutRegistry } from "./types"
+
+function _sortEntries(entries: RegistryEntry[]): RegistryEntry[] {
+    if (entries.length <= 1) return entries
+
+    return [...entries].sort((a, b) => {
+        if (b.priority !== a.priority) return b.priority - a.priority
+        return a.id - b.id
+    })
+}
+
+function _dispatchRegistryEvent(registry: ShortcutRegistry, event: KeyboardEvent) {
+    const runtimeOptions = registry.options
+    if (runtimeOptions.disabled) return
+    if (runtimeOptions.eventFilter && !runtimeOptions.eventFilter(event)) return
+
+    const candidateCombos = new Set<string>()
+    const firstStepCombos = registry.firstStepIndex.get(_eventToMatchStep(event))
+    if (firstStepCombos) {
+        for (const combo of firstStepCombos) candidateCombos.add(combo)
+    }
+    for (const combo of registry.activeSequenceCombos) {
+        candidateCombos.add(combo)
+    }
+
+    for (const combo of candidateCombos) {
+        const comboEntries = registry.listeners.get(combo)
+        if (!comboEntries) continue
+
+        const orderedEntries = _sortEntries(comboEntries)
+
+        for (const item of orderedEntries) {
+            if (!item.isEnabled) continue
+
+            if (!_scopeMatch(item.scopes, registry.activeScopes)) {
+                continue
+            }
+
+            if (runtimeOptions.ignoreInputs !== false && !item.except) {
+                const targetEl = event.target as HTMLElement
+                if (targetEl && (_IGNORED_TAGS.has(targetEl.tagName) || targetEl.isContentEditable)) {
+                    continue
+                }
+            }
+
+            if (_shouldExcept(event, item.except)) {
+                _debugLog(runtimeOptions.debug, "Skipped due to except condition:", combo)
+                continue
+            }
+
+            const expected = item.parsedSteps[item.progress]
+            const now = Date.now()
+
+            if (item.progress > 0 && now - item.lastMatchedAt > item.sequenceTimeout) {
+                item.progress = 0
+            }
+
+            let matched = false
+
+            if (matchesShortcut(event, expected)) {
+                item.progress += 1
+                item.lastMatchedAt = now
+
+                if (item.progress === item.parsedSteps.length) {
+                    matched = true
+                    item.progress = 0
+                }
+            } else if (item.progress > 0 && matchesShortcut(event, item.parsedSteps[0])) {
+                item.progress = 1
+                item.lastMatchedAt = now
+            } else {
+                item.progress = 0
+            }
+
+            for (const cb of item.attemptCallbacks) {
+                cb(matched, event)
+            }
+
+            if (!matched) continue
+
+            _debugLog(runtimeOptions.debug, "MATCHED:", combo)
+
+            if (item.preventDefault) {
+                event.preventDefault()
+            }
+
+            if (item.stopPropagation) {
+                event.stopPropagation()
+            }
+
+            const executeHandler = () => item.userHandler(event)
+
+            if (item.delay > 0) {
+                _debugLog(runtimeOptions.debug, "Delaying execution by", item.delay, "ms")
+                setTimeout(executeHandler, item.delay)
+            } else {
+                executeHandler()
+            }
+
+            if (item.stopOnMatch) {
+                break
+            }
+        }
+
+        if (comboEntries.some((entry) => entry.progress > 0)) {
+            registry.activeSequenceCombos.add(combo)
+        } else {
+            registry.activeSequenceCombos.delete(combo)
+        }
+    }
+}
+
+export function _attachRegistryListener(registry: ShortcutRegistry) {
+    if (registry.listener) return
+
+    const target = registry.options.target ?? (typeof window !== "undefined" ? window : null)
+    if (!target) return
+
+    const eventType = registry.options.eventType ?? "keydown"
+    const listener = (event: KeyboardEvent) => _dispatchRegistryEvent(registry, event)
+    target.addEventListener(eventType, listener as EventListener)
+
+    registry.listener = listener
+    registry.listenerTarget = target
+    registry.listenerEventType = eventType
+
+    _debugLog(registry.options.debug, "Listener attached")
+}
+
+export function _detachRegistryListener(registry: ShortcutRegistry) {
+    if (!registry.listener || !registry.listenerTarget) return
+
+    registry.listenerTarget.removeEventListener(registry.listenerEventType, registry.listener as EventListener)
+    registry.listener = null
+    registry.listenerTarget = null
+    _debugLog(registry.options.debug, "Listener detached")
+}

package/src/runtime/recording.ts

@@ -0,0 +1,39 @@
+import type { ShortcutRecordingOptions, UseShortcutOptions } from "../types"
+import { _eventToCombo } from "./keys"
+import { _isPureModifier } from "./guards"
+
+export function _createRecorder(options: UseShortcutOptions) {
+    return (recordingOptions: ShortcutRecordingOptions = {}): Promise<string> => {
+        return new Promise((resolve, reject) => {
+            const target = recordingOptions.target ?? options.target ?? (typeof window !== "undefined" ? window : null)
+            const eventType = recordingOptions.eventType ?? options.eventType ?? "keydown"
+
+            if (!target) {
+                reject(new Error("[useShortcut] Cannot record shortcut without a target."))
+                return
+            }
+
+            let timeout: ReturnType<typeof setTimeout> | undefined
+
+            const listener = (event: Event) => {
+                const keyboardEvent = event as KeyboardEvent
+                if (_isPureModifier(keyboardEvent)) return
+
+                keyboardEvent.preventDefault()
+                target.removeEventListener(eventType, listener as EventListener)
+                if (timeout) clearTimeout(timeout)
+                resolve(_eventToCombo(keyboardEvent))
+            }
+
+            target.addEventListener(eventType, listener as EventListener)
+
+            const timeoutMs = recordingOptions.timeoutMs
+            if (timeoutMs && timeoutMs > 0) {
+                timeout = setTimeout(() => {
+                    target.removeEventListener(eventType, listener as EventListener)
+                    reject(new Error(`[useShortcut] Recording timed out after ${timeoutMs}ms.`))
+                }, timeoutMs)
+            }
+        })
+    }
+}

package/src/runtime/types.ts

@@ -0,0 +1,48 @@
+import type {
+    ModifierFlags,
+    ShortcutHandler,
+    UseShortcutOptions,
+    ExceptPreset,
+    ExceptPredicate,
+    ShortcutScope,
+    ParsedShortcut,
+} from "../types"
+
+export type BuilderState = {
+    modifiers: Partial<ModifierFlags>
+    steps: string[]
+    options: UseShortcutOptions
+    except?: ExceptPreset | ExceptPreset[] | ExceptPredicate
+    scopes?: ShortcutScope
+}
+
+export type RegistryEntry = {
+    id: number
+    userHandler: ShortcutHandler
+    isEnabled: boolean
+    attemptCallbacks: Set<(matched: boolean, event: KeyboardEvent) => void>
+    parsedSteps: ParsedShortcut[]
+    scopes: Set<string>
+    progress: number
+    lastMatchedAt: number
+    except?: ExceptPreset | ExceptPreset[] | ExceptPredicate
+    delay: number
+    sequenceTimeout: number
+    preventDefault: boolean
+    stopPropagation: boolean
+    stopOnMatch: boolean
+    priority: number
+}
+
+export type ShortcutRegistry = {
+    listeners: Map<string, RegistryEntry[]>
+    firstStepIndex: Map<string, Set<string>>
+    activeSequenceCombos: Set<string>
+    options: UseShortcutOptions
+    activeScopes: Set<string>
+    nextId: number
+    listener: ((event: KeyboardEvent) => void) | null
+    listenerTarget: (HTMLElement | Window) | null
+    listenerEventType: "keydown" | "keyup"
+}
+

package/src/types.ts

@@ -83,8 +83,10 @@ export type ExceptPredicate = (event: KeyboardEvent) => boolean
  */
 export type ExceptPreset = "input" | "editable" | "typing" | "modal" | "disabled"
 
+/** Scope selector used to enable/disable subsets of shortcuts at runtime. */
 export type ShortcutScope = string | string[]
 
+/** Conflict metadata emitted when two registered shortcuts overlap. */
 export type ShortcutConflict = {
     combo: string
     existingCombo: string
@@ -105,8 +107,6 @@ export type HandlerOptions = {
     description?: string
     /** Disable this specific shortcut */
     disabled?: boolean
-    /** Limit shortcut to a specific DOM element */
-    scope?: HTMLElement | null
     /** Conditions to skip the shortcut */
     except?: ExceptPreset | ExceptPreset[] | ExceptPredicate
     /** Required named scopes that must be active */
@@ -142,14 +142,6 @@ export type ShortcutResult = {
     onAttempt?: (callback: (matched: boolean, event: KeyboardEvent) => void) => () => void
 }
 
-export type RemainingModifiers<Used extends Partial<ModifierFlags>> = Exclude<
-    ModifierName,
-    | (Used extends { ctrl: true } ? "ctrl" : never)
-    | (Used extends { shift: true } ? "shift" : never)
-    | (Used extends { alt: true } ? "alt" : never)
-    | (Used extends { cmd: true } ? "cmd" | "mod" : never)
->
-
 /**
  * Chainable modifier builder with type-safe exhaustion
  * Each modifier can only be used once in a chain
@@ -160,35 +152,36 @@ export type ModifierChain<Used extends Partial<ModifierFlags>> = {
     alt: Used["alt"] extends true ? never : ModifierChain<Used & { alt: true }>
     cmd: Used["cmd"] extends true ? never : ModifierChain<Used & { cmd: true }>
     mod: Used["cmd"] extends true ? never : ModifierChain<Used & { cmd: true }>
-    key: <K extends ActionKey>(key: K) => KeyChain<Used, K>
+    key: <K extends ActionKey>(key: K) => KeyChain<K>
     in: (scopes: ShortcutScope) => ModifierChain<Used>
 }
 
 /**
  * Chain state after calling `.key()` - ready to attach a handler
  */
-export type KeyChain<Used extends Partial<ModifierFlags>, Key extends string> = {
+export type KeyChain<Key extends string> = {
     /** Attach a handler to this shortcut */
     on: (handler: ShortcutHandler, options?: HandlerOptions) => ShortcutResult
     /** Attach a handler with inline options */
     handle: (options: HandlerOptions & { handler: ShortcutHandler }) => ShortcutResult
     /** Add exception conditions before attaching handler */
-    except: (condition: ExceptPreset | ExceptPreset[] | ExceptPredicate) => KeyChainWithExcept<Used, Key>
+    except: (condition: ExceptPreset | ExceptPreset[] | ExceptPredicate) => KeyChainWithExcept<Key>
     /** Add required named scopes */
-    in: (scopes: ShortcutScope) => KeyChain<Used, Key>
+    in: (scopes: ShortcutScope) => KeyChain<Key>
     /** Add the next step in a sequence */
-    then: <K extends ActionKey | string>(key: K) => KeyChain<Used, `${Key} ${K}`>
+    then: <K extends ActionKey | string>(key: K) => KeyChain<`${Key} ${K}`>
 }
 
 /**
  * Chain state after calling `.except()` - ready to attach handler
  */
-export type KeyChainWithExcept<Used extends Partial<ModifierFlags>, Key extends string> = {
+export type KeyChainWithExcept<Key extends string> = {
     on: (handler: ShortcutHandler, options?: Omit<HandlerOptions, "except">) => ShortcutResult
-    in: (scopes: ShortcutScope) => KeyChainWithExcept<Used, Key>
-    then: <K extends ActionKey | string>(key: K) => KeyChainWithExcept<Used, `${Key} ${K}`>
+    in: (scopes: ShortcutScope) => KeyChainWithExcept<Key>
+    then: <K extends ActionKey | string>(key: K) => KeyChainWithExcept<`${Key} ${K}`>
 }
 
+/** Options for `ShortcutBuilder.record()` and low-level recording flows. */
 export type ShortcutRecordingOptions = {
     target?: HTMLElement | Window | null
     eventType?: "keydown" | "keyup"
@@ -204,7 +197,7 @@ export type ShortcutBuilder = ModifierChain<EmptyModifiers> & {
     alt: ModifierChain<{ alt: true }>
     cmd: ModifierChain<{ cmd: true }>
     mod: ModifierChain<{ cmd: true }>
-    key: <K extends ActionKey>(key: K) => KeyChain<EmptyModifiers, K>
+    key: <K extends ActionKey>(key: K) => KeyChain<K>
     /** Set required scopes for upcoming chain calls */
     in: (scopes: ShortcutScope) => ShortcutBuilder
     /** Update active scopes at runtime */
@@ -249,18 +242,22 @@ export type UseShortcutOptions = {
     eventFilter?: (event: KeyboardEvent) => boolean
 }
 
+/** Single shortcut-map entry used by `registerShortcutMap` and `useShortcutMap`. */
 export type ShortcutMapEntry = {
     keys: string | string[]
     handler: ShortcutHandler
     options?: HandlerOptions
 }
 
+/** Bulk registration shape mapping action ids to key+handler definitions. */
 export type ShortcutMap = Record<string, ShortcutMapEntry>
 
+/** Return type for map registrations, keyed by the same ids as the source map. */
 export type ShortcutMapResult<T extends ShortcutMap = ShortcutMap> = {
     [K in keyof T]: ShortcutResult
 }
 
+/** Imperative grouping controller for binding/unbinding many shortcut registrations together. */
 export type ShortcutGroup = {
     add: (...results: ShortcutResult[]) => void
     addMany: (results: ShortcutResult[] | Record<string, ShortcutResult>) => void