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:

```javascript
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**:
```html
<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:

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

const html = generator.generate();
```

**Generated HTML includes**:
```html
<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:

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

### Serve with Web Server

Ensure your web server can serve files from `_jsui/`:

```bash
# 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:
   ```bash
   touch _jsui/css/themes/custom-theme.css
   ```

2. Define theme styles:
   ```css
   :root {
       --custom-primary: #8b5cf6;
       --custom-border: #e5e7eb;
       /* ... more variables ... */
   }

   .theme-custom-theme .markitect-section {
       /* ... theme styles ... */
   }
   ```

3. Generate HTML with custom theme:
   ```javascript
   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:
   ```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:

```javascript
// 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:

```bash
# 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**:
   ```bash
   npx cssnano _jsui/css/*.css
   ```

2. **Minify JavaScript**:
   ```bash
   npx terser _jsui/js/**/*.js -c -m
   ```

3. **Bundle** (optional):
   ```bash
   # Combine all JS into single file
   cat _jsui/js/**/*.js > _jsui/js/testdrive-jsui.bundle.js
   ```

## Related Documentation

- [HTML Generator API](../docs/api/html-generator.md) (coming soon)
- [Themes](../docs/features/themes.md)
- [Customization](../docs/customization.md) (coming soon)

---

**Version**: 1.0.0
**Last Updated**: 2025-12-16