@remcostoeten/use-shortcut 1.3.0 → 2.0.0

package/src/constants.ts

@@ -1,19 +1,61 @@
-export const Platform = {
+/** Supported runtime OS identifiers used by formatter and parser normalization. */
+export const OS = {
     MAC: "mac",
     WINDOWS: "windows",
     LINUX: "linux",
 } as const
 
-export type PlatformType = (typeof Platform)[keyof typeof Platform]
+export type PlatformType = (typeof OS)[keyof typeof OS]
 
+/** Public platform constant alias (`Platform.MAC`, `Platform.WINDOWS`, `Platform.LINUX`). */
+export const Platform = OS
+
+let _cachedPlatform: PlatformType | null = null
+
+/**
+ * Detect the current OS platform for modifier normalization and display formatting.
+ * Result is memoized for the page lifecycle.
+ */
 export function detectPlatform(): PlatformType {
-    if (typeof navigator === "undefined") return Platform.WINDOWS
-    const platform = navigator.platform.toLowerCase()
-    if (platform.includes("mac")) return Platform.MAC
-    if (platform.includes("linux")) return Platform.LINUX
-    return Platform.WINDOWS
+    if (_cachedPlatform) return _cachedPlatform
+    if (typeof navigator === "undefined") {
+        _cachedPlatform = OS.WINDOWS
+        return _cachedPlatform
+    }
+
+    const uaPlatform = (
+        navigator as Navigator & {
+            userAgentData?: { platform?: string }
+        }
+    ).userAgentData?.platform?.toLowerCase()
+
+    const platform = (uaPlatform ?? navigator.platform ?? navigator.userAgent ?? "").toLowerCase()
+
+    if (
+        platform.includes("mac")
+        || platform.includes("iphone")
+        || platform.includes("ipad")
+        || platform.includes("ipod")
+    ) {
+        _cachedPlatform = OS.MAC
+        return _cachedPlatform
+    }
+
+    if (platform.includes("linux") || platform.includes("android")) {
+        _cachedPlatform = OS.LINUX
+        return _cachedPlatform
+    }
+
+    if (platform.includes("win")) {
+        _cachedPlatform = OS.WINDOWS
+        return _cachedPlatform
+    }
+
+    _cachedPlatform = OS.WINDOWS
+    return _cachedPlatform
 }
 
+/** Canonical modifier token names used internally across parsing/formatting. */
 export const ModifierKey = {
     META: "meta",
     CTRL: "ctrl",
@@ -23,6 +65,7 @@ export const ModifierKey = {
 
 export type ModifierKeyType = (typeof ModifierKey)[keyof typeof ModifierKey]
 
+/** Alias map from user-facing modifier tokens to canonical modifier keys. */
 export const ModifierAliases: Record<string, ModifierKeyType> = {
     command: ModifierKey.META,
     cmd: ModifierKey.META,
@@ -45,6 +88,7 @@ export const ModifierAliases: Record<string, ModifierKeyType> = {
     shft: ModifierKey.SHIFT,
 } as const
 
+/** Alias map from human shortcut key tokens to `KeyboardEvent.key`-compatible values. */
 export const SpecialKeyMap: Record<string, string> = {
     up: "ArrowUp",
     down: "ArrowDown",
@@ -86,20 +130,21 @@ export const SpecialKeyMap: Record<string, string> = {
     closebracket: "]",
 } as const
 
+/** Platform-specific display labels/symbols for modifier keys. */
 export const ModifierDisplaySymbols: Record<PlatformType, Record<ModifierKeyType, string>> = {
-    [Platform.MAC]: {
+    [OS.MAC]: {
         [ModifierKey.META]: "⌘",
         [ModifierKey.CTRL]: "⌃",
         [ModifierKey.ALT]: "⌥",
         [ModifierKey.SHIFT]: "⇧",
     },
-    [Platform.WINDOWS]: {
+    [OS.WINDOWS]: {
         [ModifierKey.META]: "Ctrl",
         [ModifierKey.CTRL]: "Ctrl",
         [ModifierKey.ALT]: "Alt",
         [ModifierKey.SHIFT]: "Shift",
     },
-    [Platform.LINUX]: {
+    [OS.LINUX]: {
         [ModifierKey.META]: "Super",
         [ModifierKey.CTRL]: "Ctrl",
         [ModifierKey.ALT]: "Alt",
@@ -107,8 +152,9 @@ export const ModifierDisplaySymbols: Record<PlatformType, Record<ModifierKeyType
     },
 } as const
 
+/** Platform-specific canonical order for modifier rendering and combo normalization. */
 export const ModifierDisplayOrder: Record<PlatformType, ModifierKeyType[]> = {
-    [Platform.MAC]: [ModifierKey.CTRL, ModifierKey.ALT, ModifierKey.SHIFT, ModifierKey.META],
-    [Platform.WINDOWS]: [ModifierKey.META, ModifierKey.ALT, ModifierKey.SHIFT, ModifierKey.CTRL],
-    [Platform.LINUX]: [ModifierKey.META, ModifierKey.ALT, ModifierKey.SHIFT, ModifierKey.CTRL],
+    [OS.MAC]: [ModifierKey.CTRL, ModifierKey.ALT, ModifierKey.SHIFT, ModifierKey.META],
+    [OS.WINDOWS]: [ModifierKey.META, ModifierKey.ALT, ModifierKey.SHIFT, ModifierKey.CTRL],
+    [OS.LINUX]: [ModifierKey.META, ModifierKey.ALT, ModifierKey.SHIFT, ModifierKey.CTRL],
 } as const

package/src/formatter.ts

@@ -1,13 +1,44 @@
 import {
     ModifierDisplayOrder,
     ModifierDisplaySymbols,
-    Platform,
+    OS,
     detectPlatform,
     type ModifierKeyType,
     type PlatformType,
 } from "./constants"
 import { parseShortcut } from "./parser"
 
+const _BASE_DISPLAY_NAMES: Record<string, string> = {
+    ArrowUp: "↑",
+    ArrowDown: "↓",
+    ArrowLeft: "←",
+    ArrowRight: "→",
+    Home: "Home",
+    End: "End",
+    PageUp: "PgUp",
+    PageDown: "PgDn",
+}
+
+const _MAC_DISPLAY_NAMES: Record<string, string> = {
+    ..._BASE_DISPLAY_NAMES,
+    Enter: "↩",
+    Tab: "⇥",
+    Escape: "⎋",
+    Backspace: "⌫",
+    Delete: "⌦",
+    " ": "␣",
+}
+
+const _NON_MAC_DISPLAY_NAMES: Record<string, string> = {
+    ..._BASE_DISPLAY_NAMES,
+    Enter: "Enter",
+    Tab: "Tab",
+    Escape: "Esc",
+    Backspace: "Backspace",
+    Delete: "Del",
+    " ": "Space",
+}
+
 /**
  * Format a shortcut string for display with platform-aware symbols
  *
@@ -35,31 +66,16 @@ export function formatShortcut(shortcut: string, platform?: PlatformType): strin
         }
     }
 
-    const displayKey = formatKey(parsed.key, targetPlatform)
+    const displayKey = _formatKey(parsed.key, targetPlatform)
     parts.push(displayKey)
 
-    const separator = targetPlatform === Platform.MAC ? "" : "+"
+    const separator = targetPlatform === OS.MAC ? "" : "+"
 
     return parts.join(separator)
 }
 
-function formatKey(key: string, platform: PlatformType): string {
-    const displayNames: Record<string, string> = {
-        ArrowUp: "↑",
-        ArrowDown: "↓",
-        ArrowLeft: "←",
-        ArrowRight: "→",
-        Enter: platform === Platform.MAC ? "↩" : "Enter",
-        Tab: platform === Platform.MAC ? "⇥" : "Tab",
-        Escape: platform === Platform.MAC ? "⎋" : "Esc",
-        Backspace: platform === Platform.MAC ? "⌫" : "Backspace",
-        Delete: platform === Platform.MAC ? "⌦" : "Del",
-        " ": platform === Platform.MAC ? "␣" : "Space",
-        Home: "Home",
-        End: "End",
-        PageUp: "PgUp",
-        PageDown: "PgDn",
-    }
+function _formatKey(key: string, platform: PlatformType): string {
+    const displayNames = platform === OS.MAC ? _MAC_DISPLAY_NAMES : _NON_MAC_DISPLAY_NAMES
 
     return displayNames[key] || key.toUpperCase()
 }
@@ -73,10 +89,9 @@ function formatKey(key: string, platform: PlatformType): string {
  * @example
  * ```ts
  * getModifierSymbols("mac") // { meta: "⌘", ctrl: "⌃", alt: "⌥", shift: "⇧" }
- * ```
+ * ```-
  */
 export function getModifierSymbols(platform?: PlatformType): Record<ModifierKeyType, string> {
     const targetPlatform = platform ?? detectPlatform()
     return ModifierDisplaySymbols[targetPlatform]
 }
-

package/src/hook.ts

@@ -1,7 +1,7 @@
 "use client"
 
 import { useEffect, useRef, useMemo } from "react"
-import { createShortcutBuilder } from "./builder"
+import { _createShortcutBuilder } from "./builder"
 import type {
     ShortcutBuilder,
     UseShortcutOptions,
@@ -10,9 +10,59 @@ import type {
     ShortcutMapEntry,
     ShortcutGroup,
     ShortcutResult,
+    ShortcutHandler,
+    HandlerOptions,
+    ActionKey,
 } from "./types"
 
-function normalizeShortcutMapKeys(keys: ShortcutMapEntry["keys"]): string[] {
+type ShortcutMapSequenceChain = {
+    then: (step: string) => ShortcutMapSequenceChain
+    on: (handler: ShortcutHandler, options?: HandlerOptions) => ShortcutResult
+}
+
+type ShortcutMapChain = {
+    ctrl: ShortcutMapChain
+    shift: ShortcutMapChain
+    alt: ShortcutMapChain
+    cmd: ShortcutMapChain
+    mod: ShortcutMapChain
+    key: (key: ActionKey) => ShortcutMapSequenceChain
+}
+
+function _areShortcutMapKeysEqual(a: ShortcutMapEntry["keys"], b: ShortcutMapEntry["keys"]): boolean {
+    if (Array.isArray(a) && Array.isArray(b)) {
+        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
+    }
+
+    if (!Array.isArray(a) && !Array.isArray(b)) {
+        return a === b
+    }
+
+    return false
+}
+
+function _areShortcutMapsEquivalent(a: ShortcutMap, b: ShortcutMap): boolean {
+    const aKeys = Object.keys(a)
+    const bKeys = Object.keys(b)
+    if (aKeys.length !== bKeys.length) return false
+
+    for (const key of aKeys) {
+        const aEntry = a[key]
+        const bEntry = b[key]
+        if (!bEntry) return false
+        if (!_areShortcutMapKeysEqual(aEntry.keys, bEntry.keys)) return false
+        if (aEntry.handler !== bEntry.handler) return false
+        if (aEntry.options !== bEntry.options) return false
+    }
+
+    return true
+}
+
+function _normalizeShortcutMapKeys(keys: ShortcutMapEntry["keys"]): string[] {
     if (Array.isArray(keys)) {
         return keys.map((key) => key.trim()).filter(Boolean)
     }
@@ -31,7 +81,7 @@ function normalizeShortcutMapKeys(keys: ShortcutMapEntry["keys"]): string[] {
     return [trimmed]
 }
 
-function applyStep(builder: any, step: string): any {
+function _applyStep(builder: ShortcutMapChain, step: string): ShortcutMapSequenceChain {
     const tokens = step
         .toLowerCase()
         .split("+")
@@ -74,9 +124,25 @@ function applyStep(builder: any, step: string): any {
         throw new Error(`[useShortcutMap] Unsupported modifier token "${token}" in step "${step}"`)
     }
 
-    return chain.key(key)
+    return chain.key(key as ActionKey)
 }
 
+/**
+ * Registers an object-based shortcut map in one call and returns per-action handles.
+ *
+ * @param builder - Builder returned by `useShortcut()`
+ * @param shortcutMap - Record of action ids to key bindings, handlers, and options
+ * @returns A result map with one `ShortcutResult` per shortcut id
+ *
+ * @example
+ * ```ts
+ * const $ = useShortcut()
+ * const results = registerShortcutMap($, {
+ *   save: { keys: "mod+s", handler: onSave },
+ *   nav: { keys: ["g", "d"], handler: onGoDashboard },
+ * })
+ * ```
+ */
 export function registerShortcutMap<T extends ShortcutMap>(
     builder: ShortcutBuilder,
     shortcutMap: T,
@@ -85,13 +151,13 @@ export function registerShortcutMap<T extends ShortcutMap>(
 
     for (const id of Object.keys(shortcutMap) as Array<keyof T>) {
         const entry = shortcutMap[id]
-        const steps = normalizeShortcutMapKeys(entry.keys)
+        const steps = _normalizeShortcutMapKeys(entry.keys)
 
         if (steps.length === 0) {
             throw new Error(`[useShortcutMap] Shortcut "${String(id)}" has no key steps`)
         }
 
-        let chain = applyStep(builder, steps[0])
+        let chain = _applyStep(builder, steps[0])
 
         for (const step of steps.slice(1)) {
             chain = chain.then(step)
@@ -108,13 +174,22 @@ export function registerShortcutMap<T extends ShortcutMap>(
  *
  * @param options - Configuration options for the hook
  * @returns A chainable shortcut builder (`$`)
+ *
+ * @example
+ * ```ts
+ * const $ = useShortcut({ activeScopes: ["editor"] })
+ * $.mod.key("s").on((event) => {
+ *   event.preventDefault()
+ *   saveDocument()
+ * })
+ * ```
  */
 export function useShortcut(options: UseShortcutOptions = {}): ShortcutBuilder {
     const optionsRef = useRef(options)
     optionsRef.current = options
 
     const { builder, registry } = useMemo(() => {
-        return createShortcutBuilder(optionsRef.current)
+        return _createShortcutBuilder(optionsRef.current)
     }, [])
 
     useEffect(() => {
@@ -127,12 +202,19 @@ export function useShortcut(options: UseShortcutOptions = {}): ShortcutBuilder {
 
             registry.activeScopes = new Set(scopes.map((scope) => scope.trim()).filter(Boolean))
         }
-    })
+    }, [registry, options])
 
     useEffect(() => {
         return () => {
-            registry.listeners.forEach((entry) => entry.unbind())
             registry.listeners.clear()
+            registry.firstStepIndex.clear()
+            registry.activeSequenceCombos.clear()
+
+            if (registry.listener && registry.listenerTarget) {
+                registry.listenerTarget.removeEventListener(registry.listenerEventType, registry.listener as EventListener)
+                registry.listener = null
+                registry.listenerTarget = null
+            }
         }
     }, [registry])
 
@@ -140,40 +222,67 @@ export function useShortcut(options: UseShortcutOptions = {}): ShortcutBuilder {
 }
 
 /**
- * Bulk registration helper for shortcut maps.
+ * React hook that registers a shortcut map and automatically unbinds on cleanup.
+ *
+ * @param shortcutMap - Record of action ids to key bindings, handlers, and options
+ * @param options - Same options as `useShortcut()`
+ * @returns A map of `ShortcutResult` keyed by your shortcut ids
+ *
+ * @example
+ * ```ts
+ * const mapResults = useShortcutMap({
+ *   save: { keys: "mod+s", handler: onSave },
+ *   close: { keys: "escape", handler: onClose },
+ * })
+ * ```
  */
 export function useShortcutMap<T extends ShortcutMap>(
     shortcutMap: T,
     options: UseShortcutOptions = {},
 ): ShortcutMapResult<T> {
     const $ = useShortcut(options)
-    return registerShortcutMap($, shortcutMap)
+    const stableShortcutMapRef = useRef(shortcutMap)
+    if (!_areShortcutMapsEquivalent(stableShortcutMapRef.current, shortcutMap)) {
+        stableShortcutMapRef.current = shortcutMap
+    }
+
+    const stableShortcutMap = stableShortcutMapRef.current
+    const resultsRef = useRef<ShortcutMapResult<T>>({} as ShortcutMapResult<T>)
+
+    useEffect(() => {
+        const registrations = registerShortcutMap($, stableShortcutMap)
+        const results = resultsRef.current
+        for (const key of Object.keys(results)) {
+            delete (results as Record<string, unknown>)[key]
+        }
+        Object.assign(results, registrations)
+
+        return () => {
+            for (const result of Object.values(registrations)) {
+                result.unbind()
+            }
+            for (const key of Object.keys(results)) {
+                delete (results as Record<string, unknown>)[key]
+            }
+        }
+    }, [$, stableShortcutMap])
+
+    return resultsRef.current
 }
 
 /**
- * Create a shortcut builder for non-React usage
+ * Creates an imperative group controller for many shortcut registrations.
  *
- * Unlike `useShortcut`, this does not auto-cleanup - you must call `.unbind()` manually.
+ * @returns A `ShortcutGroup` that can add and unbind multiple shortcuts together
  *
- * @param options - Configuration options
- * @returns A chainable shortcut builder
- */
-export function createShortcut(options: UseShortcutOptions = {}): ShortcutBuilder {
-    const { builder } = createShortcutBuilder(options)
-    return builder as ShortcutBuilder
-}
-
-/**
- * Bulk registration helper for non-React usage.
+ * @example
+ * ```ts
+ * const group = createShortcutGroup()
+ * group.add($.mod.key("s").on(onSave))
+ * group.add($.key("escape").on(onClose))
+ * group.unbindAll()
+ * ```
  */
-export function createShortcutMap<T extends ShortcutMap>(
-    shortcutMap: T,
-    options: UseShortcutOptions = {},
-): ShortcutMapResult<T> {
-    const builder = createShortcut(options)
-    return registerShortcutMap(builder, shortcutMap)
-}
-
 export function createShortcutGroup(): ShortcutGroup {
     const results: ShortcutResult[] = []
 
@@ -202,6 +311,16 @@ export function createShortcutGroup(): ShortcutGroup {
     }
 }
 
+/**
+ * React hook that returns a stable `ShortcutGroup` instance.
+ *
+ * @returns A memoized `ShortcutGroup` tied to the component lifecycle
+ *
+ * @example
+ * ```ts
+ * const group = useShortcutGroup()
+ * ```
+ */
 export function useShortcutGroup(): ShortcutGroup {
     const groupRef = useRef<ShortcutGroup | null>(null)
 

package/src/index.ts

@@ -31,29 +31,18 @@ export type {
     ExceptPredicate,
     ShortcutScope,
     ShortcutConflict,
-    ShortcutMap,
-    ShortcutMapEntry,
-    ShortcutMapResult,
     ShortcutRecordingOptions,
-    ShortcutGroup,
 } from "./types"
 
 export {
     parseShortcut,
     parseShortcuts,
-    getModifiersFromEvent,
     matchesShortcut,
     matchesAnyShortcut,
 } from "./parser"
 
-export { formatShortcut, getModifierSymbols } from "./formatter"
+export { formatShortcut } from "./formatter"
 
 export {
     useShortcut,
-    createShortcut,
-    useShortcutMap,
-    createShortcutMap,
-    registerShortcutMap,
-    createShortcutGroup,
-    useShortcutGroup,
 } from "./hook"

package/src/parser.ts

@@ -1,6 +1,10 @@
 import { ModifierAliases, SpecialKeyMap, detectPlatform, Platform } from "./constants"
 import type { ModifierState, ParsedShortcut } from "./types"
 
+function _normalizeKeyToken(key: string): string {
+    return key === " " ? "space" : key.toLowerCase()
+}
+
 /**
  * Parse a shortcut string into its components
  *
@@ -93,7 +97,7 @@ export function getModifiersFromEvent(event: KeyboardEvent): ModifierState {
  */
 export function matchesShortcut(event: KeyboardEvent, parsed: ParsedShortcut): boolean {
     const eventModifiers = getModifiersFromEvent(event)
-    const eventKey = event.key.toLowerCase()
+    const eventKey = _normalizeKeyToken(event.key)
 
     const modifiersMatch =
         eventModifiers.meta === parsed.modifiers.meta &&
@@ -101,7 +105,7 @@ export function matchesShortcut(event: KeyboardEvent, parsed: ParsedShortcut): b
         eventModifiers.alt === parsed.modifiers.alt &&
         eventModifiers.shift === parsed.modifiers.shift
 
-    const keyMatches = eventKey === parsed.key.toLowerCase()
+    const keyMatches = eventKey === _normalizeKeyToken(parsed.key)
 
     return modifiersMatch && keyMatches
 }
@@ -116,4 +120,3 @@ export function matchesShortcut(event: KeyboardEvent, parsed: ParsedShortcut): b
 export function matchesAnyShortcut(event: KeyboardEvent, parsedShortcuts: ParsedShortcut[]): boolean {
     return parsedShortcuts.some((parsed) => matchesShortcut(event, parsed))
 }
-

package/src/runtime/binding.ts

@@ -0,0 +1,136 @@
+import { parseShortcut } from "../parser"
+import type { HandlerOptions, ShortcutHandler, ShortcutResult } from "../types"
+
+import { _debugLog } from "./debug"
+import { _detectConflict, _emitConflict } from "./conflicts"
+import { _canonicalizeParsed, _formatSequenceDisplay } from "./keys"
+import { _normalizeScopes } from "./guards"
+import { _attachRegistryListener, _detachRegistryListener } from "./listener"
+import type { BuilderState, RegistryEntry, ShortcutRegistry } from "./types"
+
+export 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, entries] of registry.listeners.entries()) {
+        for (const existing of 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,
+    }
+
+    const comboEntries = registry.listeners.get(combo)
+    if (comboEntries) {
+        comboEntries.push(entry)
+    } else {
+        registry.listeners.set(combo, [entry])
+
+        const firstStep = _canonicalizeParsed(parsedSteps[0])
+        const indexedCombos = registry.firstStepIndex.get(firstStep)
+        if (indexedCombos) {
+            indexedCombos.add(combo)
+        } else {
+            registry.firstStepIndex.set(firstStep, new Set([combo]))
+        }
+    }
+
+    _attachRegistryListener(registry)
+
+    const unbindEntry = () => {
+        const currentEntries = registry.listeners.get(combo)
+        if (!currentEntries) return
+
+        const nextEntries = currentEntries.filter((item) => item.id !== entry.id)
+
+        if (nextEntries.length === 0) {
+            registry.listeners.delete(combo)
+            registry.activeSequenceCombos.delete(combo)
+
+            const firstStep = _canonicalizeParsed(parsedSteps[0])
+            const indexedCombos = registry.firstStepIndex.get(firstStep)
+            if (indexedCombos) {
+                indexedCombos.delete(combo)
+                if (indexedCombos.size === 0) {
+                    registry.firstStepIndex.delete(firstStep)
+                }
+            }
+
+            _debugLog(debug, "Unregistered:", combo)
+        } else {
+            registry.listeners.set(combo, nextEntries)
+        }
+
+        if (registry.listeners.size === 0) {
+            _detachRegistryListener(registry)
+        }
+    }
+
+    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)
+        },
+    }
+}
+