chart-factory 0.1.2

package/docs/chart-guide.md

@@ -0,0 +1,872 @@
+# Chart guide — which chart, for which data
+
+> **Generated file — do not edit.** Per-builder entries come from
+> `metadata/*.mjs` (`whenToUse` / `notFor` / `cardinality`; schema in
+> [../metadata/README.md](../metadata/README.md)). Regenerate with
+> `npm run conformance`.
+
+This is the chart-**selection** layer: given your data's shape and the
+question you're answering, which builder to reach for — and when a nearby
+variant is the better call. Option-level support lives in the
+[conformance matrix](conformance-matrix.md), full config in [API.md](API.md),
+and color judgment in the [color guide](color-guide.md).
+
+## Start from the question
+
+| The question | Reach for | When it bends |
+|---|---|---|
+| How has one measure changed over time? | Line.createBasic (dense series: Line.createYearly) | Area.createBasic when filled magnitude-from-zero is the message |
+| How do a few series' trends compare? | Line.createMulti | Past ~6 series: `facet()` or an interactive-legend isolate; same measure across years: Line.createYoY |
+| How does the mix (part-of-whole) change over time? | Area.createStacked | Totals are noise: Area.createNormalized; few periods: Bar.createVerticalStacked; many series, gestalt only: Area.createStreamgraph |
+| How do categories compare on one value? | Bar.createBasic | Ordered/time-ish categories: Bar.createVertical; past ~20 rows: `data.topN` or Table.createSortable |
+| What's the composition per category? | Bar.createStacked | Individual key values matter more than totals: Bar.createGrouped |
+| What changed between exactly two points in time? | Slope.createBasic | Past ~20 items, or gap size beats crossings: Dot.createDumbbell |
+| Signed values around a meaningful zero? | Bar.createDiverging | Deltas that accumulate to a total: Bar.createWaterfall; over time: Line.createGrowthRate |
+| How is one numeric distributed? | Histogram.createBasic | Individuals should stay visible: Scatter.createBeeswarm; countable small n: Dot.createUnitHistogram |
+| How do distributions compare across groups? | BoxPlot.createBasic | ≤4 groups with shape detail: Histogram.createOverlay; individuals visible: Scatter.createBeeswarm |
+| Are two numeric measures related? | Scatter.createBasic | Dense clouds: Scatter.createHexbin / createHeatmap / createContour; identity matters: Scatter.createLogos; same-scale verdict: Scatter.createDiagonal; strategic cells: Scatter.createQuadrant |
+| Part-of-whole at one moment? | Donut.createBasic | More than ~6 slices or close values: Bar.createBasic |
+| How did rankings shift over periods? | Line.createBumpChart | Magnitudes matter, not just order: Line.createMulti |
+| What flows where? | Sankey.createBasic | — |
+| What's the daily rhythm? | Calendar.createHeatmap | — |
+| What happens when, for how long? | Bar.createGantt | — |
+| KPI vs target? | Bar.createBullet | Attainment toward a fixed max: Bar.createProgress |
+| How certain are these estimates? | Dot.createConfidence | Expected range over time: Line.createForecastBand; historical context: Dot.createPercentile |
+| The reader needs exact values? | Table.createSortable | Add scannability: Table.createWithBars / Table.createWithHeatmap / Table.createCombined |
+
+## Start from the data signature
+
+The mechanical route: count your **dimensions** (categorical fields you'd
+group by), note whether one is **temporal** (dates, ordered periods), and
+count your **measures** (numeric fields you'd aggregate). Then look up the
+signature. Where this table and the question table disagree, the question
+wins — the signature narrows candidates, the question picks.
+
+This table also runs at runtime: `ChartFactory.suggest(rows)` profiles the
+fields, applies these rules scored against each builder's cardinality
+ranges, and returns ranked candidates with render-ready configs (see
+[API.md](API.md#suggest-chartfactorysuggest)).
+
+| Signature | Reach for | When it bends |
+|---|---|---|
+| 1 measure, 0 dimensions (many records) | Histogram.createBasic | Individuals should stay visible: Scatter.createBeeswarmHorizontal; countable small n: Dot.createUnitHistogram |
+| 1 categorical + 1 measure | Bar.createBasic (ranked) | Ordered categories: Bar.createVertical; the values are parts of one whole: Donut.createBasic |
+| 1 categorical + 1 measure, many records per category | BoxPlot.createBasic | Individuals visible (<~150/category): Scatter.createBeeswarm; ≤4 groups with shape detail: Histogram.createOverlay |
+| 1 temporal + 1 measure | Line.createBasic | Magnitude-from-zero: Area.createBasic; daily grain: Calendar.createHeatmap; exactly two dates: Slope.createBasic |
+| 1 categorical + 1 temporal + 1 measure | Line.createMulti (series = the categorical) | >~6 categories: `facet()`; composition/mix: Area.createStacked; rank only: Line.createBumpChart; the categorical is "year" of the same measure: Line.createYoY |
+| 2 categorical + 1 measure | Scatter.createHeatmap (categorical mode) | Both small (≤~6 × ≤~8): Bar.createGrouped / Bar.createStacked; exact-value lookup: Table.createWithHeatmap |
+| 2 measures | Scatter.createBasic | Same scale/unit: Scatter.createDiagonal; a defensible center: Scatter.createQuadrant; add a categorical via colors/colorMap |
+| 2 measures, same unit, paired per entity | Dot.createDumbbell | Crossings/rates matter and rows ≤~20: Slope.createBasic; it's an interval, not a pair: Bar.createRange |
+| 3 measures | Scatter.createQuadrant with sizeAccessor | Put the two that must be read on position; size carries the third (read coarsely) |
+| n same-unit measures + 1 categorical | Dot.createBasic | Different units: Table.createCombined — a shared axis forces one unit |
+| 2 measures + temporal, per entity | Scatter.createTrajectory | Only two time points: Scatter.createComet |
+| categorical → categorical + 1 measure (flow) | Sankey.createBasic | — |
+| 1 categorical + temporal interval (start, end) | Bar.createGantt | — |
+
+Signatures this library deliberately doesn't serve: **spatial** (maps) and
+network graphs — application territory.
+
+## When a dimension is temporal
+
+Time changes the defaults. In order:
+
+1. **Count the periods.** Exactly 2 → Slope.createBasic or Dot.createDumbbell.
+   A handful of discrete periods (3–30) → Bar.createVertical (columns are
+   legitimate for discrete time). Dense or continuous → Line/Area; never
+   horizontal bars for time.
+2. **Time goes on x, left → right.** Pass `Date` objects or ISO strings and
+   trend charts switch to a time scale with adaptive tick formatting
+   automatically — don't pre-format dates into strings.
+3. **Match the builder to the temporal question.** Same measure compared
+   across years (seasonality): Line.createYoY. Rank over time:
+   Line.createBumpChart. Composition over time: Area.createStacked /
+   createNormalized. Daily rhythm: Calendar.createHeatmap. Scheduled
+   intervals: Bar.createGantt. Actual → future with uncertainty:
+   Line.createDynamicBand; tracking against an expected range:
+   Line.createForecastBand. Signed change over time: Line.createGrowthRate.
+4. **Mark events, don't add series.** Point-in-time context (launches,
+   policy changes) is an `{type: 'event'}` annotation below the x-axis,
+   not another line.
+
+## Rules that trump chart choice
+
+- **Cardinality first.** Every builder below lists comfortable ranges. When
+  the data exceeds them, don't shrink the marks — reshape the data
+  (`data.topN` with an auto-grayed "Other", `data.rollup` to a coarser
+  grain, `facet()` into small multiples) or move to a denser form.
+- **Rank is not magnitude.** Bump charts and sorted bars show order; if the
+  reader will ask "by how much?", plot the values.
+- **Shares need a whole.** Normalized/donut forms answer "what fraction?" —
+  if anyone will ask "how much total?", keep absolute values in view.
+- **Density forms need density.** Hexbin/contour/KDE/heatmap summarize what a
+  scatter can't show; below their minimum n they invent structure that isn't
+  there. Small n is a feature — show the individuals.
+- **Two time points is a special number.** Slope and dumbbell exist for it;
+  three or more points want a line.
+- **When precision beats perception, use a table.** A chart the reader
+  squints at to extract numbers should have been a table row.
+- **Spend the best encodings on the most important variables.** Perceptual
+  accuracy ranks roughly: position > length > slope/angle > area > color
+  intensity > hue (Cleveland & McGill; Mackinlay). This is why donuts cap at
+  ~6 slices (angle), why heatmap/calendar values read coarsely (color), and
+  why a third measure goes on bubble size only after the two that must be
+  read exactly are on the axes.
+
+## Grounding
+
+The taxonomy here follows the field's standard references: the
+[FT Visual Vocabulary](https://github.com/Financial-Times/chart-doctor/tree/main/visual-vocabulary)
+(question table — its nine data relationships minus spatial),
+Mackinlay's APT expressiveness/effectiveness criteria and the
+[Draco](https://github.com/cmudig/draco2) constraint line (signature table,
+encoding ranking), and Cleveland & McGill's graphical-perception experiments
+(the accuracy ordering above).
+
+## Data-shape cheat sheet
+
+- **Tidy rows, one numeric over ordered x** `{ x, y }` → Line / Area basics.
+- **Wide rows, one field per series** `{ x, key1..keyN }` → stacked/normalized/grouped builders (`keys: [...]`); get there with `data.pivotWider`.
+- **Series-of-arrays** `series: [{ name, data: [{x, y}] }]` → Line.createMulti / createYoY / createTextures.
+- **Category + value** `{ category, value }` → Bar family, BoxPlot (raw mode), beeswarms.
+- **Two values per row** `{ name, before, after }` / `{ name, start, end }` / `{ name, low, high }` → Slope, Dot.createDumbbell, Bar.createRange (aliases are normalized — both spellings work).
+- **Two numerics per record** `{ x, y }` → Scatter family.
+- **Flows** `{ source, target, value }` → Sankey. **Daily** `{ date, value }` → Calendar.
+
+Ranges below are **comfortable ranges, not hard limits** — the point where
+the form starts to degrade, and the moment to reshape or switch.
+
+## Area
+
+### Area.createBasic
+
+Single-series area with line overlay, optional data-point dots, and the shared hover-line tooltip.
+
+- **Use when:** One measure over continuous/ordered x where the filled magnitude from zero is the message — revenue, traffic, cumulative totals.
+- **Not for:** Values without a meaningful zero baseline, or comparing several series (the fill hides crossings) — use Line.createBasic / Line.createMulti.
+- **Comfortable at:** exactly 1 series · 2–500 points
+- **Record:** `{ x: number | Date | ISO string, y: number }`
+
+### Area.createDiverging
+
+Single series filled against a baseline — above in one color, below in another — with the line stroke switching color at the crossing and a solid baseline rule.
+
+- **Use when:** One measure read as above/below a meaningful reference — a long-run average, a target, .500, zero — where the polarity of each stretch is the message (surplus/deficit, hitters’ years vs pitchers’ years).
+- **Not for:** Magnitude-from-zero stories (use Area.createBasic), period-over-period growth rates in percent (Line.createGrowthRate owns that framing), or categorical above/below comparisons (Bar.createDiverging).
+- **Comfortable at:** exactly 1 series · 2–500 points
+- **Record:** `{ x: number | Date | ISO string, y: number }`
+
+### Area.createNormalized
+
+100% stacked area (stackOffsetExpand, y fixed 0-1) with hover-line tooltip showing per-key percentages.
+
+- **Use when:** Share-of-total over time when the changing mix is the message and the absolute total is noise — market share, channel mix.
+- **Not for:** When the total matters (the 100% ceiling hides growth/shrinkage — use Area.createStacked), or very few time points (use Bar.createVerticalNormalized).
+- **Comfortable at:** 2–6 series · 3–200 points
+- **Record:** `{ x: number | Date | ISO string, key1..keyN: number (one field per entry in keys) }`
+
+### Area.createSmoothed
+
+Single-series smoothed (cardinal curve) area with vertical gradient fill, optional dots, and the shared hover-line tooltip.
+
+- **Use when:** A single noisy series where the gestalt trend matters more than exact values — the cardinal curve visibly departs from the data points.
+- **Not for:** Precise value reading or sparse data — smoothing invents curvature between points; use Area.createBasic. For honest smoothing, Line.createCombined shows a real moving average.
+- **Comfortable at:** exactly 1 series · 10–500 points
+- **Record:** `{ x: number | Date | ISO string, y: number }`
+
+### Area.createStacked
+
+Stacked multi-series area with per-key lines and a hover-line tooltip (per-key rows + optional Total footer).
+
+- **Use when:** Part-of-whole composition over time when the total AND the mix both matter — the top edge is the total, layers are the mix.
+- **Not for:** Reading individual series precisely — middle layers have no stable baseline; use Line.createMulti or facet(). Negative values do not stack.
+- **Comfortable at:** 2–6 series · 3–200 points — Past ~6 keys, aggregate the tail with data.topN — a residual "Other" auto-grays.
+- **Record:** `{ x: number | Date | ISO string, key1..keyN: number (one field per entry in keys) }`
+
+### Area.createStreamgraph
+
+Wiggle-offset streamgraph (curveBasis) with smart inline layer labels, hover-line tooltip with share bars, and a highlightKey extra.
+
+- **Use when:** Many-series composition where organic flow and relative rise/fall are the point (genres over decades) — inline labels and highlightKey manage the crowd.
+- **Not for:** Reading values or totals — the wiggle baseline sacrifices both; use Area.createStacked when anyone will ask "how much?".
+- **Comfortable at:** 4–12 series · 10–200 points
+- **Record:** `{ x: number | Date | ISO string, key1..keyN: number (one field per entry in keys) }`
+
+## Line
+
+### Line.createAreaGradient
+
+Single line over a vertical-gradient area fill, hover-line tooltip.
+
+- **Use when:** A single series that needs visual weight without a hard area fill — hero/featured chart styling for the same data Line.createBasic would show.
+- **Not for:** Multi-series comparison, or when the gradient would imply a magnitude-from-zero reading the data cannot support.
+- **Comfortable at:** exactly 1 series · 2–1000 points
+- **Record:** `{ x: number | Date | ISO string, y: number }`
+
+### Line.createBasic
+
+Single line with optional data-point dots and the shared hover-line tooltip.
+
+- **Use when:** The default for one measure over ordered x (usually time) where level and change both need precise reading.
+- **Not for:** Categorical x with no order (Bar.createVertical) or several series (Line.createMulti).
+- **Comfortable at:** exactly 1 series · 2–1000 points
+- **Record:** `{ x: number | Date | ISO string, y: number }`
+
+### Line.createBumpChart
+
+Ranking changes over periods: point-scale x of period labels, inverted rank y, auto-measured side label margins, staggered draw-in animation.
+
+- **Use when:** Rank order changing across a handful of periods — who passed whom; entries and exits (churn) are supported.
+- **Not for:** Magnitudes — rank spacing is uniform, so a 1-vs-2 gap can hide a 10x value gap; use Line.createMulti on the values when "by how much" matters.
+- **Comfortable at:** 2–10 series · 2–12 periods
+- **Record:** `{ name: string, rankings: [{ period: 'string', rank: 'number' }] (need not cover every period — churn supported) }`
+
+### Line.createCombined
+
+Muted raw line + computed trailing moving-average overlay, dual-dot hover tooltip.
+
+- **Use when:** One noisy series shown with both the raw signal (muted) and its computed trailing moving average — smoothing without lying about the data.
+- **Not for:** Comparing different measures (Line.createMulti) or pre-computed smoothed columns (Line.createCumulativeVsMoving).
+- **Comfortable at:** exactly 1 series · 10–1000 points
+- **Record:** `{ x: number | Date | ISO string, y: number }`
+
+### Line.createCumulativeVsMoving
+
+Pre-computed cumulative vs moving-average lines with hot/cold gradient shading between them.
+
+- **Use when:** Two precomputed views of one series — cumulative vs moving average — with hot/cold shading where they diverge (pace vs season average).
+- **Not for:** Raw rows (both columns must be precomputed) or generic two-series comparison — use Line.createMulti.
+- **Comfortable at:** exactly 2 series · 10–1000 points
+- **Record:** `{ x: number | Date | ISO string, cumulative: number, moving: number }`
+
+### Line.createDynamicBand
+
+Actual → forecast handoff: solid actual line, dashed forecast line, expanding band, optional divider at forecastStart.
+
+- **Use when:** Actual history handing off to a forecast at a known date — solid turns dashed with an expanding uncertainty band.
+- **Not for:** Retrospective anomaly detection over a fully-actual series — use Line.createForecastBand or createPulseAnomalies.
+- **Comfortable at:** exactly 1 series · 10–1000 points
+- **Record:** `{ x: number | Date | ISO string, actual: number | null, forecast: number | null, upper: number, lower: number }`
+
+### Line.createForecastBand
+
+Actual line inside a confidence band with dashed anomaly markers where the actual exits the band.
+
+- **Use when:** An actual measure tracked against a precomputed expected range, with anomaly markers where it exits the band — monitoring and backtests.
+- **Not for:** An actual→forecast handoff at a known date (Line.createDynamicBand). The builder draws bands you supply; it does not fit models.
+- **Comfortable at:** exactly 1 series · 10–2000 points
+- **Record:** `{ x: number | Date | ISO string, actual: number, upper: number, lower: number }`
+
+### Line.createGrowthRate
+
+Positive/negative colored line + gradient areas around a zero baseline (symmetric y domain, clip-path split).
+
+- **Use when:** A signed rate oscillating around zero (growth %, net change) — color flips at the zero baseline and the y domain is symmetric.
+- **Not for:** All-positive levels — the symmetric zero-centered domain wastes half the plot; use Line.createBasic.
+- **Comfortable at:** exactly 1 series · 3–500 points
+- **Record:** `{ x: number | Date | ISO string, value: number (± growth rate) }`
+
+### Line.createMulti
+
+Multiple lines on one x axis with a shared hover-line tooltip (all series at nearest x).
+
+- **Use when:** Comparing the trends of a few series on one axis — crossings and relative slopes are the message.
+- **Not for:** More than ~6 lines (spaghetti — use facet(), an interactive-legend isolate, or Line.createBumpChart if only rank order matters).
+- **Comfortable at:** 2–6 series · 2–500 points/series
+- **Record:** series: [{ name?, data: [{ x, y }], color?, yAccessor?, valueFormat?, width?, opacity?, front? }]
+
+### Line.createPulseAnomalies
+
+Band chart whose anomalous points get pulsing dots — flagged via anomalyAccessor or auto-detected as out-of-band.
+
+- **Use when:** Live-monitoring feel: a band chart whose anomalous points pulse — flagged via anomalyAccessor or auto-detected as out-of-band.
+- **Not for:** Static or print output (the pulse is the point) and series with many anomalies — a screen full of pulsing dots reads as alarm, not information.
+- **Comfortable at:** exactly 1 series · 10–1000 points
+- **Record:** `{ x: number | Date | ISO string, actual: number, upper: number, lower: number }`
+
+### Line.createSmoothed
+
+Alias: delegates to Line.createYearly with curve FORCED to d3.curveBasis (L1779-1784) — a user-passed curve is silently overridden.
+
+- **Use when:** The createYearly dense line with forced curveBasis smoothing — noisy dense series where shape beats fidelity.
+- **Not for:** Anything needing faithful values — the curve is forced (a user-passed curve is overridden) and departs from the data; use Line.createYearly, or Line.createCombined for an honest moving average.
+- **Comfortable at:** exactly 1 series · 30–5000 points
+- **Record:** `{ x: number | Date | ISO string, y: number }`
+
+### Line.createTextures
+
+Multi-line chart distinguishing series by dash texture rather than a rotating palette.
+
+- **Use when:** A few series that must stay distinguishable without color — print, single-hue brands, or colorblind-critical contexts (dash textures carry identity).
+- **Not for:** More than ~4 series (dash vocabularies exhaust fast) or series with unaligned point indexes — hover assumes aligned indexes across series.
+- **Comfortable at:** 2–4 series · 2–300 points/series
+- **Record:** series: [{ name?, data, color?, dash?, xAccessor?, yAccessor? }] — dash is an SVG dasharray string ('' = solid); hover assumes ALIGNED point indexes across series (L2185, L2198)
+
+### Line.createYearly
+
+Dense single-series time-series line, no dots, hover-line tooltip.
+
+- **Use when:** A long, dense single series (daily/weekly points over months or years) — no dots, built for point counts where markers would smear.
+- **Not for:** Short series where individual points deserve markers — use Line.createBasic.
+- **Comfortable at:** exactly 1 series · 50–5000 points
+- **Record:** `{ x: number | Date | ISO string, y: number }`
+
+### Line.createYoY
+
+Year-over-year overlay: multiple series on one axis with an emphasis palette (oldest gray → newest blue).
+
+- **Use when:** The same measure compared across years — one series per year with a recency ramp (oldest gray, newest blue); a partial current year is safe.
+- **Not for:** Series that are not the same measure repeated over periods — the emphasis palette implies recency; use Line.createMulti.
+- **Comfortable at:** 2–6 series · 2–400 points/series
+- **Record:** series: [{ name?, data, color?, xAccessor?, yAccessor?, valueFormat?, width?, opacity?, front? }] — one entry per year; hover bisects each series independently (shared addMultiHoverTooltip), so unequal point counts (e.g. a partial current season) are safe
+
+## Slope
+
+### Slope.createAnimated
+
+Slope chart with staggered line-draw animation.
+
+- **Use when:** The two-snapshot slope with staggered draw-in — presentations and scrollytelling where the reveal is part of the story.
+- **Not for:** Dashboards and static/print contexts — the animation replays add nothing after the first view; use createBasic.
+- **Comfortable at:** 2–20 rows · exactly 2 periods
+- **Record:** `{ name: string, before: number, after: number }`
+
+### Slope.createBands
+
+Slope chart over background band zones (default: four quartile bands, yDomain [0, 100]).
+
+- **Use when:** Two-point change read against fixed reference zones (quartiles, grade bands) — did items change tier, not just value?
+- **Not for:** Data without meaningful fixed zones — bands imply thresholds; use createBasic with yDomain instead.
+- **Comfortable at:** 2–20 rows · exactly 2 periods
+- **Record:** `{ name: string, before: number, after: number }`
+
+### Slope.createBasic
+
+Two-column slope chart (before/after) with value/name labels and per-line tooltips.
+
+- **Use when:** Exactly two snapshots (before/after) across many items — every item’s direction and rate of change in one glance.
+- **Not for:** More than two periods (Line.createMulti or createBumpChart) or more than ~20 items (labels collide — use Dot.createDumbbell rows).
+- **Comfortable at:** 2–20 rows · exactly 2 periods
+- **Record:** `{ name: string, before: number, after: number }`
+
+### Slope.createCategorical
+
+Slope chart with one d3.schemeTableau10 color per line.
+
+- **Use when:** The two-snapshot slope when items belong to groups worth coloring — one hue per line from a categorical scheme.
+- **Not for:** Many items — per-item colors stop being readable past ~10 lines; use createTrend or createHighlight to encode less.
+- **Comfortable at:** 2–10 rows · exactly 2 periods
+- **Record:** `{ name: string, before: number, after: number }`
+
+### Slope.createHighlight
+
+Slope chart with one item highlighted (orange) and the rest muted.
+
+- **Use when:** One item’s two-point change against a deliberately muted field — "look at this one" framing.
+- **Not for:** Comparing many items against each other — the muting hides them by design; use createTrend.
+- **Comfortable at:** 3–25 rows · exactly 2 periods
+- **Record:** `{ name: string, before: number, after: number }`
+
+### Slope.createIndexed
+
+Indexed "fan" slope chart: every item starts from one merged origin dot (all before values equal, e.g. indexed to 100) with a baseline hairline at the origin and stacked two-line right labels showing each item's signed percent change.
+
+- **Use when:** Several measures indexed to a common base ("1995 = 100") — which grew, which shrank, and by how much, read as a fan of diverging lines from one origin.
+- **Not for:** Items with genuinely different start values (Slope.createBasic keeps two real columns) or more than two periods (Line.createMulti indexed series).
+- **Comfortable at:** 2–12 rows · exactly 2 periods
+- **Record:** `{ name: string, before: number, after: number }`
+
+### Slope.createTrend
+
+Slope chart with trend coloring (up green, down red, flat gray).
+
+- **Use when:** The two-snapshot slope when direction is the story — up/down/flat coloring sorts winners from losers at a glance.
+- **Not for:** Data where group membership matters more than direction (Slope.createCategorical) or >2 periods (Line.createMulti).
+- **Comfortable at:** 2–20 rows · exactly 2 periods
+- **Record:** `{ name: string, before: number, after: number }`
+
+## Bar
+
+### Bar.createBasic
+
+Horizontal bars with auto-measured category labels left and value labels at bar ends.
+
+- **Use when:** The default categorical comparison — one value per category as ranked horizontal rows; long names fit naturally.
+- **Not for:** More than ~20 rows (aggregate with data.topN or use Table.createSortable) or time-ordered categories (Bar.createVertical / Line).
+- **Comfortable at:** 2–20 rows
+- **Record:** `{ category: string, value: number }`
+
+### Bar.createBullet
+
+Bullet chart: slim measure bar, target tick, and optional qualitative range bands per row.
+
+- **Use when:** KPI vs target with qualitative context bands — dashboard rows where each bar is a different metric, not a category.
+- **Not for:** Plain category comparison without targets (Bar.createBasic) or many rows — bullets reward close reading.
+- **Comfortable at:** 1–8 rows
+- **Record:** `{ category: string, value: number, target: number, ranges: number[]? }`
+
+### Bar.createDiverging
+
+Bars diverging left (negative) / right (positive) from a centered category-label column.
+
+- **Use when:** Signed values around a meaningful zero — surplus/deficit, above/below average, net sentiment.
+- **Not for:** All-positive data (plain bars) or signed deltas that accumulate into a total (Bar.createWaterfall).
+- **Comfortable at:** 2–20 rows
+- **Record:** `{ category: string, value: number (may be negative) }`
+
+### Bar.createGantt
+
+Timeline (Gantt) bars spanning start-end ranges with a bottom time/linear axis, grid, and optional milestones.
+
+- **Use when:** Activities spanning start→end on a shared timeline, with optional milestones — schedules, project phases, eras.
+- **Not for:** Value magnitudes (bar length means duration here, not amount) or dependency graphs — dependencies are app territory.
+- **Comfortable at:** 2–25 rows
+- **Record:** `{ label: string, start: Date | number, end: Date | number }`
+
+### Bar.createGrouped
+
+Grouped horizontal bars (one sub-bar per key per category) with optional progress-style tracks.
+
+- **Use when:** A few keys per category compared side by side with a shared baseline — when individual key values matter more than totals.
+- **Not for:** More than ~4 keys (row count explodes) or when totals are the message (Bar.createStacked).
+- **Comfortable at:** 2–8 rows · 2–4 series
+- **Record:** `{ category: string, <key>: number — one field per entry in keys }`
+
+### Bar.createInline
+
+Horizontal bars with the category label inside the bar (white text) and value at the bar end.
+
+- **Use when:** Basic horizontal bars in tight layouts — the category label sits inside the bar, saving the label column.
+- **Not for:** Short bars or long names (labels overflow the bar) and values near zero — use Bar.createBasic.
+- **Comfortable at:** 2–15 rows
+- **Record:** `{ category: string, value: number }`
+
+### Bar.createLabelAbove
+
+Horizontal bars with the category label above each bar (taller rows, suits long names).
+
+- **Use when:** Categorical bars with long labels — the name above each bar frees the full width for the bar itself.
+- **Not for:** Many rows — the taller two-line rows roughly double vertical cost; past ~12 rows use Bar.createBasic.
+- **Comfortable at:** 2–12 rows
+- **Record:** `{ category: string, value: number }`
+
+### Bar.createLikert
+
+Diverging stacked (Likert) bars centered on neutral; doubles as a population pyramid, with a frame-tween update().
+
+- **Use when:** Ordinal survey scales centered on neutral — agreement distributions per question, negative left / positive right.
+- **Not for:** Keys without a negative→positive order — the diverging center assumes ordinal keys; use Bar.createStacked.
+- **Comfortable at:** 1–12 rows · 3–7 series
+- **Record:** `{ question: string, <key>: number — one field per entry in keys (ordered negative -> positive) }`
+
+### Bar.createProgress
+
+Progress-style bars against a fixed maximum with a background track and value-based coloring.
+
+- **Use when:** Attainment toward a known maximum per item — completion, quota, capacity — with the remaining headroom visible as track.
+- **Not for:** Open-ended values with no defensible maximum — use Bar.createBasic.
+- **Comfortable at:** 1–15 rows
+- **Record:** `{ category: string, value: number (0..maxValue) }`
+
+### Bar.createPyramid
+
+Population pyramid: two opposed magnitudes per category row mirrored around a center axis, with a frame-tween update().
+
+- **Use when:** Two opposed populations mirrored per category band — the classic age pyramid; shape asymmetry is the message.
+- **Not for:** More than two groups (Bar.createGrouped) or precise left-vs-right comparison — mirrored axes read badly for exact gaps; use Dot.createDumbbell.
+- **Comfortable at:** 3–25 rows · exactly 2 series
+- **Record:** `{ category: string, left: number — left-wing magnitude (field name configurable via leftKey), right: number — right-wing magnitude (field name configurable via rightKey) }`
+
+### Bar.createRange
+
+Horizontal floating bars spanning [low, high] per category on a numeric value axis (temperature ranges, salary bands).
+
+- **Use when:** A low→high interval per category — temperature ranges, salary bands — where the extent is the message, not a point value.
+- **Not for:** Point estimates with uncertainty (Dot.createConfidence) or before/after pairs where direction matters (Dot.createDumbbell).
+- **Comfortable at:** 2–20 rows
+- **Record:** `{ name: string, low: number, high: number }`
+
+### Bar.createStacked
+
+Horizontal stacked bars (one segment per series key) with rounded-outer-edge clipping and total labels.
+
+- **Use when:** Composition per category — segment mix across a modest number of keys, with totals labeled at bar ends.
+- **Not for:** Comparing middle segments across rows — only the first segment has a shared baseline; use Bar.createGrouped or Dot.createBasic.
+- **Comfortable at:** 2–15 rows · 2–6 series
+- **Record:** `{ category: string, <key>: number — one field per entry in keys }`
+
+### Bar.createVertical
+
+Vertical (column) bars with band x axis, linear y axis, grid, and optional labels above bars.
+
+- **Use when:** Categorical comparison where x order carries meaning (months, ordered stages) or column form is expected; density-aware labels handle many bands.
+- **Not for:** Long category names (horizontal bars read better) or truly continuous x (Line/Area).
+- **Comfortable at:** 2–60 categories — Past ~25 bands labels auto-thin to round numbers — fine for time-ish x, wrong for names the reader must see; switch to horizontal bars.
+- **Record:** `{ x: string (category), y: number }`
+
+### Bar.createVerticalNormalized
+
+100% stacked vertical columns — each column normalized to percentages of its own total.
+
+- **Use when:** Share-of-total per ordered category (100% columns) — mix shift across periods when totals are noise.
+- **Not for:** When totals matter (createVerticalStacked) — the 100% ceiling hides growth; single-series data.
+- **Comfortable at:** 2–30 categories · 2–6 series
+- **Record:** `{ x: string (category), <key>: number — one field per entry in keys (normalized to % of the row total) }`
+
+### Bar.createVerticalStacked
+
+Vertical stacked columns with rounded-top clipping, layer-by-layer build animation, and segment labels.
+
+- **Use when:** Composition per ordered category — mix plus total per column, few periods (use Area.createStacked when x is dense enough to read as continuous).
+- **Not for:** More than ~6 keys, or comparing middle segments across columns (no shared baseline — Bar.createGrouped or Line.createMulti).
+- **Comfortable at:** 2–30 categories · 2–6 series
+- **Record:** `{ x: string (category), <key>: number — one field per entry in keys }`
+
+### Bar.createWaterfall
+
+Waterfall: signed deltas become cumulative floating bars with sign-based coloring and connector hairlines; total rows re-anchor at zero.
+
+- **Use when:** Signed steps composing a total — how you got from A to B (P&L bridges, headcount changes); total rows re-anchor at zero.
+- **Not for:** Independent signed values that do not accumulate (Bar.createDiverging) or long sequences — past ~15 steps the bridge stops reading.
+- **Comfortable at:** 3–15 steps
+- **Record:** `{ name: string, value: number? — signed delta; ignored on total rows, total: boolean? — true renders the running total from zero (subtotal / grand total) }`
+
+## Scatter
+
+### Scatter.createAnimated
+
+createBasic plus a continuous random-walk animation loop with fading gradient trails (demo/ambient — positions leave the data).
+
+- **Use when:** Ambient/demo motion — a continuous random-walk loop with fading trails for hero sections and loading screens.
+- **Not for:** Any analytical reading — positions leave the data after the first frame; for real movement over time use Scatter.createTrajectory.
+- **Comfortable at:** 5–100 points
+- **Record:** `{ x: number, y: number, category: string?, name: string? }`
+
+### Scatter.createBasic
+
+X/Y scatter with optional category coloring and DOT_STYLES presets.
+
+- **Use when:** The relationship between two numeric measures across records — correlation, clusters, outliers.
+- **Not for:** Dense clouds where dots occlude (≥~500 points — Scatter.createHexbin/createHeatmap/createContour) or one numeric across categories (beeswarm).
+- **Comfortable at:** 10–1000 points
+- **Record:** `{ x: number, y: number, category: string?, name: string? }`
+
+### Scatter.createBeeswarm
+
+Horizontal beeswarm grouped into category rows: value pins x exactly, dots dodge along y (deterministic beeswarmDodge, zero overlap).
+
+- **Use when:** Distribution of one numeric across category rows with every individual visible and its value exact (dodge never distorts value).
+- **Not for:** Large n — the dodge runs out of room around ~150 points per category; use BoxPlot.createBasic or Histogram. Two numerics want a scatter.
+- **Comfortable at:** 1–8 categories · 10–400 points — ~150 points per category row before the swarm outgrows its band.
+- **Record:** `{ value: number, category: string }`
+
+### Scatter.createBeeswarmHorizontal
+
+Single-row horizontal beeswarm (value on x, dodge around the vertical center); renders logos when imageAccessor is given, dots otherwise.
+
+- **Use when:** A single-row horizontal swarm of one numeric — compact strip-plot framing; renders logos automatically when imageAccessor is given.
+- **Not for:** Multiple category rows (createBeeswarm) or large n.
+- **Comfortable at:** 5–150 points
+- **Record:** `{ value: number, category: string?, name: string?, logo: string? }`
+
+### Scatter.createBeeswarmLogos
+
+Vertical single-column beeswarm of images: value pins y exactly, logos dodge along x around the center.
+
+- **Use when:** A vertical swarm of images — small leagues/rosters where each mark must be recognizable.
+- **Not for:** More than ~50 images (logo size vs collision radius stops working) or anonymous data — use createBeeswarmVertical dots.
+- **Comfortable at:** 5–50 points
+- **Record:** `{ value: number, image | logo: string, name: string? }`
+
+### Scatter.createBeeswarmVertical
+
+Vertical beeswarm (value on y), optional single centered column, per-item colors and in-dot text labels.
+
+- **Use when:** One numeric distribution as a vertical swarm — league-table style with per-item colors and in-dot labels; singleColumn for one ungrouped field.
+- **Not for:** Large n (~150 per column max) or when identity needs images — use createBeeswarmLogos.
+- **Comfortable at:** 1–6 categories · 5–300 points
+- **Record:** `{ value: number, category: string?, name: string? }`
+
+### Scatter.createComet
+
+Before/after comets: hollow tail dot, tapered gradient trail, solid head dot per record.
+
+- **Use when:** Before→after movement in 2D — direction and magnitude per entity in a single tapered mark.
+- **Not for:** More than two time points per entity (createTrajectory) or crowded fields — past ~40 comets the tails cross-hatch.
+- **Comfortable at:** 3–40 points
+- **Record:** `{ name: string?, x1: number, y1: number, x2: number, y2: number, category: string? }`
+
+### Scatter.createContour
+
+Filled density contours (d3.contourDensity) with optional contour outlines.
+
+- **Use when:** The smooth shape of a dense 2D distribution — modes and ridges rather than counts; no per-point marks.
+- **Not for:** Small n — below ~100 points contours hallucinate structure; and any use needing per-point identity or tooltips (the surface has no point marks).
+- **Comfortable at:** 100+ points
+- **Record:** `{ x: number (or d[0]), y: number (or d[1]) }`
+
+### Scatter.createDiagonal
+
+Scatter with parallel diagonal offset bands (y − x = constant) for two-metric comparisons (offense vs defense).
+
+- **Use when:** Two metrics on the same scale where above/below the y = x line is the verdict — offense vs defense, expected vs actual.
+- **Not for:** Metrics on different scales — the diagonal and its offset bands are meaningless; use createQuadrant or createBasic.
+- **Comfortable at:** 5–100 points
+- **Record:** `{ x: number, y: number, name: string? }`
+
+### Scatter.createHeatmap
+
+Grid heatmap with two modes: density (bins raw x/y points into a pixel grid, linear scales) and categorical (each record is a cell {x, y, value}, band scales).
+
+- **Use when:** Density mode: where a large x/y cloud concentrates, binned to a pixel grid. Categorical mode: an x×y grid of cell values (day × hour matrices).
+- **Not for:** Small n where individuals should stay visible (Scatter.createBasic); smooth density shape (createContour reads better than a coarse grid).
+- **Comfortable at:** 300+ points — Density mode; categorical mode instead wants one record per grid cell (rows × columns ≲ ~400 cells).
+- **Record:** `{ x: number, y: number, value: number? (categorical mode: cell value; unused in density mode) }`
+
+### Scatter.createHexbin
+
+Hexagonal density binning.
+
+- **Use when:** Dense two-numeric clouds where overplotting hides structure — hexagonal density with counts per cell.
+- **Not for:** Small n (below ~200 points a plain scatter keeps individuals visible and honest).
+- **Comfortable at:** 200+ points
+- **Record:** `{ x: number (or d[0]), y: number (or d[1]) }`
+
+### Scatter.createKDE
+
+2D kernel-density fill (d3.contourDensity, filled levels) with an optional overlay of raw data dots.
+
+- **Use when:** Filled 2D density with an optional overlay of the raw dots — distribution shape plus individuals in one plot.
+- **Not for:** Small n (density smoothing misleads) — and note tooltips exist only on the overlay dots; with showDots: false there is no hover surface.
+- **Comfortable at:** 100–5000 points
+- **Record:** `{ x: number, y: number, name: string? }`
+
+### Scatter.createLogos
+
+X/Y scatter that renders an image (logo) at each point instead of a dot.
+
+- **Use when:** A small scatter where each point’s identity is the story — team or brand images as the marks.
+- **Not for:** More than ~40 points (images occlude and stop being recognizable) or anonymous records — use Scatter.createBasic.
+- **Comfortable at:** 5–40 points
+- **Record:** `{ x: number, y: number, image | imageUrl | logo: string, name: string? }`
+
+### Scatter.createMarginal
+
+Scatter with per-category marginal histograms on the top and right panels.
+
+- **Use when:** A relationship plus each variable’s distribution — per-category histograms on the top and right panels.
+- **Not for:** Mini/tight layouts (the panels need room — aspect 1.25) or many categories (>4 histogram colors blend; use createMarginalSimple).
+- **Comfortable at:** 30–2000 points · 1–4 categories
+- **Record:** `{ x: number, y: number, category: string? }`
+
+### Scatter.createMarginalKDE
+
+Scatter with per-category smoothed KDE curves (Epanechnikov kernel) in the top and right marginal panels instead of histograms.
+
+- **Use when:** The marginal scatter with smoothed KDE curves instead of histograms — polished editorial framing of the same question.
+- **Not for:** Small n per category — smooth curves over a handful of points imply distributions the data cannot support; use createMarginal or createMarginalSimple.
+- **Comfortable at:** 50–2000 points · 1–4 categories
+- **Record:** `{ x: number, y: number, category: string? }`
+
+### Scatter.createMarginalSimple
+
+Single-color scatter with rug-mark marginals (tick lines on the bottom and left edges) instead of histogram panels.
+
+- **Use when:** A relationship with lightweight rug-mark marginals — distribution context without the panel cost.
+- **Not for:** Large n — rug ticks smear solid past a few hundred points; use createMarginal.
+- **Comfortable at:** 20–500 points
+- **Record:** `{ x: number, y: number, name: string? }`
+
+### Scatter.createQuadrant
+
+Four-quadrant analysis scatter with switchable center (average/zero/median or explicit centerX/centerY), tinted quadrant backgrounds, corner labels, and optional bubble sizing.
+
+- **Use when:** Classifying items into four strategic cells around a defensible center — share × growth, effort × impact; optional bubble sizing for a third measure.
+- **Not for:** Data with no meaningful center (plain scatter — a forced center implies a verdict) or dense clouds where labels and tooltips crowd.
+- **Comfortable at:** 5–100 points
+- **Record:** `{ x: number, y: number, category: string?, name: string?, size: number? }`
+
+### Scatter.createTrajectory
+
+Connected Catmull-Rom path trail per entity with start (hollow) and end (solid, hoverable) dots.
+
+- **Use when:** Entities moving through a 2D metric space over time — each smoothed path is one entity’s history, start hollow, end solid.
+- **Not for:** Many entities (paths tangle past ~10) or single-snapshot data (Scatter.createBasic); for just two time points use createComet.
+- **Comfortable at:** 1–10 series · 2–20 points/series
+- **Record:** Array of { name, category?, points: [{ x: number, y: number }, ...] } — point coordinates are fixed keys (no x/y accessors).
+
+## Dot
+
+### Dot.createBasic
+
+Multi-category dot row chart — one dot per category per row on a shared value axis.
+
+- **Use when:** Several measures per row compared as dots on one shared axis — compact multi-metric comparison without bar ink.
+- **Not for:** One value per row (Bar.createBasic ranks faster) or measures on different scales — a shared axis forces one unit.
+- **Comfortable at:** 2–20 rows · 2–5 series
+- **Record:** `{ name: string, <categories[i].key>: number — one field per entry in categories }`
+
+### Dot.createComet
+
+Before→after comet rows — gradient tail into a head dot, trend-colored, optionally animated.
+
+- **Use when:** Before→after per row rendered as motion — a gradient tail into a trend-colored head; more energetic than a dumbbell.
+- **Not for:** Neutral/analytical contexts where the motion metaphor overstates — use createDumbbell.
+- **Comfortable at:** 2–20 rows
+- **Record:** `{ name: string, before: number, after: number }`
+
+### Dot.createConfidence
+
+Point estimate + confidence-interval band per row, with automatic significance coloring vs a control row.
+
+- **Use when:** Point estimates with confidence intervals per row, auto-colored for significance vs a control row — experiment readouts.
+- **Not for:** Data without real intervals — drawing invented CIs is worse than none; use Dot.createBasic.
+- **Comfortable at:** 2–15 rows
+- **Record:** `{ name: string, value: number, ci_low: number, ci_high: number, isControl: boolean? }`
+
+### Dot.createDumbbell
+
+Dumbbell row chart — two dots per row joined by a connector, with optional value labels.
+
+- **Use when:** Two values per row (before/after, A vs B) with the gap as the message — scales to more rows than a slope chart because rows do not cross.
+- **Not for:** More than two values per row (Dot.createBasic) or when crossing/rate-of-change matters more than gap size (Slope.createBasic).
+- **Comfortable at:** 2–25 rows
+- **Record:** `{ name: string, start: number, end: number }`
+
+### Dot.createGradient
+
+Dumbbell row chart with a gradient connector fading startColor→endColor to show direction.
+
+- **Use when:** A dumbbell whose connector fades start→end color — adds direction when rows move both ways and the reader must see which way.
+- **Not for:** When plain gap size suffices (createDumbbell) or when color already encodes a category — two color meanings collide.
+- **Comfortable at:** 2–25 rows
+- **Record:** `{ name: string, start: number, end: number }`
+
+### Dot.createPercentile
+
+Value dot over a temperature-colored percentile-band strip per row.
+
+- **Use when:** A value in the context of its historical percentile bands per row — "how unusual is this?" (temperature vs climatology).
+- **Not for:** Rows without a percentile history to stand on; for plain low/high extents use Bar.createRange.
+- **Comfortable at:** 1–15 rows
+- **Record:** `{ name: string (or season), value: number, p0: number, p10..p100: number — one field per entry in percentileKeys }`
+
+### Dot.createUnitHistogram
+
+Unit histogram — one circle per unit stacked vertically per category bin; both dimensions derived from data.
+
+- **Use when:** Small-count distributions where each unit is real and countable — one circle per unit, stacked per bin.
+- **Not for:** Counts beyond a few hundred (units blur into texture — Histogram.createBasic). Also the one fixed-size builder: it never fills its container.
+- **Comfortable at:** 10–300 units · 2–15 bins
+- **Record:** `{ category: string, count: number }`
+
+## Histogram
+
+### Histogram.createBasic
+
+Single-series distribution histogram over a numeric field, with count/percent/density/cumulative y modes.
+
+- **Use when:** The shape of one numeric distribution — skew, modes, spread — with count/percent/density/cumulative y modes.
+- **Not for:** Small n (below ~30, show the individuals: beeswarm or Dot.createUnitHistogram) or categorical data (Bar.createBasic).
+- **Comfortable at:** 30+ points · 5–60 bins
+- **Record:** `{ value: number (field picked by valueAccessor) }`
+
+### Histogram.createOverlay
+
+Multi-series histogram over shared bin edges — translucent overlay by default, side-by-side grouped columns via style.
+
+- **Use when:** Comparing a few distributions on shared bin edges — translucent overlay by default, grouped columns via style.
+- **Not for:** More than ~4 series (translucent overlays turn to mud — use facet() or BoxPlot.createBasic).
+- **Comfortable at:** 2–4 series · 60+ points
+- **Record:** `{ value: number (field picked by valueAccessor) }`
+
+## Donut
+
+### Donut.createBasic
+
+Share-of-whole arc chart — donut by default (innerRatio 0 = pie), min-slice "Other" aggregation, collision-managed callout labels.
+
+- **Use when:** Part-of-whole at a single moment with a handful of slices; minSlice sweeps the tail into an auto-grayed "Other".
+- **Not for:** More than ~6 slices or close values — angles compare worse than lengths (Bar.createBasic); composition over time (Area.createStacked).
+- **Comfortable at:** 2–6 slices
+- **Record:** `{ label: string, value: number >= 0 }`
+
+## BoxPlot
+
+### BoxPlot.createBasic
+
+Five-number distribution boxes per category — raw rows or precomputed stats, Tukey/min-max whiskers, outliers, both orientations, deterministic jitter overlay.
+
+- **Use when:** Summarizing distributions across categories when n is too large to show individuals — five-number boxes, whiskers, outliers.
+- **Not for:** Small n per group (below ~5 the summary misleads — beeswarm shows the truth) or audiences unfamiliar with quartiles (histogram reads plainly).
+- **Comfortable at:** 1–15 categories · 5+ points — points = per-group n in raw mode; precomputed-stats mode has no minimum.
+- **Record:** `{ category: string, value: number }`
+
+## Calendar
+
+### Calendar.createHeatmap
+
+Calendar heatmap — GitHub-style weekly grid, a month-per-row layout, or a vertical wall-calendar transpose; subtle month gutters; missing days render as quiet track cells.
+
+- **Use when:** A daily metric’s rhythm over months or years — weekday patterns, streaks, seasonal texture; missing days render as quiet track cells.
+- **Not for:** Non-daily data (aggregate first or use a line) and precise value comparison — color encodes value far more coarsely than position.
+- **Comfortable at:** 30–1100 days
+- **Record:** `{ date: 'YYYY-MM-DD' string or Date, value: number }`
+
+## Sankey
+
+### Sankey.createBasic
+
+Flow diagram over link rows; nodes derived in first-appearance order, gradient ribbons by default, transitive hover highlighting.
+
+- **Use when:** Quantities flowing from sources to targets — budgets, funnels, energy balances; ribbon width is the amount and flows conserve.
+- **Not for:** Non-flow relationships or cyclic graphs (source→target must be acyclic); past ~30 nodes the diagram stops being readable.
+- **Comfortable at:** 4–30 nodes · 3–60 links
+- **Record:** `{ source: string, target: string, value: number > 0 }`
+
+## Table
+
+### Table.createBasic
+
+Non-sortable DOM table (selector is an element ID without "#", targeting a <table>, or any container element — a <table><thead><tbody> is created inside non-table targets, and an unmatched id console.warns instead of failing silently).
+
+- **Use when:** Exact values the reader will look up — when precision beats pattern; short, fixed-order lists.
+- **Not for:** Perceiving trends or comparisons (that is what charts are for) or lists the reader will want to rank — use Table.createSortable.
+- **Comfortable at:** 1–50 rows · 2–10 columns
+- **Record:** Flat row object keyed by columns[].key — values string | number; bar/heatmap column values are parseFloat()ed (non-numeric → 0).
+
+### Table.createCombined
+
+Sortable DOM table combining bar cells and heatmap cells (pass both barColumns and heatmapColumns; no missing-config warning, d3-chart-factory.js L11633-11636).
+
+- **Use when:** The dashboard-grade table: bar columns for magnitudes plus heatmap columns for rates, in one sortable surface.
+- **Not for:** Simple lists — reach for the lighter table variants first; every treated column adds scan cost.
+- **Comfortable at:** 2–100 rows · 3–12 columns
+- **Record:** Flat row object keyed by columns[].key — values string | number; bar/heatmap column values are parseFloat()ed (non-numeric → 0). Bar domain [0, max]; heatmap domain [min, max].
+
+### Table.createSortable
+
+Sortable DOM table with click-to-sort headers and sort indicators (selector is an element ID without "#", targeting a <table>, or any container element — a <table><thead><tbody> is created inside non-table targets, and an unmatched id console.warns instead of failing silently).
+
+- **Use when:** Lookup plus reader-driven ranking — click-to-sort columns for lists where different readers care about different columns.
+- **Not for:** Data with one obvious story — a chart tells it faster; sorting is for exploration, not narration.
+- **Comfortable at:** 2–100 rows · 2–10 columns
+- **Record:** Flat row object keyed by columns[].key — values string | number; bar/heatmap column values are parseFloat()ed (non-numeric → 0).
+
+### Table.createWithBars
+
+Sortable DOM table with animated percent-bar cells in designated columns (console.warn if barColumns is missing, d3-chart-factory.js L11606-11608).
+
+- **Use when:** A sortable table where one or two numeric columns deserve at-a-glance magnitude — in-cell percent bars beside the numbers.
+- **Not for:** Many bar columns (past two, the table reads as a failed bar chart — use Bar.createBasic per metric or Dot.createBasic).
+- **Comfortable at:** 2–100 rows · 2–10 columns
+- **Record:** Flat row object keyed by columns[].key — values string | number; bar column values are parseFloat()ed (non-numeric → 0) and scaled against [0, max].
+
+### Table.createWithHeatmap
+
+Sortable DOM table with heatmap-box cells (auto-contrast text) in designated columns (console.warn if heatmapColumns is missing, d3-chart-factory.js L11621-11623).
+
+- **Use when:** A sortable table where value intensity should pop — heatmap cells (sequential or diverging) behind the numbers.
+- **Not for:** Precise cross-column comparison of the tinted values — color supports scanning, not reading; keep the numbers visible.
+- **Comfortable at:** 2–100 rows · 2–12 columns
+- **Record:** Flat row object keyed by columns[].key — values string | number; heatmap column values are parseFloat()ed (non-numeric → 0) and scaled against [min, max].
+