testdrive-jsui/_jsui/README.md

TestDrive-JSUI External Resources Directory

This directory contains external CSS and JavaScript files used when generating HTML in external resources mode.

Purpose

TestDrive-JSUI HTML generator supports two modes:

1. Standalone mode (default): All CSS/JS embedded inline in HTML file
2. External resources mode: HTML references external files from this _jsui/ directory

Directory Structure

_jsui/
├── README.md (this file)
├── css/
│   ├── base.css           # Base styles
│   ├── editor.css         # Editor styles
│   ├── controls.css       # Control panel styles
│   └── themes/
│       └── github.css     # GitHub theme
└── js/
    ├── core/
    │   ├── event-emitter.js    # Event system
    │   ├── section.js          # Section class
    │   └── section-manager.js  # Section management
    ├── components/
    │   ├── dom-renderer.js     # DOM rendering
    │   └── floating-menu.js    # Floating editor menu
    ├── controls/
    │   ├── control-base.js     # Base control class
    │   ├── edit-control.js     # Edit control panel
    │   ├── status-control.js   # Status control panel
    │   ├── contents-control.js # Contents control panel
    │   └── debug-control.js    # Debug control panel
    ├── utils/
    │   └── html-generator.js   # HTML generation utility
    └── testdrive-jsui.js       # Main library

Usage

External Resources Mode

Generate HTML that references files in this directory:

const generator = new HTMLGenerator({
    title: 'My Document',
    markdown: '# Hello World',
    standalone: false,  // Use external resources
    baseUrl: '_jsui'    // Path to this directory
});

const html = generator.generate();

Generated HTML includes:

<link rel="stylesheet" href="_jsui/css/base.css">
<link rel="stylesheet" href="_jsui/css/editor.css">
<link rel="stylesheet" href="_jsui/css/controls.css">
<link rel="stylesheet" href="_jsui/css/themes/github.css">

<script src="_jsui/js/core/event-emitter.js"></script>
<script src="_jsui/js/core/section.js"></script>
<!-- ... more scripts ... -->

Standalone Mode

Generate HTML with all resources embedded:

const generator = new HTMLGenerator({
    title: 'My Document',
    markdown: '# Hello World',
    standalone: true  // Embed all resources (default)
});

const html = generator.generate();

Generated HTML includes:

<style>
  /* All CSS embedded here */
</style>

<script>
  // All JavaScript embedded here
</script>

When to Use Each Mode

Use External Resources Mode When:

• ✅ Generating multiple HTML files (share resources)
• ✅ Want smaller individual HTML files
• ✅ Need browser caching for performance
• ✅ Easier to debug (separate files)
• ✅ Want to update resources without regenerating HTML

Use Standalone Mode When:

• ✅ Single file portability required
• ✅ Email HTML file to someone
• ✅ No web server available
• ✅ Simplicity (one file, no dependencies)
• ✅ Offline usage (no external dependencies)

Deployment

Copy to Project

Copy this directory to your project:

cp -r capabilities/testdrive-jsui/_jsui /path/to/your/project/

Serve with Web Server

Ensure your web server can serve files from _jsui/:

# Python
python3 -m http.server 8080

# Node.js
npx http-server -p 8080

# PHP
php -S localhost:8080

Access your HTML: http://localhost:8080/your-document.html

Customization

Add Custom Theme

1. Create theme CSS file:

   touch _jsui/css/themes/custom-theme.css
   

2. Define theme styles:

   :root {
       --custom-primary: #8b5cf6;
       --custom-border: #e5e7eb;
       /* ... more variables ... */
   }
   
   .theme-custom-theme .markitect-section {
       /* ... theme styles ... */
   }
   

3. Generate HTML with custom theme:

   const generator = new HTMLGenerator({
       theme: 'custom-theme',
       standalone: false
   });
   

Modify Styles

Edit CSS files in _jsui/css/ to customize appearance.

Note: These are symlinks to source files in static/css/. Changes affect source.

Extend Functionality

Add custom JavaScript:

1. Create file: _jsui/js/custom/my-extension.js
2. Reference in generated HTML:

   <script src="_jsui/js/custom/my-extension.js"></script>
   

File Sizes

Approximate sizes (unminified):

File	Size	Description
css/base.css	~2 KB	Base styles
css/editor.css	~3 KB	Editor styles
css/controls.css	~5 KB	Control panels
css/themes/github.css	~2 KB	GitHub theme
js/testdrive-jsui.js	~20 KB	Main library
js/core/*.js	~15 KB	Core functionality
js/components/*.js	~10 KB	UI components
js/controls/*.js	~25 KB	Control panels

Total: ~82 KB unminified, ~30 KB minified + gzipped

Performance

External Resources Mode

• First load: Download all files (~82 KB)
• Subsequent loads: Browser cache (0 KB)
• Multiple pages: Share cached resources

Standalone Mode

• Every load: Full HTML file (~100+ KB per file)
• No caching: Resources embedded, not cached separately
• Single page: More efficient for one-time use

Troubleshooting

Resources Not Loading

Problem: CSS/JS files return 404 errors

Solutions:

1. Verify _jsui/ directory exists in same directory as HTML
2. Check file paths in HTML match directory structure
3. Ensure web server serves static files
4. Use browser DevTools Network tab to debug

Relative Path Issues

Problem: Resources work locally but not on server

Solution: Use correct base URL:

// For local file://
baseUrl: '_jsui'

// For web server
baseUrl: '/path/to/_jsui'

// For CDN
baseUrl: 'https://cdn.example.com/_jsui'

Symlink Issues (Development)

Problem: Symlinks don't work on Windows

Solution: Copy files instead of symlinking:

# Copy instead of symlink
cp -r static/css/* _jsui/css/
cp -r js/* _jsui/js/

Development

Updating Resources

Files in _jsui/ are symlinked to source files:

• Edit source files in js/ or static/css/
• Changes automatically reflect in _jsui/ (via symlinks)
• No need to manually copy files

Building for Production

1. Minify CSS:

   npx cssnano _jsui/css/*.css
   

2. Minify JavaScript:

   npx terser _jsui/js/**/*.js -c -m
   

3. Bundle (optional):

   # Combine all JS into single file
   cat _jsui/js/**/*.js > _jsui/js/testdrive-jsui.bundle.js
   

Related Documentation

• HTML Generator API (coming soon)
• Themes
• Customization (coming soon)

---

Version: 1.0.0 Last Updated: 2025-12-16