testdrive-jsui/docs/features/edit-control.md

# Edit Control

**Document actions and editing tools** 📝

The Edit Control provides comprehensive document-level actions including save, export, print, navigation tools, text formatting, and markdown shortcuts. Positioned in the northeast by default.

---

## Overview

The Edit Control is your command center for document-wide operations. It groups related actions into organized sections for easy access.

### Position
- **Default**: Northeast (ne) - top-right corner
- **Appearance**: ✏️ icon when collapsed
- **Title**: "Edit"

### Key Features

- 📄 Document actions (save, print, export, reset)
- 🧭 Navigation tools (scroll to top/bottom, go to line)
- 🔍 Text tools (find & replace, font size)
- ✍️ Markdown shortcuts (bold, italic, headers, links)

---

## Configuration

### Enable/Disable

```javascript
new TestDriveJSUI({
    container: '#editor',
    controls: {
        editControl: true  // Enable (default: true)
    }
});
```

### Custom Position

```javascript
new TestDriveJSUI({
    container: '#editor',
    controlPositions: {
        editControl: 'ne'  // Northeast (default), or: nw, e, se, s, sw, w
    }
});
```

---

## Features

### 1. Document Actions

#### 🖨️ Print Document
Opens browser print dialog for the current document.

**Usage**:
- Click "Print Document" button
- Or use keyboard shortcut: `Ctrl+P`

**What happens**:
- Formats document for printing
- Opens browser print dialog
- Preserves markdown formatting

#### 💾 Save Changes
Downloads the current document as a markdown file.

**Usage**:
- Click "Save Changes" button
- Or use keyboard shortcut: `Ctrl+S`

**Behavior**:
- Generates timestamped filename
- Downloads as `.md` file
- Includes all accepted edits

**Example filename**: `document-edited-2025-12-16-143052.md`

#### 📄 Export Document
Export document in various formats.

**Usage**:
- Click "Export Document" button
- Choose format in dialog

**Formats** (coming soon):
- Markdown (`.md`)
- HTML (`.html`)
- PDF (`.pdf`)
- Plain text (`.txt`)

#### 🔄 Reset All
Resets all sections to their original content.

**Usage**:
- Click "Reset All" button
- Confirm in dialog

**Warning**: This discards ALL changes! Cannot be undone.

---

### 2. Navigation Tools

#### ⬆️ Scroll to Top
Instantly scrolls to the beginning of the document.

**Usage**:
- Click "Top" button
- Smooth scroll animation

#### ⬇️ Scroll to Bottom
Instantly scrolls to the end of the document.

**Usage**:
- Click "Bottom" button
- Smooth scroll animation

#### 🎯 Go to Line
Jump to a specific line or section in the document.

**Usage**:
- Click "Go to Line" button
- Enter line number or section name
- Press Enter to navigate

---

### 3. Text Tools

#### 🔍 Find & Replace
Search and replace text across the document.

**Usage**:
- Click "Find & Replace" button
- Or use keyboard shortcut: `Ctrl+F`

**Features**:
- Case-sensitive option
- Replace one or all occurrences
- Regex support (coming soon)
- Highlight matches

#### 🔍+ / 🔍- Font Size
Adjust document font size for better readability.

**Usage**:
- Click "🔍+ Font" to increase
- Click "🔍- Font" to decrease

**Range**: 12px - 24px

**Tip**: Useful for presentations or accessibility

#### 📋 Copy Page Link
Copies the current page URL to clipboard.

**Usage**:
- Click "Copy Page Link" button
- Link copied to clipboard
- Paste anywhere with `Ctrl+V`

---

### 4. Markdown Tools

Quick markdown formatting shortcuts.

#### **B** Bold
Wraps selected text in `**bold**` markers.

**Usage**:
- Select text
- Click "B" button
- Or use: `Ctrl+B`

**Result**: `**selected text**`

#### *I* Italic
Wraps selected text in `*italic*` markers.

**Usage**:
- Select text
- Click "I" button
- Or use: `Ctrl+I`

**Result**: `*selected text*`

#### # Header
Converts line to heading.

**Levels**:
- H1: `# Heading`
- H2: `## Heading`
- H3: `### Heading`

#### 🔗 Link
Inserts markdown link format.

**Usage**:
- Click "Link" button
- Inserts: `[text](url)`

#### 📋 Code
Wraps text in code markers.

**Inline**: `` `code` ``
**Block**:
```
```language
code block
```
```

---

## Examples

### Basic Usage

```javascript
const editor = new TestDriveJSUI({
    container: '#editor',
    markdown: '# My Document\n\nContent here...',
    controls: {
        editControl: true
    }
});
```

### Custom Position

```javascript
// Move to northwest (top-left)
const editor = new TestDriveJSUI({
    container: '#editor',
    controlPositions: {
        editControl: 'nw'  // Top-left instead of top-right
    }
});
```

### With Event Tracking

```javascript
const editor = new TestDriveJSUI({
    container: '#editor',
    controls: { editControl: true }
});

// Listen to save events
editor.on('save', (data) => {
    console.log('Document saved:', data.markdown);
    // Send to backend, update UI, etc.
});

// Access edit control directly
if (editor.editControl) {
    // Programmatically trigger actions
    editor.editControl.saveDocument();
}
```

---

## API Reference

### Methods

Access via `editor.editControl`:

```javascript
const editCtrl = editor.editControl;

// Document actions
editCtrl.printDocument();      // Open print dialog
editCtrl.saveDocument();       // Download as .md
editCtrl.exportDocument();     // Export in format
editCtrl.resetAll();           // Reset all sections

// Navigation
editCtrl.scrollToTop();        // Scroll to top
editCtrl.scrollToBottom();     // Scroll to bottom
editCtrl.showGoToLine();       // Show go-to dialog

// Text tools
editCtrl.showFindReplace();    // Open find & replace
editCtrl.increaseFontSize();   // Increase font
editCtrl.decreaseFontSize();   // Decrease font
editCtrl.copyLink();           // Copy page URL

// Markdown tools
editCtrl.insertMarkdown(before, after, placeholder);
// Example: insertMarkdown('**', '**', 'bold text')
```

### Properties

```javascript
editCtrl.config.position       // Current position (e.g., 'ne')
editCtrl.config.icon          // Icon emoji ('✏️')
editCtrl.config.title         // Panel title ('Edit')
editCtrl.isExpanded           // true if panel expanded
editCtrl.fontSize             // Current font size (px)
```

---

## Keyboard Shortcuts

The Edit Control provides these shortcuts:

| Shortcut | Action |
|----------|--------|
| `Ctrl+S` | Save document |
| `Ctrl+P` | Print document |
| `Ctrl+F` | Find & replace |
| `Ctrl+B` | Bold selected text |
| `Ctrl+I` | Italic selected text |
| `Escape` | Exit edit mode |

**Enable/disable**:
```javascript
new TestDriveJSUI({
    container: '#editor',
    shortcuts: true  // Enable shortcuts (default: true)
});
```

---

## Customization

### Disable Specific Actions

Currently, all Edit Control actions are enabled by default. To hide the control entirely:

```javascript
new TestDriveJSUI({
    container: '#editor',
    controls: {
        editControl: false  // Hide completely
    }
});
```

### Future: Granular Control

Planned for v1.1:
```javascript
new TestDriveJSUI({
    container: '#editor',
    controls: {
        editControl: {
            enabled: true,
            actions: {
                print: true,
                save: true,
                export: false,    // Hide export
                reset: false      // Hide reset
            }
        }
    }
});
```

---

## Best Practices

### For Writers

1. **Save frequently** - Use `Ctrl+S` or Save button regularly
2. **Use shortcuts** - Learn `Ctrl+B`, `Ctrl+I` for quick formatting
3. **Navigate efficiently** - Use Top/Bottom for long documents
4. **Find & Replace** - Bulk edit repetitive content

### For Developers

1. **Listen to events** - Track saves for auto-sync
2. **Custom save handlers** - Override default behavior
3. **Programmatic control** - Trigger actions via API
4. **Error handling** - Catch save failures

Example custom save:
```javascript
const editor = new TestDriveJSUI({ container: '#editor' });

editor.on('save', async (data) => {
    try {
        // Send to backend
        await fetch('/api/save', {
            method: 'POST',
            body: JSON.stringify({ markdown: data.markdown })
        });
        alert('Saved to server!');
    } catch (error) {
        alert('Save failed: ' + error.message);
    }
});
```

---

## Troubleshooting

### "Save Changes" Not Working

**Problem**: Clicking save does nothing

**Solutions**:
1. Check browser console for errors
2. Verify EditControl is loaded: `typeof EditControl !== 'undefined'`
3. Check if control is enabled in config
4. Test programmatically: `editor.editControl.saveDocument()`

### Print Dialog Not Opening

**Problem**: Print button doesn't open dialog

**Solutions**:
1. Check browser pop-up blocker
2. Test with `Ctrl+P` keyboard shortcut
3. Verify browser print permissions
4. Try programmatically: `window.print()`

### Font Size Not Changing

**Problem**: Font buttons don't affect text size

**Solutions**:
1. Check CSS conflicts with `font-size: inherit`
2. Inspect element to verify font-size style applied
3. Clear browser cache
4. Test with browser zoom instead

---

## Related Features

- **[Section Editing](section-editing.md)** - Edit individual sections
- **[Keyboard Shortcuts](keyboard-shortcuts.md)** - All available shortcuts
- **[Status Control](status-control.md)** - Track editing progress

---

**See Also**:
- [API Reference](../api/edit-control.md)
- [Examples](../../examples/)

---

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