testdrive-jsui/docs/features/section-editing.md

# Section Editing

**Click any section to edit it independently**

Section editing is the core feature of TestDrive-JSUI that enables interactive markdown editing. Each section of your document can be edited independently without affecting other sections.

---

## Overview

TestDrive-JSUI automatically parses your markdown into logical sections and makes each one independently editable. Click any section to open a floating editor with Accept, Cancel, and Reset options.

### Key Benefits

- ✅ **Non-destructive** - Changes are isolated to individual sections
- ✅ **Visual feedback** - Hover effects and editing indicators
- ✅ **Easy to use** - Simple click-to-edit interface
- ✅ **Undo/redo** - Cancel or reset changes at any time

---

## How It Works

### 1. Automatic Section Detection

TestDrive-JSUI splits your markdown into sections using these rules:

- **Double newlines** create section boundaries
- **Headings** start new sections
- **Images** are treated as individual sections
- **Code blocks** stay together in one section

Example markdown:
```markdown
# My Document

This is the first section.

## A Heading

This is the second section.

![An Image](image.png)

Final section here.
```

This creates **4 sections**:
1. Heading + paragraph
2. Subheading + paragraph
3. Image
4. Final paragraph

### 2. Section States

Each section has a state:

| State | Description | Visual |
|-------|-------------|--------|
| **Original** | Unchanged from initial load | Normal appearance |
| **Editing** | Currently being edited | Blue border, floating editor |
| **Modified** | Changed but not saved | Pending changes |
| **Saved** | Changes accepted | Saved to current document |

### 3. Visual Feedback

**Hover Effect**:
- Light background highlight
- Subtle border
- Shows section is clickable

**Editing State**:
- Blue border with glow
- Floating editor dialog
- Textarea with current content

---

## Using Section Editing

### Basic Workflow

1. **Click a section** to start editing
2. **Edit the markdown** in the textarea
3. **Choose an action**:
   - **✓ Accept** - Save changes to section
   - **✗ Cancel** - Discard changes
   - **↺ Reset** - Restore original content

### Keyboard Shortcuts

While editing:
- `Ctrl+Enter` - Accept changes (coming soon)
- `Escape` - Cancel editing
- `Tab` - Insert tab character

### Tips

**Multiple Edits**:
- Edit one section at a time
- Previous section auto-saves when starting a new edit
- All changes stay in memory until you export/save the document

**Long Sections**:
- Textarea expands vertically
- Scroll within the editor
- Resize handle in floating dialog

**Image Sections**:
- Special image editor with preview
- Drag & drop image replacement
- Edit alt text inline

---

## Configuration

### Enable/Disable Section Editing

```javascript
new TestDriveJSUI({
    container: '#editor',
    sections: true  // Enable section editing (default: true)
});
```

### Disable for View-Only Mode

```javascript
new TestDriveJSUI({
    container: '#viewer',
    mode: 'view',     // No editing allowed
    sections: false   // Disable section detection
});
```

---

## Advanced Features

### Section Metadata

Each section has metadata you can access:

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

// Get section manager
const manager = editor.sectionManager;

// Get all sections
const sections = manager.getAllSections();

sections.forEach(section => {
    console.log({
        id: section.id,
        type: section.type,           // 'heading', 'paragraph', 'image', etc.
        state: section.state,          // 'original', 'editing', 'modified', 'saved'
        hasChanges: section.hasChanges(),
        isEditing: section.isEditing(),
        content: section.currentMarkdown
    });
});
```

### Section Types

| Type | Description | Detection |
|------|-------------|-----------|
| **heading** | h1-h6 headings | Starts with `#` |
| **paragraph** | Regular text | Default type |
| **image** | Images | `![alt](url)` pattern |
| **code** | Code blocks | Fenced with ` ``` ` |
| **list** | Lists | Starts with `-` or `1.` |
| **quote** | Blockquotes | Starts with `>` |

### Events

Listen to section editing events:

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

// Section manager events
editor.sectionManager.on('edit-started', (data) => {
    console.log('Started editing:', data.sectionId);
});

editor.sectionManager.on('changes-accepted', (data) => {
    console.log('Accepted changes:', data.sectionId, data.content);
});

editor.sectionManager.on('changes-cancelled', (data) => {
    console.log('Cancelled edit:', data.sectionId);
});
```

---

## Examples

### Basic Section Editing

```html
<!DOCTYPE html>
<html>
<head>
    <script src="https://cdn.jsdelivr.net/npm/marked/marked.min.js"></script>
    <script src="testdrive-jsui.js"></script>
</head>
<body>
    <div id="editor"></div>
    <script>
        const editor = new TestDriveJSUI({
            container: '#editor',
            markdown: '# Welcome\n\nClick this section to edit it.\n\n## Try It!\n\nClick this section too!',
            mode: 'edit',
            sections: true
        });
    </script>
</body>
</html>
```

### With Event Tracking

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

// Track edits
let editCount = 0;
editor.sectionManager.on('changes-accepted', (data) => {
    editCount++;
    console.log(`Edit #${editCount}:`, data.content.substring(0, 50) + '...');
});

// Get final document
document.getElementById('export').addEventListener('click', () => {
    const markdown = editor.getMarkdown();
    console.log('Final document:', markdown);
    console.log('Total edits made:', editCount);
});
```

---

## Troubleshooting

### Sections Not Clickable

**Problem**: Sections don't respond to clicks

**Solutions**:
1. Check that `mode: 'edit'` (not 'view')
2. Ensure `sections: true` in config
3. Verify SectionManager and DOMRenderer are loaded
4. Check browser console for JavaScript errors

### Editor Dialog Not Appearing

**Problem**: Click works but no floating editor shows

**Solutions**:
1. Check z-index conflicts with other elements
2. Verify CSS is loaded properly
3. Check for JavaScript errors in console
4. Ensure marked.js is loaded for markdown parsing

### Changes Not Persisting

**Problem**: Edits disappear after accepting

**Solutions**:
1. Click **Accept (✓)** not Cancel
2. Check that section state changed to 'saved'
3. Use `editor.getMarkdown()` to export current state
4. Enable autosave or use save button to persist

---

## Best Practices

### For Writers

1. **Edit small sections** - Break long documents into manageable pieces
2. **Use Accept liberally** - Save frequently as you edit
3. **Test with Reset** - Preview original vs edited
4. **Export regularly** - Download or save your work

### For Developers

1. **Listen to events** - Track user edits for analytics
2. **Validate sections** - Check content before accepting
3. **Custom section types** - Extend Section.detectType() for custom logic
4. **Batch operations** - Use sectionManager API for bulk updates

---

## Related Features

- **[Edit Control](edit-control.md)** - Document-level save/export actions
- **[Status Control](status-control.md)** - Track editing progress
- **[Keyboard Shortcuts](keyboard-shortcuts.md)** - Quick editing actions

---

**See Also**:
- [Getting Started](../../README.md#quick-start)
- [API Reference](../api/section-manager.md)
- [Examples](../../examples/)

---

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