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:

```javascript
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

```javascript
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**:
```javascript
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**:
```javascript
// 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**:
```javascript
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**:
```javascript
// 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**:
```markdown
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)

```javascript
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)

```javascript
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)

```javascript
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**:
```html
<button aria-label="Accept changes (Ctrl+Enter)">✓ Accept</button>
```

### Custom Key Bindings

For users with accessibility needs:

```javascript
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**:
   ```javascript
   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**:
   ```javascript
   console.log(document.activeElement); // Check what has focus
   ```

### Shortcut Conflicts

**Problem**: Shortcut triggers wrong action

**Solutions**:

1. **Disable TestDrive-JSUI shortcuts**:
   ```javascript
   new TestDriveJSUI({ shortcuts: false });
   ```

2. **Implement custom shortcuts**:
   ```javascript
   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**:
```javascript
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

```javascript
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

```javascript
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](https://github.com/anthropics/testdrive-jsui/issues)

---

## Related Features

- **[Section Editing](section-editing.md)** - Edit sections with keyboard
- **[Edit Control](edit-control.md)** - Document actions and shortcuts
- **[Accessibility](accessibility.md)** - Keyboard-only operation (coming soon)

---

**See Also**:
- [Configuration](../api/configuration.md)
- [Events](../api/events.md)
- [Examples](../../examples/)

---

**Version**: 1.0.0
**Last Updated**: 2025-12-16