TimeTracker/docs/COMMAND_PALETTE_USAGE.md

Command Palette Usage Guide

Overview

The TimeTracker command palette is a powerful keyboard-driven interface that allows you to quickly navigate and execute commands without using the mouse. It's inspired by similar features in modern applications like VS Code, Sublime Text, and GitHub.

Opening the Command Palette

You can open the command palette in multiple ways:

Primary Method

• Press ? (question mark key) - Simply press the ? key anywhere in the application
  • Quick, easy to remember
  • Doesn't require modifier keys
  • Works on all keyboard layouts

Alternative Methods

• Click the command palette button in the navigation bar (terminal icon)
• Use the help menu dropdown

Quick Search

To quickly access the search functionality:

• Press Ctrl+K (Windows/Linux) or Cmd+K (Mac) - Focuses the search box
  • Works from anywhere in the application
  • Instantly ready to search projects, tasks, clients, and more

Using the Command Palette

Once opened, you can:

1. Type to search - Start typing to filter available commands
2. Navigate - Use arrow keys (↑/↓) to move between commands
3. Execute - Press Enter to run the selected command or click on it
4. Cancel - Press Esc or click outside the palette to close

Available Commands

Navigation Commands

• Go to Dashboard (g d) - Navigate to the main dashboard
• Go to Projects (g p) - View all projects
• Go to Tasks (g t) - View all tasks
• Go to Reports (g r) - View reports and analytics
• Go to Invoices (g i) - View invoices
• Go to Analytics - View analytics dashboard
• Open Calendar - View the time tracking calendar

Action Commands

• New Time Entry (n e) - Create a new manual time entry
• New Project (n p) - Create a new project
• New Task (n t) - Create a new task
• New Client (n c) - Create a new client
• Start Timer - Start a new timer
• Stop Timer - Stop the currently running timer

General Commands

• Toggle Theme (Ctrl+Shift+L) - Switch between light and dark mode
• Open Help - View keyboard shortcuts help

Keyboard Sequences

Some commands can be triggered directly without opening the palette using key sequences:

• g d - Go to Dashboard
• g p - Go to Projects
• g t - Go to Tasks
• g r - Go to Reports

Type the first letter, then the second letter in quick succession (within 1 second).

Tips and Tricks

1. Fuzzy Search - You don't need to type the exact command name. Type keywords related to what you want to do.
2. Category Filtering - Commands are organized by category (Navigation, Actions, Timer, General)
3. First-Time Hint - A tooltip will appear on your first visit showing you how to use the command palette
4. Accessibility - Full keyboard navigation support with visual focus indicators
5. Theme Support - The command palette automatically adapts to light and dark themes

Keyboard Shortcuts Reference

Press Shift+? to view the complete keyboard shortcuts help modal with all available commands.

Mobile Support

On mobile devices:

• Command palette can be accessed via the help menu
• Touch-friendly interface for selecting commands
• Keyboard shortcuts are hidden to save space

Implementation Details

The command palette features:

• Fast, responsive search
• Smooth animations and transitions
• Glass morphism effects
• Backdrop blur for better focus
• Color-coded command categories
• Visual keyboard shortcut hints
• Auto-completion and suggestions

Examples

Example 1: Quick Navigation

1. Press ?
2. Type "proj"
3. See "Go to Projects" highlighted
4. Press Enter

Example 2: Creating a New Task

1. Press ?
2. Type "new task"
3. Select "New Task"
4. You're taken to the task creation page

Example 3: Using Sequences

1. Press g (wait briefly)
2. Press d
3. Immediately navigate to Dashboard

Customization

The command palette can be extended with custom commands programmatically:

// Register a custom command
window.keyboardShortcuts.registerShortcut({
    id: 'my-custom-command',
    category: 'Custom',
    title: 'My Custom Action',
    description: 'Does something custom',
    icon: 'fas fa-star',
    keys: ['c', 'a'],
    action: () => {
        // Your custom action here
    }
});

Troubleshooting

Command Palette Won't Open

• Make sure you're not typing in a text input field
• Check that JavaScript is enabled
• Try refreshing the page

Shortcuts Not Working

• Some shortcuts may conflict with browser shortcuts
• Try using the alternative ? key method
• Check your keyboard language settings

Visual Issues

• Clear your browser cache
• Make sure you're using a modern browser (Chrome, Firefox, Safari, Edge)
• Check if dark/light theme is causing issues

Browser Support

The command palette works best on:

• Chrome/Edge (latest)
• Firefox (latest)
• Safari (latest)
• Opera (latest)

Requires:

• JavaScript enabled
• CSS backdrop-filter support (for blur effects)

Feedback

If you have suggestions for new commands or improvements to the command palette, please open an issue on the GitHub repository or contact support.

---

Pro Tip: Use the command palette regularly to speed up your workflow. Most power users find they can navigate 2-3x faster using keyboard shortcuts compared to clicking through menus!