@tanstack/hotkeys 0.9.0 → 0.10.0

package/src/_named-keys.ts

@@ -1,62 +0,0 @@
-/** Names defined for both KeyboardEvent.key and KeyboardEvent.code, beyond the basic key groups. */
-export const SHARED_NAMED_KEYS = [
-  'CapsLock',
-  'ContextMenu',
-  'Convert',
-  'KanaMode',
-  'NonConvert',
-  'Help',
-  'Insert',
-  'NumLock',
-  'Fn',
-  'FnLock',
-  'PrintScreen',
-  'ScrollLock',
-  'Pause',
-  'BrowserBack',
-  'BrowserFavorites',
-  'BrowserForward',
-  'BrowserHome',
-  'BrowserRefresh',
-  'BrowserSearch',
-  'BrowserStop',
-  'Eject',
-  'LaunchMail',
-  'MediaPlayPause',
-  'MediaStop',
-  'MediaTrackNext',
-  'MediaTrackPrevious',
-  'Power',
-  'AudioVolumeDown',
-  'AudioVolumeMute',
-  'AudioVolumeUp',
-  'WakeUp',
-  'Hyper',
-  'Super',
-  'Again',
-  'Copy',
-  'Cut',
-  'Find',
-  'Open',
-  'Paste',
-  'Props',
-  'Select',
-  'Undo',
-  'Hiragana',
-  'Katakana',
-] as const
-
-/** Logical counterparts whose physical positions use different names (for example Sleep and Lang1). */
-export const LOGICAL_ONLY_NAMED_KEYS = [
-  'Clear',
-  'Cancel',
-  'Standby',
-  'LaunchApplication1',
-  'LaunchApplication2',
-  'LaunchMediaPlayer',
-  'HangulMode',
-  'HanjaMode',
-  'Zenkaku',
-  'Hankaku',
-  'ZenkakuHankaku',
-] as const

package/src/_recorder-chord.ts

@@ -1,76 +0,0 @@
-import { normalizeKeyName } from './constants'
-import { normalizeKeyboardEvent } from './_keyboard-event'
-import {
-  isModifierKey,
-  normalizeHotkeyFromParsed,
-  parseKeyboardEvent,
-} from './parse'
-import type {
-  RecorderKeyMode,
-  RecorderOptions,
-  RecorderRejection,
-} from './recorder-options'
-import type { Hotkey } from './hotkey.types'
-
-/**
- * Converts a keydown to a replayable chord, preserving physical codes by default.
- * Returns null for composition, modifier-only input, or unusable physical input.
- * Key mode retains the produced character; neither mode guesses layout letters.
- */
-export function hotkeyChordFromKeydown(
-  event: KeyboardEvent,
-  platform: 'mac' | 'windows' | 'linux',
-  recordBy: RecorderKeyMode = 'code',
-): Hotkey | null {
-  const normalized = normalizeKeyboardEvent(event, platform)
-  if (
-    normalized.isComposing ||
-    isModifierKey(normalizeKeyName(event.key)) ||
-    event.key === 'AltGraph'
-  )
-    return null
-  if (
-    recordBy === 'code' &&
-    (!/^[A-Za-z][A-Za-z0-9]*$/.test(event.code) ||
-      event.code === 'Unidentified' ||
-      normalized.altGraph)
-  )
-    return null
-  const parsed = parseKeyboardEvent(event, platform)
-  if (recordBy === 'code') {
-    // Remove logical identity rather than placing a physical code in the key field.
-    const { key: _key, code: _code, ...modifiers } = parsed
-    return normalizeHotkeyFromParsed(
-      { ...modifiers, code: event.code },
-      platform,
-    )
-  }
-  return parsed.key ? normalizeHotkeyFromParsed(parsed, platform) : null
-}
-
-/**
- * Explains why a physical chord cannot be recorded before syntax/policy checks.
- * Logical mode deliberately accepts produced characters instead of requiring a code.
- */
-export function chordRejection(
-  event: KeyboardEvent,
-  options: RecorderOptions,
-): RecorderRejection | undefined {
-  if (options.recordBy === 'key') return undefined
-  // AltGr is character entry, often reported as synthetic Ctrl+Alt; macOS Option is handled separately.
-  if (normalizeKeyboardEvent(event, options.platform).altGraph)
-    return {
-      reason: 'alt-graph',
-      message:
-        'AltGraph character entry cannot be recorded as a physical shortcut. Use key mode for characters.',
-    }
-  if (
-    !/^[A-Za-z][A-Za-z0-9]*$/.test(event.code) ||
-    event.code === 'Unidentified'
-  )
-    return {
-      reason: 'missing-code',
-      message: 'This event has no usable physical key code.',
-    }
-  return undefined
-}

package/src/_recording-guard.ts

@@ -1,63 +0,0 @@
-import { MODIFIER_KEYS, normalizeKeyName } from './constants'
-
-// Shared only by recorders and dispatchers. Does not own bindings or preferences.
-// Multiple recorder instances may be active; dispatch resumes after the last one ends.
-const sessions = new Set<object>()
-// Remember consumed event objects through the remainder of their DOM dispatch.
-const captured = new WeakSet<KeyboardEvent>()
-// Captured physical identities stay blocked through repeats and their eventual keyup.
-const pending = new Map<string, string>()
-let listening = false
-// Prefer the stable physical identity when modifier release changes event.key.
-const identity = (event: KeyboardEvent) => event.code || `key:${event.key}`
-
-/** Consumes recorded key releases and removes guards for completed chords. */
-function release(event: KeyboardEvent): void {
-  if (pending.delete(identity(event))) captured.add(event)
-  // macOS can swallow the main key's keyup while Command is held.
-  // Releasing a modifier ends that chord, as in KeyStateTracker.
-  if (MODIFIER_KEYS.has(normalizeKeyName(event.key))) {
-    for (const [id, key] of pending) {
-      if (!MODIFIER_KEYS.has(key)) pending.delete(id)
-    }
-  }
-  cleanup()
-}
-/** Clears pending releases when focus loss prevents the browser from delivering them. */
-function blur(): void {
-  pending.clear()
-  cleanup()
-}
-/** Detaches shared listeners once neither active sessions nor pending releases need them. */
-function cleanup(): void {
-  if (listening && sessions.size === 0 && pending.size === 0) {
-    document.removeEventListener('keyup', release, true)
-    window.removeEventListener('blur', blur)
-    listening = false
-  }
-}
-/** Pauses application shortcut dispatch and starts tracking releases for this recorder. */
-export function beginRecording(owner: object): void {
-  sessions.add(owner)
-  if (!listening && typeof document !== 'undefined') {
-    document.addEventListener('keyup', release, true)
-    window.addEventListener('blur', blur)
-    listening = true
-  }
-}
-/** Ends a session while retaining guards for keys still held after commit or cancellation. */
-export function endRecording(owner: object): void {
-  sessions.delete(owner)
-  cleanup()
-}
-/** Marks a consumed keydown and guards subsequent repeats and its release. */
-export function captureRecordingEvent(event: KeyboardEvent): void {
-  captured.add(event)
-  pending.set(identity(event), normalizeKeyName(event.key))
-}
-/** Whether managers should suppress callbacks for this recording session or captured chord. */
-export function isRecordingEvent(event: KeyboardEvent): boolean {
-  return (
-    sessions.size > 0 || captured.has(event) || pending.has(identity(event))
-  )
-}

package/src/_registration.ts

@@ -1,79 +0,0 @@
-import type { ConflictBehavior, ParsedHotkey } from './hotkey.types'
-
-/**
- * Default options for hotkey/sequence registration.
- * Omitted: platform, target (resolved at registration), requireReset (HotkeyManager only).
- */
-export const defaultHotkeyOptions = {
-  preventDefault: true,
-  stopPropagation: true,
-  eventType: 'keydown' as const,
-  enabled: true,
-  ignoreInputs: true,
-  conflictBehavior: 'warn' as ConflictBehavior,
-}
-
-/**
- * Computes the default ignoreInputs value based on the hotkey.
- * Ctrl/Meta shortcuts and Escape fire in inputs; single keys and Shift/Alt combos are ignored.
- */
-export function getDefaultIgnoreInputs(parsedHotkey: ParsedHotkey): boolean {
-  if (parsedHotkey.ctrl || parsedHotkey.meta) return false // Mod+S, Ctrl+C, etc.
-  if (parsedHotkey.key === 'Escape' || parsedHotkey.code === 'Escape')
-    return false // Close modal, etc.
-  return true // Single keys, Shift+key, Alt+key
-}
-
-/**
- * Handles conflicts between registrations based on conflict behavior.
- *
- * @param conflictingId - The ID of the conflicting registration
- * @param keyDisplay - Display string for the conflicting key/sequence (for error messages)
- * @param conflictBehavior - How to handle the conflict
- * @param unregister - Function to unregister by ID
- */
-export function handleConflict(
-  conflictingId: string,
-  keyDisplay: string,
-  conflictBehavior: ConflictBehavior,
-  unregister: (id: string) => void,
-): void {
-  if (conflictBehavior === 'allow') {
-    return
-  }
-
-  if (conflictBehavior === 'warn') {
-    console.warn(
-      `'${keyDisplay}' is already registered. Multiple handlers will be triggered. ` +
-        `Use conflictBehavior: 'replace' to replace the existing handler, ` +
-        `or conflictBehavior: 'allow' to suppress this warning.`,
-    )
-    return
-  }
-
-  if (conflictBehavior === 'error') {
-    throw new Error(
-      `'${keyDisplay}' is already registered. ` +
-        `Use conflictBehavior: 'replace' to replace the existing handler, ` +
-        `or conflictBehavior: 'allow' to allow multiple registrations.`,
-    )
-  }
-
-  // At this point, conflictBehavior must be 'replace'
-  unregister(conflictingId)
-}
-
-/** Compare updates without publishing unchanged options, including fresh metadata objects. */
-export function optionsEqual(left: object, right: object): boolean {
-  const a = left as Record<string, unknown>
-  const b = right as Record<string, unknown>
-  const keys = Object.keys(a)
-  return (
-    keys.length === Object.keys(b).length &&
-    keys.every((key) =>
-      key === 'meta' && a[key] && b[key]
-        ? optionsEqual(a[key] as object, b[key] as object)
-        : Object.is(a[key], b[key]),
-    )
-  )
-}

package/src/conflicts.ts

@@ -1,125 +0,0 @@
-import { detectPlatform } from './platform'
-import { parseRegisterableHotkey } from './parse'
-import { keysEqual } from './_keyboard-event'
-import { matchesKeyboardEvent } from './match'
-import { getHotkeyManager, toHotkeyRegistrationView } from './hotkey-manager'
-import { getSequenceManager } from './sequence-manager'
-import type { HotkeyRegistrationView } from './hotkey-manager'
-import type { SequenceRegistrationView } from './sequence-manager'
-import type { RegisterableHotkey } from './hotkey.types'
-
-export type HotkeyConflict =
-  | { type: 'hotkey'; registration: HotkeyRegistrationView }
-  | { type: 'sequence'; registration: SequenceRegistrationView }
-
-export interface HotkeyConflictOptions {
-  /** Intended registration target. Defaults to document; disjoint targets are excluded. */
-  target?: HTMLElement | Document | Window
-  /** Check all targets instead of overlapping targets. Default: overlapping. */
-  scope?: 'overlapping' | 'all'
-  /** Intended event type. Default: keydown. */
-  eventType?: 'keydown' | 'keyup'
-  /** Include disabled registrations. Default: false. */
-  includeDisabled?: boolean
-  /** IDs of registrations being edited. */
-  excludeIds?: ReadonlyArray<string>
-  /** Additional app-specific exclusions, such as all instances of one action. */
-  exclude?: (
-    registration: HotkeyRegistrationView | SequenceRegistrationView,
-  ) => boolean
-  /** Platform used to resolve Mod in the candidate. Registrations retain their own platform. */
-  platform?: 'mac' | 'windows' | 'linux'
-  /** Source events allow detecting physical/logical overlap on the recorded layout. */
-  events?: ReadonlyArray<KeyboardEvent>
-}
-
-/** Whether two targets share a document and one contains the other (or is its window). */
-function targetsOverlap(
-  a: HTMLElement | Document | Window,
-  b: HTMLElement | Document | Window,
-): boolean {
-  if (a === b) return true
-  // Resolve the owning document without relying on cross-frame instanceof checks.
-  const documentOf = (target: typeof a): Document | null => {
-    if ('document' in target) return target.document
-    if (target.nodeType === 9) return target as Document
-    return target.ownerDocument
-  }
-  if (documentOf(a) !== documentOf(b)) return false
-  if (!('contains' in a) || !('contains' in b)) return true
-  return a.contains(b as Node) || b.contains(a as Node)
-}
-
-/**
- * Find equivalent bindings and sequence-prefix conflicts in the live registry.
- * With source events, also checks observed logical/physical overlap. Does not
- * discover unmounted handlers, external listeners, or other keyboard layouts.
- */
-export function findHotkeyConflicts(
-  candidate: RegisterableHotkey | ReadonlyArray<RegisterableHotkey>,
-  options: HotkeyConflictOptions = {},
-): Array<HotkeyConflict> {
-  const steps: ReadonlyArray<RegisterableHotkey> = Array.isArray(candidate)
-    ? candidate
-    : [candidate as RegisterableHotkey]
-  if (steps.length === 0) return []
-  const platform = options.platform ?? detectPlatform()
-  const parsed = steps.map((step) => parseRegisterableHotkey(step, platform))
-  const target =
-    options.target ?? (typeof document === 'undefined' ? undefined : document)
-  const conflicts: Array<HotkeyConflict> = []
-  // Apply scope policy before comparing equivalent bindings or observed event overlap.
-  const matches = (
-    registration: HotkeyRegistrationView | SequenceRegistrationView,
-    bindings: ReadonlyArray<RegisterableHotkey>,
-  ) => {
-    if (
-      (!options.includeDisabled && registration.options.enabled === false) ||
-      (registration.options.eventType ?? 'keydown') !==
-        (options.eventType ?? 'keydown') ||
-      options.excludeIds?.includes(registration.id) ||
-      options.exclude?.(registration) ||
-      (options.scope !== 'all' &&
-        target &&
-        !targetsOverlap(target, registration.target))
-    )
-      return false
-    // Compare only the common prefix: a shorter sequence can collide with a longer one.
-    return parsed
-      .slice(0, Math.min(parsed.length, bindings.length))
-      .every((a, index) => {
-        const b = parseRegisterableHotkey(
-          bindings[index]!,
-          registration.options.platform,
-        )
-        const same =
-          a.ctrl === b.ctrl &&
-          a.alt === b.alt &&
-          a.shift === b.shift &&
-          a.meta === b.meta &&
-          (a.code !== undefined || b.code !== undefined
-            ? a.code === b.code
-            : keysEqual(a.key, b.key))
-        // A source event can establish code/key overlap without guessing its layout.
-        const event = options.events?.[index]
-        return (
-          same ||
-          (event !== undefined &&
-            matchesKeyboardEvent(event, a, platform) &&
-            matchesKeyboardEvent(event, b, registration.options.platform))
-        )
-      })
-  }
-  for (const registration of getHotkeyManager().registrations.state.values()) {
-    if (matches(registration, [registration.hotkey]))
-      conflicts.push({
-        type: 'hotkey',
-        registration: toHotkeyRegistrationView(registration),
-      })
-  }
-  for (const registration of getSequenceManager().registrations.state.values()) {
-    if (matches(registration, registration.sequence))
-      conflicts.push({ type: 'sequence', registration })
-  }
-  return conflicts
-}