@tanstack/lit-hotkeys 0.0.1

package/dist/index.cjs

@@ -0,0 +1,27 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_hotkey_sequence = require('./controllers/hotkey-sequence.cjs');
+const require_hotkey_sequence$1 = require('./decorators/hotkey-sequence.cjs');
+const require_hotkey = require('./controllers/hotkey.cjs');
+const require_hotkey$1 = require('./decorators/hotkey.cjs');
+const require_held_key_codes = require('./controllers/held-key-codes.cjs');
+const require_held_keys = require('./controllers/held-keys.cjs');
+const require_hotkey_recorder = require('./controllers/hotkey-recorder.cjs');
+const require_hotkey_sequence_recorder = require('./controllers/hotkey-sequence-recorder.cjs');
+const require_key_hold = require('./controllers/key-hold.cjs');
+
+exports.HeldKeyCodesController = require_held_key_codes.HeldKeyCodesController;
+exports.HeldKeysController = require_held_keys.HeldKeysController;
+exports.HotkeyController = require_hotkey.HotkeyController;
+exports.HotkeyRecorderController = require_hotkey_recorder.HotkeyRecorderController;
+exports.HotkeySequenceController = require_hotkey_sequence.HotkeySequenceController;
+exports.HotkeySequenceRecorderController = require_hotkey_sequence_recorder.HotkeySequenceRecorderController;
+exports.KeyHoldController = require_key_hold.KeyHoldController;
+exports.hotkey = require_hotkey$1.hotkey;
+exports.hotkeySequence = require_hotkey_sequence$1.hotkeySequence;
+var _tanstack_hotkeys = require("@tanstack/hotkeys");
+Object.keys(_tanstack_hotkeys).forEach(function (k) {
+  if (k !== 'default' && !Object.prototype.hasOwnProperty.call(exports, k)) Object.defineProperty(exports, k, {
+    enumerable: true,
+    get: function () { return _tanstack_hotkeys[k]; }
+  });
+});

package/dist/index.d.cts

@@ -0,0 +1,11 @@
+import { hotkeySequence } from "./decorators/hotkey-sequence.cjs";
+import { hotkey } from "./decorators/hotkey.cjs";
+import { HeldKeyCodesController } from "./controllers/held-key-codes.cjs";
+import { HeldKeysController } from "./controllers/held-keys.cjs";
+import { HotkeyController } from "./controllers/hotkey.cjs";
+import { HotkeyRecorderController } from "./controllers/hotkey-recorder.cjs";
+import { HotkeySequenceController } from "./controllers/hotkey-sequence.cjs";
+import { HotkeySequenceRecorderController } from "./controllers/hotkey-sequence-recorder.cjs";
+import { KeyHoldController } from "./controllers/key-hold.cjs";
+export * from "@tanstack/hotkeys";
+export { HeldKeyCodesController, HeldKeysController, HotkeyController, HotkeyRecorderController, HotkeySequenceController, HotkeySequenceRecorderController, KeyHoldController, hotkey, hotkeySequence };

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+import { hotkeySequence } from "./decorators/hotkey-sequence.js";
+import { hotkey } from "./decorators/hotkey.js";
+import { HeldKeyCodesController } from "./controllers/held-key-codes.js";
+import { HeldKeysController } from "./controllers/held-keys.js";
+import { HotkeyController } from "./controllers/hotkey.js";
+import { HotkeyRecorderController } from "./controllers/hotkey-recorder.js";
+import { HotkeySequenceController } from "./controllers/hotkey-sequence.js";
+import { HotkeySequenceRecorderController } from "./controllers/hotkey-sequence-recorder.js";
+import { KeyHoldController } from "./controllers/key-hold.js";
+export * from "@tanstack/hotkeys";
+export { HeldKeyCodesController, HeldKeysController, HotkeyController, HotkeyRecorderController, HotkeySequenceController, HotkeySequenceRecorderController, KeyHoldController, hotkey, hotkeySequence };

package/dist/index.js

@@ -0,0 +1,13 @@
+import { HotkeySequenceController } from "./controllers/hotkey-sequence.js";
+import { hotkeySequence } from "./decorators/hotkey-sequence.js";
+import { HotkeyController } from "./controllers/hotkey.js";
+import { hotkey } from "./decorators/hotkey.js";
+import { HeldKeyCodesController } from "./controllers/held-key-codes.js";
+import { HeldKeysController } from "./controllers/held-keys.js";
+import { HotkeyRecorderController } from "./controllers/hotkey-recorder.js";
+import { HotkeySequenceRecorderController } from "./controllers/hotkey-sequence-recorder.js";
+import { KeyHoldController } from "./controllers/key-hold.js";
+
+export * from "@tanstack/hotkeys"
+
+export { HeldKeyCodesController, HeldKeysController, HotkeyController, HotkeyRecorderController, HotkeySequenceController, HotkeySequenceRecorderController, KeyHoldController, hotkey, hotkeySequence };

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@tanstack/lit-hotkeys",
+  "version": "0.0.1",
+  "description": "Lit adapter for TanStack Hotkeys",
+  "author": "Tanner Linsley",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TanStack/hotkeys.git",
+    "directory": "packages/lit-hotkeys"
+  },
+  "homepage": "https://tanstack.com/hotkeys",
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/tannerlinsley"
+  },
+  "keywords": [
+    "lit",
+    "tanstack",
+    "keys"
+  ],
+  "scripts": {
+    "clean": "premove ./build ./dist",
+    "lint": "eslint ./src",
+    "lint:fix": "eslint ./src --fix",
+    "test:eslint": "eslint ./src",
+    "test:lib": "vitest --passWithNoTests",
+    "test:lib:dev": "pnpm test:lib --watch",
+    "test:types": "tsc",
+    "build": "tsdown"
+  },
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.cts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "@tanstack/hotkeys": "workspace:*"
+  },
+  "devDependencies": {
+    "lit": "^3.3.2"
+  },
+  "peerDependencies": {
+    "lit": ">=3.0.0"
+  }
+}

package/src/constants.ts

@@ -0,0 +1,23 @@
+import type { HotkeyOptions, SequenceOptions } from '@tanstack/hotkeys'
+
+export const HOTKEY_DEFAULT_OPTIONS: HotkeyOptions = {
+  enabled: true,
+  preventDefault: true,
+  stopPropagation: true,
+  eventType: 'keydown',
+  requireReset: false,
+  ignoreInputs: undefined, // smart default: false for Mod+S, true for single keys
+  platform: undefined, // auto-detected
+  conflictBehavior: 'warn',
+}
+
+export const HOTKEY_SEQUENCE_DEFAULT_OPTIONS: SequenceOptions = {
+  enabled: true,
+  timeout: 1000,
+  preventDefault: true,
+  stopPropagation: true,
+  eventType: 'keydown',
+  ignoreInputs: undefined, // smart default: false for Mod+S, true for single keys
+  platform: undefined, // auto-detected
+  conflictBehavior: 'warn',
+}

package/src/controllers/held-key-codes.ts

@@ -0,0 +1,67 @@
+import { getKeyStateTracker } from '@tanstack/hotkeys'
+import type { KeyStateTracker } from '@tanstack/hotkeys'
+import type { ReactiveController, ReactiveControllerHost } from 'lit'
+
+/**
+ * A Lit ReactiveController that tracks all currently held key names to their physical `event.code` values.
+ *
+ * Subscribes to the global KeyStateTracker and triggers host updates
+ * whenever keys are pressed or released.
+ *
+ * @example
+ * ```ts
+ * class KeyDisplay extends LitElement {
+ *   private heldKeyCodes = new HeldKeyCodesController(this)
+ *
+ *   render() {
+ *     const heldCodes = Object.entries(this.heldKeyCodes.value).map(([key, code]) => `${key}: ${code}`).join(' + ')
+ *     return html`
+ *       <div>
+ *         Currently pressed: ${heldCodes || 'None'}
+ *       </div>
+ *     `
+ *   }
+ * }
+ * ```
+ */
+export class HeldKeyCodesController implements ReactiveController {
+  /** The unsubscribe function to unsubscribe from the tracker store. */
+  private _unsubscribe: (() => void) | undefined
+  /** The currently held key names to their physical `event.code` values. */
+  private _value: Record<string, string> = {}
+
+  /** Map of currently held key names to their physical `event.code` values. */
+  public get value(): Record<string, string> {
+    return this._value
+  }
+
+  /**
+   * @param _host - The Lit component that owns this controller.
+   */
+  constructor(private _host: ReactiveControllerHost) {
+    this._host.addController(this)
+  }
+
+  /** Subscribes to the tracker store and updates the internal state when changes occur. */
+  public hostConnected(): void {
+    const tracker: KeyStateTracker = getKeyStateTracker()
+    this._value = tracker.store.state.heldCodes
+    this._host.requestUpdate()
+
+    const subscription = tracker.store.subscribe(() => {
+      const { heldCodes } = tracker.store.state
+
+      this._value = heldCodes
+      this._host.requestUpdate()
+    })
+
+    this._unsubscribe = () => subscription.unsubscribe()
+  }
+
+  /** Unsubscribes from the tracker store and stops tracking the held key codes. */
+  public hostDisconnected(): void {
+    this._unsubscribe?.()
+    this._unsubscribe = undefined
+    this._value = {}
+  }
+}

package/src/controllers/held-keys.ts

@@ -0,0 +1,64 @@
+import { getKeyStateTracker } from '@tanstack/hotkeys'
+import type { KeyStateTracker } from '@tanstack/hotkeys'
+import type { ReactiveController, ReactiveControllerHost } from 'lit'
+
+/**
+ * A Lit ReactiveController that tracks all currently held keyboard keys.
+ *
+ * Subscribes to the global KeyStateTracker and triggers host updates
+ * whenever keys are pressed or released.
+ *
+ * @example
+ * ```ts
+ * class KeyDisplay extends LitElement {
+ *   private heldKeys = new HeldKeysController(this)
+ *
+ *   render() {
+ *     return html`
+ *       <div>
+ *         Currently pressed: ${this.heldKeys.value.join(' + ') || 'None'}
+ *       </div>
+ *     `
+ *   }
+ * }
+ * ```
+ */
+export class HeldKeysController implements ReactiveController {
+  /** The unsubscribe function to unsubscribe from the tracker store. */
+  private _unsubscribe: (() => void) | undefined
+  /** The currently held key names. */
+  private _value: Array<string> = []
+
+  /** Array of currently held key names. */
+  public get value(): Array<string> {
+    return this._value
+  }
+
+  /**
+   * @param _host - The Lit component that owns this controller.
+   */
+  constructor(private _host: ReactiveControllerHost) {
+    this._host.addController(this)
+  }
+
+  /** Subscribes to the tracker store and updates the internal state when changes occur. */
+  public hostConnected(): void {
+    const tracker: KeyStateTracker = getKeyStateTracker()
+
+    const subscription = tracker.store.subscribe(() => {
+      const { heldKeys } = tracker.store.state
+
+      this._value = heldKeys
+      this._host.requestUpdate()
+    })
+
+    this._unsubscribe = () => subscription.unsubscribe()
+  }
+
+  /** Unsubscribes from the tracker store and stops tracking the held keys. */
+  public hostDisconnected(): void {
+    this._unsubscribe?.()
+    this._unsubscribe = undefined
+    this._value = []
+  }
+}

package/src/controllers/hotkey-recorder.ts

@@ -0,0 +1,120 @@
+import { HotkeyRecorder } from '@tanstack/hotkeys'
+import type { ReactiveController, ReactiveControllerHost } from 'lit'
+import type { Hotkey, HotkeyRecorderOptions } from '@tanstack/hotkeys'
+
+/**
+ * A Lit ReactiveController that records keyboard shortcuts.
+ *
+ * Wraps the framework-agnostic `HotkeyRecorder` class, managing all the
+ * complexity of capturing keyboard events, converting them to hotkey strings,
+ * and handling edge cases like Escape to cancel or Backspace/Delete to clear.
+ *
+ * @example
+ * ```ts
+ * class ShortcutSettings extends LitElement {
+ *   private recorder = new HotkeyRecorderController(this, {
+ *     onRecord: (hotkey) => {
+ *       this.shortcut = hotkey
+ *       this.requestUpdate()
+ *     },
+ *     onCancel: () => {
+ *       console.log('Recording cancelled')
+ *     },
+ *   })
+ *
+ *   private shortcut: Hotkey | null = null
+ *
+ *   render() {
+ *     return html`
+ *       <button @click=${() => this.recorder.startRecording()}>
+ *         ${this.recorder.isRecording ? 'Recording...' : 'Edit Shortcut'}
+ *       </button>
+ *       ${this.recorder.recordedHotkey
+ *         ? html`<div>Recording: ${this.recorder.recordedHotkey}</div>`
+ *         : nothing}
+ *     `
+ *   }
+ * }
+ * ```
+ */
+export class HotkeyRecorderController implements ReactiveController {
+  /** The recorder instance. */
+  private _recorder: HotkeyRecorder
+  /** The unsubscribe function to unsubscribe from the recorder store. */
+  private _unsubscribe: (() => void) | undefined
+  /** Whether recording is currently active. */
+  private _isRecording = false
+  /** The currently recorded hotkey (for live preview). */
+  private _recordedHotkey: Hotkey | null = null
+
+  /** Whether recording is currently active. */
+  public get isRecording(): boolean {
+    return this._isRecording
+  }
+
+  /** The currently recorded hotkey (for live preview). */
+  public get recordedHotkey(): Hotkey | null {
+    return this._recordedHotkey
+  }
+
+  /**
+   * @param _host - The Lit component that owns this controller.
+   * @param _options - Configuration options for the recorder.
+   */
+  constructor(
+    private _host: ReactiveControllerHost,
+    private _options: HotkeyRecorderOptions,
+  ) {
+    this._recorder = new HotkeyRecorder(_options)
+    this._host.addController(this)
+  }
+
+  /** Subscribes to the recorder store and updates the internal state when changes occur. */
+  public hostConnected(): void {
+    const subscription = this._recorder.store.subscribe(() => {
+      const { isRecording, recordedHotkey } = this._recorder.store.state
+
+      const hasChanged: boolean =
+        isRecording !== this._isRecording ||
+        recordedHotkey !== this._recordedHotkey
+
+      if (hasChanged) {
+        this._isRecording = isRecording
+        this._recordedHotkey = recordedHotkey
+        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._recordedHotkey = null
+  }
+
+  /** Updates the recorder options (e.g. callbacks). */
+  public setOptions(options: Partial<HotkeyRecorderOptions>): void {
+    this._options = { ...this._options, ...options }
+    this._recorder.setOptions(this._options)
+  }
+
+  /** Start recording a new hotkey. */
+  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()
+  }
+}

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

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

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