generated from coulomb/repo-seed
docs: add comprehensive feature documentation
Created feature documentation structure: docs/features/README.md: - Overview of all control panels - Configuration examples - Use case scenarios - Feature toggle documentation docs/features/section-editing.md: - Complete section editing guide - How it works (automatic detection, states, visual feedback) - Configuration options - Advanced features (metadata, events, section types) - Examples and troubleshooting - Best practices Remaining documentation to be created: - edit-control.md - status-control.md - contents-control.md - debug-control.md - keyboard-shortcuts.md - themes.md 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com)
This commit is contained in:
305
docs/features/README.md
Normal file
305
docs/features/README.md
Normal file
@@ -0,0 +1,305 @@
|
||||
# TestDrive-JSUI Features
|
||||
|
||||
**Complete feature documentation for TestDrive-JSUI**
|
||||
|
||||
TestDrive-JSUI provides a modular system of interactive controls that enhance markdown editing and viewing. Each control can be enabled/disabled independently and positioned using compass directions.
|
||||
|
||||
---
|
||||
|
||||
## 📚 Feature Documentation
|
||||
|
||||
### Core Features
|
||||
- **[Section Editing](section-editing.md)** - Click any section to edit it independently
|
||||
- **[Keyboard Shortcuts](keyboard-shortcuts.md)** - Quick actions via keyboard
|
||||
- **[Themes](themes.md)** - Visual theming system
|
||||
|
||||
### Control Panels
|
||||
|
||||
#### [Edit Control](edit-control.md) 📝
|
||||
**Position**: Northeast (ne)
|
||||
**Purpose**: Document actions and editing tools
|
||||
|
||||
Features:
|
||||
- Print, save, export document
|
||||
- Navigation helpers (scroll to top/bottom, go to line)
|
||||
- Text formatting tools
|
||||
- Find & replace
|
||||
- Font size adjustment
|
||||
- Markdown shortcuts
|
||||
|
||||
**[→ Full Documentation](edit-control.md)**
|
||||
|
||||
---
|
||||
|
||||
#### [Status Control](status-control.md) 📊
|
||||
**Position**: East (e)
|
||||
**Purpose**: Real-time document statistics
|
||||
|
||||
Features:
|
||||
- Word and character count
|
||||
- Reading time estimation
|
||||
- Document structure analysis (headings, paragraphs, lists)
|
||||
- Change tracking
|
||||
- Content complexity metrics
|
||||
|
||||
**[→ Full Documentation](status-control.md)**
|
||||
|
||||
---
|
||||
|
||||
#### [Contents Control](contents-control.md) 📋
|
||||
**Position**: Northwest (nw)
|
||||
**Purpose**: Table of contents navigation
|
||||
|
||||
Features:
|
||||
- Automatic heading extraction
|
||||
- Hierarchical display with indentation
|
||||
- Click to navigate with smooth scrolling
|
||||
- Search within headings
|
||||
- Real-time updates
|
||||
|
||||
**[→ Full Documentation](contents-control.md)**
|
||||
|
||||
---
|
||||
|
||||
####[Debug Control](debug-control.md) 🐛
|
||||
**Position**: Southeast (se)
|
||||
**Purpose**: Development and debugging tools
|
||||
|
||||
Features:
|
||||
- Real-time debug logs
|
||||
- Error tracking
|
||||
- Performance monitoring
|
||||
- Component state inspection
|
||||
- Event tracking
|
||||
|
||||
**[→ Full Documentation](debug-control.md)**
|
||||
|
||||
---
|
||||
|
||||
## 🎛️ Configuration
|
||||
|
||||
### Enabling/Disabling Controls
|
||||
|
||||
```javascript
|
||||
const editor = new TestDriveJSUI({
|
||||
container: '#editor',
|
||||
markdown: '# My Document',
|
||||
mode: 'edit',
|
||||
|
||||
// Control configuration
|
||||
controls: {
|
||||
editControl: true, // Document actions (default: true)
|
||||
statusControl: true, // Statistics (default: true)
|
||||
contentsControl: true, // Table of contents (default: true)
|
||||
debugControl: false // Debug logs (default: false)
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
### Custom Positioning
|
||||
|
||||
```javascript
|
||||
const editor = new TestDriveJSUI({
|
||||
container: '#editor',
|
||||
|
||||
// Custom compass positions
|
||||
controlPositions: {
|
||||
editControl: 'ne', // Northeast (default)
|
||||
statusControl: 'e', // East (default)
|
||||
contentsControl: 'nw', // Northwest (default)
|
||||
debugControl: 'se' // Southeast (default)
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
**Compass Positions**:
|
||||
- `nw` - Northwest (top-left)
|
||||
- `ne` - Northeast (top-right)
|
||||
- `e` - East (middle-right)
|
||||
- `se` - Southeast (bottom-right)
|
||||
- `s` - South (bottom-center)
|
||||
- `sw` - Southwest (bottom-left)
|
||||
- `w` - West (middle-left)
|
||||
|
||||
---
|
||||
|
||||
## 🎨 Control Behavior
|
||||
|
||||
### States
|
||||
|
||||
Each control has two states:
|
||||
|
||||
1. **Collapsed** (40x40px icon button)
|
||||
- Minimal screen space
|
||||
- Shows icon only
|
||||
- Click to expand
|
||||
|
||||
2. **Expanded** (full panel)
|
||||
- Shows full functionality
|
||||
- Draggable by header
|
||||
- Resizable from bottom-left corner
|
||||
- Click close (✕) to collapse
|
||||
|
||||
### Interactions
|
||||
|
||||
- **Click icon**: Expand panel
|
||||
- **Click header**: Toggle content visibility (header-only mode)
|
||||
- **Drag header**: Reposition panel
|
||||
- **Drag resize handle**: Resize panel
|
||||
- **Click close (✕)**: Collapse to icon
|
||||
|
||||
---
|
||||
|
||||
## 📖 Example Configurations
|
||||
|
||||
### Minimal (Section Editing Only)
|
||||
|
||||
```javascript
|
||||
new TestDriveJSUI({
|
||||
container: '#editor',
|
||||
controls: {
|
||||
editControl: false,
|
||||
statusControl: false,
|
||||
contentsControl: false,
|
||||
debugControl: false
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
### Writer Mode (Edit + Status)
|
||||
|
||||
```javascript
|
||||
new TestDriveJSUI({
|
||||
container: '#editor',
|
||||
controls: {
|
||||
editControl: true,
|
||||
statusControl: true,
|
||||
contentsControl: false,
|
||||
debugControl: false
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
### Reader Mode (Contents Only)
|
||||
|
||||
```javascript
|
||||
new TestDriveJSUI({
|
||||
container: '#editor',
|
||||
mode: 'view',
|
||||
controls: {
|
||||
editControl: false,
|
||||
statusControl: false,
|
||||
contentsControl: true,
|
||||
debugControl: false
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
### Developer Mode (All Controls)
|
||||
|
||||
```javascript
|
||||
new TestDriveJSUI({
|
||||
container: '#editor',
|
||||
controls: {
|
||||
editControl: true,
|
||||
statusControl: true,
|
||||
contentsControl: true,
|
||||
debugControl: true // Enable debug panel
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Advanced Features
|
||||
|
||||
### Auto-save
|
||||
|
||||
```javascript
|
||||
new TestDriveJSUI({
|
||||
container: '#editor',
|
||||
autosave: true // Saves to localStorage every 30 seconds
|
||||
});
|
||||
```
|
||||
|
||||
### Keyboard Shortcuts
|
||||
|
||||
```javascript
|
||||
new TestDriveJSUI({
|
||||
container: '#editor',
|
||||
shortcuts: true // Enable keyboard shortcuts (default: true)
|
||||
});
|
||||
```
|
||||
|
||||
Common shortcuts:
|
||||
- `Ctrl+S` - Save document
|
||||
- `Escape` - Close editor/dialog
|
||||
- `Ctrl+F` - Find & replace
|
||||
- `Ctrl+B` - Bold
|
||||
- `Ctrl+I` - Italic
|
||||
|
||||
### Themes
|
||||
|
||||
```javascript
|
||||
new TestDriveJSUI({
|
||||
container: '#editor',
|
||||
theme: 'github' // Available: 'github' (more coming soon)
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Use Cases
|
||||
|
||||
### Documentation Editor
|
||||
```javascript
|
||||
new TestDriveJSUI({
|
||||
container: '#editor',
|
||||
controls: {
|
||||
editControl: true, // For saving/exporting
|
||||
statusControl: true, // Track word count
|
||||
contentsControl: true, // Navigate long docs
|
||||
debugControl: false
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
### Blog Post Editor
|
||||
```javascript
|
||||
new TestDriveJSUI({
|
||||
container: '#editor',
|
||||
controls: {
|
||||
editControl: true, // Save drafts
|
||||
statusControl: true, // Monitor length
|
||||
contentsControl: false, // Usually shorter posts
|
||||
debugControl: false
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
### Code Documentation Viewer
|
||||
```javascript
|
||||
new TestDriveJSUI({
|
||||
container: '#viewer',
|
||||
mode: 'view',
|
||||
controls: {
|
||||
editControl: false,
|
||||
statusControl: false,
|
||||
contentsControl: true, // Navigate API docs
|
||||
debugControl: false
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📚 Next Steps
|
||||
|
||||
- Read individual control documentation for detailed features
|
||||
- Check out [examples](../../examples/) for working demos
|
||||
- See [API Reference](../api/) for complete API documentation
|
||||
|
||||
---
|
||||
|
||||
**Version**: 1.0.0
|
||||
**Last Updated**: 2025-12-16
|
||||
318
docs/features/section-editing.md
Normal file
318
docs/features/section-editing.md
Normal file
@@ -0,0 +1,318 @@
|
||||
# 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.
|
||||
|
||||
|
||||
|
||||
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 | `` 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
|
||||
Reference in New Issue
Block a user