Skip to content

CROSS_PLATFORM_SHORTCUTS.md

Latest commit

 

History

History
235 lines (174 loc) · 6.17 KB

CROSS_PLATFORM_SHORTCUTS.md

File metadata and controls

235 lines (174 loc) · 6.17 KB
Raw

Cross-Platform Keyboard Shortcuts - Complete Guide

✅ Implementation Complete

The Ubuntu Autoinstall Configuration Builder now has fully cross-platform keyboard shortcuts that work seamlessly on Windows, macOS, and Linux!

🌍 Platform Support

Platform Modifier Key Status Symbol
macOS ⌘ Command ✅ Fully Supported ⌘
Windows Ctrl ✅ Fully Supported Ctrl
Linux Ctrl ✅ Fully Supported Ctrl

🎯 How It Works

1. Automatic Platform Detection

The system automatically detects the user's operating system:

detectMac() {
    return navigator.platform.toUpperCase().indexOf('MAC') >= 0 ||
           navigator.userAgent.toUpperCase().indexOf('MAC') >= 0;
}

2. Universal Modifier Key ('mod')

When registering shortcuts, use mod instead of ctrl:

// ✅ Correct - Works on all platforms
shortcuts.register('mod+s', downloadYAML, 'Download YAML file');

// ❌ Incorrect - Only works on Windows/Linux
shortcuts.register('ctrl+s', downloadYAML, 'Download YAML file');

3. Smart Event Handling

The event handler listens for both Ctrl and Command keys:

handleKeyDown(event) {
    const keys = [];

    // Support both Ctrl (Windows/Linux) and Cmd (macOS)
    if (event.ctrlKey || event.metaKey) keys.push('ctrl');

    // ... process the shortcut
}

4. Platform-Specific Display

Shortcuts are displayed with the correct symbols for each platform:

On macOS:

  • ⌘ S (Command + S)
  • ⌘ ⇧ C (Command + Shift + C)
  • ⌘ Z (Command + Z)

On Windows/Linux:

  • Ctrl+S
  • Ctrl+Shift+C
  • Ctrl+Z

⌨️ Complete Shortcut List

All 15+ keyboard shortcuts work across all platforms:

File Operations

  • Mod+S - Download autoinstall.yaml
  • Mod+O - Load YAML file
  • Mod+B - Save to bookmark

Editing

  • Mod+Z - Undo last change
  • Mod+Y - Redo last change
  • Mod+Shift+Y - Redo (alternative)

Tools

  • Mod+K - Open version manager
  • Mod+/ - Show keyboard shortcuts
  • Mod+Shift+C - Copy YAML to clipboard
  • Mod+Shift+V - Validate configuration
  • Mod+Shift+T - Open templates

Navigation

  • ←/→ - Navigate between tabs
  • Home - Go to first tab
  • End - Go to last tab
  • Esc - Close modal/dialog

🎨 UI Enhancements

1. Keyboard Shortcuts Modal

The shortcuts modal now shows:

  • Platform indicator badge: 🍎 macOS, 🪟 Windows, or 🐧 Linux
  • Info box: Explains which modifier key to use
  • Platform-specific shortcuts: Displays ⌘ or Ctrl based on OS
  • Responsive layout: Works on mobile and desktop

2. Undo/Redo Toolbar

Button tooltips show the correct shortcut:

  • macOS: "Undo (⌘+Z)"
  • Windows/Linux: "Undo (Ctrl+Z)"

3. Onboarding Tour

The interactive tour dynamically shows shortcuts:

  • Detects platform on tour start
  • Shows ⌘ symbols on Mac
  • Shows Ctrl notation elsewhere
  • Includes platform indicator

🧪 Testing

Test on macOS

1. Open the app on Mac
2. Press ⌘+S → Should download YAML
3. Press ⌘+Z → Should undo
4. Press ⌘+/ → Should show shortcuts with ⌘ symbols

Test on Windows

1. Open the app on Windows
2. Press Ctrl+S → Should download YAML
3. Press Ctrl+Z → Should undo
4. Press Ctrl+/ → Should show shortcuts with Ctrl notation

Test on Linux

1. Open the app on Linux
2. Press Ctrl+S → Should download YAML
3. Press Ctrl+Z → Should undo
4. Press Ctrl+/ → Should show shortcuts with Ctrl notation

🔧 Technical Details

KeyboardShortcuts Class Methods

class KeyboardShortcuts {
    detectMac()                    // Detect if user is on macOS
    getModifierKey()               // Get 'Cmd' or 'Ctrl'
    formatDisplayKey(key)          // Format for display (⌘ S or Ctrl+S)
    register(key, callback, desc)  // Register shortcut with 'mod' support
    handleKeyDown(event)           // Handle both ctrlKey and metaKey
    getPlatformInfo()              // Get detailed platform info
    getAll()                       // Get all shortcuts with display keys
}

Platform Detection

The system checks:

  1. navigator.platform (primary method)
  2. navigator.userAgent (fallback)

Recognized platforms:

  • 'MAC' in platform → macOS
  • 'WIN' in platform → Windows
  • 'LINUX' in platform → Linux

Symbol Mapping

Input macOS Output Windows/Linux Output
mod ⌘ Ctrl
ctrl ⌘ Ctrl
alt ⌥ Alt
shift ⇧ Shift

📝 Best Practices

1. Always Use 'mod'

// ✅ Good
shortcuts.register('mod+s', callback);
shortcuts.register('mod+shift+p', callback);

// ❌ Bad
shortcuts.register('ctrl+s', callback);  // Won't work on Mac
shortcuts.register('cmd+s', callback);   // Won't work on Windows/Linux

2. Test on Multiple Platforms

If possible, test shortcuts on:

  • At least one Mac
  • At least one Windows or Linux machine
  • Different browsers (Chrome, Firefox, Safari, Edge)

3. Avoid Platform-Specific Keys

Don't use keys that don't exist on all platforms:

  • ❌ F13-F24 (not on all keyboards)
  • ❌ Browser-specific keys
  • ✅ Letters, numbers, arrows
  • ✅ Common keys (Home, End, Esc)

🚀 Benefits

  1. Universal Experience: Same shortcuts work everywhere
  2. Native Feel: Uses platform conventions (⌘ on Mac, Ctrl elsewhere)
  3. No Configuration: Automatically adapts to user's platform
  4. Clear Communication: UI shows correct keys for each platform
  5. Accessibility: Keyboard navigation works identically everywhere

📚 Resources

  • Integration Guide: See INTEGRATION_GUIDE.md for implementation details
  • utils.js: See KeyboardShortcuts class for full implementation
  • components.js: See KeyboardShortcutsModal for UI implementation

✨ Summary

The keyboard shortcuts system is now fully cross-platform with:

  • ✅ Automatic platform detection
  • ✅ Universal 'mod' key support
  • ✅ Platform-specific symbol display
  • ✅ Smart event handling (Ctrl + Cmd)
  • ✅ Responsive UI with platform indicators
  • ✅ 15+ shortcuts working on all platforms

No manual configuration required - it just works! 🎉