testdrive-jsui/docs/features/keyboard-shortcuts.md

Keyboard Shortcuts

Quick actions via keyboard ⌨️

TestDrive-JSUI provides comprehensive keyboard shortcuts for efficient document editing and navigation. All shortcuts are enabled by default and work across all browsers. Keyboard shortcuts improve accessibility and productivity for power users.

---

Overview

Keyboard shortcuts provide fast access to common actions without reaching for the mouse. They're organized by context: global shortcuts, section editing shortcuts, and control-specific shortcuts.

Quick Reference

Shortcut	Action	Context
Ctrl+S	Save document	Global
Escape	Close editor/dialog	Global
Ctrl+Enter	Accept changes	Section editing
Ctrl+P	Print document	Document (planned)
Ctrl+F	Find & replace	Document (planned)
Ctrl+B	Bold text	Text editing (planned)
Ctrl+I	Italic text	Text editing (planned)
Tab	Indent	Section editing

Note: On macOS, Ctrl can be replaced with Cmd (⌘) for most shortcuts.

---

Configuration

Enable/Disable Shortcuts

Keyboard shortcuts are enabled by default. To disable:

new TestDriveJSUI({
    container: '#editor',
    shortcuts: false  // Disable all keyboard shortcuts
});

When to disable:

• Conflict with existing application shortcuts
• Custom keyboard handling required
• Accessibility requirement for specific workflow

Check Shortcut Status

const editor = new TestDriveJSUI({ container: '#editor' });
console.log(editor.config.shortcuts); // true or false

---

Global Shortcuts

Available throughout the application, regardless of focus.

Ctrl+S (Save Document)

Action: Save/download current document as markdown file

Platforms:

• Windows/Linux: Ctrl+S
• macOS: Cmd+S (⌘S)

Behavior:

1. Prevents browser's default save behavior
2. Calls editor.save() method
3. Downloads file with timestamped name: document-edited-YYYY-MM-DD-HHMMSS.md
4. Triggers save event for custom handlers

Example:

const editor = new TestDriveJSUI({ container: '#editor' });

// Listen to save event
editor.on('save', (data) => {
    console.log('Document saved via Ctrl+S');
    console.log('Content:', data.markdown);
});

// User presses Ctrl+S → save event fires

Use cases:

• Quick save during writing
• Prevent accidental data loss
• Trigger auto-upload to server

---

Escape (Close Editor/Dialog)

Action: Close active floating editor or dialog

Platforms: All (no modifier key needed)

Behavior:

1. Checks for active floating menu
2. Closes section editor if open
3. Cancels current edit operation
4. Returns focus to document

Contexts:

• Section editing: Cancels edit, discards changes
• Find & replace: Closes find dialog (planned)
• Go to line: Closes navigation dialog (planned)
• Image editor: Closes image editor (planned)

Example:

// User clicks section to edit
// Section editor opens with textarea
// User presses Escape
// → Editor closes, changes discarded

Use cases:

• Quick cancel during editing
• Close dialogs without mouse
• Keyboard-only workflow

---

Section Editing Shortcuts

Active when editing a section (textarea has focus).

Ctrl+Enter (Accept Changes)

Action: Accept changes and close section editor

Platforms:

• Windows/Linux: Ctrl+Enter
• macOS: Cmd+Enter (⌘Enter)

Behavior:

1. Prevents default Enter behavior (new line)
2. Applies changes to section
3. Closes floating editor
4. Updates rendered markdown
5. Triggers changes-accepted event

Example:

const editor = new TestDriveJSUI({ container: '#editor' });

editor.sectionManager.on('changes-accepted', (data) => {
    console.log('Section updated via Ctrl+Enter');
    console.log('New content:', data.content);
});

// User edits section, presses Ctrl+Enter
// → Changes applied, editor closes

Use cases:

• Fast editing workflow
• Apply changes without clicking Accept button
• Keyboard-only editing

Alternative: Click "✓ Accept" button

---

Escape (Cancel Section Edit)

Action: Cancel editing and discard changes

Platforms: All

Behavior:

1. Restores original section content
2. Closes floating editor
3. No changes applied
4. Triggers changes-cancelled event

Example:

// User clicks section, makes edits
// User presses Escape
// → Editor closes, original content restored

Use cases:

• Discard unwanted changes quickly
• Exit edit mode without saving
• Keyboard-only workflow

Alternative: Click "✗ Cancel" button

---

Tab (Indent)

Action: Insert tab character (4 spaces)

Platforms: All

Behavior:

1. Inserts 4 spaces at cursor position
2. Does not move focus to next element
3. Useful for code blocks and lists

Example:

Before: |cursor here

After pressing Tab:
    |cursor here

Use cases:

• Indent code in code blocks
• Create nested lists
• Format markdown content

Note: Most browsers use Tab to move focus. TestDrive-JSUI overrides this behavior within textareas.

---

Document Actions (Planned)

These shortcuts are planned for future releases.

Ctrl+P (Print Document)

Action: Open browser print dialog

Status: 🔜 Planned for v1.1

Platforms:

• Windows/Linux: Ctrl+P
• macOS: Cmd+P (⌘P)

Expected behavior:

1. Prevents browser's default print
2. Formats document for printing
3. Opens print preview dialog

Use cases:

• Quick print from editor
• Print formatted markdown
• Generate PDF via print

---

Ctrl+F (Find & Replace)

Action: Open find and replace dialog

Status: 🔜 Planned for v1.1

Platforms:

• Windows/Linux: Ctrl+F
• macOS: Cmd+F (⌘F)

Expected behavior:

1. Prevents browser's default find
2. Opens TestDrive-JSUI find dialog
3. Focuses search input field
4. Highlights matches in document

Use cases:

• Search for text across document
• Replace repetitive content
• Navigate long documents

---

Text Formatting (Planned)

These shortcuts will be available when text is selected or cursor is in text.

Ctrl+B (Bold)

Action: Wrap selected text in **bold** markers

Status: 🔜 Planned for v1.1

Platforms:

• Windows/Linux: Ctrl+B
• macOS: Cmd+B (⌘B)

Expected behavior:

Before: Selected text
After: **Selected text**

Use cases:

• Quick markdown formatting
• Bold emphasis in writing
• Keyboard-only formatting

Alternative: Click "B" button in Edit Control

---

Ctrl+I (Italic)

Action: Wrap selected text in *italic* markers

Status: 🔜 Planned for v1.1

Platforms:

• Windows/Linux: Ctrl+I
• macOS: Cmd+I (⌘I)

Expected behavior:

Before: Selected text
After: *Selected text*

Use cases:

• Quick markdown formatting
• Italic emphasis in writing
• Keyboard-only formatting

Alternative: Click "I" button in Edit Control

---

Browser vs. Application Shortcuts

Conflicts

Some shortcuts conflict with browser defaults:

Shortcut	Browser Default	TestDrive-JSUI
Ctrl+S	Browser save dialog	Document save
Ctrl+P	Browser print	Document print (planned)
Ctrl+F	Browser find	Document find (planned)
Ctrl+B	Bookmarks sidebar	Bold text (planned)
Ctrl+I	Open DevTools	Italic text (planned)

Solution: TestDrive-JSUI calls event.preventDefault() to override browser behavior.

Preserving Browser Shortcuts

Some browser shortcuts remain available:

• Ctrl+Z / Cmd+Z - Undo (within textareas)
• Ctrl+Y / Cmd+Shift+Z - Redo (within textareas)
• Ctrl+C / Cmd+C - Copy
• Ctrl+V / Cmd+V - Paste
• Ctrl+X / Cmd+X - Cut
• Ctrl+A / Cmd+A - Select all
• F5 / Ctrl+R - Refresh page
• F11 - Fullscreen
• F12 - DevTools

---

Custom Shortcuts

You can add custom shortcuts by listening to keyboard events:

Example: Ctrl+E (Export)

const editor = new TestDriveJSUI({ container: '#editor' });

document.addEventListener('keydown', (event) => {
    // Ctrl+E or Cmd+E
    if ((event.ctrlKey || event.metaKey) && event.key === 'e') {
        event.preventDefault();

        // Custom export action
        const markdown = editor.getMarkdown();
        console.log('Export triggered:', markdown);

        // Trigger export
        if (editor.editControl) {
            editor.editControl.exportDocument();
        }
    }
});

Example: Ctrl+Shift+D (Debug Toggle)

document.addEventListener('keydown', (event) => {
    // Ctrl+Shift+D
    if (event.ctrlKey && event.shiftKey && event.key === 'D') {
        event.preventDefault();

        // Toggle debug control
        if (editor.debugControl) {
            if (editor.debugControl.isExpanded) {
                editor.debugControl.collapse();
            } else {
                editor.debugControl.expand();
            }
        }
    }
});

Example: Ctrl+K (Insert Link)

document.addEventListener('keydown', (event) => {
    if ((event.ctrlKey || event.metaKey) && event.key === 'k') {
        event.preventDefault();

        // Get active textarea
        const activeTextarea = document.activeElement;
        if (activeTextarea.tagName === 'TEXTAREA') {
            // Insert link markdown
            const selectedText = activeTextarea.value.substring(
                activeTextarea.selectionStart,
                activeTextarea.selectionEnd
            );

            const linkMarkdown = selectedText
                ? `[${selectedText}](url)`
                : '[text](url)';

            // Insert at cursor
            const start = activeTextarea.selectionStart;
            const end = activeTextarea.selectionEnd;
            const text = activeTextarea.value;

            activeTextarea.value = text.substring(0, start) + linkMarkdown + text.substring(end);

            // Select 'url' part
            const urlStart = start + linkMarkdown.indexOf('(') + 1;
            const urlEnd = urlStart + 3;
            activeTextarea.setSelectionRange(urlStart, urlEnd);
            activeTextarea.focus();
        }
    }
});

---

Accessibility

Keyboard-Only Operation

All TestDrive-JSUI features are accessible via keyboard:

1. Navigation: Tab through interactive elements
2. Section editing: Enter to open, Escape to close
3. Controls: Tab to reach, Space/Enter to activate
4. Shortcuts: All documented shortcuts work

Screen Reader Support

Keyboard shortcuts work with screen readers:

• ARIA labels: All buttons have descriptive labels
• Focus management: Proper focus order maintained
• Announcements: State changes announced to screen readers

Example:

<button aria-label="Accept changes (Ctrl+Enter)">✓ Accept</button>

Custom Key Bindings

For users with accessibility needs:

const editor = new TestDriveJSUI({
    container: '#editor',
    shortcuts: false  // Disable defaults
});

// Implement custom shortcuts matching user's needs
document.addEventListener('keydown', (event) => {
    // Custom bindings here
});

---

Troubleshooting

Shortcut Not Working

Problem: Pressing shortcut does nothing

Solutions:

1. Check if shortcuts enabled:

   console.log(editor.config.shortcuts); // Should be true
   

2. Check browser extension conflicts:

   • Disable extensions like Vimium, Shortkeys
   • Test in incognito/private mode

3. Check operating system conflicts:

   • Some OS shortcuts override browser shortcuts
   • Example: Windows Ctrl+S might open system save dialog

4. Test with different modifier:

   • Try Cmd instead of Ctrl on macOS
   • Try Ctrl instead of Cmd on Windows

5. Verify focus:

   console.log(document.activeElement); // Check what has focus
   

Shortcut Conflicts

Problem: Shortcut triggers wrong action

Solutions:

1. Disable TestDrive-JSUI shortcuts:

   new TestDriveJSUI({ shortcuts: false });
   

2. Implement custom shortcuts:

   document.addEventListener('keydown', (event) => {
       // Your custom logic
   });
   

3. Check browser extensions: Disable conflicting extensions

macOS Specific Issues

Problem: Ctrl shortcuts don't work on macOS

Solution: Use Cmd (⌘) key instead:

• Cmd+S instead of Ctrl+S
• Cmd+Enter instead of Ctrl+Enter

Code detects platform automatically:

if (event.ctrlKey || event.metaKey) { // metaKey = Cmd on Mac
    // Handle shortcut
}

---

Best Practices

For Users

1. Learn core shortcuts first: Ctrl+S, Escape, Ctrl+Enter
2. Use shortcuts consistently: Build muscle memory
3. Combine with mouse: Use whichever is faster for context
4. Customize if needed: Add shortcuts for frequent actions

For Developers

1. Document custom shortcuts: Provide cheat sheet to users
2. Avoid conflicts: Check existing shortcuts before adding new
3. Provide alternatives: Always offer mouse-based alternative
4. Test across platforms: Verify shortcuts work on Windows, Mac, Linux
5. Respect user settings: Allow disabling shortcuts if needed

Example: Shortcut Cheat Sheet

const editor = new TestDriveJSUI({ container: '#editor' });

// Add help button that shows shortcuts
const helpButton = document.createElement('button');
helpButton.textContent = 'Keyboard Shortcuts (?)';
helpButton.onclick = () => {
    alert(`
TestDrive-JSUI Keyboard Shortcuts:

Ctrl+S - Save document
Escape - Close editor
Ctrl+Enter - Accept changes
Tab - Indent

More shortcuts: /docs/keyboard-shortcuts
    `);
};

document.body.appendChild(helpButton);

---

Platform Differences

Windows/Linux

• Uses Ctrl key for shortcuts
• Alt key for alternative shortcuts
• Standard keyboard layout

macOS

• Uses Cmd (⌘) key instead of Ctrl
• Option (⌥) key instead of Alt
• Control key rarely used for app shortcuts

Detection in Code

const isMac = navigator.platform.toUpperCase().indexOf('MAC') >= 0;

document.addEventListener('keydown', (event) => {
    const modifierPressed = isMac ? event.metaKey : event.ctrlKey;

    if (modifierPressed && event.key === 's') {
        // Save action
    }
});

---

Future Shortcuts (Roadmap)

Planned for future versions:

Version 1.1

• ✅ Ctrl+P - Print document
• ✅ Ctrl+F - Find & replace
• ✅ Ctrl+B - Bold text
• ✅ Ctrl+I - Italic text
• ✅ Ctrl+K - Insert link
• ✅ Ctrl+Shift+C - Insert code block

Version 1.2

• 🔜 Ctrl+H - Insert heading
• 🔜 Ctrl+L - Insert list
• 🔜 Ctrl+Shift+I - Insert image
• 🔜 Ctrl+G - Go to line
• 🔜 Ctrl+D - Duplicate line

Version 2.0

• 🔜 Ctrl+/ - Toggle comment
• 🔜 Ctrl+Shift+K - Delete line
• 🔜 Ctrl+[ / Ctrl+] - Indent/unindent
• 🔜 Ctrl+Space - Autocomplete
• 🔜 F3 - Find next

Request features: Submit suggestions at GitHub Issues

---

Related Features

• Section Editing - Edit sections with keyboard
• Edit Control - Document actions and shortcuts
• Accessibility - Keyboard-only operation (coming soon)

---

See Also:

• Configuration
• Events
• Examples

---

Version: 1.0.0 Last Updated: 2025-12-16