@quantabit/hotkey-sdk 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 QuantaBit Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,30 @@
+# @quantabit/hotkey-sdk
+
+> Keyboard shortcut and hotkey management
+
+## Features
+- **useHotkey** — Single shortcut: `useHotkey('mod+s', save)`
+- **useHotkeys** — Batch: `useHotkeys([{combo:'mod+k',handler:search}])`
+- **HotkeyDisplay** — Render `⌘S` / `Ctrl+S` (auto Mac/Win)
+- **formatHotkey** — Format combo string for display
+- Auto-ignores input/textarea focus
+
+```jsx
+import { useHotkey, HotkeyDisplay } from '@quantabit/hotkey-sdk';
+useHotkey('mod+s', () => save(), { preventDefault: true });
+<HotkeyDisplay combo="mod+k" /> // renders ⌘K on Mac
+```
+
+## License
+MIT
+
+
+
+---
+
+## 🌐 Brand & Links
+- Official Mainnet: [QuantaBit Chain](https://qbitchain.io/)
+- Developer Platform: [Developer Platform](https://developer.quantabit.io/)
+- Open Platform: [Open Platform](https://open.quantabit.io/)
+- Payment Platform: [Pay Platform](https://pay.qbitwallet.io/)
+- Feedback: [Feedback](https://xwin.live/qbit)

package/dist/index.cjs

@@ -0,0 +1,142 @@
+'use strict';
+
+var React = require('react');
+
+/**
+ * 快捷键解析/格式化工具
+ */
+const isMac = typeof navigator !== 'undefined' && /Mac|iPhone|iPad/.test(navigator.platform);
+const MOD_MAP = {
+  ctrl: isMac ? '⌃' : 'Ctrl',
+  alt: isMac ? '⌥' : 'Alt',
+  shift: isMac ? '⇧' : 'Shift',
+  meta: isMac ? '⌘' : 'Win'};
+const KEY_MAP = {
+  arrowup: '↑',
+  arrowdown: '↓',
+  arrowleft: '←',
+  arrowright: '→',
+  escape: 'Esc',
+  enter: '↩',
+  backspace: '⌫',
+  delete: '⌦',
+  tab: '⇥',
+  space: 'Space'
+};
+function parseHotkey(combo) {
+  const parts = combo.toLowerCase().split('+').map(s => s.trim());
+  const mods = {
+    ctrl: false,
+    alt: false,
+    shift: false,
+    meta: false
+  };
+  let key = '';
+  parts.forEach(p => {
+    if (p === 'ctrl' || p === 'control') mods.ctrl = true;else if (p === 'alt' || p === 'option') mods.alt = true;else if (p === 'shift') mods.shift = true;else if (p === 'meta' || p === 'cmd' || p === 'command' || p === 'win') mods.meta = true;else if (p === 'mod') {
+      if (isMac) mods.meta = true;else mods.ctrl = true;
+    } else key = p;
+  });
+  return {
+    ...mods,
+    key
+  };
+}
+function formatHotkey(combo) {
+  const {
+    ctrl,
+    alt,
+    shift,
+    meta,
+    key
+  } = parseHotkey(combo);
+  const parts = [];
+  if (ctrl) parts.push(MOD_MAP.ctrl);
+  if (alt) parts.push(MOD_MAP.alt);
+  if (shift) parts.push(MOD_MAP.shift);
+  if (meta) parts.push(MOD_MAP.meta);
+  const display = KEY_MAP[key] || key.toUpperCase();
+  parts.push(display);
+  return isMac ? parts.join('') : parts.join(' + ');
+}
+function isInputElement(el) {
+  if (!el) return false;
+  const tag = el.tagName;
+  return tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT' || el.isContentEditable;
+}
+
+function useHotkey(combo, callback, opts = {}) {
+  const {
+    enabled = true,
+    preventDefault = true,
+    ignoreInput = true
+  } = opts;
+  const parsed = parseHotkey(combo);
+  const handler = React.useCallback(e => {
+    if (!enabled) return;
+    if (ignoreInput && isInputElement(e.target)) return;
+    const match = e.key.toLowerCase() === parsed.key && e.ctrlKey === parsed.ctrl && e.altKey === parsed.alt && e.shiftKey === parsed.shift && e.metaKey === parsed.meta;
+    if (match) {
+      if (preventDefault) e.preventDefault();
+      callback(e);
+    }
+  }, [combo, callback, enabled, preventDefault, ignoreInput]);
+  React.useEffect(() => {
+    document.addEventListener('keydown', handler);
+    return () => document.removeEventListener('keydown', handler);
+  }, [handler]);
+}
+
+function useHotkeys(bindings = [], opts = {}) {
+  bindings.forEach(({
+    combo,
+    handler
+  }) => useHotkey(combo, handler, opts));
+}
+
+function HotkeyDisplay({
+  combo,
+  size = 'small',
+  className = ''
+}) {
+  const display = formatHotkey(combo);
+  const sz = {
+    small: {
+      font: 11,
+      pad: '2px 5px'
+    },
+    medium: {
+      font: 12,
+      pad: '3px 7px'
+    },
+    large: {
+      font: 13,
+      pad: '4px 8px'
+    }
+  };
+  const s = sz[size] || sz.small;
+  return /*#__PURE__*/React.createElement("kbd", {
+    className: `qhk-key ${className}`,
+    style: {
+      display: 'inline-flex',
+      gap: 2,
+      fontSize: s.font,
+      fontFamily: 'SF Mono,Menlo,monospace',
+      padding: s.pad,
+      borderRadius: 4,
+      background: 'rgba(128,128,128,0.08)',
+      color: '#71717a',
+      border: '1px solid rgba(128,128,128,0.12)',
+      lineHeight: 1.2,
+      fontWeight: 500
+    }
+  }, display);
+}
+
+exports.HotkeyDisplay = HotkeyDisplay;
+exports.formatHotkey = formatHotkey;
+exports.isInputElement = isInputElement;
+exports.parseHotkey = parseHotkey;
+exports.useHotkey = useHotkey;
+exports.useHotkeys = useHotkeys;
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","sources":["../src/utils/hotkey.js","../src/hooks/useHotkey.js","../src/hooks/useHotkeys.js","../src/components/HotkeyDisplay.jsx"],"sourcesContent":["/**\n * 快捷键解析/格式化工具\n */\nconst isMac=typeof navigator!=='undefined'&&/Mac|iPhone|iPad/.test(navigator.platform);\nconst MOD_MAP={ctrl:isMac?'⌃':'Ctrl',alt:isMac?'⌥':'Alt',shift:isMac?'⇧':'Shift',meta:isMac?'⌘':'Win',mod:isMac?'⌘':'Ctrl'};\nconst KEY_MAP={arrowup:'↑',arrowdown:'↓',arrowleft:'←',arrowright:'→',escape:'Esc',enter:'↩',backspace:'⌫',delete:'⌦',tab:'⇥',space:'Space'};\n\nexport function parseHotkey(combo){\n  const parts=combo.toLowerCase().split('+').map(s=>s.trim());\n  const mods={ctrl:false,alt:false,shift:false,meta:false};\n  let key='';\n  parts.forEach(p=>{if(p==='ctrl'||p==='control')mods.ctrl=true;\n    else if(p==='alt'||p==='option')mods.alt=true;\n    else if(p==='shift')mods.shift=true;\n    else if(p==='meta'||p==='cmd'||p==='command'||p==='win')mods.meta=true;\n    else if(p==='mod'){if(isMac)mods.meta=true;else mods.ctrl=true;}\n    else key=p;});\n  return{...mods,key};\n}\n\nexport function formatHotkey(combo){\n  const{ctrl,alt,shift,meta,key}=parseHotkey(combo);\n  const parts=[];\n  if(ctrl)parts.push(MOD_MAP.ctrl);if(alt)parts.push(MOD_MAP.alt);\n  if(shift)parts.push(MOD_MAP.shift);if(meta)parts.push(MOD_MAP.meta);\n  const display=KEY_MAP[key]||key.toUpperCase();parts.push(display);\n  return isMac?parts.join(''):parts.join(' + ');\n}\n\nexport function isInputElement(el){\n  if(!el)return false;\n  const tag=el.tagName;\n  return tag==='INPUT'||tag==='TEXTAREA'||tag==='SELECT'||el.isContentEditable;\n}\n","import{useEffect,useCallback}from'react';\nimport{parseHotkey,isInputElement}from'../utils/hotkey';\nexport function useHotkey(combo,callback,opts={}){\n  const{enabled=true,preventDefault=true,ignoreInput=true}=opts;\n  const parsed=parseHotkey(combo);\n  const handler=useCallback(e=>{if(!enabled)return;\n    if(ignoreInput&&isInputElement(e.target))return;\n    const match=e.key.toLowerCase()===parsed.key&&e.ctrlKey===parsed.ctrl&&e.altKey===parsed.alt&&e.shiftKey===parsed.shift&&e.metaKey===parsed.meta;\n    if(match){if(preventDefault)e.preventDefault();callback(e);}\n  },[combo,callback,enabled,preventDefault,ignoreInput]);\n  useEffect(()=>{document.addEventListener('keydown',handler);return()=>document.removeEventListener('keydown',handler);},[handler]);\n}\n","import{useHotkey}from'./useHotkey';\nexport function useHotkeys(bindings=[],opts={}){\n  bindings.forEach(({combo,handler})=>useHotkey(combo,handler,opts));\n}\n","import React from'react';\nimport{formatHotkey}from'../utils/hotkey';\nexport function HotkeyDisplay({combo,size='small',className=''}){\n  const display=formatHotkey(combo);\n  const sz={small:{font:11,pad:'2px 5px'},medium:{font:12,pad:'3px 7px'},large:{font:13,pad:'4px 8px'}};\n  const s=sz[size]||sz.small;\n  return(<kbd className={`qhk-key ${className}`}\n    style={{display:'inline-flex',gap:2,fontSize:s.font,fontFamily:'SF Mono,Menlo,monospace',padding:s.pad,\n      borderRadius:4,background:'rgba(128,128,128,0.08)',color:'#71717a',border:'1px solid rgba(128,128,128,0.12)',\n      lineHeight:1.2,fontWeight:500}}>{display}</kbd>);\n}\n"],"names":["isMac","navigator","test","platform","MOD_MAP","ctrl","alt","shift","meta","KEY_MAP","arrowup","arrowdown","arrowleft","arrowright","escape","enter","backspace","delete","tab","space","parseHotkey","combo","parts","toLowerCase","split","map","s","trim","mods","key","forEach","p","formatHotkey","push","display","toUpperCase","join","isInputElement","el","tag","tagName","isContentEditable","useHotkey","callback","opts","enabled","preventDefault","ignoreInput","parsed","handler","useCallback","e","target","match","ctrlKey","altKey","shiftKey","metaKey","useEffect","document","addEventListener","removeEventListener","useHotkeys","bindings","HotkeyDisplay","size","className","sz","small","font","pad","medium","large","React","createElement","style","gap","fontSize","fontFamily","padding","borderRadius","background","color","border","lineHeight","fontWeight"],"mappings":"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"}

package/dist/index.esm.js

@@ -0,0 +1,135 @@
+import React, { useCallback, useEffect } from 'react';
+
+/**
+ * 快捷键解析/格式化工具
+ */
+const isMac = typeof navigator !== 'undefined' && /Mac|iPhone|iPad/.test(navigator.platform);
+const MOD_MAP = {
+  ctrl: isMac ? '⌃' : 'Ctrl',
+  alt: isMac ? '⌥' : 'Alt',
+  shift: isMac ? '⇧' : 'Shift',
+  meta: isMac ? '⌘' : 'Win'};
+const KEY_MAP = {
+  arrowup: '↑',
+  arrowdown: '↓',
+  arrowleft: '←',
+  arrowright: '→',
+  escape: 'Esc',
+  enter: '↩',
+  backspace: '⌫',
+  delete: '⌦',
+  tab: '⇥',
+  space: 'Space'
+};
+function parseHotkey(combo) {
+  const parts = combo.toLowerCase().split('+').map(s => s.trim());
+  const mods = {
+    ctrl: false,
+    alt: false,
+    shift: false,
+    meta: false
+  };
+  let key = '';
+  parts.forEach(p => {
+    if (p === 'ctrl' || p === 'control') mods.ctrl = true;else if (p === 'alt' || p === 'option') mods.alt = true;else if (p === 'shift') mods.shift = true;else if (p === 'meta' || p === 'cmd' || p === 'command' || p === 'win') mods.meta = true;else if (p === 'mod') {
+      if (isMac) mods.meta = true;else mods.ctrl = true;
+    } else key = p;
+  });
+  return {
+    ...mods,
+    key
+  };
+}
+function formatHotkey(combo) {
+  const {
+    ctrl,
+    alt,
+    shift,
+    meta,
+    key
+  } = parseHotkey(combo);
+  const parts = [];
+  if (ctrl) parts.push(MOD_MAP.ctrl);
+  if (alt) parts.push(MOD_MAP.alt);
+  if (shift) parts.push(MOD_MAP.shift);
+  if (meta) parts.push(MOD_MAP.meta);
+  const display = KEY_MAP[key] || key.toUpperCase();
+  parts.push(display);
+  return isMac ? parts.join('') : parts.join(' + ');
+}
+function isInputElement(el) {
+  if (!el) return false;
+  const tag = el.tagName;
+  return tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT' || el.isContentEditable;
+}
+
+function useHotkey(combo, callback, opts = {}) {
+  const {
+    enabled = true,
+    preventDefault = true,
+    ignoreInput = true
+  } = opts;
+  const parsed = parseHotkey(combo);
+  const handler = useCallback(e => {
+    if (!enabled) return;
+    if (ignoreInput && isInputElement(e.target)) return;
+    const match = e.key.toLowerCase() === parsed.key && e.ctrlKey === parsed.ctrl && e.altKey === parsed.alt && e.shiftKey === parsed.shift && e.metaKey === parsed.meta;
+    if (match) {
+      if (preventDefault) e.preventDefault();
+      callback(e);
+    }
+  }, [combo, callback, enabled, preventDefault, ignoreInput]);
+  useEffect(() => {
+    document.addEventListener('keydown', handler);
+    return () => document.removeEventListener('keydown', handler);
+  }, [handler]);
+}
+
+function useHotkeys(bindings = [], opts = {}) {
+  bindings.forEach(({
+    combo,
+    handler
+  }) => useHotkey(combo, handler, opts));
+}
+
+function HotkeyDisplay({
+  combo,
+  size = 'small',
+  className = ''
+}) {
+  const display = formatHotkey(combo);
+  const sz = {
+    small: {
+      font: 11,
+      pad: '2px 5px'
+    },
+    medium: {
+      font: 12,
+      pad: '3px 7px'
+    },
+    large: {
+      font: 13,
+      pad: '4px 8px'
+    }
+  };
+  const s = sz[size] || sz.small;
+  return /*#__PURE__*/React.createElement("kbd", {
+    className: `qhk-key ${className}`,
+    style: {
+      display: 'inline-flex',
+      gap: 2,
+      fontSize: s.font,
+      fontFamily: 'SF Mono,Menlo,monospace',
+      padding: s.pad,
+      borderRadius: 4,
+      background: 'rgba(128,128,128,0.08)',
+      color: '#71717a',
+      border: '1px solid rgba(128,128,128,0.12)',
+      lineHeight: 1.2,
+      fontWeight: 500
+    }
+  }, display);
+}
+
+export { HotkeyDisplay, formatHotkey, isInputElement, parseHotkey, useHotkey, useHotkeys };
+//# sourceMappingURL=index.esm.js.map

package/dist/index.esm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.esm.js","sources":["../src/utils/hotkey.js","../src/hooks/useHotkey.js","../src/hooks/useHotkeys.js","../src/components/HotkeyDisplay.jsx"],"sourcesContent":["/**\n * 快捷键解析/格式化工具\n */\nconst isMac=typeof navigator!=='undefined'&&/Mac|iPhone|iPad/.test(navigator.platform);\nconst MOD_MAP={ctrl:isMac?'⌃':'Ctrl',alt:isMac?'⌥':'Alt',shift:isMac?'⇧':'Shift',meta:isMac?'⌘':'Win',mod:isMac?'⌘':'Ctrl'};\nconst KEY_MAP={arrowup:'↑',arrowdown:'↓',arrowleft:'←',arrowright:'→',escape:'Esc',enter:'↩',backspace:'⌫',delete:'⌦',tab:'⇥',space:'Space'};\n\nexport function parseHotkey(combo){\n  const parts=combo.toLowerCase().split('+').map(s=>s.trim());\n  const mods={ctrl:false,alt:false,shift:false,meta:false};\n  let key='';\n  parts.forEach(p=>{if(p==='ctrl'||p==='control')mods.ctrl=true;\n    else if(p==='alt'||p==='option')mods.alt=true;\n    else if(p==='shift')mods.shift=true;\n    else if(p==='meta'||p==='cmd'||p==='command'||p==='win')mods.meta=true;\n    else if(p==='mod'){if(isMac)mods.meta=true;else mods.ctrl=true;}\n    else key=p;});\n  return{...mods,key};\n}\n\nexport function formatHotkey(combo){\n  const{ctrl,alt,shift,meta,key}=parseHotkey(combo);\n  const parts=[];\n  if(ctrl)parts.push(MOD_MAP.ctrl);if(alt)parts.push(MOD_MAP.alt);\n  if(shift)parts.push(MOD_MAP.shift);if(meta)parts.push(MOD_MAP.meta);\n  const display=KEY_MAP[key]||key.toUpperCase();parts.push(display);\n  return isMac?parts.join(''):parts.join(' + ');\n}\n\nexport function isInputElement(el){\n  if(!el)return false;\n  const tag=el.tagName;\n  return tag==='INPUT'||tag==='TEXTAREA'||tag==='SELECT'||el.isContentEditable;\n}\n","import{useEffect,useCallback}from'react';\nimport{parseHotkey,isInputElement}from'../utils/hotkey';\nexport function useHotkey(combo,callback,opts={}){\n  const{enabled=true,preventDefault=true,ignoreInput=true}=opts;\n  const parsed=parseHotkey(combo);\n  const handler=useCallback(e=>{if(!enabled)return;\n    if(ignoreInput&&isInputElement(e.target))return;\n    const match=e.key.toLowerCase()===parsed.key&&e.ctrlKey===parsed.ctrl&&e.altKey===parsed.alt&&e.shiftKey===parsed.shift&&e.metaKey===parsed.meta;\n    if(match){if(preventDefault)e.preventDefault();callback(e);}\n  },[combo,callback,enabled,preventDefault,ignoreInput]);\n  useEffect(()=>{document.addEventListener('keydown',handler);return()=>document.removeEventListener('keydown',handler);},[handler]);\n}\n","import{useHotkey}from'./useHotkey';\nexport function useHotkeys(bindings=[],opts={}){\n  bindings.forEach(({combo,handler})=>useHotkey(combo,handler,opts));\n}\n","import React from'react';\nimport{formatHotkey}from'../utils/hotkey';\nexport function HotkeyDisplay({combo,size='small',className=''}){\n  const display=formatHotkey(combo);\n  const sz={small:{font:11,pad:'2px 5px'},medium:{font:12,pad:'3px 7px'},large:{font:13,pad:'4px 8px'}};\n  const s=sz[size]||sz.small;\n  return(<kbd className={`qhk-key ${className}`}\n    style={{display:'inline-flex',gap:2,fontSize:s.font,fontFamily:'SF Mono,Menlo,monospace',padding:s.pad,\n      borderRadius:4,background:'rgba(128,128,128,0.08)',color:'#71717a',border:'1px solid rgba(128,128,128,0.12)',\n      lineHeight:1.2,fontWeight:500}}>{display}</kbd>);\n}\n"],"names":["isMac","navigator","test","platform","MOD_MAP","ctrl","alt","shift","meta","KEY_MAP","arrowup","arrowdown","arrowleft","arrowright","escape","enter","backspace","delete","tab","space","parseHotkey","combo","parts","toLowerCase","split","map","s","trim","mods","key","forEach","p","formatHotkey","push","display","toUpperCase","join","isInputElement","el","tag","tagName","isContentEditable","useHotkey","callback","opts","enabled","preventDefault","ignoreInput","parsed","handler","useCallback","e","target","match","ctrlKey","altKey","shiftKey","metaKey","useEffect","document","addEventListener","removeEventListener","useHotkeys","bindings","HotkeyDisplay","size","className","sz","small","font","pad","medium","large","React","createElement","style","gap","fontSize","fontFamily","padding","borderRadius","background","color","border","lineHeight","fontWeight"],"mappings":"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"}

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@quantabit/hotkey-sdk",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "Keyboard shortcut and hotkey management",
+  "main": "dist/index.cjs",
+  "module": "dist/index.esm.js",
+  "types": "types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "import": "./dist/index.esm.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "types",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "rollup -c",
+    "dev": "rollup -c -w",
+    "test": "jest --passWithNoTests",
+    "prepublishOnly": "npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/quantabit-chain/qbit-sdk.git",
+    "directory": "packages/hotkey-sdk"
+  },
+  "keywords": [
+    "hotkey",
+    "keyboard",
+    "shortcut",
+    "react"
+  ],
+  "author": "QuantaBit Team",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "peerDependencies": {
+    "react": ">=17.0.0",
+    "react-dom": ">=17.0.0"
+  },
+  "dependencies": {
+    "@quantabit/sdk-config": "^1.0.6"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://github.com/quantabit-chain/qbit-sdk/tree/main/packages/hotkey-sdk",
+  "bugs": {
+    "url": "https://github.com/quantabit-chain/qbit-sdk/issues"
+  },
+  "sideEffects": false,
+  "qbit": {
+    "privacy": {
+      "level": "functional",
+      "dataCollection": "Feature-related data for personalization. Requires user consent.",
+      "gdprCompliant": true,
+      "ccpaCompliant": true
+    }
+  }
+}

package/types/index.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @quantabit/hotkey-sdk TypeScript Type Definitions
+ * 
+ * Auto-generated type stubs. Enhance with specific types as the SDK matures.
+ */
+
+import { FC, ReactNode } from 'react';
+
+// ============ Components ============
+
+export interface HotkeyDisplayProps {
+  className?: string;
+  style?: React.CSSProperties;
+  [key: string]: any;
+}
+
+export declare const HotkeyDisplay: FC<HotkeyDisplayProps>;
+
+// ============ Hooks ============
+
+export interface UseHotkeyReturn {
+  data: any;
+  loading: boolean;
+  error: string | null;
+  [key: string]: any;
+}
+
+export declare function useHotkey(...args: any[]): UseHotkeyReturn;
+
+export interface UseHotkeysReturn {
+  data: any;
+  loading: boolean;
+  error: string | null;
+  [key: string]: any;
+}
+
+export declare function useHotkeys(...args: any[]): UseHotkeysReturn;
+
+// ============ Functions & Utilities ============
+
+export declare function parseHotkey(...args: any[]): any;
+export declare function formatHotkey(...args: any[]): any;
+export declare function isInputElement(...args: any[]): any;
+