@tanstack/lit-hotkeys 0.12.0 → 0.13.1

package/src/controllers/hotkey-registrations.ts

@@ -1,89 +0,0 @@
-import {
-  getHotkeyManager,
-  getSequenceManager,
-  toHotkeyRegistrationView,
-} from '@tanstack/hotkeys'
-import type {
-  HotkeyRegistrationView,
-  SequenceRegistrationView,
-} from '@tanstack/hotkeys'
-import type { ReactiveController, ReactiveControllerHost } from 'lit'
-
-/**
- * A Lit ReactiveController that tracks all hotkey and sequence registrations.
- *
- * Subscribes to the singleton HotkeyManager and SequenceManager stores and
- * triggers host updates whenever registrations change.
- *
- * @example
- * ```ts
- * class ShortcutPalette extends LitElement {
- *   private registrations = new HotkeyRegistrationsController(this)
- *
- *   render() {
- *     return html`
- *       <ul>
- *         ${this.registrations.hotkeys.map(
- *           (reg) => html`<li>${reg.options.meta?.name ?? reg.hotkey}</li>`,
- *         )}
- *       </ul>
- *     `
- *   }
- * }
- * ```
- */
-export class HotkeyRegistrationsController implements ReactiveController {
-  private _unsubscribeHotkeys: (() => void) | undefined
-  private _unsubscribeSequences: (() => void) | undefined
-  private _hotkeys: Array<HotkeyRegistrationView> = []
-  private _sequences: Array<SequenceRegistrationView> = []
-
-  /** All registered hotkeys (public view, no callbacks). */
-  public get hotkeys(): Array<HotkeyRegistrationView> {
-    return this._hotkeys
-  }
-
-  /** All registered sequences. */
-  public get sequences(): Array<SequenceRegistrationView> {
-    return this._sequences
-  }
-
-  constructor(private _host: ReactiveControllerHost) {
-    this._host.addController(this)
-  }
-
-  public hostConnected(): void {
-    const hotkeyManager = getHotkeyManager()
-    const sequenceManager = getSequenceManager()
-
-    const hotkeysSub = hotkeyManager.registrations.subscribe(() => {
-      this._hotkeys = Array.from(
-        hotkeyManager.registrations.state.values(),
-      ).map(toHotkeyRegistrationView)
-      this._host.requestUpdate()
-    })
-
-    const sequencesSub = sequenceManager.registrations.subscribe(() => {
-      this._sequences = Array.from(sequenceManager.registrations.state.values())
-      this._host.requestUpdate()
-    })
-
-    this._unsubscribeHotkeys = () => hotkeysSub.unsubscribe()
-    this._unsubscribeSequences = () => sequencesSub.unsubscribe()
-
-    // Sync initial state
-    this._hotkeys = Array.from(hotkeyManager.registrations.state.values()).map(
-      toHotkeyRegistrationView,
-    )
-    this._sequences = Array.from(sequenceManager.registrations.state.values())
-  }
-
-  public hostDisconnected(): void {
-    this._unsubscribeHotkeys?.()
-    this._unsubscribeSequences?.()
-    this._unsubscribeHotkeys = undefined
-    this._unsubscribeSequences = undefined
-    this._hotkeys = []
-    this._sequences = []
-  }
-}

package/src/controllers/hotkey-sequence-recorder.ts

@@ -1,141 +0,0 @@
-import { HotkeySequenceRecorder } from '@tanstack/hotkeys'
-import type { ReactiveController, ReactiveControllerHost } from 'lit'
-import type {
-  HotkeySequence,
-  HotkeySequenceRecorderOptions,
-} from '@tanstack/hotkeys'
-
-/**
- * A Lit ReactiveController that records multi-chord sequences (Vim-style shortcuts).
- *
- * Wraps the framework-agnostic `HotkeySequenceRecorder` class, managing store
- * subscriptions and host update lifecycle automatically.
- *
- * @example
- * ```ts
- * class ShortcutSettings extends LitElement {
- *   private recorder = new HotkeySequenceRecorderController(this, {
- *     onRecord: (sequence) => {
- *       this.sequence = sequence
- *       this.requestUpdate()
- *     },
- *     onCancel: () => {
- *       console.log('Recording cancelled')
- *     },
- *   })
- *
- *   private sequence: HotkeySequence | null = null
- *
- *   render() {
- *     return html`
- *       <button @click=${() => this.recorder.startRecording()}>
- *         ${this.recorder.isRecording ? 'Recording...' : 'Edit Sequence'}
- *       </button>
- *       ${this.recorder.steps.length
- *         ? html`<div>Steps: ${this.recorder.steps.join(' → ')}</div>`
- *         : nothing}
- *       ${this.recorder.recordedSequence
- *         ? html`<div>Recorded: ${this.recorder.recordedSequence.join(' → ')}</div>`
- *         : nothing}
- *     `
- *   }
- * }
- * ```
- */
-export class HotkeySequenceRecorderController implements ReactiveController {
-  /** The recorder instance. */
-  private _recorder: HotkeySequenceRecorder
-  /** The unsubscribe function. */
-  private _unsubscribe: (() => void) | undefined
-  /** Whether recording is currently active. */
-  private _isRecording = false
-  /** Chords captured in the current session. */
-  private _steps: HotkeySequence = []
-  /** Last committed sequence, or null if none. */
-  private _recordedSequence: HotkeySequence | null = null
-
-  /** Whether recording is currently active. */
-  public get isRecording(): boolean {
-    return this._isRecording
-  }
-
-  /** Chords captured in the current session. */
-  public get steps(): HotkeySequence {
-    return this._steps
-  }
-
-  /** Last committed sequence, or null if none. */
-  public get recordedSequence(): HotkeySequence | null {
-    return this._recordedSequence
-  }
-
-  /**
-   * @param _host - The Lit component that owns this controller.
-   * @param _options - Configuration options for the sequence recorder.
-   */
-  constructor(
-    private _host: ReactiveControllerHost,
-    private _options: HotkeySequenceRecorderOptions,
-  ) {
-    this._recorder = new HotkeySequenceRecorder(_options)
-    this._host.addController(this)
-  }
-
-  /** Subscribes to the recorder store and updates internal state when changes occur. */
-  public hostConnected(): void {
-    const subscription = this._recorder.store.subscribe(() => {
-      const { isRecording, steps, recordedSequence } =
-        this._recorder.store.state
-
-      const hasChanged: boolean =
-        isRecording !== this._isRecording ||
-        steps !== this._steps ||
-        recordedSequence !== this._recordedSequence
-
-      if (hasChanged) {
-        this._isRecording = isRecording
-        this._steps = steps
-        this._recordedSequence = recordedSequence
-        this._host.requestUpdate()
-      }
-    })
-
-    this._unsubscribe = () => subscription.unsubscribe()
-  }
-
-  /** Unsubscribes from the recorder store and destroys the recorder instance to prevent memory leaks. */
-  public hostDisconnected(): void {
-    this._unsubscribe?.()
-    this._unsubscribe = undefined
-    this._recorder.stop()
-    this._isRecording = false
-    this._steps = []
-    this._recordedSequence = null
-  }
-
-  /** Updates the recorder options. */
-  public setOptions(options: Partial<HotkeySequenceRecorderOptions>): void {
-    this._options = { ...this._options, ...options }
-    this._recorder.setOptions(this._options)
-  }
-
-  /** Start recording a new sequence. */
-  public startRecording(): void {
-    this._recorder.start()
-  }
-
-  /** Stop recording (same as cancel but without calling onCancel). */
-  public stopRecording(): void {
-    this._recorder.stop()
-  }
-
-  /** Cancel recording without saving. */
-  public cancelRecording(): void {
-    this._recorder.cancel()
-  }
-
-  /** Commit current steps as a sequence (no-op if empty). */
-  public commitRecording(): void {
-    this._recorder.commit()
-  }
-}

package/src/controllers/hotkey-sequence.ts

@@ -1,82 +0,0 @@
-import { getSequenceManager } from '@tanstack/hotkeys'
-import { HOTKEY_SEQUENCE_DEFAULT_OPTIONS } from '../constants'
-import type { ReactiveController, ReactiveControllerHost } from 'lit'
-import type {
-  HotkeyCallback,
-  HotkeySequence,
-  SequenceManager,
-  SequenceOptions,
-  SequenceRegistrationHandle,
-} from '@tanstack/hotkeys'
-
-/**
- * A Lit ReactiveController that registers a keyboard sequence (e.g. Vim-style)
- * when the host element is connected and unregisters it when the host is disconnected.
- *
- * @example
- * ```ts
- * class MyElement extends LitElement {
- *   private seq = new HotkeySequenceController(this, ['G', 'G'], () => this.goToTop())
- *
- *   constructor() {
- *     super()
- *     this.addController(this.seq)
- *   }
- * }
- * ```
- */
-export class HotkeySequenceController implements ReactiveController {
-  /** The sequence registration handle. */
-  private _registration: SequenceRegistrationHandle | undefined
-
-  /**
-   * @param _host - The Lit component that owns this controller (use `this` and pass it to `addController()`).
-   * @param _sequence - The key sequence to listen for (e.g. `['G', 'G']`).
-   * @param _callback - Function to run when the sequence is completed; called with the host as `this`.
-   * @param _options - Optional sequence options (target, timeout, enabled, etc.).
-   */
-  constructor(
-    private _host: ReactiveControllerHost,
-    private _sequence: HotkeySequence,
-    private _callback: HotkeyCallback,
-    private _options: SequenceOptions = HOTKEY_SEQUENCE_DEFAULT_OPTIONS,
-  ) {}
-
-  /**
-   * Registers the sequence with the global sequence manager when the host is connected to the DOM.
-   * Skips registration if disabled, sequence is empty, or no target is available.
-   */
-  public hostConnected(): void {
-    const { target: _target, ...optionsWithoutTarget } = this._options
-
-    const manager: SequenceManager = getSequenceManager()
-
-    const hasExplicitTarget = 'target' in this._options
-    const resolvedTarget = hasExplicitTarget
-      ? (this._options.target ?? null)
-      : typeof document !== 'undefined'
-        ? document
-        : null
-
-    if (!resolvedTarget) {
-      return
-    }
-
-    const boundCallback: HotkeyCallback = this._callback.bind(
-      this._host as unknown as object,
-    )
-
-    this._registration = manager.register(this._sequence, boundCallback, {
-      ...optionsWithoutTarget,
-      target: resolvedTarget,
-    })
-  }
-
-  /** Unregisters the sequence when the host is disconnected from the DOM. */
-  public hostDisconnected(): void {
-    if (this._registration?.isActive) {
-      this._registration.unregister()
-    }
-    this._registration = undefined
-  }
-}

package/src/controllers/hotkey.ts

@@ -1,96 +0,0 @@
-import {
-  detectPlatform,
-  formatHotkey,
-  getHotkeyManager,
-  rawHotkeyToParsedHotkey,
-} from '@tanstack/hotkeys'
-import { HOTKEY_DEFAULT_OPTIONS } from '../constants'
-import type { ReactiveController, ReactiveControllerHost } from 'lit'
-import type {
-  Hotkey,
-  HotkeyCallback,
-  HotkeyManager,
-  HotkeyOptions,
-  HotkeyRegistrationHandle,
-  RegisterableHotkey,
-} from '@tanstack/hotkeys'
-
-/**
- * A Lit ReactiveController that registers a keyboard hotkey when the host
- * element is connected and unregisters it when the host is disconnected.
- *
- * @example
- * ```ts
- * class MyElement extends LitElement {
- *   private hotkey = new HotkeyController(this, 'Mod+S', () => this.save())
- *
- *   constructor() {
- *     super()
- *     this.addController(this.hotkey)
- *   }
- * }
- * ```
- */
-export class HotkeyController implements ReactiveController {
-  /** The hotkey registration handle. */
-  private _registration: HotkeyRegistrationHandle | undefined
-
-  /**
-   * @param _host - The Lit component that owns this controller (use `this` and pass it to `addController()`).
-   * @param _hotkey - The key or key combo to listen for (e.g. `'Mod+S'` or a raw hotkey object).
-   * @param _callback - Function to run when the hotkey is pressed; called with the host as `this`.
-   * @param _options - Optional registration options (target, platform, enabled, etc.).
-   */
-  constructor(
-    private _host: ReactiveControllerHost,
-    private _hotkey: RegisterableHotkey,
-    private _callback: HotkeyCallback,
-    private _options: HotkeyOptions = HOTKEY_DEFAULT_OPTIONS,
-  ) {}
-
-  /**
-   * Registers the hotkey with the global manager when the host is connected to the DOM.
-   * Skips registration if no target is available (e.g. no document or options.target is null).
-   */
-  public hostConnected(): void {
-    const manager: HotkeyManager = getHotkeyManager()
-
-    const platform = this._options.platform ?? detectPlatform()
-    const hotkeyString: Hotkey =
-      typeof this._hotkey === 'string'
-        ? this._hotkey
-        : (formatHotkey(
-            rawHotkeyToParsedHotkey(this._hotkey, platform),
-          ) as Hotkey)
-
-    const hasExplicitTarget = 'target' in this._options
-    const resolvedTarget = hasExplicitTarget
-      ? (this._options.target ?? null)
-      : typeof document !== 'undefined'
-        ? document
-        : null
-
-    if (!resolvedTarget) {
-      return
-    }
-
-    const { target: _target, ...optionsWithoutTarget } = this._options
-
-    const boundCallback: HotkeyCallback = this._callback.bind(
-      this._host as unknown as object,
-    )
-
-    this._registration = manager.register(hotkeyString, boundCallback, {
-      ...optionsWithoutTarget,
-      target: resolvedTarget,
-    })
-  }
-
-  /** Unregisters the hotkey when the host is disconnected from the DOM. */
-  public hostDisconnected(): void {
-    if (this._registration?.isActive) {
-      this._registration.unregister()
-    }
-    this._registration = undefined
-  }
-}

package/src/controllers/index.ts

@@ -1,9 +0,0 @@
-export * from './held-key-codes'
-export * from './held-keys'
-export * from './hotkey'
-export * from './hotkey-recorder'
-export * from './hotkey-registrations'
-export * from './hotkey-sequence'
-export * from './hotkey-sequence-recorder'
-export * from './key-hold'
-export * from './hotkey-hint'

package/src/controllers/key-hold.ts

@@ -1,88 +0,0 @@
-import { getKeyStateTracker } from '@tanstack/hotkeys'
-import type { ReactiveController, ReactiveControllerHost } from 'lit'
-import type { IndividualKey, KeyStateTracker } from '@tanstack/hotkeys'
-
-/**
- * A Lit ReactiveController that tracks whether a specific key is currently held.
- *
- * Subscribes to the global KeyStateTracker and triggers host updates
- * when the held state of the specified key changes.
- *
- * @example
- * ```ts
- * class MyElement extends LitElement {
- *   private shiftHold = new KeyHoldController(this, 'Shift')
- *
- *   render() {
- *     return html`
- *       <div style="opacity: ${this.shiftHold.value ? 1 : 0.5}">
- *         ${this.shiftHold.value ? 'Shift is pressed!' : 'Press Shift'}
- *       </div>
- *     `
- *   }
- * }
- * ```
- *
- * @example
- * ```ts
- * class ModifierIndicators extends LitElement {
- *   private ctrl = new KeyHoldController(this, 'Control')
- *   private shift = new KeyHoldController(this, 'Shift')
- *   private alt = new KeyHoldController(this, 'Alt')
- *
- *   render() {
- *     return html`
- *       <span style="opacity: ${this.ctrl.value ? 1 : 0.3}">Ctrl</span>
- *       <span style="opacity: ${this.shift.value ? 1 : 0.3}">Shift</span>
- *       <span style="opacity: ${this.alt.value ? 1 : 0.3}">Alt</span>
- *     `
- *   }
- * }
- * ```
- */
-export class KeyHoldController implements ReactiveController {
-  /** The unsubscribe function to unsubscribe from the tracker store. */
-  private _unsubscribe: (() => void) | undefined
-  /** Whether the tracked key is currently held down. */
-  private _value = false
-
-  /** Whether the tracked key is currently held down. */
-  public get value(): boolean {
-    return this._value
-  }
-
-  /**
-   * @param host - The Lit component that owns this controller.
-   * @param key - The key to track (e.g. 'Shift', 'Control', 'A').
-   */
-  constructor(
-    private _host: ReactiveControllerHost,
-    private _key: IndividualKey,
-  ) {
-    this._host.addController(this)
-  }
-
-  public hostConnected(): void {
-    const tracker: KeyStateTracker = getKeyStateTracker()
-    const normalizedKey: string = this._key.toLowerCase()
-
-    const subscription = tracker.store.subscribe(() => {
-      const isHeld: boolean = tracker.store.state.heldKeys.some(
-        (heldKey: string) => heldKey.toLowerCase() === normalizedKey,
-      )
-
-      if (isHeld !== this._value) {
-        this._value = isHeld
-        this._host.requestUpdate()
-      }
-    })
-
-    this._unsubscribe = () => subscription.unsubscribe()
-  }
-
-  public hostDisconnected(): void {
-    this._unsubscribe?.()
-    this._unsubscribe = undefined
-    this._value = false
-  }
-}

package/src/decorators/hotkey-sequence.ts

@@ -1,68 +0,0 @@
-import { HotkeySequenceController } from '../controllers/hotkey-sequence'
-import { HOTKEY_SEQUENCE_DEFAULT_OPTIONS } from '../constants'
-import type { LitElement } from 'lit'
-import type {
-  HotkeyCallback,
-  HotkeySequence,
-  SequenceOptions,
-} from '@tanstack/hotkeys'
-
-/**
- * Decorator that registers a keyboard sequence (e.g. Vim-style) on the element
- * when it connects and unregisters when it disconnects. Uses
- * {@link HotkeySequenceController} under the hood.
- *
- * @param sequence - The key sequence to listen for (e.g. `['G', 'G']` for "g g").
- * @param options - Optional sequence options (target, timeout, enabled, etc.).
- * @returns A method decorator for use on LitElement methods.
- *
- * @example
- * ```ts
- * class MyElement extends LitElement {
- *   @hotkeySequence(['G', 'G'])
- *   goToTop() { window.scrollTo(0, 0) }
- *
- *   @hotkeySequence(['D', 'D'], { timeout: 500 })
- *   deleteLine() { this.deleteCurrentLine() }
- * }
- * ```
- */
-export function hotkeySequence(
-  sequence: HotkeySequence,
-  options: SequenceOptions = HOTKEY_SEQUENCE_DEFAULT_OPTIONS,
-) {
-  return function <T extends HotkeyCallback>(
-    proto: LitElement,
-    methodName: string,
-    descriptor: TypedPropertyDescriptor<T>,
-  ) {
-    const originalConnected = proto.connectedCallback
-    const controllerKey = Symbol(`@hotkeySequence:${methodName}`)
-
-    proto.connectedCallback = function () {
-      originalConnected.call(this)
-
-      const host = this as unknown as {
-        [key: symbol]: HotkeySequenceController | undefined
-        addController: (c: unknown) => void
-        [key: string]: unknown
-      }
-      if (!host[controllerKey]) {
-        const callback: HotkeyCallback = descriptor.value
-          ? descriptor.value.bind(this)
-          : (host[methodName] as HotkeyCallback).bind(this)
-
-        if (typeof callback !== 'function') {
-          throw new Error(
-            `@hotkeySequence decorator can only be applied to functions`,
-          )
-        }
-
-        const controller: HotkeySequenceController =
-          new HotkeySequenceController(this, sequence, callback, options)
-        host[controllerKey] = controller
-        this.addController(controller)
-      }
-    }
-  }
-}

package/src/decorators/hotkey.ts

@@ -1,70 +0,0 @@
-import { HotkeyController } from '../controllers/hotkey'
-import { HOTKEY_DEFAULT_OPTIONS } from '../constants'
-import type { LitElement } from 'lit'
-import type {
-  HotkeyCallback,
-  HotkeyOptions,
-  RegisterableHotkey,
-} from '@tanstack/hotkeys'
-
-/**
- * Decorator that registers a keyboard hotkey on the element when it connects
- * and unregisters when it disconnects. Uses {@link HotkeyController} under the hood.
- *
- * @param hotkey - The key or key combo to listen for (e.g. `'Mod+S'` or a raw hotkey object).
- * @param options - Optional registration options (target, platform, enabled, etc.).
- * @returns A method decorator for use on LitElement methods.
- *
- * @example
- * ```ts
- * class MyElement extends LitElement {
- *   @hotkey('Mod+S')
- *   save() { this.doSave() }
- *
- *   @hotkey('Escape')
- *   close() { this.dismiss() }
- * }
- * ```
- */
-export function hotkey(
-  hotkey: RegisterableHotkey,
-  options: HotkeyOptions = HOTKEY_DEFAULT_OPTIONS,
-) {
-  return function <T extends HotkeyCallback>(
-    proto: LitElement,
-    propertyKey: string,
-    descriptor?: TypedPropertyDescriptor<T>,
-  ) {
-    const originalConnected = proto.connectedCallback
-    const controllerKey = Symbol(`@hotkey:${propertyKey}`)
-
-    proto.connectedCallback = function () {
-      originalConnected.call(this)
-
-      const host = this as unknown as {
-        [key: symbol]: HotkeyController | undefined
-        addController: (c: unknown) => void
-        [key: string]: unknown
-      }
-
-      if (!host[controllerKey]) {
-        const callback: HotkeyCallback = descriptor?.value
-          ? (descriptor.value.bind(this) as HotkeyCallback)
-          : (host[propertyKey] as HotkeyCallback)
-
-        if (typeof callback !== 'function') {
-          throw new Error(`@hotkey decorator can only be applied to functions`)
-        }
-
-        const controller: HotkeyController = new HotkeyController(
-          this,
-          hotkey,
-          callback,
-          options,
-        )
-        host[controllerKey] = controller
-        this.addController(controller)
-      }
-    }
-  }
-}

package/src/decorators/index.ts

@@ -1,2 +0,0 @@
-export * from './hotkey-sequence'
-export * from './hotkey'

package/src/index.ts

@@ -1,6 +0,0 @@
-// Re-export everything from the core package
-export * from '@tanstack/hotkeys'
-
-// Lit-specific exports
-export * from './decorators'
-export * from './controllers'