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>
363 lines
12 KiB
Markdown
363 lines
12 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Overview
|
|
|
|
**TestDrive-JSUI is a JavaScript-first markdown editor library.**
|
|
|
|
This is a pure JavaScript library for interactive markdown editing that works standalone in any browser. Language adapters (Python, Ruby, Java) are **optional integration helpers** - they do NOT provide core functionality.
|
|
|
|
**Key Facts**:
|
|
- **Core:** Complete JavaScript library (`js/testdrive-jsui.js`)
|
|
- **Dependencies:** Only marked.js for markdown parsing
|
|
- **Standalone:** Works without any backend (can run from file://)
|
|
- **Optional Adapters:** Python/Ruby/Java adapters help with asset serving and backend integration
|
|
- **Architecture:** JavaScript-first design (see `ARCHITECTURE.md`)
|
|
|
|
## JavaScript Library
|
|
|
|
### Quick Start
|
|
|
|
```html
|
|
<!DOCTYPE html>
|
|
<html>
|
|
<head>
|
|
<script src="https://cdn.jsdelivr.net/npm/marked/marked.min.js"></script>
|
|
<script src="js/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'
|
|
});
|
|
</script>
|
|
</body>
|
|
</html>
|
|
```
|
|
|
|
### API
|
|
|
|
**Constructor Options:**
|
|
- `container` (required): CSS selector or DOM element
|
|
- `markdown`: Initial content
|
|
- `mode`: 'edit' or 'view' (default: 'edit')
|
|
- `theme`: Theme name (default: 'github')
|
|
- `autosave`: Auto-save enabled (default: false)
|
|
- `shortcuts`: Keyboard shortcuts (default: true)
|
|
- `sections`: Section-based editing (default: true)
|
|
- `debug`: Debug mode (default: false)
|
|
|
|
**Methods:**
|
|
- `getMarkdown()`: Get current content
|
|
- `setMarkdown(markdown)`: Set content
|
|
- `getStatus()`: Get editor status
|
|
- `save()`: Trigger save event
|
|
- `download(filename)`: Download as .md file
|
|
- `on(event, callback)`: Listen to events
|
|
- `destroy()`: Clean up
|
|
|
|
**Events:** `initialized`, `save`, `content-changed`, `autosave`, `download`, `reset`, `destroyed`
|
|
|
|
### Examples
|
|
|
|
See `/examples`:
|
|
- `standalone.html` - Minimal proof of concept
|
|
- `full-editor.html` - Complete demo with all features
|
|
|
|
## Migration Status
|
|
|
|
**✅ MIGRATION FULLY COMPLETE - ALL PHASES**
|
|
|
|
This capability migration is now **fully complete** including cleanup. The main MarkiTect application exclusively uses the capability location, and legacy files have been removed.
|
|
|
|
**Current Status**: ✅ Phase 4 Complete (December 16, 2025)
|
|
- All 24 original JavaScript files copied to capability ✅
|
|
- 84 automated tests passing (68 JS + 15 Python + 1 fixes) ✅
|
|
- Templates updated to use capability location ✅
|
|
- Main app **fully using capability** (no hybrid approach) ✅
|
|
- Verified in both view and edit modes ✅
|
|
- **Legacy files removed** - cleanup complete ✅
|
|
|
|
**Key Facts**:
|
|
- **Main app status**: Fully migrated to capability location
|
|
- **Original files**: **REMOVED** from `/markitect/static/js/` (Phase 4 cleanup)
|
|
- **Single source of truth**: All JavaScript in `/capabilities/testdrive-jsui/js/`
|
|
- **Testing**: All rendering modes work correctly
|
|
- **Migration**: Fully complete - no further phases needed
|
|
|
|
**Documentation**: See `MIGRATION_STATUS.md` for complete migration details, all phases, and final verification results.
|
|
|
|
## Build and Test Commands
|
|
|
|
### Setup
|
|
```bash
|
|
# Complete setup (Python + JavaScript dependencies)
|
|
make testdrive-jsui-setup
|
|
|
|
# Check environment status
|
|
make testdrive-jsui-status
|
|
```
|
|
|
|
### Testing
|
|
```bash
|
|
# Run all tests (recommended before commits)
|
|
make testdrive-jsui-test-all
|
|
|
|
# Run JavaScript tests only (Jest)
|
|
make testdrive-jsui-test-js
|
|
npm test
|
|
|
|
# Run specific JavaScript test
|
|
npm test -- --testNamePattern="SectionManager"
|
|
|
|
# Run Python integration tests only
|
|
make testdrive-jsui-test-python
|
|
pytest tests/ -v
|
|
|
|
# Run tests with coverage
|
|
npm run test:coverage
|
|
|
|
# Watch mode for development
|
|
make testdrive-jsui-watch
|
|
```
|
|
|
|
### Linting and Formatting
|
|
```bash
|
|
# Lint JavaScript
|
|
make testdrive-jsui-lint-js
|
|
|
|
# Lint Python
|
|
make testdrive-jsui-lint-python
|
|
|
|
# Format Python code with black
|
|
make testdrive-jsui-format-python
|
|
```
|
|
|
|
### Cleanup
|
|
```bash
|
|
make testdrive-jsui-clean
|
|
```
|
|
|
|
## Architecture
|
|
|
|
### Directory Structure
|
|
```
|
|
testdrive-jsui/
|
|
├── js/ # JavaScript library (Core functionality)
|
|
│ ├── testdrive-jsui.js # 🎯 Main library entry point
|
|
│ ├── core/ # Core JS: debug-system, section-manager
|
|
│ ├── components/ # UI components: dom-renderer, debug-panel, document-controls
|
|
│ ├── controls/ # Control panels: edit, debug, status, contents
|
|
│ ├── plugins/ # JS plugins
|
|
│ ├── widgets/ # UI widgets
|
|
│ ├── utils/ # JS utilities
|
|
│ ├── tests/ # JavaScript tests (Jest)
|
|
│ ├── config-loader.js # Configuration loader
|
|
│ ├── main.js # Legacy main entry point
|
|
│ └── main-updated.js # Refactored main entry
|
|
├── examples/ # 📚 Working examples
|
|
│ ├── standalone.html # Minimal proof of concept
|
|
│ └── full-editor.html # Complete demo
|
|
├── src/testdrive_jsui/ # Python adapter (optional)
|
|
│ ├── core/ # Adapter core
|
|
│ ├── components/ # Adapter helpers
|
|
│ ├── utils/ # Utilities
|
|
│ └── testing/ # Python-JS bridge
|
|
│ ├── js_test_runner.py # JavaScript test execution
|
|
│ └── integration.py # Pytest integration
|
|
├── static/ # Static assets
|
|
│ ├── css/ # Stylesheets (editor, controls, themes)
|
|
│ ├── images/ # Image assets and icons
|
|
│ └── templates/ # HTML templates
|
|
├── tests/ # Python tests
|
|
├── docs/ # Documentation
|
|
│ ├── prototypes/ # Archived HTML prototypes
|
|
│ └── migration/ # Migration records
|
|
├── ARCHITECTURE.md # JavaScript-first architecture details
|
|
└── README.md # Main documentation
|
|
```
|
|
|
|
### Key Design Principles
|
|
|
|
**JavaScript-First Architecture** (NEW in v1.0.0)
|
|
- **Core functionality in JavaScript**: All UI logic, rendering, and editing in JS
|
|
- **Standalone capable**: Works without any backend (can run from file://)
|
|
- **marked.js only dependency**: For markdown parsing
|
|
- **Language adapters optional**: Python/Ruby/Java are integration helpers, not functionality providers
|
|
- **Event-driven API**: Clean event system for integration
|
|
- **See `ARCHITECTURE.md`** for complete architectural documentation
|
|
|
|
**Plugin Independence**
|
|
- **Self-declaring**: Plugin declares its own location - no hardcoded paths needed
|
|
- **Single source of truth**: All assets in one capability directory
|
|
- **Clean boundaries**: JSON config interface between adapters and JavaScript
|
|
- **No code mixing**: JavaScript stays in `.js` files, never embedded in strings
|
|
- Works regardless of installation location
|
|
|
|
**Testing Architecture**
|
|
- **Dual-track testing**: JavaScript tests (Jest) + Python integration tests (pytest)
|
|
- **Python-JS bridge**: `JavaScriptTestRunner` executes JS tests from Python
|
|
- **Test isolation**: Proper setup/teardown with JSDOM environment
|
|
- **Coverage integration**: Combines Python and JavaScript coverage
|
|
|
|
**Component Organization**
|
|
- **Core**: `debug-system.js`, `section-manager.js` - fundamental framework components
|
|
- **Components**: `dom-renderer.js`, `debug-panel.js` - UI rendering components
|
|
- **Controls**: `control-base.js`, `edit-control.js`, `debug-control.js`, `status-control.js`, `contents-control.js` - interactive control panels
|
|
- All components are modular and testable in isolation
|
|
|
|
### Python-JavaScript Bridge
|
|
|
|
The capability provides seamless integration between Python and JavaScript tests:
|
|
|
|
**JavaScriptTestRunner** (`src/testdrive_jsui/testing/js_test_runner.py`):
|
|
- Executes JavaScript tests via subprocess (Node.js + Jest)
|
|
- Parses JSON test results into Python dataclasses (`JSTestResult`)
|
|
- Provides methods: `run_js_tests()`, `run_specific_test()`, `list_available_tests()`
|
|
- Auto-discovers capability root if not specified
|
|
- Validates Node.js environment before execution
|
|
|
|
**Usage Example**:
|
|
```python
|
|
from testdrive_jsui.testing import JavaScriptTestRunner
|
|
|
|
runner = JavaScriptTestRunner()
|
|
result = runner.run_js_tests(coverage=True)
|
|
assert result.success
|
|
assert result.tests_passed > 0
|
|
```
|
|
|
|
### Jest Configuration
|
|
|
|
Located in `package.json` (no separate jest.config.js):
|
|
- **Test environment**: jsdom
|
|
- **Test patterns**: `**/js/tests/**/*.test.js`
|
|
- **Coverage**: Collects from `js/core/`, `js/components/`, `js/utils/`
|
|
- **Setup**: `js/tests/jest.setup.js`
|
|
- **Ignored files**: `refactor-test-runner.js`, `setup.js`
|
|
|
|
### Pytest Configuration
|
|
|
|
Located in `pyproject.toml`:
|
|
- **Test paths**: `tests/`, `src/testdrive_jsui/tests/`
|
|
- **Markers**: `@pytest.mark.javascript` for JS integration tests
|
|
- **Coverage target**: 58% minimum
|
|
- **Addopts**: Strict markers, verbose output, coverage reports
|
|
|
|
## Development Workflow
|
|
|
|
### Adding JavaScript Components
|
|
|
|
1. Create component in appropriate `js/` subdirectory (`core/`, `components/`, `controls/`, etc.)
|
|
2. Write tests in `js/tests/` with naming: `component-name.test.js` or `test-component-name.js`
|
|
3. Run tests: `npm test`
|
|
4. Add Python integration tests if needed in `tests/`
|
|
|
|
### Adding Python Integration
|
|
|
|
1. Create test in `tests/` directory
|
|
2. Use `JavaScriptTestRunner` to execute JS tests from Python
|
|
3. Mark with `@pytest.mark.javascript` for selective test execution
|
|
4. Run: `pytest tests/ -v -m javascript`
|
|
|
|
### Migration Strategy (Copy-First)
|
|
|
|
**Status**: ✅ ALL PHASES COMPLETE - See `MIGRATION_STATUS.md` for full details
|
|
|
|
The capability followed a **copy-first, verify-later** migration principle:
|
|
|
|
**Phase 1: Copy** ✅ COMPLETE (December 16, 2025)
|
|
1. ✅ Copy all original files to `js/` directory
|
|
2. ✅ Verify copies are correct
|
|
3. ✅ Run all tests in capability
|
|
4. ✅ Document current state
|
|
|
|
**Phase 2: Dual-Track Testing** (SKIPPED)
|
|
- Skipped as Phase 1 testing was comprehensive enough
|
|
|
|
**Phase 3: Gradual Switch** ✅ COMPLETE (December 16, 2025)
|
|
1. ✅ Update templates to use capability location
|
|
2. ✅ Test each change individually (view & edit modes)
|
|
3. ✅ Maintain rollback capability (originals preserved)
|
|
4. ✅ Monitor for issues (none found)
|
|
|
|
**Phase 4: Cleanup** ✅ COMPLETE (December 16, 2025)
|
|
1. ✅ Remove original files (29 files deleted)
|
|
2. ✅ Update documentation references
|
|
3. ✅ Archive migration records
|
|
4. ✅ Tag final migration commit
|
|
|
|
**Final State**: Migration **fully complete**. Main app exclusively uses capability location. Legacy files removed. Single source of truth: `/capabilities/testdrive-jsui/js/`. All tests passing. See `MIGRATION_STATUS.md` for complete history.
|
|
|
|
## Common Development Tasks
|
|
|
|
### Running Single Test
|
|
```bash
|
|
# JavaScript
|
|
npm test -- --testNamePattern="specific test name"
|
|
|
|
# Python
|
|
pytest tests/test_specific.py -v
|
|
```
|
|
|
|
### Debugging Tests
|
|
```bash
|
|
# Verbose JavaScript output
|
|
npm run test:verbose
|
|
|
|
# Python with debug output
|
|
pytest tests/ -v -s
|
|
```
|
|
|
|
### Checking Test Coverage
|
|
```bash
|
|
# JavaScript coverage (generates coverage/ directory)
|
|
npm run test:coverage
|
|
|
|
# Python coverage (included in pytest runs)
|
|
pytest tests/ -v --cov=testdrive_jsui --cov-report=html
|
|
```
|
|
|
|
### Development Watch Mode
|
|
```bash
|
|
# Auto-rerun tests on file changes
|
|
make testdrive-jsui-watch
|
|
# or
|
|
npm run test:watch
|
|
```
|
|
|
|
## Important Notes
|
|
|
|
### Code Quality Standards
|
|
- **ESLint**: Standard config with Jest plugin, warns on `console`, errors on `debugger`
|
|
- **Black**: Python formatting with 88 char line length
|
|
- **MyPy**: Strict typing for Python code (can be disabled for tests)
|
|
|
|
### Test Execution Order
|
|
When running `make testdrive-jsui-test-all`:
|
|
1. JavaScript tests (Jest)
|
|
2. JavaScript fixes test (Python-based validation)
|
|
3. Python integration tests (pytest)
|
|
4. HTML manual tests (available for browser testing)
|
|
|
|
### Node.js Requirements
|
|
- Node.js 16+ required for JavaScript testing
|
|
- npm automatically installs dependencies from `package.json`
|
|
- If Node.js unavailable, JavaScript tests gracefully skip with warning
|
|
|
|
### Rendering Modes
|
|
The engine supports two modes:
|
|
- `'edit'`: Interactive editing mode with controls
|
|
- `'view'`: View-only mode
|
|
|
|
Validate modes before rendering:
|
|
```python
|
|
if engine.validate_mode('edit'):
|
|
html = engine.render_document(content, 'edit', config)
|
|
```
|