hotkeys

name	hotkeys
description	Reference for the kww-omni-hub hotkey/command system. Use when adding new features, keyboard shortcuts, or extending the command palette.

Hotkey & Command Palette System

This project uses a config-driven hotkey system. All keyboard shortcuts and command palette entries are defined in a single registry.

Architecture

src/config/hotkeys.ts        <- Central command registry (add entries here)
src/lib/hotkeys.ts           <- Shortcut matching & display formatting utils
src/components/ui/HotkeyProvider.tsx <- Context provider + useHotkeys() hook
src/components/ui/CommandPalette.tsx  <- Cmd+K modal UI
src/components/ui/Tooltip.tsx        <- Tooltip with shortcut badge display

Adding a New Command

1. Open src/config/hotkeys.ts
2. Add an entry to the commands array:

{
  id: 'my-new-command',
  labelKey: 'commands.myNewCommand',   // i18n key
  shortcut: ['meta', 'shift', 'n'],    // optional keyboard shortcut
  action: { type: 'navigate', to: '/my-page' },
  // OR: action: { type: 'function', fn: 'myFunctionName' },
  group: 'navigation',                 // groups shown in command palette
  icon: SomeLucideIcon,                // optional icon
}

3. Add the i18n translation key in src/i18n/locales/en/common.json under commands.*
4. If using action.type: 'function', register the handler via registerHandler('myFunctionName', () => { ... }) in the relevant component using useHotkeys().

Action Types

Type	Usage
navigate	Navigates to action.to via React Router
function	Calls a registered handler by action.fn name

Registering Function Handlers

import { useHotkeys } from '@/components/ui/HotkeyProvider'

function MyComponent() {
  const { registerHandler } = useHotkeys()

  useEffect(() => {
    return registerHandler('myFunctionName', () => {
      // do something
    })
  })
}

The registerHandler returns an unregister function for cleanup.

Built-in Handlers

These are auto-registered by HotkeyProvider:

• openCommandPalette — toggles the command palette
• toggleSidebar — toggles sidebar collapsed state

These are registered by their respective components:

• toggleTheme — registered by ThemeToggle

Shortcut Format

Shortcuts are arrays of key names: ['meta', 'shift', 'k']

Modifier keys: meta, shift, alt, ctrl

• meta maps to Cmd on Mac, Ctrl on Windows/Linux

Tooltip Usage

Wrap any interactive element to show a tooltip with shortcut:

import { Tooltip } from '@/components/ui/Tooltip'

<Tooltip label={t('commands.toggleSidebar')} shortcut={['meta', 'b']} side="right">
  <button>...</button>
</Tooltip>

Groups

Commands are grouped in the palette. Add new groups by:

1. Using a new group string in the command entry
2. Adding commands.groups.<groupName> translation key

Current groups: navigation, app

Conventions

• Every navigable feature page should have a command entry
• Use sequential number shortcuts for navigation: meta+1, meta+2, etc.
• Function shortcuts should use meta+<letter> or meta+shift+<letter>
• Always add a tooltip to sidebar nav items and action buttons