generated from coulomb/repo-seed
docs: comprehensive feature documentation and HTML generation system
Added complete documentation for all TestDrive-JSUI controls and features, plus flexible HTML generation system supporting standalone and external modes. Documentation (8 files, 3,533 lines): - docs/features/README.md: Central hub with overview, config, examples - docs/features/section-editing.md: Section editing guide - docs/features/edit-control.md: Document actions and editing tools - docs/features/status-control.md: Real-time statistics and tracking - docs/features/contents-control.md: Table of contents navigation - docs/features/debug-control.md: Development and debugging tools - docs/features/keyboard-shortcuts.md: Complete shortcuts reference - docs/features/themes.md: Visual theming and customization HTML Generation System (3 files, 1,104 lines): - js/utils/html-generator.js: Dual-mode HTML generator class * Standalone mode: All CSS/JS embedded inline * External mode: References _jsui/ directory * Configurable options for title, content, controls, theme * Download and save functionality - _jsui/ directory: External resources structure * README.md: Comprehensive usage guide * css/: Symlinked CSS files (base, editor, controls, themes) * js/: Symlinked JavaScript files (core, components, controls) * Enables smaller HTML files with browser caching - examples/html-generator-demo.html: Interactive demo * Web-based configuration form * Side-by-side mode comparison * Live generation and preview * Download and copy functionality Key Features: - 4,637 total lines of documentation and code - All controls documented with examples and troubleshooting - Flexible deployment options (standalone vs external) - Developer-friendly structure with clear guides - Production-ready system 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
291
_jsui/README.md
Normal file
291
_jsui/README.md
Normal file
@@ -0,0 +1,291 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user