coulomb/testdrive-jsui
2
0
Fork 0
generated from coulomb/repo-seed
Code Issues Pull Requests Actions Projects Releases Wiki Activity
Files
main
testdrive-jsui/CLAUDE.md
tegwick 796c04709a feat: implement JavaScript-first TestDriveJSUI library (v1.0.0) 
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>
2025-12-16 12:14:58 +01:00

12 KiB
Raw Permalink Blame History

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

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

# Complete setup (Python + JavaScript dependencies)
make testdrive-jsui-setup

# Check environment status
make testdrive-jsui-status

Testing

# 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

# 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

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:

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

# JavaScript
npm test -- --testNamePattern="specific test name"

# Python
pytest tests/test_specific.py -v

Debugging Tests

# Verbose JavaScript output
npm run test:verbose

# Python with debug output
pytest tests/ -v -s

Checking Test Coverage

# 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

# 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:

if engine.validate_mode('edit'):
    html = engine.render_document(content, 'edit', config)
Reference in New Issue View Git Blame Copy Permalink