tanstack-hotkeys

TanStack Hotkeys

TanStack Hotkeys に関わる作業、特に React のキーボードショートカット、コマンドパレット、ショートカット設定 UI、スコープ付きショートカット、Vim スタイルのシーケンス、キー押下状態を扱う際に、このスキルを使用してください。

ワークフロー

1. コードを変更する前に、ローカルのショートカット関連の構成を確認します。
   • @tanstack/react-hotkeys（0.12.x）、@tanstack/hotkeys（0.10.x）、devtools、React、フレームワークアダプター、テストユーティリティのパッケージバージョンを確認します。core 0.8 以前向けのコードは、0.9 より前のレコーダーや型の動作に依存している場合があります。
   • ショートカットの形式（単発のホットキー、動的なショートカットリスト、要素スコープのショートカット、グローバルなデフォルト、シーケンス、ユーザーが記録したバインド、ショートカットパレット）を確認します。
   • 操作上の制約（フォーカスされた入力欄、モーダル、コマンドパレット、ブラウザーのネイティブショートカット、アプリのモード、無効状態、アクセシビリティ）を確認します。
2. 動作やバージョンが重要な場合は、最新のドキュメントとパッケージの情報を確認します。source-map.md から始めてください。
3. インストール、ESM／ランタイム要件、論理バインドと物理バインド、HotkeysProvider、useHotkey、useHotkeys、デフォルト、オプション、スコープ対象、登録については、setup-core.md を参照してください。
4. useHotkeySequence、useHotkeySequences、useHotkeyRecorder、useHotkeySequenceRecorder、レコーダーの検証／競合、キー押下状態を扱うフック、useHotkeyHint、動的なユーザーショートカットについては、sequences-recording-state.md を参照してください。
5. 表示形式、ショートカットパレット、devtools、SSR に関する注意事項、アクセシビリティ、テストについては、display-production.md を参照してください。

実装上の判断

• クロスプラットフォームのアプリショートカットには Mod を優先してください。macOS では Command、Windows／Linux では Control に対応します。
• このライブラリはアルファ版（0.x）として扱ってください。特にレコーダーのオプション、バインドの型、シーケンスの処理など、境界的な動作に依存する前に最新のドキュメントを確認してください。パッケージは core 0.10 以降、ESM のみです。
• 覚えやすさを重視するショートカットには論理バインド（Mod+S）、位置ベースの操作には物理バインド（Mod+[KeyS]、{ code: 'KeyS', mod: true }）を使用してください。バインドには key または code のどちらか一方を指定し、両方は指定しません。
• 固定ショートカットには useHotkey、動的または可変長のリストには useHotkeys を使用してください。メニューデータを登録するためにループ内でフックを呼び出さないでください。
• パネル、エディター、モーダルのホットキーは、target refs を使ってスコープを設定してください。通常は tabIndex を指定するなどして、対象がフォーカスを受け取れるようにしてください。
• preventDefault と stopPropagation は意図を持って設定してください。デフォルトは true です。これは Mod+S のようなアプリショートカットには適切ですが、ブラウザーのネイティブ動作を維持する場合には適切ではありません。
• 通常の文字入力を妨げないようにしてください。テキスト入力欄で単一キーのショートカットを強制的に実行する前に、スマートな ignoreInputs のデフォルト動作を把握してください。
• モードや状態による制御には enabled を使用してください。無効にしたホットキーも登録されたままになり、devtools には表示されますが、実行は抑制されます。
• ヘルプ画面、コマンドパレット、devtools に表示するショートカットには、meta の名前、説明、group を追加してください。
• レコーダーフックは、ユーザーがショートカットをカスタマイズする設定 UI でのみ使用してください。レコーダーのデフォルトは recordBy: 'code'（Mod+[KeyS] のような物理キー文字列）です。クリア時に呼び出されるのは onClear のみです。手作りの重複チェックではなく、validate、detectConflicts、onReject を使用してください。表示ラベルではなく、正規化された Hotkey または HotkeySequence の値を永続化してください。

検証

リポジトリに既存のチェックがあれば、そちらを優先してください。TanStack Hotkeys に意味のある変更を加えた場合は、関連する項目を以下から選んで実施してください。

• ホットキー文字列、Hotkey／HotkeySequence の値、RawHotkey／ParsedHotkey のユニオン、ターゲット参照、アダプターのインポートを型チェックします。
• コールバックの呼び出し、enabled、ignoreInputs、preventDefault、stopPropagation、ターゲットのフォーカス、アンマウント時のクリーンアップについて、key と code の両方を含む合成イベントを使ったユニットテストまたはコンポーネントテストを実施します。
• クロスプラットフォームの表示ラベル、フォーカス中の入力欄の動作、モーダルのスコープ、コマンドパレットのショートカット、シーケンスのタイムアウトについて、ブラウザーでスモークテストを実施します。
• シーケンスのタイムアウト、レコーダーのアイドル時の確定、ショートカットのキャプチャーを囲む UI のデバウンスについて、フェイクタイマーを使ったテストを実施します。
• 重複した登録、無効な登録、押下中のキー、ターゲットのスコープ、競合時の動作を DevTools で確認します。