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:

# 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

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

Disable for View-Only Mode

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:

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	 pattern
code	Code blocks	Fenced with ```
list	Lists	Starts with - or 1.
quote	Blockquotes	Starts with >

Events

Listen to section editing events:

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

<!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

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 - Document-level save/export actions
• Status Control - Track editing progress
• Keyboard Shortcuts - Quick editing actions

---

See Also:

• Getting Started
• API Reference
• Examples

---

Version: 1.0.0 Last Updated: 2025-12-16