generated from coulomb/repo-seed
tegwick
796c04709a
Completed Phase 1 refactoring to JavaScript-first architecture: Core Library Implementation: - Created js/testdrive-jsui.js main library class - Integrated all existing components (SectionManager, DOMRenderer, DocumentControls) - Added marked.js integration for markdown rendering - Implemented event-driven API (on/off/emit) - Support for edit/view modes and themes - LocalStorage save/load functionality - Download as markdown file - Keyboard shortcuts (Ctrl+S, Escape) - Auto-save capability (optional) Examples: - examples/full-editor.html - Complete demo with all features - Updated examples/README.md with full documentation Documentation: - Updated README.md with JavaScript-first architecture section - Added complete API reference (constructor, methods, events) - Updated CLAUDE.md with library quick start and API - Emphasized JavaScript-first design principles Architecture: - JavaScript provides ALL functionality - Language adapters are optional integration helpers - Works standalone in browser (no backend required) - Clean separation: JS (functionality) vs Adapters (integration) This completes the architectural shift documented in ARCHITECTURE.md and JS_FIRST_REFACTORING.md Phase 1. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
580 lines
17 KiB
Markdown
580 lines
17 KiB
Markdown
# TestDrive-JSUI
|
|
|
|
**A JavaScript-first markdown editor and UI library.**
|
|
|
|
TestDrive-JSUI is a pure JavaScript library for interactive markdown editing with section-based management. Language adapters (Python, Ruby, Java) are optional integration helpers for serving assets and backend integration - they do not provide core functionality.
|
|
|
|
## 🎯 **Purpose**
|
|
|
|
TestDrive-JSUI is designed to:
|
|
|
|
- **📝 Provide a complete JavaScript library** for interactive markdown editing
|
|
- **🌐 Work standalone in any browser** without backend requirements
|
|
- **🔌 Offer optional language adapters** for Python, Ruby, Java, etc.
|
|
- **✂️ Enable section-based editing** with independent section management
|
|
- **🎨 Support multiple modes** (edit/view) and themes
|
|
- **💾 Handle content persistence** (localStorage, download, custom backends)
|
|
- **🧪 Include comprehensive testing** for JavaScript and integrations
|
|
- **🚀 Support extensibility** through events and configuration
|
|
|
|
## 🏛️ **Architecture: JavaScript-First Design**
|
|
|
|
TestDrive-JSUI follows a **JavaScript-first architecture**:
|
|
|
|
```
|
|
┌─────────────────────────────────────┐
|
|
│ Core: JavaScript Library │
|
|
│ - All functionality in JS │
|
|
│ - Works standalone in browser │
|
|
│ - No backend required │
|
|
│ - Uses marked.js for markdown │
|
|
└─────────────────────────────────────┘
|
|
↑ ↑ ↑
|
|
│ │ │
|
|
┌──────────┴──┐ ┌───┴────┐ ┌──┴──────┐
|
|
│ Python │ │ Ruby │ │ Java │
|
|
│ Adapter │ │ Adapter│ │ Adapter │
|
|
│ (optional) │ │(future)│ │(future) │
|
|
└─────────────┘ └────────┘ └─────────┘
|
|
```
|
|
|
|
**Key Principle:** JavaScript provides ALL functionality. Language adapters only help with:
|
|
- Asset serving
|
|
- Configuration injection
|
|
- Backend integration (storage, auth, etc.)
|
|
- Testing infrastructure
|
|
|
|
### Quick Start: JavaScript Library
|
|
|
|
```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: '# Hello World\n\nEdit me!',
|
|
mode: 'edit',
|
|
theme: 'github'
|
|
});
|
|
|
|
// Listen to events
|
|
editor.on('save', (data) => {
|
|
console.log('Saved:', data.markdown);
|
|
});
|
|
</script>
|
|
</body>
|
|
</html>
|
|
```
|
|
|
|
### API Reference
|
|
|
|
#### Constructor Options
|
|
|
|
```javascript
|
|
new TestDriveJSUI({
|
|
container: '#editor', // CSS selector or DOM element (required)
|
|
markdown: '# Content', // Initial markdown content
|
|
mode: 'edit', // 'edit' or 'view' (default: 'edit')
|
|
theme: 'github', // Theme name (default: 'github')
|
|
autosave: false, // Auto-save to localStorage (default: false)
|
|
shortcuts: true, // Keyboard shortcuts (default: true)
|
|
sections: true, // Section-based editing (default: true)
|
|
debug: false // Debug mode (default: false)
|
|
})
|
|
```
|
|
|
|
#### Methods
|
|
|
|
| Method | Description |
|
|
|--------|-------------|
|
|
| `getMarkdown()` | Get current document content |
|
|
| `setMarkdown(markdown)` | Set document content |
|
|
| `getStatus()` | Get editor status (sections, words, etc.) |
|
|
| `save()` | Trigger save event |
|
|
| `download(filename)` | Download as markdown file |
|
|
| `loadFromLocalStorage()` | Load from browser storage |
|
|
| `saveToLocalStorage()` | Save to browser storage |
|
|
| `resetAll()` | Reset all sections to original content |
|
|
| `destroy()` | Clean up and destroy editor |
|
|
| `on(event, callback)` | Listen to events |
|
|
| `off(event, callback)` | Remove event listener |
|
|
|
|
#### Events
|
|
|
|
| Event | Data | Description |
|
|
|-------|------|-------------|
|
|
| `initialized` | `{mode, theme, sections}` | Editor finished initializing |
|
|
| `save` | `{markdown}` | Save triggered |
|
|
| `content-changed` | `{markdown}` | Content modified |
|
|
| `autosave` | `{markdown}` | Auto-save occurred |
|
|
| `download` | `{filename, markdown}` | Document downloaded |
|
|
| `reset` | `{}` | Document reset |
|
|
| `destroyed` | `{}` | Editor destroyed |
|
|
|
|
### Examples
|
|
|
|
See the `/examples` directory for:
|
|
- **`standalone.html`** - Minimal proof of concept (works from file://)
|
|
- **`full-editor.html`** - Complete demo with all features
|
|
|
|
## 🐍 **Python Adapter (Optional)**
|
|
|
|
For Python projects, TestDrive-JSUI provides an **optional adapter** for integration:
|
|
|
|
## 🏗️ **Architecture**
|
|
|
|
```
|
|
capabilities/testdrive-jsui/
|
|
├── src/testdrive_jsui/ # Python package
|
|
│ ├── core/ # Core framework components
|
|
│ ├── components/ # UI component helpers
|
|
│ ├── utils/ # Utility functions
|
|
│ └── testing/ # Python-JS bridge
|
|
│ ├── js_test_runner.py # JavaScript test execution
|
|
│ └── integration.py # Pytest integration
|
|
├── js/ # JavaScript source (consolidated)
|
|
│ ├── core/ # Core JS (debug-system, section-manager)
|
|
│ ├── components/ # UI components (dom-renderer, debug-panel)
|
|
│ ├── controls/ # Control panels (edit, debug, status, contents)
|
|
│ ├── plugins/ # JS plugins
|
|
│ ├── widgets/ # UI widgets
|
|
│ ├── utils/ # JS utilities
|
|
│ ├── tests/ # JavaScript tests
|
|
│ ├── config-loader.js # Configuration loader
|
|
│ ├── main.js # Main entry point
|
|
│ └── main-updated.js # Updated main (refactored)
|
|
├── static/ # Static assets
|
|
│ ├── css/ # Stylesheets
|
|
│ │ ├── editor.css # Editor styles
|
|
│ │ ├── controls.css # Control panel styles
|
|
│ │ └── themes/ # Theme files
|
|
│ ├── images/ # Image assets
|
|
│ │ └── icons/ # UI icons
|
|
│ └── templates/ # HTML templates
|
|
│ └── index.html # Main template
|
|
├── tests/ # Python tests
|
|
├── Makefile # Capability commands
|
|
├── pyproject.toml # Python package config
|
|
├── package.json # JavaScript dependencies
|
|
└── README.md # This file
|
|
```
|
|
|
|
**Key Design Principles:**
|
|
|
|
- **Single Source of Truth**: All assets in one capability directory
|
|
- **Self-Declaration**: Plugin declares its own paths (no hardcoded discovery)
|
|
- **Clean Boundaries**: JSON config interface between Python and JavaScript
|
|
- **No Code Mixing**: JavaScript stays in `.js` files, never embedded in Python
|
|
- **Plugin Independence**: Can be moved/installed anywhere
|
|
|
|
## 🚀 **Quick Start**
|
|
|
|
### Prerequisites
|
|
|
|
- **Python 3.8+** with pip
|
|
- **Node.js 16+** with npm (optional, for JavaScript testing)
|
|
|
|
### Standalone Installation
|
|
|
|
TestDrive-JSUI can be used completely independently of MarkiTect:
|
|
|
|
```bash
|
|
# Clone or copy this directory
|
|
git clone <repo-url> testdrive-jsui
|
|
cd testdrive-jsui
|
|
|
|
# Install Python package in development mode
|
|
pip install -e .
|
|
|
|
# (Optional) Install JavaScript dependencies for testing
|
|
npm install
|
|
```
|
|
|
|
### Integration with MarkiTect
|
|
|
|
If using within the MarkiTect project:
|
|
|
|
```bash
|
|
# Navigate to the capability directory
|
|
cd capabilities/testdrive-jsui
|
|
|
|
# Quick setup (installs everything)
|
|
make testdrive-jsui-quickstart
|
|
|
|
# Or step by step:
|
|
make testdrive-jsui-setup # Install all dependencies
|
|
make testdrive-jsui-status # Check environment
|
|
make testdrive-jsui-test-all # Run all tests
|
|
```
|
|
|
|
## 📦 **Standalone Usage**
|
|
|
|
### As a Rendering Engine Plugin
|
|
|
|
TestDrive-JSUI implements a plugin interface that allows it to be used independently:
|
|
|
|
```python
|
|
from pathlib import Path
|
|
from testdrive_jsui import TestDriveJSUIEngine
|
|
|
|
# Create engine instance
|
|
engine = TestDriveJSUIEngine()
|
|
|
|
# The engine declares its own location - no hardcoded paths!
|
|
source_dir = engine.get_plugin_source_dir()
|
|
print(f"Plugin located at: {source_dir}")
|
|
|
|
# Get organized asset paths
|
|
asset_paths = engine.get_asset_paths()
|
|
# Returns: {'js': Path(...), 'css': Path(...), 'images': Path(...), 'templates': Path(...)}
|
|
|
|
# Get required assets list
|
|
assets = engine.get_required_assets()
|
|
# Returns: {'js': [...], 'css': [...], 'images': [...], 'external': [...]}
|
|
```
|
|
|
|
### Rendering Documents
|
|
|
|
Use the engine to render markdown content with an interactive JavaScript UI:
|
|
|
|
```python
|
|
from testdrive_jsui import TestDriveJSUIEngine
|
|
from markitect.plugins.rendering import RenderingConfig
|
|
from pathlib import Path
|
|
|
|
# Create engine
|
|
engine = TestDriveJSUIEngine()
|
|
|
|
# Configure for development (serves from source)
|
|
config = RenderingConfig(
|
|
asset_base_url='.',
|
|
development_mode=True,
|
|
plugin_source_dirs={'testdrive-jsui': engine.get_plugin_source_dir()}
|
|
)
|
|
|
|
# Render markdown content
|
|
markdown_content = """
|
|
# My Document
|
|
|
|
This is a test of the **TestDrive-JSUI** rendering engine.
|
|
|
|
## Features
|
|
- Interactive editing
|
|
- Section management
|
|
- Debug controls
|
|
"""
|
|
|
|
html = engine.render_document(markdown_content, 'edit', config)
|
|
|
|
# Save to file
|
|
Path('output.html').write_text(html)
|
|
print("✅ Rendered to output.html")
|
|
```
|
|
|
|
### Production Deployment
|
|
|
|
For production, deploy assets to a static directory:
|
|
|
|
```python
|
|
from testdrive_jsui import TestDriveJSUIEngine
|
|
from markitect.plugins.rendering import RenderingConfig
|
|
from pathlib import Path
|
|
|
|
engine = TestDriveJSUIEngine()
|
|
|
|
# Configure for production
|
|
config = RenderingConfig(
|
|
asset_base_url='/_static',
|
|
development_mode=False,
|
|
output_directory=Path('./dist')
|
|
)
|
|
|
|
# Assets will be copied to: dist/_static/plugins/testdrive-jsui/
|
|
html = engine.render_document(content, 'view', config)
|
|
```
|
|
|
|
### Plugin Independence
|
|
|
|
TestDrive-JSUI is designed to be fully independent:
|
|
|
|
- ✅ **Self-contained**: All assets in one directory
|
|
- ✅ **Self-declaring**: Plugin declares its own location
|
|
- ✅ **No hardcoded paths**: Works regardless of installation location
|
|
- ✅ **Clean interface**: Pure JSON configuration boundary
|
|
- ✅ **No JavaScript in Python**: All JS in separate files
|
|
- ✅ **Reusable**: Can be used in any Python project
|
|
|
|
### Supported Modes
|
|
|
|
```python
|
|
# Check supported rendering modes
|
|
modes = engine.get_supported_modes()
|
|
# Returns: ['edit', 'view']
|
|
|
|
# Validate a mode
|
|
if engine.validate_mode('edit'):
|
|
html = engine.render_document(content, 'edit', config)
|
|
```
|
|
|
|
## 🧪 **Testing**
|
|
|
|
### JavaScript Tests
|
|
|
|
```bash
|
|
# Run JavaScript tests only
|
|
make testdrive-jsui-test-js
|
|
|
|
# Run with coverage
|
|
npm run test:coverage
|
|
|
|
# Watch mode for development
|
|
make testdrive-jsui-watch
|
|
```
|
|
|
|
### Python Integration Tests
|
|
|
|
```bash
|
|
# Run Python tests only
|
|
make testdrive-jsui-test-python
|
|
|
|
# Run integration tests
|
|
make testdrive-jsui-test-integration
|
|
|
|
# Run all tests
|
|
make testdrive-jsui-test-all
|
|
```
|
|
|
|
### Main Project Integration
|
|
|
|
From the main MarkiTect project:
|
|
|
|
```bash
|
|
# Run capability tests
|
|
make testdrive-jsui-test-all
|
|
|
|
# Include in main test suite
|
|
make test-all # (when integrated)
|
|
```
|
|
|
|
## 📋 **Available Commands**
|
|
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `make testdrive-jsui-help` | Show all available commands |
|
|
| `make testdrive-jsui-status` | Check environment status |
|
|
| `make testdrive-jsui-setup` | Install all dependencies |
|
|
| `make testdrive-jsui-test-all` | Run all tests |
|
|
| `make testdrive-jsui-watch` | Development watch mode |
|
|
| `make testdrive-jsui-clean` | Clean build artifacts |
|
|
|
|
## 🔧 **Development**
|
|
|
|
### Adding JavaScript Tests
|
|
|
|
1. Create test files in `js/tests/`:
|
|
```javascript
|
|
// js/tests/test-my-component.js
|
|
describe('MyComponent', () => {
|
|
test('should do something', () => {
|
|
// Your test here
|
|
});
|
|
});
|
|
```
|
|
|
|
2. Run tests:
|
|
```bash
|
|
make testdrive-jsui-test-js
|
|
```
|
|
|
|
### Adding Python Integration Tests
|
|
|
|
1. Create test files in `tests/`:
|
|
```python
|
|
# tests/test_my_integration.py
|
|
import pytest
|
|
from testdrive_jsui.testing import JavaScriptTestRunner
|
|
|
|
@pytest.mark.javascript
|
|
def test_my_js_component():
|
|
runner = JavaScriptTestRunner()
|
|
result = runner.run_specific_test('test-my-component.js')
|
|
assert result.success
|
|
```
|
|
|
|
2. Run tests:
|
|
```bash
|
|
make testdrive-jsui-test-integration
|
|
```
|
|
|
|
### Code Quality
|
|
|
|
```bash
|
|
# Lint JavaScript
|
|
make testdrive-jsui-lint-js
|
|
|
|
# Lint Python
|
|
make testdrive-jsui-lint-python
|
|
|
|
# Format Python code
|
|
make testdrive-jsui-format-python
|
|
```
|
|
|
|
## 🔗 **Integration with Main Project**
|
|
|
|
### Python Test Suite Integration
|
|
|
|
The capability provides pytest integration to run JavaScript tests from Python:
|
|
|
|
```python
|
|
# In main project tests
|
|
from testdrive_jsui.testing import JavaScriptTestRunner
|
|
|
|
def test_javascript_ui_components():
|
|
runner = JavaScriptTestRunner()
|
|
result = runner.run_js_tests()
|
|
assert result.success
|
|
assert result.tests_passed > 0
|
|
```
|
|
|
|
### Capability System Integration
|
|
|
|
The capability integrates with MarkiTect's capability discovery system:
|
|
|
|
```bash
|
|
# From main project
|
|
make capabilities-list # Shows testdrive-jsui
|
|
make testdrive-jsui-test-all # Direct delegation
|
|
make capabilities-test # Includes JS tests
|
|
```
|
|
|
|
## 📊 **Testing Framework Features**
|
|
|
|
### JavaScript Test Runner
|
|
|
|
- **Jest integration** with JSDOM environment
|
|
- **Coverage reporting** with detailed metrics
|
|
- **Test isolation** with proper setup/teardown
|
|
- **Mock support** for DOM APIs and browser features
|
|
- **Async testing** support for modern JavaScript
|
|
|
|
### Python-JavaScript Bridge
|
|
|
|
- **Subprocess execution** of JavaScript tests
|
|
- **Result parsing** with structured output
|
|
- **Error handling** with detailed failure information
|
|
- **Test discovery** for pytest integration
|
|
- **Coverage integration** between Python and JavaScript
|
|
|
|
### Safety Mechanisms
|
|
|
|
- **Copy-first migration** (never move, always copy)
|
|
- **Dual-track testing** during migration
|
|
- **Gradual integration** with rollback options
|
|
- **Test verification** at each step
|
|
- **Environment validation** before execution
|
|
|
|
## 🔄 **Migration Strategy**
|
|
|
|
When migrating JavaScript UI code to this capability:
|
|
|
|
1. **Copy** (don't move) JavaScript files to `js/` directory
|
|
2. **Verify** tests work in new location
|
|
3. **Create** Python integration tests
|
|
4. **Run** dual-track testing to compare results
|
|
5. **Gradually** switch to capability-based testing
|
|
6. **Remove** original files only after full verification
|
|
|
|
## 📚 **Examples**
|
|
|
|
### Running Specific Tests
|
|
|
|
```bash
|
|
# Run a specific JavaScript test
|
|
npm test -- --testNamePattern="SectionManager"
|
|
|
|
# Run specific Python integration test
|
|
pytest tests/test_section_manager_integration.py -v
|
|
|
|
# Run tests with coverage
|
|
npm run test:coverage
|
|
```
|
|
|
|
### Environment Information
|
|
|
|
```bash
|
|
# Get detailed environment info
|
|
make testdrive-jsui-info
|
|
|
|
# Check what tests are available
|
|
make testdrive-jsui-status
|
|
```
|
|
|
|
### Development Workflow
|
|
|
|
```bash
|
|
# Start development session
|
|
make testdrive-jsui-watch # Terminal 1: Watch JS tests
|
|
make testdrive-jsui-test-python # Terminal 2: Run Python tests
|
|
|
|
# Before committing
|
|
make testdrive-jsui-lint-js # Lint JavaScript
|
|
make testdrive-jsui-format-python # Format Python
|
|
make testdrive-jsui-test-all # Run all tests
|
|
```
|
|
|
|
## 🎯 **Future Enhancements**
|
|
|
|
- **Visual regression testing** with screenshot comparison
|
|
- **Performance benchmarking** for JavaScript components
|
|
- **Browser automation** with Selenium/Playwright
|
|
- **Component documentation** auto-generation
|
|
- **Real browser testing** in CI/CD pipelines
|
|
|
|
## 📋 **Troubleshooting**
|
|
|
|
### Common Issues
|
|
|
|
**Node.js not found:**
|
|
```bash
|
|
# Install Node.js first
|
|
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
|
|
sudo apt-get install -y nodejs
|
|
```
|
|
|
|
**Tests failing:**
|
|
```bash
|
|
# Check environment
|
|
make testdrive-jsui-status
|
|
|
|
# Reinstall dependencies
|
|
make testdrive-jsui-clean
|
|
make testdrive-jsui-setup
|
|
```
|
|
|
|
**Integration issues:**
|
|
```bash
|
|
# Verify Python package is installed
|
|
pip list | grep testdrive-jsui
|
|
|
|
# Check JavaScript dependencies
|
|
npm list
|
|
```
|
|
|
|
## 📄 **License**
|
|
|
|
MIT License - See main MarkiTect project for details.
|
|
|
|
---
|
|
|
|
**Version:** 1.0.0
|
|
**Status:** Full JavaScript Library Implementation Complete ✅
|
|
**Architecture:** JavaScript-First with Optional Language Adapters
|
|
**Last Updated:** 2025-12-16
|
|
|
|
See `/examples` for working demos and `ARCHITECTURE.md` for detailed design documentation. |