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:

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

xxx