# DataViz — v0.1

A dependency-free CSV data visualizer for the [Free Open Tools](https://freeopentools.com/) suite. Upload a CSV, and DataViz parses it, detects column types, aggregates the data, and renders it as charts on a freeform canvas — all in the browser, with no data ever leaving the machine.

Live: [dataviz.freeopentools.com](https://dataviz.freeopentools.com/)

## Features

- **CSV parsing** — automatic delimiter detection (comma, semicolon, tab, pipe), quoted fields with embedded commas and newlines, and per-column type inference (number, date, boolean, text).
- **Canvas workspace** — place multiple charts on a pannable, zoomable canvas. Drag to move, use eight resize handles, snap to a grid, and reorder layers.
- **Seven chart types** — bar / column (vertical or horizontal), line, area, scatter, pie, donut, and histogram; each chart keeps its own settings.
- **Aggregation** — sum, average, count, minimum, maximum, median, or none (raw rows).
- **Grouping and multi-series** — pivot a category column into multiple series, or plot several numeric columns at once.
- **Sorting and top-N** — order categories by X or Y and cap the chart to the top N rows.
- **Presentation controls** — titles, subtitles, axis labels, grid lines, data labels, point markers, legend position, and five color palettes.
- **Export** — canvas or single-chart SVG, 2× PNG, aggregated CSV, and raw CSV.
- **Projects** — save/load JSON projects (including the whole canvas), auto-save to `localStorage`, and optional file-based auto-save.
- **Multi-tab coordination** — BroadcastChannel sync with automatic read-only mode for stale tabs.
- **Undo / redo** — snapshots cover chart geometry and per-chart settings, plus full snapshots when data is loaded.

## Getting Started

DataViz is a static site. Serve the directory with any static server and open `index.html`:

```bash
python3 -m http.server 8000
# then open http://localhost:8000/
```

Or just open `index.html` directly in a browser — no build step, no dependencies.

## Usage

### Loading data

Click **Open CSV** in the toolbar, drag a file onto the canvas, or click **Try sample data** for a built-in 48-row sales dataset (12 months × 4 regions).

### Choosing fields

Open the **Data** tab to see every detected column and its inferred type. Use the **X** button to set the category axis and **Y** to add a numeric value series. Fields can also be assigned from the **Chart** tab.

### Refining the chart

Use the **Chart** tab to set the chart type, aggregation, grouping, sorting, a top-N limit, titles, axis labels, palette, and legend position. Every chart on the canvas has its own settings — select one to edit it.

> **Tip:** With *Aggregate* set to *None*, every CSV row becomes a data point. Switch to *Sum* or *Average* to combine rows that share a category.

### Arranging the canvas

Click **Add Chart** (or a chart-type button with nothing selected) to add another chart. Drag a chart to move it, drag any of its eight handles to resize, and drag empty space to pan (middle-drag or right-drag also pans; two-finger trackpad scroll pans). **Ctrl/Cmd+scroll** or pinch zooms about the cursor, and the toolbar offers **+ / −** and **Fit**. Duplicate, delete, bring-to-front, and send-to-back are in the toolbar and the right-click menu. Selected charts can be nudged with the arrow keys (hold `Shift` for a full grid step).

### Exporting

The **Export** dropdown offers:

| Option | Output |
|---|---|
| Canvas as SVG | Every chart composed onto one vector canvas |
| Canvas as PNG | The whole canvas rasterized at 2× |
| Selected chart (SVG) | Just the selected chart, as vector |
| Selected chart (PNG) | Just the selected chart, at 2× |
| Aggregated data (CSV) | The aggregated values shown in the selected chart |
| Full dataset (CSV) | Every loaded row |

## Chart Types

| Type | Best for | Notes |
|---|---|---|
| Bar / Column | Comparing categories | Vertical or horizontal; multiple series grouped side by side |
| Line | Trends over time | Uses a true numeric/date axis when X is numeric or a date |
| Area | Magnitude over time | Same axis logic as line, with a filled baseline |
| Scatter | Correlation between two numbers | Requires a numeric X; group by a column for colored series |
| Pie | Part-to-whole | Top 12 slices, remainder grouped as “Other” |
| Donut | Part-to-whole with a center hole | Same data rules as pie |
| Histogram | Distribution of one numeric column | Bin count derived from the row count |

## Keyboard Shortcuts

| Shortcut | Action |
|---|---|
| `Ctrl/Cmd+O` | Open CSV |
| `Ctrl/Cmd+S` | Save project |
| `Ctrl/Cmd+N` | New project |
| `Ctrl/Cmd+Z` | Undo |
| `Ctrl/Cmd+Y` | Redo |
| `Alt+T` | Toggle theme |
| `Ctrl/Cmd+\` | Toggle properties panel |
| `Ctrl/Cmd+D` | Duplicate the selected chart |
| `Ctrl/Cmd+0` | Fit the canvas to the window |
| `Delete` | Delete the selected chart |
| Arrow keys | Nudge the selected chart (`Shift` = grid step) |
| `Esc` | Deselect / close the context menu |

## File Structure

```
data visualization/
├── index.html      # Page layout: toolbar, chart canvas, properties panel
├── styles.css      # Ecosystem styles plus DataViz canvas/chart styles
├── ui.js           # Shared UI layer: theme, panel, tabs, log, auto-save, exports
├── app.js          # Domain logic: CSV parsing, aggregation, canvas + SVG chart rendering
├── about/
│   └── index.html  # Standalone about page
├── CNAME           # dataviz.freeopentools.com
└── README.md       # This file
```

`ui.js` is a generic interaction layer and calls back into `app.js` via `window.on*` hooks (`onSave`, `onLoad`, `onExport`, `onChartType`, …). `app.js` exposes `window.getAppState()` and `window.applyAutoSavePayload()` for auto-save and multi-tab sync.

## Technical Details

- **Framework:** vanilla JavaScript (ES5-compatible), no dependencies, no build step
- **Rendering:** hand-built inline SVG — no charting library; charts are DOM nodes on a transformed canvas
- **Parsing:** custom RFC 4180–style CSV parser with delimiter detection
- **Limits:** up to 20,000 rows per dataset; 100-row preview in the Data tab
- **State:** chart objects on a canvas, each with its own config; geometry + config + full-data undo/redo snapshots (40-step history)
- **Theme:** Free Open Tools ecosystem dark/light scheme, persisted in `localStorage`
- **Export:** canvas or single-chart SVG, PNG (2×), aggregated CSV, raw CSV

## Browser Support

Modern evergreen browsers (Chrome, Edge, Firefox, Safari). File System Access API auto-save is available in Chromium-based browsers; other browsers fall back to download-based saving.

## License

Part of the Free Open Tools suite.
# dataviz