timeline-svg/README.md

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:

{
  "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:

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 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