@remcostoeten/use-shortcut 1.3.0 → 2.0.0

package/src/builder.ts

@@ -1,489 +1,50 @@
-import {
-    detectPlatform,
-    Platform,
-    ModifierDisplaySymbols,
-    ModifierKey,
-    ModifierDisplayOrder,
-} from "./constants"
-import { formatShortcut } from "./formatter"
-import { parseShortcut, matchesShortcut } from "./parser"
+import { detectPlatform, Platform } from "./constants"
 import type {
     ActionKey,
-    ModifierFlags,
-    ShortcutHandler,
     HandlerOptions,
-    ShortcutResult,
+    ShortcutBuilder as IShortcutBuilder,
+    ShortcutScope,
     UseShortcutOptions,
     ExceptPreset,
     ExceptPredicate,
-    ShortcutBuilder as IShortcutBuilder,
-    ShortcutScope,
-    ShortcutConflict,
-    ParsedShortcut,
-    ShortcutRecordingOptions,
+    ShortcutHandler,
 } from "./types"
 
-const MODIFIER_KEYS = new Set(["ctrl", "shift", "alt", "cmd", "mod"])
-const IGNORED_TAGS = new Set(["INPUT", "TEXTAREA", "SELECT"])
-
-const EXCEPT_PREDICATES: Record<ExceptPreset, ExceptPredicate> = {
-    input: (e) => {
-        const target = e.target as HTMLElement
-        return IGNORED_TAGS.has(target.tagName)
-    },
-    editable: (e) => {
-        const target = e.target as HTMLElement
-        return target.isContentEditable
-    },
-    typing: (e) => {
-        const target = e.target as HTMLElement
-        return IGNORED_TAGS.has(target.tagName) || target.isContentEditable
-    },
-    modal: () => {
-        return document.querySelector('[data-modal="true"], [role="dialog"]') !== null
-    },
-    disabled: (e) => {
-        const target = e.target as HTMLElement
-        return target.hasAttribute("disabled") || target.getAttribute("aria-disabled") === "true"
-    },
-}
-
-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
-}
-
-type BuilderState = {
-    modifiers: Partial<ModifierFlags>
-    steps: string[]
-    options: UseShortcutOptions
-    except?: ExceptPreset | ExceptPreset[] | ExceptPredicate
-    scopes?: ShortcutScope
-}
-
-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
-}
-
-type ComboListener = {
-    listener: (e: KeyboardEvent) => void
-    entries: RegistryEntry[]
-    unbind: () => void
-}
-
-type ShortcutRegistry = {
-    listeners: Map<string, ComboListener>
-    options: UseShortcutOptions
-    activeScopes: Set<string>
-    nextId: number
-}
-
-function normalizeScopes(scopes?: ShortcutScope): string[] {
-    if (!scopes) return []
-    return (Array.isArray(scopes) ? scopes : [scopes])
-        .map((scope) => scope.trim())
-        .filter(Boolean)
-}
-
-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
-}
-
-function getActiveModifierTokens(modifiers: Partial<ModifierFlags>): string[] {
-    const platform = detectPlatform()
-    const order = ModifierDisplayOrder[platform]
-
-    return order
-        .filter((key) => {
-            if (key === ModifierKey.CTRL) return modifiers.ctrl
-            if (key === ModifierKey.ALT) return modifiers.alt
-            if (key === ModifierKey.SHIFT) return modifiers.shift
-            if (key === ModifierKey.META) return modifiers.cmd
-            return false
-        })
-        .map((key) => {
-            if (key === ModifierKey.CTRL) return "ctrl"
-            if (key === ModifierKey.ALT) return "alt"
-            if (key === ModifierKey.SHIFT) return "shift"
-            if (key === ModifierKey.META) return "cmd"
-            return ""
-        })
-}
-
-function buildComboString(modifiers: Partial<ModifierFlags>, key: string): string {
-    const tokens = getActiveModifierTokens(modifiers)
-    return [...tokens, key].join("+")
-}
-
-function formatSequenceDisplay(steps: string[]): string {
-    return steps.map((step) => formatShortcut(step)).join(" then ")
-}
-
-function debugLog(debug: boolean | undefined, ...args: unknown[]) {
-    if (debug) {
-        console.log("[useShortcut]", ...args)
-    }
-}
-
-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")
-    return [...modifiers, parsed.key.toLowerCase()].join("+")
-}
-
-function isPureModifier(event: KeyboardEvent): boolean {
-    const key = event.key.toLowerCase()
-    return key === "shift" || key === "control" || key === "alt" || key === "meta"
-}
-
-function eventToCombo(event: KeyboardEvent): string {
-    const platform = detectPlatform()
-    const symbols = ModifierDisplaySymbols[platform]
-
-    const modifiers: string[] = []
-    if (event.ctrlKey) modifiers.push(symbols[ModifierKey.CTRL] === "⌃" ? "ctrl" : "ctrl")
-    if (event.altKey) modifiers.push("alt")
-    if (event.shiftKey) modifiers.push("shift")
-    if (event.metaKey) modifiers.push("cmd")
-
-    const key = event.key.length === 1 ? event.key.toLowerCase() : event.key.toLowerCase()
-    return [...modifiers, key].join("+")
-}
-
-function isPrefix(a: ParsedShortcut[], b: ParsedShortcut[]): boolean {
-    if (a.length > b.length) return false
-    for (let i = 0; i < a.length; i += 1) {
-        if (canonicalizeParsed(a[i]) !== canonicalizeParsed(b[i])) {
-            return false
-        }
-    }
-    return true
-}
-
-function detectConflict(newSteps: ParsedShortcut[], existingSteps: ParsedShortcut[]): ShortcutConflict["reason"] | null {
-    const newCombo = newSteps.map(canonicalizeParsed).join(" ")
-    const existingCombo = existingSteps.map(canonicalizeParsed).join(" ")
-
-    if (newCombo === existingCombo) return "exact"
-    if (isPrefix(newSteps, existingSteps) || isPrefix(existingSteps, newSteps)) {
-        return "sequence-prefix"
-    }
-
-    return null
-}
-
-function emitConflict(registry: ShortcutRegistry, conflict: ShortcutConflict) {
-    const conflictWarnings = registry.options.conflictWarnings ?? true
-
-    if (registry.options.onConflict) {
-        registry.options.onConflict(conflict)
-        return
-    }
-
-    if (!conflictWarnings) return
+import { _createBinding } from "./runtime/binding"
+import { _debugLog } from "./runtime/debug"
+import { _normalizeScopes } from "./runtime/guards"
+import { _buildComboString } from "./runtime/keys"
+import { _createRecorder } from "./runtime/recording"
+import type { BuilderState, ShortcutRegistry } from "./runtime/types"
 
-    console.warn(
-        `[useShortcut] Conflict detected (${conflict.reason}) between "${conflict.combo}" and "${conflict.existingCombo}"`,
-    )
-}
-
-function sortEntries(entries: RegistryEntry[]): RegistryEntry[] {
-    return [...entries].sort((a, b) => {
-        if (b.priority !== a.priority) return b.priority - a.priority
-        return a.id - b.id
-    })
-}
-
-function createBinding(
-    state: BuilderState,
-    handler: ShortcutHandler,
-    handlerOptions: HandlerOptions = {},
-    registry: ShortcutRegistry,
-): ShortcutResult {
-    const { options, except: stateExcept } = state
-
-    const rawSteps = state.steps
-
-    if (rawSteps.length === 0) {
-        throw new Error('[useShortcut] No key specified. Use .key() to set the action key.')
-    }
-
-    const parsedSteps = rawSteps.map((step) => parseShortcut(step))
-    const combo = parsedSteps.map(canonicalizeParsed).join(" ")
-    const display = formatSequenceDisplay(rawSteps)
-    const debug = options.debug ?? false
-    const except = stateExcept ?? handlerOptions.except
-
-    for (const [existingCombo, listener] of registry.listeners.entries()) {
-        for (const existing of listener.entries) {
-            if (existingCombo === combo) continue
-            const reason = detectConflict(parsedSteps, existing.parsedSteps)
-            if (!reason) continue
-            emitConflict(registry, { combo, existingCombo, reason })
-        }
-    }
-
-    const isEnabled = !handlerOptions.disabled && !options.disabled
-    const delay = handlerOptions.delay ?? options.delay ?? 0
-    const sequenceTimeout = handlerOptions.sequenceTimeout ?? options.sequenceTimeout ?? 800
-    const requiredScopes = new Set(normalizeScopes(state.scopes ?? handlerOptions.scopes))
-    const attemptCallbacks = new Set<(matched: boolean, event: KeyboardEvent) => void>()
-
-    debugLog(debug, "Registering:", combo, "→", display, {
-        parsedSteps,
-        except: !!except,
-        scopes: [...requiredScopes],
-    })
-
-    const entry: RegistryEntry = {
-        id: registry.nextId++,
-        userHandler: handler,
-        isEnabled,
-        attemptCallbacks,
-        parsedSteps,
-        scopes: requiredScopes,
-        progress: 0,
-        lastMatchedAt: 0,
-        except,
-        delay,
-        sequenceTimeout,
-        preventDefault: handlerOptions.preventDefault !== false,
-        stopPropagation: handlerOptions.stopPropagation ?? false,
-        stopOnMatch: handlerOptions.stopOnMatch ?? false,
-        priority: handlerOptions.priority ?? 0,
-    }
-
-    let comboListener = registry.listeners.get(combo)
-
-    if (!comboListener) {
-        const target = options.target ?? (typeof window !== "undefined" ? window : null)
-        const eventType = options.eventType ?? "keydown"
-
-        const listener = (event: KeyboardEvent) => {
-            const runtimeOptions = registry.options
-            if (runtimeOptions.disabled) return
-            if (runtimeOptions.eventFilter && !runtimeOptions.eventFilter(event)) return
-
-            const current = registry.listeners.get(combo)
-            if (!current) return
-
-            const orderedEntries = sortEntries(current.entries)
-
-            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(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
-                }
-
-                item.attemptCallbacks.forEach((cb) => cb(matched, event))
-
-                if (!matched) continue
-
-                debugLog(debug, "MATCHED:", combo, "→", display)
-
-                if (item.preventDefault) {
-                    event.preventDefault()
-                }
-
-                if (item.stopPropagation) {
-                    event.stopPropagation()
-                }
-
-                const executeHandler = () => item.userHandler(event)
-
-                if (item.delay > 0) {
-                    debugLog(debug, "Delaying execution by", item.delay, "ms")
-                    setTimeout(executeHandler, item.delay)
-                } else {
-                    executeHandler()
-                }
-
-                if (item.stopOnMatch) {
-                    break
-                }
-            }
-        }
-
-        if (target) {
-            target.addEventListener(eventType, listener as EventListener)
-            debugLog(debug, "Listener attached for:", combo)
-        }
-
-        const unbind = () => {
-            if (target) {
-                target.removeEventListener(eventType, listener as EventListener)
-                registry.listeners.delete(combo)
-                debugLog(debug, "Unregistered:", combo)
-            }
-        }
-
-        comboListener = {
-            listener,
-            entries: [],
-            unbind,
-        }
-
-        registry.listeners.set(combo, comboListener)
-    }
-
-    comboListener.entries.push(entry)
-
-    const unbindEntry = () => {
-        const current = registry.listeners.get(combo)
-        if (!current) return
-
-        current.entries = current.entries.filter((item) => item.id !== entry.id)
-
-        if (current.entries.length === 0) {
-            current.unbind()
-        }
-    }
-
-    return {
-        unbind: unbindEntry,
-        display,
-        combo,
-        trigger: () => handler(new KeyboardEvent(registry.options.eventType ?? "keydown")),
-        get isEnabled() {
-            return entry.isEnabled
-        },
-        enable: () => {
-            entry.isEnabled = true
-        },
-        disable: () => {
-            entry.isEnabled = false
-        },
-        onAttempt: (callback) => {
-            entry.attemptCallbacks.add(callback)
-            return () => entry.attemptCallbacks.delete(callback)
-        },
-    }
-}
-
-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, { once: false })
-
-            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)
-            }
-        })
-    }
-}
+const _MODIFIER_KEYS = new Set(["ctrl", "shift", "alt", "cmd", "mod"])
 
-export function createShortcutBuilder(options: UseShortcutOptions = {}): {
+export function _createShortcutBuilder(options: UseShortcutOptions = {}): {
     builder: IShortcutBuilder
     registry: ShortcutRegistry
 } {
     const registry: ShortcutRegistry = {
         listeners: new Map(),
+        firstStepIndex: new Map(),
+        activeSequenceCombos: new Set(),
         options,
-        activeScopes: new Set(normalizeScopes(options.activeScopes)),
+        activeScopes: new Set(_normalizeScopes(options.activeScopes)),
         nextId: 1,
+        listener: null,
+        listenerTarget: null,
+        listenerEventType: options.eventType ?? "keydown",
     }
 
-    debugLog(options.debug, "Builder created with options:", options)
+    _debugLog(options.debug, "Builder created with options:", options)
 
-    function createProxy(currentState: BuilderState): IShortcutBuilder {
+    function _createProxy(currentState: BuilderState): IShortcutBuilder {
         return new Proxy({} as IShortcutBuilder, {
             get(_, prop: string) {
                 if (prop === "__debug") {
                     return currentState.options.debug
                 }
 
-                if (MODIFIER_KEYS.has(prop)) {
+                if (_MODIFIER_KEYS.has(prop)) {
                     const platform = detectPlatform()
                     const modKey = prop === "mod" ? (platform === Platform.MAC ? "cmd" : "ctrl") : prop
 
@@ -492,26 +53,26 @@ export function createShortcutBuilder(options: UseShortcutOptions = {}): {
                         modifiers: { ...currentState.modifiers, [modKey]: true },
                     }
 
-                    debugLog(currentState.options.debug, `Chain: +${prop} →`, newState.modifiers)
+                    _debugLog(currentState.options.debug, `Chain: +${prop} →`, newState.modifiers)
 
-                    return createProxy(newState)
+                    return _createProxy(newState)
                 }
 
                 if (prop === "in") {
                     return (scopes: ShortcutScope) => {
-                        const nextScopes = [...normalizeScopes(currentState.scopes), ...normalizeScopes(scopes)]
+                        const nextScopes = [..._normalizeScopes(currentState.scopes), ..._normalizeScopes(scopes)]
                         const newState: BuilderState = {
                             ...currentState,
                             scopes: nextScopes,
                         }
 
-                        return createProxy(newState)
+                        return _createProxy(newState)
                     }
                 }
 
                 if (prop === "setScopes") {
                     return (scopes: ShortcutScope) => {
-                        registry.activeScopes = new Set(normalizeScopes(scopes))
+                        registry.activeScopes = new Set(_normalizeScopes(scopes))
                     }
                 }
 
@@ -538,21 +99,21 @@ export function createShortcutBuilder(options: UseShortcutOptions = {}): {
                 }
 
                 if (prop === "record") {
-                    return createRecorder(registry.options)
+                    return _createRecorder(registry.options)
                 }
 
                 if (prop === "key") {
                     return (key: ActionKey) => {
-                        const nextStep = buildComboString(currentState.modifiers, key)
+                        const nextStep = _buildComboString(currentState.modifiers, key)
                         const newState: BuilderState = {
                             ...currentState,
                             modifiers: {},
                             steps: [...currentState.steps, nextStep],
                         }
 
-                        debugLog(currentState.options.debug, `Chain: .key("${key}")`)
+                        _debugLog(currentState.options.debug, `Chain: .key("${key}")`)
 
-                        return createProxy(newState)
+                        return _createProxy(newState)
                     }
                 }
 
@@ -568,9 +129,9 @@ export function createShortcutBuilder(options: UseShortcutOptions = {}): {
                             steps: [...currentState.steps, nextStep],
                         }
 
-                        debugLog(currentState.options.debug, `Chain: .then("${nextStep}")`)
+                        _debugLog(currentState.options.debug, `Chain: .then("${nextStep}")`)
 
-                        return createProxy(newState)
+                        return _createProxy(newState)
                     }
                 }
 
@@ -581,22 +142,22 @@ export function createShortcutBuilder(options: UseShortcutOptions = {}): {
                             except: condition,
                         }
 
-                        debugLog(currentState.options.debug, "Chain: .except()", condition)
+                        _debugLog(currentState.options.debug, "Chain: .except()", condition)
 
-                        return createProxy(newState)
+                        return _createProxy(newState)
                     }
                 }
 
                 if (prop === "on") {
                     return (handler: ShortcutHandler, handlerOptions?: HandlerOptions) => {
-                        return createBinding(currentState, handler, handlerOptions, registry)
+                        return _createBinding(currentState, handler, handlerOptions, registry)
                     }
                 }
 
                 if (prop === "handle") {
                     return (opts: HandlerOptions & { handler: ShortcutHandler }) => {
                         const { handler, ...rest } = opts
-                        return createBinding(currentState, handler, rest, registry)
+                        return _createBinding(currentState, handler, rest, registry)
                     }
                 }
 
@@ -612,7 +173,7 @@ export function createShortcutBuilder(options: UseShortcutOptions = {}): {
     }
 
     return {
-        builder: createProxy(initialState),
+        builder: _createProxy(initialState),
         registry,
     }
 }