D3.js Visualization

# D3.js Visualization

Build interactive data visualizations with D3.js when the chart you need doesn't
exist in any chart library — bespoke layouts, custom transitions, fine-grained
control.

## Keywords
d3, d3.js, d3js, data visualization, dataviz, svg, scales, axes, transitions,
force layout, tree layout, sankey, chord, hierarchy, geo, projection, scatter,
brush, zoom, interactive chart, custom chart

## Core Truth

D3 is the right tool when you need control no library gives you. It's the wrong
tool when recharts, chart.js, or plotly would do the job. The learning curve
isn't worth it for a basic bar chart.

D3 thinks in:
1. **Data joins** — binding data to DOM elements
2. **Scales** — mapping data domain to visual range
3. **Selections** — d3-flavored DOM manipulation
4. **Transitions** — interpolation between states

Get these four and 80% of D3 makes sense.

---

## 1. When To Use D3 (vs alternatives)

| Want | Use |
|------|-----|
| Bar / line / pie / scatter | recharts or chart.js |
| Dashboard with several standard charts | recharts |
| Quick exploratory chart | plotly |
| Geographic map | leaflet or d3 |
| Network/force-directed graph | d3 (no good library alternative) |
| Sankey, chord, sunburst | d3 (libraries don't cover these well) |
| Custom transitions / animations | d3 |
| Million-point scatter | canvas + d3 scales |

## 2. The Margin Convention

Every D3 chart starts here:
```js
const margin = {top: 20, right: 30, bottom: 40, left: 50};
const width = 800 - margin.left - margin.right;
const height = 400 - margin.top - margin.bottom;

const svg = d3.select("#chart")
  .append("svg")
    .attr("width", width + margin.left + margin.right)
    .attr("height", height + margin.top + margin.bottom)
  .append("g")
    .attr("transform", `translate(${margin.left},${margin.top})`);
```

Skip this and your axes will be clipped.

## 3. Scales — The Heart of D3

| Data | Scale |
|------|-------|
| Continuous numbers | `scaleLinear` |
| Time | `scaleTime` |
| Logarithmic data | `scaleLog` |
| Categories | `scaleBand` (for bars) or `scaleOrdinal` |
| Color from values | `scaleSequential` (continuous) or `scaleOrdinal` (categorical) |

Scales have `.domain()` (data extent) and `.range()` (visual extent). Always
set both.

## 4. The Data Join

```js
const update = svg.selectAll("circle").data(data);
update.exit().remove();
const enter = update.enter().append("circle");
enter.merge(update)
  .attr("cx", d => x(d.x))
  .attr("cy", d => y(d.y));
```

Modern D3 has `.join()` which simplifies this:
```js
svg.selectAll("circle")
  .data(data)
  .join("circle")
    .attr("cx", d => x(d.x))
    .attr("cy", d => y(d.y));
```

Use `.join()` unless you need enter/update/exit differently.

## 5. Common Chart Recipes

- **Bar chart** — scaleBand for x, scaleLinear for y, `<rect>` elements
- **Line chart** — `d3.line()` generator, single `<path>`
- **Scatter** — `<circle>` elements, no generator needed
- **Force-directed** — `d3.forceSimulation()` with link, charge, center forces
- **Tree** — `d3.tree()` or `d3.cluster()` layout
- **Sankey** — `d3-sankey` plugin
- **Geo map** — `d3.geoPath()` + projection

## 6. Interactivity Patterns

- **Hover tooltip** — `.on("mouseover", ...)` updates a `<div>` positioned absolute
- **Click to filter** — toggle class, re-render dependent charts
- **Brush** — `d3.brushX()` for range selection
- **Zoom** — `d3.zoom()` for pan/zoom

## 7. Performance

D3 + SVG handles up to ~10,000 elements smoothly. Beyond that:
- Canvas for hot paths (lots of moving elements)
- WebGL (regl, deck.gl) for millions of points
- Server-side rendering for static charts

## 8. Common Pitfalls

| Problem | Cause | Fix |
|---------|-------|-----|
| Axis labels clipped | No margin convention | Always use the margin pattern |
| Transitions janky | Animating non-transform CSS | Animate transform/opacity, not width/height |
| Tooltip lags | Updating DOM on every mousemove | Throttle or use rAF |
| Wrong scale range | Forgot to call `.range()` | Set domain AND range |
| Data join "blinks" | Re-binding entire dataset | Use key function in `.data(data, d => d.id)` |

## 9. Key Questions Before Starting

- Can a library handle this — recharts, plotly?
- How many data points?
- Interactive or static?
- Mobile or desktop?
- One-shot visualization or part of a dashboard?

## References
- `references/d3-margin-convention.md` — Boilerplate
- `references/d3-scales.md` — Scale picker
- `references/d3-chart-recipes/` — 12 working charts
- `references/d3-performance.md` — When to switch to canvas