diff --git a/.gitignore b/.gitignore index 49c8491..da9c425 100644 --- a/.gitignore +++ b/.gitignore @@ -180,3 +180,7 @@ node_modules/ # npm package lock file package-lock.json + +# Distribution archives +timeline-svg-dist.zip +timeline-svg-dist.tar.gz diff --git a/CLAUDE.md b/CLAUDE.md index d314bbb..f8ac9ec 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -41,6 +41,22 @@ python3 -m http.server 8000 The application must be served via HTTP (not opened as file://) due to CORS restrictions when loading CSV, CSS, and SVG files. +### Distribution +```bash +make dist # Build distribution package in dist/ +make dist-zip # Build distribution and create archive +``` + +The distribution package includes: +- All runtime files (HTML, JS, CSS) +- Example projects (example/, example-1/, my-project/) +- Documentation (README.md, TEMPLATE_V2_GUIDE.md, TROUBLESHOOTING.md) +- Startup scripts for Windows (start-server.bat) and Linux/Mac (start-server.sh) + +Use this to deploy the application to Windows or other environments. The distribution is self-contained and requires only a web browser and Python (for the local server). + +**For Windows deployment from WSL**: See `WINDOWS_USAGE.md` for detailed instructions on building the distribution in WSL, transferring to Windows, and running the application on Windows OS. + ## Architecture ### Core Components diff --git a/Makefile b/Makefile index 8f95d2c..dc2d5c2 100644 --- a/Makefile +++ b/Makefile @@ -1,4 +1,4 @@ -.PHONY: help install test test-watch test-coverage test-ui clean serve lint format deps-check deps-update +.PHONY: help install test test-watch test-coverage test-ui clean serve lint format deps-check deps-update dist dist-zip # Default target help: @@ -25,6 +25,10 @@ help: @echo " deps-update Update dependencies" @echo " deps-audit Security audit of dependencies" @echo "" + @echo "Distribution:" + @echo " dist Build distribution package in dist/" + @echo " dist-zip Build distribution and create ZIP archive" + @echo "" # Development setup install: @@ -137,4 +141,136 @@ setup: clean install test @echo " • Run 'make test' to run tests" @echo " • Run 'make test-watch' for TDD" @echo " • Run 'make serve' to start development server" - @echo " • Open index.html in browser to use the app" \ No newline at end of file + @echo " • Open index.html in browser to use the app" + +# Distribution build for deployment/Windows +dist: + @echo "Building distribution package..." + @# Create dist directory + @rm -rf dist + @mkdir -p dist + @echo "📦 Created dist/ directory" + + @# Copy core application files + @cp index.html engine.js generator.js dist/ + @echo "✅ Copied core files (index.html, engine.js, generator.js)" + + @# Copy project directories + @cp -r example example-1 my-project dist/ + @echo "✅ Copied project directories (example, example-1, my-project)" + + @# Copy documentation + @cp README.md LICENSE dist/ + @[ -f TEMPLATE_V2_GUIDE.md ] && cp TEMPLATE_V2_GUIDE.md dist/ || true + @[ -f TROUBLESHOOTING.md ] && cp TROUBLESHOOTING.md dist/ || true + @echo "✅ Copied documentation" + + @# Create Windows batch file for serving + @echo '@echo off' > dist/start-server.bat + @echo 'echo Starting Timeline SVG Generator...' >> dist/start-server.bat + @echo 'echo.' >> dist/start-server.bat + @echo 'echo Opening browser at http://localhost:8000' >> dist/start-server.bat + @echo 'echo Press Ctrl+C to stop the server' >> dist/start-server.bat + @echo 'echo.' >> dist/start-server.bat + @echo 'start http://localhost:8000' >> dist/start-server.bat + @echo 'python -m http.server 8000 2^>nul || python3 -m http.server 8000 2^>nul || (echo Python not found. Please install Python or open index.html in a browser. ^& pause)' >> dist/start-server.bat + @echo "✅ Created start-server.bat for Windows" + + @# Create Linux/Mac shell script for serving + @echo '#!/bin/bash' > dist/start-server.sh + @echo 'echo "Starting Timeline SVG Generator..."' >> dist/start-server.sh + @echo 'echo ""' >> dist/start-server.sh + @echo 'echo "Opening browser at http://localhost:8000"' >> dist/start-server.sh + @echo 'echo "Press Ctrl+C to stop the server"' >> dist/start-server.sh + @echo 'echo ""' >> dist/start-server.sh + @echo 'if command -v xdg-open >/dev/null 2>&1; then' >> dist/start-server.sh + @echo ' xdg-open http://localhost:8000 &' >> dist/start-server.sh + @echo 'elif command -v open >/dev/null 2>&1; then' >> dist/start-server.sh + @echo ' open http://localhost:8000 &' >> dist/start-server.sh + @echo 'fi' >> dist/start-server.sh + @echo 'python3 -m http.server 8000 2>/dev/null || python -m SimpleHTTPServer 8000 2>/dev/null || { echo "Python not found. Please install Python or open index.html in a browser."; read -p "Press Enter to exit..."; }' >> dist/start-server.sh + @chmod +x dist/start-server.sh + @echo "✅ Created start-server.sh for Linux/Mac" + + @# Create distribution README + @echo "# Timeline SVG Generator - Distribution Package" > dist/DIST_README.md + @echo "" >> dist/DIST_README.md + @echo "This is a standalone distribution of Timeline SVG Generator." >> dist/DIST_README.md + @echo "" >> dist/DIST_README.md + @echo "## Quick Start" >> dist/DIST_README.md + @echo "" >> dist/DIST_README.md + @echo "### Windows" >> dist/DIST_README.md + @echo "" >> dist/DIST_README.md + @echo "1. Double-click \`start-server.bat\`" >> dist/DIST_README.md + @echo "2. Your browser will open automatically at http://localhost:8000" >> dist/DIST_README.md + @echo "3. The application will load the example project automatically" >> dist/DIST_README.md + @echo "" >> dist/DIST_README.md + @echo "### Linux / Mac" >> dist/DIST_README.md + @echo "" >> dist/DIST_README.md + @echo "1. Run \`./start-server.sh\` (or \`bash start-server.sh\`)" >> dist/DIST_README.md + @echo "2. Your browser will open automatically at http://localhost:8000" >> dist/DIST_README.md + @echo "3. The application will load the example project automatically" >> dist/DIST_README.md + @echo "" >> dist/DIST_README.md + @echo "### Alternative: Open Directly" >> dist/DIST_README.md + @echo "" >> dist/DIST_README.md + @echo "**Note:** Due to browser security restrictions (CORS), opening index.html directly may prevent loading of project files. Using a local server is recommended." >> dist/DIST_README.md + @echo "" >> dist/DIST_README.md + @echo "## Project Structure" >> dist/DIST_README.md + @echo "" >> dist/DIST_README.md + @echo "- \`index.html\` - Main application" >> dist/DIST_README.md + @echo "- \`engine.js\` - Application logic" >> dist/DIST_README.md + @echo "- \`generator.js\` - SVG generation engine" >> dist/DIST_README.md + @echo "- \`example/\` - Simple example project" >> dist/DIST_README.md + @echo "- \`example-1/\` - Enhanced example with styling" >> dist/DIST_README.md + @echo "- \`my-project/\` - Template for your own projects" >> dist/DIST_README.md + @echo "- \`README.md\` - Full documentation" >> dist/DIST_README.md + @echo "- \`TEMPLATE_V2_GUIDE.md\` - Template creation guide" >> dist/DIST_README.md + @echo "" >> dist/DIST_README.md + @echo "## Creating Your Own Timeline" >> dist/DIST_README.md + @echo "" >> dist/DIST_README.md + @echo "1. Copy one of the example folders (e.g., \`example/\`)" >> dist/DIST_README.md + @echo "2. Rename it to your project name" >> dist/DIST_README.md + @echo "3. Edit \`project.json\` to configure your timeline" >> dist/DIST_README.md + @echo "4. Replace \`sample.csv\` with your data" >> dist/DIST_README.md + @echo "5. Customize \`style.css\` and \`template-v2.svg\` as needed" >> dist/DIST_README.md + @echo "6. Load your project in the application using the file upload controls" >> dist/DIST_README.md + @echo "" >> dist/DIST_README.md + @echo "See README.md and TEMPLATE_V2_GUIDE.md for detailed instructions." >> dist/DIST_README.md + @echo "" >> dist/DIST_README.md + @echo "## Troubleshooting" >> dist/DIST_README.md + @echo "" >> dist/DIST_README.md + @echo "If you encounter issues, see TROUBLESHOOTING.md for solutions to common problems." >> dist/DIST_README.md + @echo "✅ Created DIST_README.md" + + @echo "" + @echo "🎉 Distribution package created in dist/" + @echo "" + @echo "Contents:" + @echo " • Core application files (HTML, JS)" + @echo " • Example projects (example, example-1, my-project)" + @echo " • Documentation (README.md, TEMPLATE_V2_GUIDE.md, etc.)" + @echo " • Server startup scripts (start-server.bat, start-server.sh)" + @echo "" + @echo "To use on Windows:" + @echo " 1. Copy the dist/ folder to your Windows machine" + @echo " 2. Double-click start-server.bat to run" + @echo "" + @echo "Or create a ZIP archive with: make dist-zip" + +# Create ZIP archive of distribution +dist-zip: dist + @echo "Creating distribution archive..." + @if command -v zip >/dev/null 2>&1; then \ + cd dist && zip -r ../timeline-svg-dist.zip . -x "*.git*" -x "*.DS_Store" && cd ..; \ + echo "✅ Created timeline-svg-dist.zip"; \ + echo ""; \ + echo "📦 Distribution archive ready: timeline-svg-dist.zip"; \ + echo " Transfer this file to Windows and extract to use the application."; \ + else \ + tar --exclude=".git*" --exclude=".DS_Store" -czf timeline-svg-dist.tar.gz -C dist .; \ + echo "✅ Created timeline-svg-dist.tar.gz (zip not available)"; \ + echo ""; \ + echo "📦 Distribution archive ready: timeline-svg-dist.tar.gz"; \ + echo " Transfer this file to Windows, extract with 7-Zip or similar tool."; \ + echo " Or install zip: sudo apt-get install zip"; \ + fi \ No newline at end of file diff --git a/WINDOWS_USAGE.md b/WINDOWS_USAGE.md new file mode 100644 index 0000000..4d1b7b6 --- /dev/null +++ b/WINDOWS_USAGE.md @@ -0,0 +1,213 @@ +# Using Timeline SVG on Windows + +This guide explains how to use Timeline SVG Generator on Windows after building the distribution in WSL. + +## Building the Distribution (in WSL) + +1. In your WSL terminal, navigate to the project directory: + ```bash + cd /home/worsch/timeline-svg + ``` + +2. Build the distribution package: + ```bash + make dist-zip + ``` + + This creates either `timeline-svg-dist.zip` (if zip is installed) or `timeline-svg-dist.tar.gz`. + +3. The distribution file is now in your project directory and accessible from Windows at: + ``` + \\wsl$\Ubuntu\home\worsch\timeline-svg\timeline-svg-dist.tar.gz + ``` + + Or if you have the WSL path mounted: + ``` + \\wsl.localhost\Ubuntu\home\worsch\timeline-svg\timeline-svg-dist.tar.gz + ``` + +## Transferring to Windows + +### Option 1: Copy from WSL Location + +1. Open Windows Explorer +2. Navigate to `\\wsl$\Ubuntu\home\worsch\timeline-svg\` +3. Copy `timeline-svg-dist.tar.gz` (or `.zip`) to your Windows directory + - Example: `C:\Users\YourName\Documents\timeline-svg\` + +### Option 2: Use Command Line + +In WSL terminal: +```bash +# Copy to Windows user directory +cp timeline-svg-dist.tar.gz /mnt/c/Users/YourName/Documents/ +``` + +Or from Windows PowerShell: +```powershell +# Copy from WSL to Windows +Copy-Item "\\wsl$\Ubuntu\home\worsch\timeline-svg\timeline-svg-dist.tar.gz" -Destination "C:\Users\YourName\Documents\" +``` + +## Extracting on Windows + +### If you have a .zip file: +- Right-click the file → "Extract All..." +- Choose destination folder + +### If you have a .tar.gz file: +- Install 7-Zip (free): https://www.7-zip.org/ +- Right-click → 7-Zip → Extract Here (twice - first for .gz, then for .tar) + +## Running on Windows + +Once extracted, you have several options: + +### Option 1: Use the Batch Script (Easiest) + +1. Double-click `start-server.bat` in the extracted folder +2. A command window will open and your browser will launch automatically +3. The application will be available at http://localhost:8000 +4. To stop the server, close the command window or press Ctrl+C + +**Note:** Requires Python to be installed on Windows. Download from https://www.python.org/ if needed. + +### Option 2: Use Python Directly + +1. Open Command Prompt or PowerShell in the extracted folder +2. Run one of these commands: + ```cmd + python -m http.server 8000 + ``` + or + ```cmd + python3 -m http.server 8000 + ``` +3. Open your browser to http://localhost:8000 + +### Option 3: Use Node.js http-server + +If you have Node.js installed: +```cmd +npx http-server -p 8000 +``` + +### Option 4: Direct File Access (Limited) + +You can open `index.html` directly in your browser, but due to CORS restrictions: +- ✅ UI will load +- ❌ Auto-loading of example projects won't work +- ❌ CSV/template files must be manually uploaded + +**Recommendation:** Use a local server (Option 1-3) for full functionality. + +## Working with Your Own Projects + +### Creating a New Project + +1. Copy one of the example folders (e.g., `example\`) +2. Rename it to your project name +3. Edit the files: + - `project.json` - Configure field mappings and settings + - `sample.csv` - Replace with your timeline data + - `style.css` - Customize colors and fonts + - `template-v2.svg` - Design your timeline layout + +### Loading Your Project + +1. Start the application (using one of the options above) +2. Use the "Load Project" button to upload your `project.json` +3. Or manually upload individual CSV/CSS/SVG files + +## File Paths on Windows + +The application uses forward slashes (`/`) in URLs, which work correctly in browsers on Windows. You don't need to change anything in the code. + +**Example project.json on Windows:** +```json +{ + "name": "My Timeline", + "dataSource": "sample.csv", + "stylesheet": "style.css", + "svgTemplate": "template-v2.svg" +} +``` + +These relative paths work the same way on Windows and Linux when served via HTTP. + +## Troubleshooting on Windows + +### "Python not found" + +Install Python: +1. Download from https://www.python.org/downloads/ +2. **Important:** Check "Add Python to PATH" during installation +3. Restart Command Prompt +4. Try running `start-server.bat` again + +### Port 8000 already in use + +Change the port in `start-server.bat`: +- Edit the file with Notepad +- Change `8000` to another port like `8080` or `3000` +- Update the browser URL accordingly + +### Files not loading (CORS errors) + +- Make sure you're using the local server (not opening index.html directly) +- Check that all project files are in the same directory structure +- Look at browser console (F12) for specific error messages + +### Browser doesn't open automatically + +If `start http://localhost:8000` doesn't work: +- Manually open your browser +- Navigate to http://localhost:8000 +- The application should load normally + +## Syncing Between WSL and Windows + +If you want to develop in WSL but test on Windows: + +### Option 1: Work in WSL-accessible location + +Develop in a Windows folder accessed from WSL: +```bash +cd /mnt/c/Users/YourName/Documents/timeline-svg +``` + +Changes made in WSL are immediately visible in Windows. + +### Option 2: Rebuild distribution after changes + +1. Make changes in WSL +2. Rebuild: `make dist-zip` +3. Copy to Windows +4. Extract and test + +### Option 3: Use the Windows folder directly + +The distribution folder can be used from both environments: +- WSL: `cd /mnt/c/Users/YourName/Documents/timeline-svg/dist` +- Windows: `C:\Users\YourName\Documents\timeline-svg\dist` + +## Performance Notes + +- The application runs entirely in the browser (no backend needed) +- Performance is identical on Windows and Linux +- Large CSV files (>1000 rows) may take a few seconds to process +- SVG generation is client-side and depends on your browser/CPU speed + +## Additional Resources + +- See `README.md` for application overview and features +- See `TEMPLATE_V2_GUIDE.md` for template customization +- See `TROUBLESHOOTING.md` for common issues and solutions + +## Questions or Issues? + +If you encounter problems specific to Windows: +1. Check the browser console (F12 → Console tab) for error messages +2. Verify Python is installed and in PATH +3. Try the alternative server options above +4. Check file permissions (extracted files should be readable)