189 lines
4.7 KiB
Markdown
189 lines
4.7 KiB
Markdown
# README **TimelineSvg**
|
||
|
||
**TimelineSvg** is a lightweight, browser-based system for generating multi-lane timelines as clean, scalable SVG graphics.
|
||
It reads simple CSV files, applies a configurable project definition, and renders a fully customizable timeline without requiring any backend or build pipeline.
|
||
|
||
All processing happens locally in the user’s browser — completely offline and fully private.
|
||
|
||
---
|
||
|
||
## **Features**
|
||
|
||
* **Pure browser execution** — no server, no installation
|
||
* **CSV-driven timelines** with customizable field mappings
|
||
* **Automatic layout** of months, lanes, and items
|
||
* **SVG templates with macros** (`{{MONTHS}}`, `{{LANES}}`)
|
||
* **Replaceable CSS and templates at runtime**
|
||
* **Internal and external view modes**
|
||
* **Offline SVG export** (external view only)
|
||
* **Extremely easy to extend or theme**
|
||
|
||
---
|
||
|
||
## **How It Works**
|
||
|
||
TimelineSvg is built around three components:
|
||
|
||
### **1. `project.json` — The project configuration**
|
||
|
||
Each project folder provides a `project.json`, defining:
|
||
|
||
```json
|
||
{
|
||
"name": "Example Project",
|
||
"dataSource": "example/sample.csv",
|
||
"stylesheet": "example/style.css",
|
||
"svgTemplate": "example/template.svg",
|
||
"settings": {
|
||
"timelineMonths": 18
|
||
},
|
||
"fieldMapping": {
|
||
"id": "ID",
|
||
"title": "Title",
|
||
"lane": "Lane",
|
||
"due": ["Due"]
|
||
}
|
||
}
|
||
```
|
||
|
||
This controls:
|
||
|
||
* data source
|
||
* styling
|
||
* template structure
|
||
* date range
|
||
* field mapping between CSV and internal timeline model
|
||
|
||
### **2. CSV input**
|
||
|
||
The CSV must contain at least:
|
||
|
||
* a title
|
||
* a date (any common format: `YYYY-MM-DD`, `DD.MM.YYYY`, etc.)
|
||
* a lane/group field
|
||
|
||
Example:
|
||
|
||
```csv
|
||
ID,Title,Due,Lane
|
||
1,Implement API,2025-12-01,Backend
|
||
2,UI Prototype,2026-02-15,Frontend
|
||
```
|
||
|
||
### **3. Template-based SVG rendering**
|
||
|
||
TimelineSvg replaces two macros in the template:
|
||
|
||
* `{{MONTHS}}` → month labels and vertical grid lines
|
||
* `{{LANES}}` → lane backgrounds, labels, and items
|
||
|
||
Example template:
|
||
|
||
```svg
|
||
<svg xmlns="http://www.w3.org/2000/svg">
|
||
<rect width="100%" height="100%" fill="#FFFFFF"/>
|
||
{{MONTHS}}
|
||
{{LANES}}
|
||
</svg>
|
||
```
|
||
|
||
This makes TimelineSvg highly customizable:
|
||
You can recreate any design, layout, or branding using your own SVG template.
|
||
|
||
---
|
||
|
||
## **Usage**
|
||
|
||
### **1. Open the application**
|
||
|
||
Just open `index.html` in any modern browser (Chrome, Firefox, Safari, Edge).
|
||
|
||
### **2. Load a project**
|
||
|
||
You can choose between:
|
||
|
||
* **Automatic loading** - When served via HTTP, the app auto-loads from `project.json` in project folders (binect/, my-project/, or example/)
|
||
* **Load Project Folder** - Click "📂 Load Project Folder" and select an entire project directory. All files (project.json, CSV, CSS, SVG) will be loaded automatically
|
||
* **Load files individually** - Upload project.json first, then manually upload CSV, CSS, and SVG files using the individual file buttons
|
||
|
||
### **3. Preview the timeline**
|
||
|
||
The timeline renders automatically when the CSV loads and is displayed inside the viewer container.
|
||
|
||
### **4. Switch views**
|
||
|
||
* **Internal View:** IDs are visible
|
||
* **External View:** IDs are hidden (used for export)
|
||
|
||
### **5. Export SVG**
|
||
|
||
Click **Download SVG**
|
||
→ an external-view SVG is saved to disk.
|
||
|
||
---
|
||
|
||
## **Project Structure**
|
||
|
||
```
|
||
/
|
||
│ index.html
|
||
│ engine.js
|
||
│ generator.js
|
||
│
|
||
├─ example/
|
||
│ ├─ project.json
|
||
│ ├─ style.css
|
||
│ ├─ template.svg
|
||
│ └─ sample.csv
|
||
│
|
||
└─ my-project/
|
||
├─ project.json
|
||
├─ style.css
|
||
├─ template.svg
|
||
└─ data.csv
|
||
```
|
||
|
||
---
|
||
|
||
## **Customizing Your Own Project**
|
||
|
||
To create your own timeline project:
|
||
|
||
1. Duplicate the `example/` folder
|
||
2. Adjust `project.json` (dataSource, mappings, template)
|
||
3. Replace the CSV with your data
|
||
4. Modify the SVG template for your layout
|
||
5. Open `index.html` and load your project
|
||
|
||
TimelineSvg will take care of the rest.
|
||
|
||
---
|
||
|
||
## **Why SVG?**
|
||
|
||
* infinitely scalable
|
||
* editable in design tools
|
||
* embeddable in documents, websites, and presentations
|
||
* easy to script, style, and customize
|
||
|
||
---
|
||
|
||
## **Requirements**
|
||
|
||
* Any modern browser
|
||
* No build tools
|
||
* No server
|
||
* No dependencies except PapaParse (bundled by CDN)
|
||
|
||
---
|
||
|
||
## **Release checklist (offline distribution)**
|
||
|
||
Before tagging a release or handing the tool to non-developers:
|
||
|
||
1. `make test` — Vitest suite green
|
||
2. `make dist` — verify `dist/` contains core JS, sample projects, `DIST_README.md`, `start-server.bat`, `start-server.sh`
|
||
3. `make dist-zip` — archive builds (`timeline-svg-dist.zip` or `.tar.gz`)
|
||
4. Smoke on Windows per `WINDOWS_USAGE.md` (double-click `start-server.bat`, load `example/` project)
|
||
5. Smoke locally: `make serve` → open `http://localhost:8000`, export SVG from `my-project/`
|
||
6. Confirm `example/` and `my-project/` `project.json` + CSV + `template-v2.svg` load without console errors
|