@tanstack/lit-hotkeys 0.0.1

package/src/controllers/hotkey.ts

@@ -0,0 +1,96 @@
+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

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

package/src/controllers/key-hold.ts

@@ -0,0 +1,88 @@
+import { getKeyStateTracker } from '@tanstack/hotkeys'
+import type { ReactiveController, ReactiveControllerHost } from 'lit'
+import type { HeldKey, 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: HeldKey,
+  ) {
+    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

@@ -0,0 +1,68 @@
+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

@@ -0,0 +1,70 @@
+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

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

package/src/index.ts

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