TimeTracker/docs/KEYBOARD_SHORTCUTS_DEVELOPER.md

Keyboard Shortcuts – Developer Guide

Persistence and API

• Storage: Per-user overrides are stored in User.keyboard_shortcuts_overrides (JSON column). Keys are shortcut id → normalized key string (e.g. "nav_dashboard": "g 1").
• Defaults: Canonical list is in app/utils/keyboard_shortcuts_defaults.py (DEFAULT_SHORTCUTS). Normalization (lowercase, Cmd → Ctrl) and forbidden keys are defined there.
• Endpoints (all require authenticated user):
  • GET /api/settings/keyboard-shortcuts — returns { shortcuts, overrides }.
  • POST /api/settings/keyboard-shortcuts — body { "overrides": { "id": "key", ... } }; validates then saves (only overrides that differ from default are stored).
  • POST /api/settings/keyboard-shortcuts/reset — clears overrides, returns full config.
• Validation: Conflicts are checked per context: the same key cannot be assigned to two actions in the same context. Forbidden keys (e.g. ctrl+w, ctrl+n, alt+f4) are rejected.

Registering new shortcuts

To add a new keyboard shortcut that appears in the settings UI and supports user overrides:

1. Backend (app/utils/keyboard_shortcuts_defaults.py):

   • Append an entry to DEFAULT_SHORTCUTS with:
     • id: unique string (e.g. "nav_analytics"), used as the key for overrides.
     • default_key: normalized default key (e.g. "g a").
     • name, description, category, context (e.g. "global", "table", "modal").
   • No database migration is needed for new defaults; overrides are keyed by id.

2. Frontend (app/static/keyboard-shortcuts-advanced.js):

   • In initDefaultShortcuts(), call this.register(...) with the same id and the same default key as in DEFAULT_SHORTCUTS.
   • Example: this.register('g a', () => this.navigateTo('/analytics'), { id: 'nav_analytics', description: 'Go to Analytics', category: 'Navigation' });

3. Conflict rules: Avoid reusing the same default_key in the same context for another action; validation will flag duplicate effective keys per context. Forbidden keys are listed in FORBIDDEN_KEYS in keyboard_shortcuts_defaults.py.

After adding the entry to both the backend list and the JS registry, the new shortcut appears in the settings page and can be overridden by the user; the injected config and the API will include it automatically.