@ruckc/truss-chart 1.6.0 → 1.8.0

package/dist/BarChart.svelte

@@ -2,7 +2,7 @@
 	import ChartFrame from './ChartFrame.svelte';
 	import Tooltip from './Tooltip.svelte';
 	import type { Series } from './types.js';
-	import { fmtAxis, fmtValue, linear, niceTicks, seriesColor, MAX_SERIES } from './util.js';
+	import { fmtAxis, fmtValue, linear, str, niceTicks, seriesColor, MAX_SERIES } from './util.js';
 
 	let {
 		categories,
@@ -13,6 +13,8 @@
 		stacked = false,
 		horizontal = false,
 		showValues = false,
+		reference,
+		details,
 		yFormat = fmtValue
 	}: {
 		categories: string[];
@@ -28,11 +30,16 @@
 		horizontal?: boolean;
 		/** Label the end of each bar (the stack total when stacked). */
 		showValues?: boolean;
+		/** One or more labelled reference lines (a target, a limit, an average) drawn across the plot at a value on the value axis. They extend the axis domain so they are always visible. */
+		reference?: Ref | Ref[];
+		/** Extra text per category (same order as `categories`), shown under the category name in the tooltip and as a Details column in the table view. */
+		details?: string[];
 		yFormat?: (n: number) => string;
 	} = $props();
 
+	type Ref = { value: number; label?: string };
 	let hidden = $state<string[]>([]);
-	type Tip = { x: number; y: number; cat: string; name: string; value: number; color: string; share?: number };
+	type Tip = { x: number; y: number; cat: string; name: string; value: number; color: string; share?: number; detail?: string };
 	let tip = $state<Tip | null>(null);
 
 	const all = $derived(series.slice(0, MAX_SERIES).map((s, i) => ({ ...s, i, color: s.color ?? seriesColor(i) })));
@@ -41,7 +48,6 @@
 	const toggle = (n: string) => (hidden = hidden.includes(n) ? hidden.filter((h) => h !== n) : [...hidden, n]);
 	const percent = $derived(stacked === 'percent');
 	const isStack = $derived(!!stacked);
-	const fmt = $derived((n: number) => (percent ? `${fmtValue(n)}%` : yFormat(n)));
 
 	/** One drawn segment: [lo, hi] on the value axis, per category and series. */
 	type Seg = { c: number; k: number; lo: number; hi: number; v: number; sign: 1 | -1; outer: boolean; inner: boolean };
@@ -69,10 +75,13 @@
 		});
 		return out;
 	});
+	const refs = $derived<Ref[]>([reference ?? []].flat());
 	const scale = $derived.by(() => {
 		let lo = 0, hi = 0;
 		for (const s of segs) { lo = Math.min(lo, s.lo); hi = Math.max(hi, s.hi); }
+		const rv = refs.map((r) => r.value);
 		if (percent && lo === 0) hi = 100;
+		lo = Math.min(lo, ...rv); hi = Math.max(hi, ...rv);
 		return niceTicks(lo, hi || 1, 5);
 	});
 	const totals = $derived(
@@ -87,6 +96,17 @@
 		return `M${x + tl},${y}H${x + w - tr}${tr ? `Q${x + w},${y} ${x + w},${y + tr}` : ''}V${y + h - br}${br ? `Q${x + w},${y + h} ${x + w - br},${y + h}` : ''}H${x + bl}${bl ? `Q${x},${y + h} ${x},${y + h - bl}` : ''}V${y + tl}${tl ? `Q${x},${y} ${x + tl},${y}` : ''}Z`;
 	}
 
+	// reference-line values: shown as a share on 100% stacked charts
+	const fmt = $derived((n: number) => (percent ? `${fmtValue(n)}%` : yFormat(n)));
+	const refText = (r: Ref) => (r.label ? `${r.label} · ${fmt(r.value)}` : fmt(r.value));
+	const tipFor = (s: Seg, ser: { name: string; color: string }, x: number, y: number): Tip => ({
+		x, y, cat: categories[s.c], name: ser.name, value: s.v, color: ser.color,
+		share: percent ? Math.abs(s.hi - s.lo) : undefined, detail: details?.[s.c]
+	});
+	// built in script: interpolating these in markup would add unreachable `?? ''` branches
+	const barLabel = (cat: string, name: string, v: number, share: number) => `${cat}, ${name}: ${str(yFormat(v))}${percent ? ` (${fmtValue(share)}%)` : ''}`;
+	const tipName = (t: Tip) => `${t.name}${t.share != null ? ` · ${fmtValue(t.share)}%` : ''}`;
+
 	const GAP = 1; // each side of a shared edge yields a 2px surface gap
 	const labelWidth = $derived(Math.min(168, Math.max(48, Math.max(0, ...categories.map((c) => c.length)) * 6.4 + 14)));
 	const trunc = (s: string, px: number) => (s.length * 6.4 > px ? `${s.slice(0, Math.max(1, Math.floor(px / 6.4) - 1))}…` : s);
@@ -94,7 +114,7 @@
 
 <ChartFrame {title} {subtitle} {items} ontoggle={toggle}>
 	{#snippet plot(w)}
-		{@const m = horizontal ? { top: 10, right: showValues ? 56 : 14, bottom: 26, left: labelWidth } : { top: showValues ? 22 : 12, right: 12, bottom: 28, left: 46 }}
+		{@const m = horizontal ? { top: refs.length ? 24 : 10, right: showValues ? 56 : 14, bottom: 26, left: labelWidth } : { top: showValues ? 22 : 12, right: 12, bottom: 28, left: 46 }}
 		{@const bandN = Math.max(categories.length, 1)}
 		{@const plotH = horizontal ? Math.max(height, bandN * (isStack ? 30 : Math.max(1, vis.length) * 16 + 14) + m.top + m.bottom) : height}
 		{@const V = horizontal ? linear(scale.min, scale.max, m.left, w - m.right) : linear(scale.min, scale.max, plotH - m.bottom, m.top)}
@@ -144,15 +164,25 @@
 					<!-- svelte-ignore a11y_no_noninteractive_tabindex -->
 					<path
 						class="bar" fill={ser.color} role="img" tabindex="0" data-cat={categories[s.c]} data-series={ser.name}
-						aria-label="{categories[s.c]}, {ser.name}: {yFormat(s.v)}{percent ? ` (${fmtValue(Math.abs(s.hi - s.lo))}%)` : ''}"
+						aria-label={barLabel(categories[s.c], ser.name, s.v, Math.abs(s.hi - s.lo))}
 						{d}
-						onpointermove={() => (tip = { x: tx, y: ty, cat: categories[s.c], name: ser.name, value: s.v, color: ser.color, share: percent ? Math.abs(s.hi - s.lo) : undefined })}
-						onfocus={() => (tip = { x: tx, y: ty, cat: categories[s.c], name: ser.name, value: s.v, color: ser.color, share: percent ? Math.abs(s.hi - s.lo) : undefined })}
+						onpointermove={() => (tip = tipFor(s, ser, tx, ty))}
+						onfocus={() => (tip = tipFor(s, ser, tx, ty))}
 						onblur={() => (tip = null)}
 					/>
 				{/if}
 			{/each}
 
+			{#each refs as r}
+				{#if horizontal}
+					<line class="ref" x1={V(r.value)} x2={V(r.value)} y1={m.top} y2={plotH - m.bottom} />
+					<text class="ref-label" x={V(r.value)} y={m.top - 6} text-anchor="middle">{refText(r)}</text>
+				{:else}
+					<line class="ref" x1={m.left} x2={w - m.right} y1={V(r.value)} y2={V(r.value)} />
+					<text class="ref-label" x={w - m.right} y={V(r.value) - 5} text-anchor="end">{refText(r)}</text>
+				{/if}
+			{/each}
+
 			{#if showValues && !percent}
 				{#each categories as cat, c}
 					{#if isStack || vis.length}
@@ -173,19 +203,25 @@
 		{#if tip}
 			<Tooltip x={tip.x} y={tip.y} width={w}>
 				<div class="head">{tip.cat}</div>
-				<div class="row"><span class="line-key" style:background={tip.color}></span><b>{yFormat(tip.value)}</b><span class="name">{tip.name}{tip.share != null ? ` · ${fmtValue(tip.share)}%` : ''}</span></div>
+				{#if tip.detail}<div class="detail">{tip.detail}</div>{/if}
+				<div class="row"><span class="line-key" style:background={tip.color}></span><b>{yFormat(tip.value)}</b><span class="name">{tipName(tip)}</span></div>
 			</Tooltip>
 		{/if}
 	{/snippet}
 
 	{#snippet table()}
 		<table>
-			<thead><tr><th>Category</th>{#each all as s}<th>{s.name}</th>{/each}</tr></thead>
+			<thead><tr><th>Category</th>{#each all as s}<th>{s.name}</th>{/each}{#if details}<th>Details</th>{/if}</tr></thead>
 			<tbody>
 				{#each categories as c, i}
-					<tr><td>{c}</td>{#each all as s}<td>{s.values[i] == null ? '—' : yFormat(s.values[i]!)}</td>{/each}</tr>
+					<tr><td>{c}</td>{#each all as s}<td>{s.values[i] == null ? '—' : yFormat(s.values[i]!)}</td>{/each}{#if details}<td>{details[i] ?? ''}</td>{/if}</tr>
 				{/each}
 			</tbody>
+			{#if refs.length}
+				<tfoot>
+					{#each refs as r}<tr><th scope="row">{r.label ?? 'Reference'}</th><td colspan={all.length + 1}>{fmt(r.value)}</td></tr>{/each}
+				</tfoot>
+			{/if}
 		</table>
 	{/snippet}
 </ChartFrame>
@@ -199,7 +235,10 @@
 	.bar { outline: none; transition: filter var(--tr-dur-fast) var(--tr-ease); }
 	.bar:hover, .bar:focus-visible { filter: brightness(1.12) saturate(1.1); }
 	.bar:focus-visible { stroke: var(--tr-on-surface); stroke-width: 2; }
+	.ref { stroke: var(--tr-on-surface); stroke-width: 1.5; stroke-dasharray: 5 4; pointer-events: none; }
+	.ref-label { fill: var(--tr-on-surface); font-size: var(--tr-text-xs); font-weight: 600; font-variant-numeric: tabular-nums; paint-order: stroke; stroke: var(--tr-surface); stroke-width: 3px; stroke-linejoin: round; pointer-events: none; }
 	.head { color: var(--tr-on-surface-variant); margin-bottom: 4px; }
+	.detail { color: var(--tr-on-surface-variant); margin: -2px 0 4px; max-width: 220px; white-space: normal; }
 	.row { display: flex; align-items: center; gap: 8px; line-height: 1.5; }
 	.row b { color: var(--tr-on-surface); font-variant-numeric: tabular-nums; }
 	.name { color: var(--tr-on-surface-variant); }

package/dist/BarChart.svelte.d.ts

@@ -1,4 +1,8 @@
 import type { Series } from './types.js';
+type Ref = {
+    value: number;
+    label?: string;
+};
 type $$ComponentProps = {
     categories: string[];
     /** Up to 8 series (fixed-order palette). Negative values are allowed everywhere, including stacked bars. */
@@ -13,6 +17,10 @@ type $$ComponentProps = {
     horizontal?: boolean;
     /** Label the end of each bar (the stack total when stacked). */
     showValues?: boolean;
+    /** One or more labelled reference lines (a target, a limit, an average) drawn across the plot at a value on the value axis. They extend the axis domain so they are always visible. */
+    reference?: Ref | Ref[];
+    /** Extra text per category (same order as `categories`), shown under the category name in the tooltip and as a Details column in the table view. */
+    details?: string[];
     yFormat?: (n: number) => string;
 };
 declare const BarChart: import("svelte").Component<$$ComponentProps, {}, "">;

package/dist/ColorScale.svelte

@@ -0,0 +1,59 @@
+<script lang="ts">
+	import { gradientFrom, type ScaleKind } from './util.js';
+
+	let {
+		low,
+		high,
+		mid,
+		caption,
+		label,
+		palette = 'sequential',
+		vertical = false,
+		size = 200
+	}: {
+		/** Label at the low end, e.g. `0%`. */
+		low: string;
+		/** Label at the high end, e.g. `40+%`. */
+		high: string;
+		/** Optional label at the midpoint (the neutral stop of a diverging scale). */
+		mid?: string;
+		/** Visible caption above the bar (horizontal) or beside it (vertical). */
+		caption?: string;
+		/** Accessible name. Defaults to "caption: low to high", e.g. "Error rate: 0% to 40+%". */
+		label?: string;
+		/** Which palette ramp to draw; match the ramp your marks use. */
+		palette?: ScaleKind;
+		/** Bar runs bottom (low) to top (high) instead of left to right. */
+		vertical?: boolean;
+		/** Bar length in px. */
+		size?: number;
+	} = $props();
+
+	const name = $derived(label ?? `${caption ? `${caption}: ` : ''}${low} to ${high}`);
+	const bg = $derived(gradientFrom(palette, vertical ? 'to top' : 'to right'));
+	const ends = $derived(vertical ? [high, low] : [low, high]);
+</script>
+
+<figure class="cs" class:vertical role="img" aria-label={name} style:--size="{size}px">
+	{#if caption}<figcaption>{caption}</figcaption>{/if}
+	<div class="body">
+		<div class="bar" style:background={bg}></div>
+		<div class="ends" aria-hidden="true">
+			<span>{ends[0]}</span>
+			{#if mid}<span>{mid}</span>{/if}
+			<span>{ends[1]}</span>
+		</div>
+	</div>
+</figure>
+
+<style>
+	.cs { margin: 0; display: inline-flex; flex-direction: column; gap: 4px; font-size: var(--tr-text-xs); color: var(--tr-on-surface-variant); }
+	figcaption { font-weight: 600; color: var(--tr-on-surface); }
+	.body { display: flex; flex-direction: column; gap: 3px; }
+	.bar { width: var(--size); height: 10px; border-radius: 3px; border: 1px solid var(--tr-outline-variant); box-sizing: border-box; }
+	.ends { display: flex; justify-content: space-between; font-variant-numeric: tabular-nums; }
+	.vertical { flex-direction: row; align-items: stretch; gap: 8px; }
+	.vertical .body { flex-direction: row; gap: 6px; }
+	.vertical .bar { width: 10px; height: var(--size); }
+	.vertical .ends { flex-direction: column; }
+</style>

package/dist/ColorScale.svelte.d.ts

@@ -0,0 +1,22 @@
+import { type ScaleKind } from './util.js';
+type $$ComponentProps = {
+    /** Label at the low end, e.g. `0%`. */
+    low: string;
+    /** Label at the high end, e.g. `40+%`. */
+    high: string;
+    /** Optional label at the midpoint (the neutral stop of a diverging scale). */
+    mid?: string;
+    /** Visible caption above the bar (horizontal) or beside it (vertical). */
+    caption?: string;
+    /** Accessible name. Defaults to "caption: low to high", e.g. "Error rate: 0% to 40+%". */
+    label?: string;
+    /** Which palette ramp to draw; match the ramp your marks use. */
+    palette?: ScaleKind;
+    /** Bar runs bottom (low) to top (high) instead of left to right. */
+    vertical?: boolean;
+    /** Bar length in px. */
+    size?: number;
+};
+declare const ColorScale: import("svelte").Component<$$ComponentProps, {}, "">;
+type ColorScale = ReturnType<typeof ColorScale>;
+export default ColorScale;

package/dist/DensityChart.svelte

@@ -0,0 +1,364 @@
+<script lang="ts">
+	import ChartFrame from './ChartFrame.svelte';
+	import Tooltip from './Tooltip.svelte';
+	import { bin, DEFAULT_RAMP, isHome, nearest, panView, parseColor, prepare, rampColor, zoomView, type DensityPoint, type View } from './density.js';
+	import { fmtAxis, fmtValue, linear, niceTicks, seriesColor } from './util.js';
+
+	let {
+		points,
+		xs,
+		ys,
+		groupIds,
+		groupNames,
+		title,
+		subtitle,
+		height = 320,
+		xLabel,
+		yLabel,
+		xFormat = fmtValue,
+		yFormat = fmtValue,
+		cellSize = 8,
+		markerThreshold = 2,
+		markerSize = 3
+	}: {
+		/** Object input, convenient up to ~10^5 points. `group` picks the palette colour of markers and a legend entry (max 8). */
+		points?: DensityPoint[];
+		/** Typed-array input for 10^5 to 10^6+ points (used as-is, no copy); wins over `points` when both `xs` and `ys` are set. */
+		xs?: ArrayLike<number>;
+		ys?: ArrayLike<number>;
+		/** Optional palette slot (0-7) per point for typed-array input, with `groupNames` naming the slots. */
+		groupIds?: Uint8Array;
+		groupNames?: string[];
+		title?: string;
+		subtitle?: string;
+		height?: number;
+		xLabel?: string;
+		yLabel?: string;
+		xFormat?: (n: number) => string;
+		yFormat?: (n: number) => string;
+		/** Heatmap cell edge in CSS px. */
+		cellSize?: number;
+		/**
+		 * Switch from heatmap to individual markers once the visible points number at most this many per heatmap cell.
+		 * Colour ramp: `--trc-seq-1` … `--trc-seq-9` (low to high count); falls back to a built-in colour-blind-safe ramp.
+		 */
+		markerThreshold?: number;
+		/** Marker edge in CSS px. */
+		markerSize?: number;
+	} = $props();
+
+	const data = $derived(prepare(points, xs, ys, groupIds, groupNames));
+	let hidden = $state<string[]>([]);
+	const hid = $derived(Uint8Array.from({ length: 8 }, (_, i) => (hidden.includes(data.names[i]) ? 1 : 0)));
+	const items = $derived(data.names.map((name, i) => ({ name, color: seriesColor(i), hidden: hidden.includes(name) })));
+	const toggle = (n: string) => (hidden = hidden.includes(n) ? hidden.filter((h) => h !== n) : [...hidden, n]);
+
+	const home = $derived.by<View>(() => {
+		const e = data.extent;
+		if (!e) return { x0: 0, x1: 1, y0: 0, y1: 1 };
+		const xt = niceTicks(e.x0, e.x1, 6), yt = niceTicks(e.y0, e.y1, 5);
+		return { x0: xt.min, x1: xt.max, y0: yt.min, y1: yt.max };
+	});
+	let zoom = $state<View | null>(null);
+	const cur = $derived(zoom ?? home);
+	// new data starts from the full view
+	$effect(() => { void data; zoom = null; });
+
+	let cw = $state(640);
+	let canvas = $state<HTMLCanvasElement | null>(null);
+	let box = $state<HTMLDivElement | null>(null);
+	let mode = $state<'heatmap' | 'markers' | ''>('');
+	let inView = $state(0);
+	let hover = $state<{ x: number; y: number; head: string; rows: [string, string][]; rx: number; ry: number; rw: number; rh: number } | null>(null);
+
+	const m = $derived({ top: 32, right: 16, bottom: xLabel ? 44 : 28, left: yLabel ? 62 : 48 });
+	const pw = $derived(Math.max(1, cw - m.left - m.right));
+	const ph = $derived(Math.max(1, height - m.top - m.bottom));
+	const total = $derived(data.n);
+
+	const readout = $derived(
+		`${fmtValue(inView)} of ${fmtValue(total)} points in view, drawn as ${mode === 'markers' ? 'individual markers' : 'a density heatmap'}. ` +
+			`${xLabel ?? 'x'} ${xFormat(cur.x0)} to ${xFormat(cur.x1)}, ${yLabel ?? 'y'} ${yFormat(cur.y0)} to ${yFormat(cur.y1)}.`
+	);
+
+	// ── drawing (redraw once per frame, whatever changed)
+	let grid = new Uint32Array(0), gCols = 1, gRows = 1;
+	let raf = 0;
+	const schedule = () => { cancelAnimationFrame(raf); raf = requestAnimationFrame(draw); };
+	$effect(() => {
+		void [canvas, cw, height, cur, data, hid, cellSize, markerThreshold, markerSize, m];
+		schedule();
+		return () => { cancelAnimationFrame(raf); raf = 0; };
+	});
+	// colours come from CSS custom properties, so follow theme switches (explicit data-theme or the OS preference)
+	$effect(() => {
+		const mo = new MutationObserver(schedule);
+		mo.observe(document.documentElement, { attributes: true, attributeFilter: ['data-theme', 'class'] });
+		// the default theme follows the OS, which changes without touching any attribute
+		const os = matchMedia('(prefers-color-scheme: dark)');
+		os.addEventListener('change', schedule);
+		return () => { mo.disconnect(); os.removeEventListener('change', schedule); };
+	});
+
+	const cssVar = (st: CSSStyleDeclaration, name: string, fallback: string) => st.getPropertyValue(name).trim() || fallback;
+
+	function draw() {
+		raf = 0;
+		const c = canvas;
+		if (!c) return;
+		const ctx = c.getContext('2d')!;
+		const dpr = window.devicePixelRatio;
+		const W = cw, H = height;
+		if (c.width !== Math.round(W * dpr)) c.width = Math.round(W * dpr);
+		if (c.height !== Math.round(H * dpr)) c.height = Math.round(H * dpr);
+		ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+		ctx.clearRect(0, 0, W, H);
+		const st = getComputedStyle(c);
+		const v = cur;
+		const X = linear(v.x0, v.x1, m.left, m.left + pw), Y = linear(v.y0, v.y1, m.top + ph, m.top);
+
+		// axes
+		ctx.font = `11px ${cssVar(st, '--tr-font-sans', 'sans-serif')}`;
+		ctx.fillStyle = cssVar(st, '--tr-on-surface-variant', '#666');
+		ctx.strokeStyle = cssVar(st, '--tr-outline-variant', '#ccc');
+		ctx.globalAlpha = 1;
+		ctx.lineWidth = 1;
+		ctx.textBaseline = 'middle';
+		ctx.textAlign = 'right';
+		for (const t of niceTicks(v.y0, v.y1, 5).ticks) {
+			if (t < v.y0 || t > v.y1) continue;
+			const y = Math.round(Y(t)) + 0.5;
+			ctx.globalAlpha = 0.6;
+			ctx.beginPath(); ctx.moveTo(m.left, y); ctx.lineTo(m.left + pw, y); ctx.stroke();
+			ctx.globalAlpha = 1;
+			ctx.fillText(fmtAxis(t), m.left - 8, y);
+		}
+		ctx.textAlign = 'center';
+		for (const t of niceTicks(v.x0, v.x1, 6).ticks) if (t >= v.x0 && t <= v.x1) ctx.fillText(fmtAxis(t), X(t), m.top + ph + 16);
+		ctx.font = `600 ${ctx.font}`;
+		if (xLabel) ctx.fillText(xLabel, m.left + pw / 2, H - 8);
+		if (yLabel) {
+			ctx.save();
+			ctx.translate(12, m.top + ph / 2);
+			ctx.rotate(-Math.PI / 2);
+			ctx.fillText(yLabel, 0, 0);
+			ctx.restore();
+		}
+
+		// data: one binning pass decides heatmap vs markers
+		gCols = Math.max(1, Math.ceil(pw / cellSize));
+		gRows = Math.max(1, Math.ceil(ph / cellSize));
+		if (grid.length < gCols * gRows) grid = new Uint32Array(gCols * gRows);
+		const n = bin(data, hid, v, gCols, gRows, grid);
+		const markers = n <= markerThreshold * gCols * gRows;
+		ctx.save();
+		ctx.beginPath();
+		ctx.rect(m.left, m.top, pw, ph);
+		ctx.clip();
+		if (markers) {
+			const slots = Array.from({ length: 8 }, (_, i) => {
+				ctx.fillStyle = '#000';
+				ctx.fillStyle = cssVar(st, `--trc-s${i + 1}`, '#2a78d6');
+				return ctx.fillStyle as string;
+			});
+			const { xs: dx, ys: dy, g } = data;
+			const half = markerSize / 2;
+			const x0 = v.x0, x1 = v.x1, y0 = v.y0, y1 = v.y1;
+			ctx.globalAlpha = 0.85;
+			let last = -1;
+			for (let i = 0; i < data.n; i++) {
+				const x = dx[i], y = dy[i];
+				if (!(x >= x0 && x <= x1 && y >= y0 && y <= y1)) continue;
+				const id = g === null ? 0 : g[i];
+				if (g !== null && hid[id] === 1) continue;
+				if (id !== last) { ctx.fillStyle = slots[id]; last = id; }
+				ctx.fillRect(X(x) - half, Y(y) - half, markerSize, markerSize);
+			}
+		} else {
+			const stops: [number, number, number][] = [];
+			for (let i = 1; i <= 9; i++) {
+				const raw = st.getPropertyValue(`--trc-seq-${i}`).trim();
+				if (!raw) break;
+				ctx.fillStyle = '#000';
+				ctx.fillStyle = raw;
+				stops.push(parseColor(ctx.fillStyle as string));
+			}
+			const ramp = stops.length > 1 ? stops : DEFAULT_RAMP.map(parseColor);
+			let max = 1;
+			for (let i = 0; i < gCols * gRows; i++) if (grid[i] > max) max = grid[i];
+			const lmax = Math.log1p(max), cw1 = pw / gCols, ch1 = ph / gRows;
+			for (let r = 0; r < gRows; r++)
+				for (let k = 0; k < gCols; k++) {
+					const cnt = grid[r * gCols + k];
+					if (!cnt) continue;
+					ctx.fillStyle = rampColor(ramp, Math.log1p(cnt) / lmax);
+					ctx.fillRect(m.left + k * cw1, m.top + (gRows - 1 - r) * ch1, cw1 + 0.5, ch1 + 0.5);
+				}
+		}
+		ctx.restore();
+		inView = n;
+		mode = markers ? 'markers' : 'heatmap';
+	}
+
+	// ── view changes
+	const commit = (v: View) => (zoom = isHome(v, home) ? null : v);
+	function zoomAt(px: number, py: number, k: number) {
+		commit(zoomView(cur, home, Math.min(1, Math.max(0, (px - m.left) / pw)), Math.min(1, Math.max(0, (py - m.top) / ph)), k));
+		hover = null;
+	}
+	const pan = (fx: number, fy: number) => { commit(panView(cur, home, fx, fy)); hover = null; };
+	const reset = () => { zoom = null; hover = null; };
+
+	$effect(() => {
+		const el = box;
+		if (!el) return;
+		const onwheel = (e: WheelEvent) => {
+			e.preventDefault();
+			const r = el.getBoundingClientRect();
+			zoomAt(e.clientX - r.left, e.clientY - r.top, Math.exp(-e.deltaY * 0.0015));
+		};
+		el.addEventListener('wheel', onwheel, { passive: false });
+		return () => el.removeEventListener('wheel', onwheel);
+	});
+
+	// ── pointers: drag pans, two pointers pinch
+	const ptrs = new Map<number, { x: number; y: number }>();
+	const spread = () => { const [a, b] = [...ptrs.values()]; return Math.hypot(a.x - b.x, a.y - b.y); };
+	function down(e: PointerEvent) {
+		ptrs.set(e.pointerId, { x: e.clientX, y: e.clientY });
+		hover = null;
+		try { (e.currentTarget as HTMLElement).setPointerCapture(e.pointerId); } catch { /* synthetic pointer */ }
+	}
+	function move(e: PointerEvent) {
+		const prev = ptrs.get(e.pointerId);
+		if (!prev) return hit(e);
+		if (ptrs.size === 1) {
+			pan(-(e.clientX - prev.x) / pw, (e.clientY - prev.y) / ph);
+			ptrs.set(e.pointerId, { x: e.clientX, y: e.clientY });
+		} else {
+			const before = spread();
+			ptrs.set(e.pointerId, { x: e.clientX, y: e.clientY });
+			const [a, b] = [...ptrs.values()];
+			const r = box!.getBoundingClientRect();
+			zoomAt((a.x + b.x) / 2 - r.left, (a.y + b.y) / 2 - r.top, spread() / (before || 1));
+		}
+	}
+	const up = (e: PointerEvent) => { ptrs.delete(e.pointerId); };
+
+	// ── hit testing: nearest marker when zoomed in, bin count when zoomed out
+	function hit(e: PointerEvent) {
+		const r = box!.getBoundingClientRect();
+		const px = e.clientX - r.left, py = e.clientY - r.top;
+		if (px < m.left || px > m.left + pw || py < m.top || py > m.top + ph) { hover = null; return; }
+		const v = cur;
+		const qx = v.x0 + ((px - m.left) / pw) * (v.x1 - v.x0), qy = v.y1 - ((py - m.top) / ph) * (v.y1 - v.y0);
+		if (mode === 'markers') {
+			const i = nearest(data, hid, qx, qy, (12 / pw) * (v.x1 - v.x0), (12 / ph) * (v.y1 - v.y0));
+			if (i < 0) { hover = null; return; }
+			const x = m.left + ((data.xs[i] - v.x0) / (v.x1 - v.x0)) * pw, y = m.top + ph - ((data.ys[i] - v.y0) / (v.y1 - v.y0)) * ph;
+			const name = data.g ? data.names[data.g[i]] : undefined;
+			hover = { x, y, head: name ?? 'Point', rows: [[xFormat(data.xs[i]), xLabel ?? 'x'], [yFormat(data.ys[i]), yLabel ?? 'y']], rx: x - 6, ry: y - 6, rw: 12, rh: 12 };
+			return;
+		}
+		const cw1 = pw / gCols, ch1 = ph / gRows;
+		const k = Math.min(gCols - 1, Math.floor((px - m.left) / cw1)), q = Math.min(gRows - 1, Math.floor((py - m.top) / ch1));
+		const cnt = grid[(gRows - 1 - q) * gCols + k];
+		if (!cnt) { hover = null; return; }
+		const sx = (v.x1 - v.x0) / gCols, sy = (v.y1 - v.y0) / gRows;
+		const bx = v.x0 + k * sx, by = v.y1 - (q + 1) * sy;
+		hover = {
+			x: px, y: py, head: 'Bin',
+			rows: [[fmtValue(cnt), 'points'], [`${xFormat(bx)} to ${xFormat(bx + sx)}`, xLabel ?? 'x'], [`${yFormat(by)} to ${yFormat(by + sy)}`, yLabel ?? 'y']],
+			rx: m.left + k * cw1, ry: m.top + q * ch1, rw: cw1, rh: ch1
+		};
+	}
+
+	function key(e: KeyboardEvent) {
+		const cx = m.left + pw / 2, cy = m.top + ph / 2;
+		if (e.key === '+' || e.key === '=') zoomAt(cx, cy, 1.5);
+		else if (e.key === '-' || e.key === '_') zoomAt(cx, cy, 1 / 1.5);
+		else if (e.key === '0') reset();
+		else if (e.key === 'ArrowLeft') pan(-0.1, 0);
+		else if (e.key === 'ArrowRight') pan(0.1, 0);
+		else if (e.key === 'ArrowUp') pan(0, 0.1);
+		else if (e.key === 'ArrowDown') pan(0, -0.1);
+		else if (e.key === 'Escape') hover = null;
+		else return;
+		e.preventDefault();
+	}
+
+	// ── table: busiest regions of the current view, never the raw rows
+	const TC = 8, TR = 6;
+	const summary = $derived.by(() => {
+		const out = new Uint32Array(TC * TR);
+		const n = bin(data, hid, cur, TC, TR, out);
+		const sx = (cur.x1 - cur.x0) / TC, sy = (cur.y1 - cur.y0) / TR;
+		const rows: { x: string; y: string; count: number; share: string }[] = [];
+		for (let i = 0; i < out.length; i++)
+			if (out[i]) {
+				const c = i % TC, r = (i - c) / TC;
+				rows.push({ x: `${xFormat(cur.x0 + c * sx)} to ${xFormat(cur.x0 + (c + 1) * sx)}`, y: `${yFormat(cur.y0 + r * sy)} to ${yFormat(cur.y0 + (r + 1) * sy)}`, count: out[i], share: `${((out[i] / n) * 100).toFixed(1)}%` });
+			}
+		rows.sort((a, b) => b.count - a.count);
+		return { n, regions: rows.length, rows: rows.slice(0, 12) };
+	});
+</script>
+
+<ChartFrame {title} {subtitle} {items} ontoggle={toggle}>
+	{#snippet plot(w)}
+		<!-- svelte-ignore a11y_no_noninteractive_tabindex, a11y_no_noninteractive_element_interactions -->
+		<div
+			class="dc" role="group" tabindex="0" bind:this={box} bind:clientWidth={cw}
+			aria-label="{title ?? 'Density chart'}, {fmtValue(total)} points. Drag or arrow keys pan, wheel or plus and minus zoom, 0 resets the view."
+			onpointerdown={down} onpointermove={move} onpointerup={up} onpointercancel={up}
+			onpointerleave={() => (hover = null)} onblur={() => (hover = null)} onkeydown={key}
+			ondblclick={(e) => { const r = box!.getBoundingClientRect(); zoomAt(e.clientX - r.left, e.clientY - r.top, 2); }}
+		>
+			<canvas bind:this={canvas} style:height="{height}px" aria-hidden="true" data-mode={mode || undefined}></canvas>
+			{#if hover}<div class="ring" style="left: {hover.rx}px; top: {hover.ry}px; width: {hover.rw}px; height: {hover.rh}px"></div>{/if}
+		</div>
+		<button type="button" class="reset" disabled={zoom === null} onclick={reset}>Reset view</button>
+		<div class="sr" role="status" aria-live="polite">{readout}</div>
+
+		{#if hover}
+			<Tooltip x={hover.x} y={hover.y} width={w}>
+				<div class="head">{hover.head}</div>
+				{#each hover.rows as [val, name]}
+					<div class="row"><b>{val}</b><span class="name">{name}</span></div>
+				{/each}
+			</Tooltip>
+		{/if}
+	{/snippet}
+
+	{#snippet table()}
+		<table>
+			<caption>{fmtValue(summary.n)} points in view, grouped into {summary.regions} regions{summary.regions > summary.rows.length ? ` (busiest ${summary.rows.length} shown)` : ''}</caption>
+			<thead><tr><th>{xLabel ?? 'X'}</th><th>{yLabel ?? 'Y'}</th><th>Points</th><th>Share</th></tr></thead>
+			<tbody>
+				{#each summary.rows as r}
+					<tr><td>{r.x}</td><td>{r.y}</td><td>{fmtValue(r.count)}</td><td>{r.share}</td></tr>
+				{:else}
+					<tr><td colspan="4">No points in view</td></tr>
+				{/each}
+			</tbody>
+		</table>
+	{/snippet}
+</ChartFrame>
+
+<style>
+	.dc { position: relative; touch-action: none; cursor: grab; outline: none; user-select: none; }
+	.dc:active { cursor: grabbing; }
+	.dc:focus-visible { border-radius: var(--tr-radius-sm); box-shadow: var(--tr-focus-ring); }
+	canvas { display: block; width: 100%; }
+	.ring { position: absolute; border: 2px solid var(--tr-on-surface); border-radius: 3px; pointer-events: none; box-sizing: border-box; }
+	.reset { position: absolute; top: 0; right: 0; height: 24px; padding: 0 10px; border: 1px solid var(--tr-outline-variant); border-radius: var(--tr-radius-sm); background: var(--tr-surface-container-low); color: var(--tr-on-surface-variant); font: 600 var(--tr-text-sm) var(--tr-font-sans); cursor: pointer; }
+	.reset:hover:not(:disabled) { background: var(--tr-surface-container-high); }
+	.reset:disabled { opacity: 0.45; cursor: default; }
+	.reset:focus-visible { outline: none; box-shadow: var(--tr-focus-ring); }
+	.sr { position: absolute; width: 1px; height: 1px; overflow: hidden; clip-path: inset(50%); white-space: nowrap; }
+	caption { caption-side: top; padding: 4px 8px; text-align: left; color: var(--tr-on-surface-variant); }
+	.head { color: var(--tr-on-surface-variant); margin-bottom: 4px; }
+	.row { display: flex; align-items: center; gap: 8px; line-height: 1.5; }
+	.row b { color: var(--tr-on-surface); font-variant-numeric: tabular-nums; min-width: 44px; text-align: right; }
+	.name { color: var(--tr-on-surface-variant); }
+</style>

package/dist/DensityChart.svelte.d.ts

@@ -0,0 +1,30 @@
+import { type DensityPoint } from './density.js';
+type $$ComponentProps = {
+    /** Object input, convenient up to ~10^5 points. `group` picks the palette colour of markers and a legend entry (max 8). */
+    points?: DensityPoint[];
+    /** Typed-array input for 10^5 to 10^6+ points (used as-is, no copy); wins over `points` when both `xs` and `ys` are set. */
+    xs?: ArrayLike<number>;
+    ys?: ArrayLike<number>;
+    /** Optional palette slot (0-7) per point for typed-array input, with `groupNames` naming the slots. */
+    groupIds?: Uint8Array;
+    groupNames?: string[];
+    title?: string;
+    subtitle?: string;
+    height?: number;
+    xLabel?: string;
+    yLabel?: string;
+    xFormat?: (n: number) => string;
+    yFormat?: (n: number) => string;
+    /** Heatmap cell edge in CSS px. */
+    cellSize?: number;
+    /**
+     * Switch from heatmap to individual markers once the visible points number at most this many per heatmap cell.
+     * Colour ramp: `--trc-seq-1` … `--trc-seq-9` (low to high count); falls back to a built-in colour-blind-safe ramp.
+     */
+    markerThreshold?: number;
+    /** Marker edge in CSS px. */
+    markerSize?: number;
+};
+declare const DensityChart: import("svelte").Component<$$ComponentProps, {}, "">;
+type DensityChart = ReturnType<typeof DensityChart>;
+export default DensityChart;