# 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

``` ### 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 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.