@ruckc/truss-chart 1.8.0 → 1.10.0

package/dist/BarChart.svelte

@@ -1,5 +1,6 @@
 <script lang="ts">
 	import ChartFrame from './ChartFrame.svelte';
+	import { watchFill } from './fill.js';
 	import Tooltip from './Tooltip.svelte';
 	import type { Series } from './types.js';
 	import { fmtAxis, fmtValue, linear, str, niceTicks, seriesColor, MAX_SERIES } from './util.js';
@@ -22,8 +23,12 @@
 		series: Series[];
 		title?: string;
 		subtitle?: string;
-		/** Plot height in px (horizontal charts grow to fit their categories). */
-		height?: number;
+		/**
+		 * Plot height in px (default 240), or `'fill'` to size to the container's height. `'fill'` measures the
+		 * parent with a ResizeObserver, so the parent needs a definite height (e.g. `height: 360px`, or a grid/flex
+		 * track with a fixed size). A parent with `height: auto` collapses to the 120px minimum. Horizontal charts still grow to fit their categories.
+		 */
+		height?: number | 'fill';
 		/** `true` stacks values (positives up/right of zero, negatives down/left); `'percent'` normalises each category to 100%. */
 		stacked?: boolean | 'percent';
 		/** Bars run left→right with categories down the side — better for long labels and many categories. */
@@ -110,10 +115,22 @@
 	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);
+
+	// height='fill': plot = container height minus the frame's own chrome (title, legend, key, padding)
+	let wrap = $state<HTMLElement>();
+	let fillH = $state(240);
+	const fill = $derived(height === 'fill');
+	const H = $derived(height === 'fill' ? fillH : height);
+	$effect(() => {
+		if (!fill || !wrap) return;
+		return watchFill(wrap, 'svg[role=img]', (h) => (fillH = h));
+	});
 </script>
 
+{#snippet chart()}
 <ChartFrame {title} {subtitle} {items} ontoggle={toggle}>
 	{#snippet plot(w)}
+		{@const height = H}
 		{@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}
@@ -225,8 +242,16 @@
 		</table>
 	{/snippet}
 </ChartFrame>
+{/snippet}
+
+{#if fill}
+	<div class="fillwrap" bind:this={wrap}>{@render chart()}</div>
+{:else}
+	{@render chart()}
+{/if}
 
 <style>
+	.fillwrap { height: 100%; min-height: 0; overflow: hidden; }
 	svg { display: block; overflow: visible; }
 	.grid { stroke: var(--tr-outline-variant); stroke-opacity: 0.6; }
 	.grid[data-zero='true'] { stroke-opacity: 1; }

package/dist/BarChart.svelte.d.ts

@@ -9,8 +9,12 @@ type $$ComponentProps = {
     series: Series[];
     title?: string;
     subtitle?: string;
-    /** Plot height in px (horizontal charts grow to fit their categories). */
-    height?: number;
+    /**
+     * Plot height in px (default 240), or `'fill'` to size to the container's height. `'fill'` measures the
+     * parent with a ResizeObserver, so the parent needs a definite height (e.g. `height: 360px`, or a grid/flex
+     * track with a fixed size). A parent with `height: auto` collapses to the 120px minimum. Horizontal charts still grow to fit their categories.
+     */
+    height?: number | 'fill';
     /** `true` stacks values (positives up/right of zero, negatives down/left); `'percent'` normalises each category to 100%. */
     stacked?: boolean | 'percent';
     /** Bars run left→right with categories down the side — better for long labels and many categories. */

package/dist/ColorScale.svelte

@@ -8,6 +8,8 @@
 		caption,
 		label,
 		palette = 'sequential',
+		gradient,
+		stops,
 		vertical = false,
 		size = 200
 	}: {
@@ -23,6 +25,17 @@
 		label?: string;
 		/** Which palette ramp to draw; match the ramp your marks use. */
 		palette?: ScaleKind;
+		/**
+		 * Any CSS gradient (e.g. `linear-gradient(to right, #fff, #06c)`), drawn exactly as given: write the
+		 * direction yourself (`to top` for a `vertical` bar). Takes precedence over `stops` and `palette`.
+		 */
+		gradient?: string;
+		/**
+		 * Colours from the low end to the high end, evenly spaced, e.g. `['#fff', '#06c', '#003']`. Built into a
+		 * linear gradient that runs in the bar's direction (`vertical` runs bottom to top). Colours may be any CSS
+		 * colour or `var(--token)`. Takes precedence over `palette`; ignored when `gradient` is set, or with fewer than two stops.
+		 */
+		stops?: string[];
 		/** Bar runs bottom (low) to top (high) instead of left to right. */
 		vertical?: boolean;
 		/** Bar length in px. */
@@ -30,7 +43,13 @@
 	} = $props();
 
 	const name = $derived(label ?? `${caption ? `${caption}: ` : ''}${low} to ${high}`);
-	const bg = $derived(gradientFrom(palette, vertical ? 'to top' : 'to right'));
+	// precedence: gradient > stops (2 or more) > palette
+	const bg = $derived.by(() => {
+		const dir = vertical ? 'to top' : 'to right';
+		if (gradient) return gradient;
+		if (stops && stops.length > 1) return `linear-gradient(${dir}, ${stops.join(', ')})`;
+		return gradientFrom(palette, dir);
+	});
 	const ends = $derived(vertical ? [high, low] : [low, high]);
 </script>
 

package/dist/ColorScale.svelte.d.ts

@@ -12,6 +12,17 @@ type $$ComponentProps = {
     label?: string;
     /** Which palette ramp to draw; match the ramp your marks use. */
     palette?: ScaleKind;
+    /**
+     * Any CSS gradient (e.g. `linear-gradient(to right, #fff, #06c)`), drawn exactly as given: write the
+     * direction yourself (`to top` for a `vertical` bar). Takes precedence over `stops` and `palette`.
+     */
+    gradient?: string;
+    /**
+     * Colours from the low end to the high end, evenly spaced, e.g. `['#fff', '#06c', '#003']`. Built into a
+     * linear gradient that runs in the bar's direction (`vertical` runs bottom to top). Colours may be any CSS
+     * colour or `var(--token)`. Takes precedence over `palette`; ignored when `gradient` is set, or with fewer than two stops.
+     */
+    stops?: string[];
     /** Bar runs bottom (low) to top (high) instead of left to right. */
     vertical?: boolean;
     /** Bar length in px. */

package/dist/DensityChart.svelte

@@ -1,7 +1,10 @@
 <script lang="ts">
+	import type { Snippet } from 'svelte';
 	import ChartFrame from './ChartFrame.svelte';
+	import { watchFill } from './fill.js';
+	import ColorScale from './ColorScale.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 { bin, DEFAULT_RAMP, extentOf, isHome, mergeExtent, nearest, panView, parseColor, prepare, rampColor, zoomView, type DensityHighlight, type DensityHover, type DensityPoint, type Prepared, type View } from './density.js';
 	import { fmtAxis, fmtValue, linear, niceTicks, seriesColor } from './util.js';
 
 	let {
@@ -19,7 +22,13 @@
 		yFormat = fmtValue,
 		cellSize = 8,
 		markerThreshold = 2,
-		markerSize = 3
+		markerSize = 3,
+		highlight,
+		highlightSize = 9,
+		tooltip,
+		colorKey = true,
+		maxCount = $bindable(0),
+		ramp = $bindable([])
 	}: {
 		/** Object input, convenient up to ~10^5 points. `group` picks the palette colour of markers and a legend entry (max 8). */
 		points?: DensityPoint[];
@@ -31,7 +40,12 @@
 		groupNames?: string[];
 		title?: string;
 		subtitle?: string;
-		height?: number;
+		/**
+		 * Plot height in px (default 320), or `'fill'` to size to the container's height. `'fill'` measures the
+		 * parent with a ResizeObserver, so the parent needs a definite height (e.g. `height: 360px`, or a grid/flex
+		 * track with a fixed size). A parent with `height: auto` collapses to the 120px minimum.
+		 */
+		height?: number | 'fill';
 		xLabel?: string;
 		yLabel?: string;
 		xFormat?: (n: number) => string;
@@ -45,16 +59,44 @@
 		markerThreshold?: number;
 		/** Marker edge in CSS px. */
 		markerSize?: number;
+		/**
+		 * A small set of notable points that stay drawn as markers on top of the heatmap at every zoom, with their
+		 * own legend entry (toggleable), tooltip hit-testing and a table section. Pass them separately from `points` /
+		 * `xs`: highlights are not part of the bin counts, so do not repeat them in the main data. Cost is linear in
+		 * the highlight count per frame, so keep the set small (thousands, not 10^5).
+		 */
+		highlight?: DensityHighlight;
+		/** Highlight marker diameter in CSS px (a surface-coloured halo is added around it). */
+		highlightSize?: number;
+		/** Replaces the default tooltip body. Receives the hovered point (index, x, y, group, highlight flag) or bin (count and ranges). */
+		tooltip?: Snippet<[item: DensityHover]>;
+		/** Show a colour key (points per cell, 1 to the busiest cell in view) under the plot while in heatmap mode. */
+		colorKey?: boolean;
+		/** Bindable: the busiest cell's point count in the current view (heatmap mode; 0 while drawing markers). Cells are coloured on a log scale from 1 to this value. */
+		maxCount?: number;
+		/** Bindable: the resolved heatmap ramp, low to high, as CSS colours (from `--trc-seq-*` or the built-in fallback). */
+		ramp?: string[];
 	} = $props();
 
-	const data = $derived(prepare(points, xs, ys, groupIds, groupNames));
+	const full = $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 hlName = $derived(highlight?.name ?? 'Highlighted');
+	const hlHidden = $derived(hidden.includes(hlName));
+	// an ungrouped set gets a "Points" legend entry once highlights exist, so the two can be toggled independently
+	const dotsEntry = $derived(!!highlight && full.names.length === 0);
+	const dotsHidden = $derived(dotsEntry && hidden.includes('Points'));
+	const data = $derived<Prepared>(dotsHidden ? { ...full, n: 0 } : full);
+	const hid = $derived(Uint8Array.from({ length: 8 }, (_, i) => (hidden.includes(full.names[i]) ? 1 : 0)));
+	const hl = $derived<Prepared | null>(highlight ? { xs: highlight.xs, ys: highlight.ys, g: null, names: [], n: Math.min(highlight.xs.length, highlight.ys.length), extent: null } : null);
+	const items = $derived([
+		...(dotsEntry ? [{ name: 'Points', color: seriesColor(0), hidden: dotsHidden }] : full.names.map((name, i) => ({ name, color: seriesColor(i), hidden: hidden.includes(name) }))),
+		...(highlight ? [{ name: hlName, color: 'var(--tr-on-surface)', hidden: hlHidden }] : [])
+	]);
+	const noHid = new Uint8Array(8);
 	const toggle = (n: string) => (hidden = hidden.includes(n) ? hidden.filter((h) => h !== n) : [...hidden, n]);
 
 	const home = $derived.by<View>(() => {
-		const e = data.extent;
+		const e = mergeExtent(full.extent, hl ? extentOf(hl.xs, hl.ys, hl.n) : null);
 		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 };
@@ -62,23 +104,42 @@
 	let zoom = $state<View | null>(null);
 	const cur = $derived(zoom ?? home);
 	// new data starts from the full view
-	$effect(() => { void data; zoom = null; });
+	$effect(() => { void full; void hl; 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);
+	let peak = $state(0);
+	let hover = $state<{ x: number; y: number; head: string; rows: [string, string][]; rx: number; ry: number; rw: number; rh: number; item: DensityHover } | null>(null);
+
+	// height='fill': plot = container height minus the frame's own chrome (title, legend, key, padding)
+	let wrap = $state<HTMLElement>();
+	let fillH = $state(320);
+	const fill = $derived(height === 'fill');
+	const H = $derived(height === 'fill' ? fillH : height);
+	$effect(() => {
+		void [mode, colorKey, items.length];
+		if (!fill || !wrap) return;
+		return watchFill(wrap, 'canvas', (h) => (fillH = h));
+	});
 
 	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 ph = $derived(Math.max(1, H - m.top - m.bottom));
+	const total = $derived(full.n);
+	const hlIn = $derived.by(() => {
+		if (!hl || hlHidden) return 0;
+		let k = 0;
+		for (let i = 0; i < hl.n; i++) if (hl.xs[i] >= cur.x0 && hl.xs[i] <= cur.x1 && hl.ys[i] >= cur.y0 && hl.ys[i] <= cur.y1) k++;
+		return k;
+	});
 
 	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)}.`
+			`${xLabel ?? 'x'} ${xFormat(cur.x0)} to ${xFormat(cur.x1)}, ${yLabel ?? 'y'} ${yFormat(cur.y0)} to ${yFormat(cur.y1)}.` +
+			(hl ? ` ${hlName}: ${fmtValue(hlIn)} in view.` : '')
 	);
 
 	// ── drawing (redraw once per frame, whatever changed)
@@ -86,7 +147,7 @@
 	let raf = 0;
 	const schedule = () => { cancelAnimationFrame(raf); raf = requestAnimationFrame(draw); };
 	$effect(() => {
-		void [canvas, cw, height, cur, data, hid, cellSize, markerThreshold, markerSize, m];
+		void [canvas, cw, H, cur, data, hl, hlHidden, highlightSize, hid, cellSize, markerThreshold, markerSize, m];
 		schedule();
 		return () => { cancelAnimationFrame(raf); raf = 0; };
 	});
@@ -108,7 +169,7 @@
 		if (!c) return;
 		const ctx = c.getContext('2d')!;
 		const dpr = window.devicePixelRatio;
-		const W = cw, H = height;
+		const W = cw;
 		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);
@@ -161,12 +222,12 @@
 				ctx.fillStyle = cssVar(st, `--trc-s${i + 1}`, '#2a78d6');
 				return ctx.fillStyle as string;
 			});
-			const { xs: dx, ys: dy, g } = data;
+			const { xs: dx, ys: dy, g, n: dn } = 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++) {
+			for (let i = 0; i < dn; 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];
@@ -183,19 +244,38 @@
 				ctx.fillStyle = raw;
 				stops.push(parseColor(ctx.fillStyle as string));
 			}
-			const ramp = stops.length > 1 ? stops : DEFAULT_RAMP.map(parseColor);
+			const colors = 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];
+			peak = max;
+			const css = colors.map((c) => rampColor([c, c], 0));
+			if (css.join() !== ramp.join()) ramp = css;
+			if (maxCount !== max) maxCount = max;
 			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.fillStyle = rampColor(colors, Math.log1p(cnt) / lmax);
 					ctx.fillRect(m.left + k * cw1, m.top + (gRows - 1 - r) * ch1, cw1 + 0.5, ch1 + 0.5);
 				}
 		}
+		if (hl && !hlHidden) {
+			const core = cssVar(st, '--tr-on-surface', '#111'), halo = cssVar(st, '--tr-surface', '#fff');
+			const r = highlightSize / 2;
+			ctx.globalAlpha = 1;
+			for (let i = 0; i < hl.n; i++) {
+				const x = hl.xs[i], y = hl.ys[i];
+				if (!(x >= v.x0 && x <= v.x1 && y >= v.y0 && y <= v.y1)) continue;
+				const px = X(x), py = Y(y);
+				ctx.fillStyle = halo;
+				ctx.beginPath(); ctx.arc(px, py, r + 2, 0, Math.PI * 2); ctx.fill();
+				ctx.fillStyle = core;
+				ctx.beginPath(); ctx.arc(px, py, r, 0, Math.PI * 2); ctx.fill();
+			}
+		}
 		ctx.restore();
+		if (markers && maxCount !== 0) maxCount = 0;
 		inView = n;
 		mode = markers ? 'markers' : 'heatmap';
 	}
@@ -252,14 +332,22 @@
 		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 };
+		const rx = (12 / pw) * (v.x1 - v.x0), ry = (12 / ph) * (v.y1 - v.y0);
+		// highlights sit on top, so they win over markers and bins
+		const hi = hl && !hlHidden ? nearest(hl, noHid, qx, qy, rx, ry) : -1;
+		const i = hi >= 0 ? hi : mode === 'markers' ? nearest(data, hid, qx, qy, rx, ry) : -1;
+		if (i >= 0) {
+			const src = hi >= 0 ? hl! : data;
+			const label = hi >= 0 ? highlight!.labels?.[i] : undefined;
+			const x = m.left + ((src.xs[i] - v.x0) / (v.x1 - v.x0)) * pw, y = m.top + ph - ((src.ys[i] - v.y0) / (v.y1 - v.y0)) * ph;
+			const group = hi >= 0 ? hlName : data.g ? data.names[data.g[i]] : undefined;
+			hover = {
+				x, y, head: label ?? group ?? 'Point', rows: [[xFormat(src.xs[i]), xLabel ?? 'x'], [yFormat(src.ys[i]), yLabel ?? 'y']], rx: x - 6, ry: y - 6, rw: 12, rh: 12,
+				item: { kind: 'point', index: i, x: src.xs[i], y: src.ys[i], group, highlight: hi >= 0, label }
+			};
 			return;
 		}
+		if (mode === 'markers') { hover = null; 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];
@@ -269,7 +357,8 @@
 		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
+			rx: m.left + k * cw1, ry: m.top + q * ch1, rw: cw1, rh: ch1,
+			item: { kind: 'bin', count: cnt, x0: bx, x1: bx + sx, y0: by, y1: by + sy }
 		};
 	}
 
@@ -302,8 +391,21 @@
 		rows.sort((a, b) => b.count - a.count);
 		return { n, regions: rows.length, rows: rows.slice(0, 12) };
 	});
+	const HL_ROWS = 50;
+	const hlRows = $derived.by(() => {
+		const rows: { label: string; x: string; y: string }[] = [];
+		let inside = 0;
+		if (hl && !hlHidden)
+			for (let i = 0; i < hl.n; i++) {
+				const x = hl.xs[i], y = hl.ys[i];
+				if (!(x >= cur.x0 && x <= cur.x1 && y >= cur.y0 && y <= cur.y1)) continue;
+				if (++inside <= HL_ROWS) rows.push({ label: highlight!.labels?.[i] ?? `${hlName} ${i + 1}`, x: xFormat(x), y: yFormat(y) });
+			}
+		return { inside, rows };
+	});
 </script>
 
+{#snippet chart()}
 <ChartFrame {title} {subtitle} {items} ontoggle={toggle}>
 	{#snippet plot(w)}
 		<!-- svelte-ignore a11y_no_noninteractive_tabindex, a11y_no_noninteractive_element_interactions -->
@@ -314,7 +416,7 @@
 			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>
+			<canvas bind:this={canvas} style:height="{H}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>
@@ -322,12 +424,20 @@
 
 		{#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}
+				{#if tooltip}
+					{@render tooltip(hover.item)}
+				{:else}
+					<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}
+				{/if}
 			</Tooltip>
 		{/if}
+
+		{#if colorKey && mode === 'heatmap'}
+			<div class="key"><ColorScale caption="Points per cell, log scale" low="1" mid={fmtValue(Math.max(1, Math.round(Math.sqrt(peak + 1) - 1)))} high={fmtValue(peak)} size={180} /></div>
+		{/if}
 	{/snippet}
 
 	{#snippet table()}
@@ -342,8 +452,28 @@
 				{/each}
 			</tbody>
 		</table>
+		{#if highlight}
+			<table class="hl">
+				<caption>{hlName}: {hlHidden ? 'hidden' : `${fmtValue(hlRows.inside)} in view${hlRows.inside > hlRows.rows.length ? ` (first ${hlRows.rows.length} shown)` : ''}`}</caption>
+				<thead><tr><th>Point</th><th>{xLabel ?? 'X'}</th><th>{yLabel ?? 'Y'}</th></tr></thead>
+				<tbody>
+					{#each hlRows.rows as r}
+						<tr><td>{r.label}</td><td>{r.x}</td><td>{r.y}</td></tr>
+					{:else}
+						<tr><td colspan="3">No highlighted points in view</td></tr>
+					{/each}
+				</tbody>
+			</table>
+		{/if}
 	{/snippet}
 </ChartFrame>
+{/snippet}
+
+{#if fill}
+	<div class="fillwrap" bind:this={wrap}>{@render chart()}</div>
+{:else}
+	{@render chart()}
+{/if}
 
 <style>
 	.dc { position: relative; touch-action: none; cursor: grab; outline: none; user-select: none; }
@@ -355,6 +485,9 @@
 	.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); }
+	.key { margin-top: 6px; }
+	.fillwrap { height: 100%; min-height: 0; overflow: hidden; }
+	.hl { margin-top: 12px; }
 	.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; }

package/dist/DensityChart.svelte.d.ts

@@ -1,4 +1,5 @@
-import { type DensityPoint } from './density.js';
+import type { Snippet } from 'svelte';
+import { type DensityHighlight, type DensityHover, 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[];
@@ -10,7 +11,12 @@ type $$ComponentProps = {
     groupNames?: string[];
     title?: string;
     subtitle?: string;
-    height?: number;
+    /**
+     * Plot height in px (default 320), or `'fill'` to size to the container's height. `'fill'` measures the
+     * parent with a ResizeObserver, so the parent needs a definite height (e.g. `height: 360px`, or a grid/flex
+     * track with a fixed size). A parent with `height: auto` collapses to the 120px minimum.
+     */
+    height?: number | 'fill';
     xLabel?: string;
     yLabel?: string;
     xFormat?: (n: number) => string;
@@ -24,7 +30,24 @@ type $$ComponentProps = {
     markerThreshold?: number;
     /** Marker edge in CSS px. */
     markerSize?: number;
+    /**
+     * A small set of notable points that stay drawn as markers on top of the heatmap at every zoom, with their
+     * own legend entry (toggleable), tooltip hit-testing and a table section. Pass them separately from `points` /
+     * `xs`: highlights are not part of the bin counts, so do not repeat them in the main data. Cost is linear in
+     * the highlight count per frame, so keep the set small (thousands, not 10^5).
+     */
+    highlight?: DensityHighlight;
+    /** Highlight marker diameter in CSS px (a surface-coloured halo is added around it). */
+    highlightSize?: number;
+    /** Replaces the default tooltip body. Receives the hovered point (index, x, y, group, highlight flag) or bin (count and ranges). */
+    tooltip?: Snippet<[item: DensityHover]>;
+    /** Show a colour key (points per cell, 1 to the busiest cell in view) under the plot while in heatmap mode. */
+    colorKey?: boolean;
+    /** Bindable: the busiest cell's point count in the current view (heatmap mode; 0 while drawing markers). Cells are coloured on a log scale from 1 to this value. */
+    maxCount?: number;
+    /** Bindable: the resolved heatmap ramp, low to high, as CSS colours (from `--trc-seq-*` or the built-in fallback). */
+    ramp?: string[];
 };
-declare const DensityChart: import("svelte").Component<$$ComponentProps, {}, "">;
+declare const DensityChart: import("svelte").Component<$$ComponentProps, {}, "maxCount" | "ramp">;
 type DensityChart = ReturnType<typeof DensityChart>;
 export default DensityChart;

package/dist/DonutChart.svelte

@@ -1,5 +1,6 @@
 <script lang="ts">
 	import ChartFrame from './ChartFrame.svelte';
+	import { watchFill } from './fill.js';
 	import { fmtValue, seriesColor, str, MAX_SERIES } from './util.js';
 
 	let {
@@ -7,13 +8,22 @@
 		title,
 		subtitle,
 		size = 200,
+		height,
 		format = fmtValue,
 		centerLabel = 'Total'
 	}: {
 		slices: { name: string; value: number }[];
 		title?: string;
 		subtitle?: string;
+		/** Donut diameter in px (default 200). Capped to the available width when `height` is `'fill'`. */
 		size?: number;
+		/**
+		 * Overrides `size`: a number sets the diameter in px, or `'fill'` sizes the donut to the container's height
+		 * (and never wider than the container). `'fill'` measures the parent with a ResizeObserver, so the parent
+		 * needs a definite height (e.g. `height: 360px`, or a grid/flex track with a fixed size). A parent with
+		 * `height: auto` collapses to the 120px minimum.
+		 */
+		height?: number | 'fill';
 		format?: (n: number) => string;
 		centerLabel?: string;
 	} = $props();
@@ -34,9 +44,20 @@
 	const items = $derived(base.map((s) => ({ name: s.name, color: s.color, hidden: hidden.includes(s.name) })));
 	const toggle = (n: string) => (hidden = hidden.includes(n) ? hidden.filter((h) => h !== n) : [...hidden, n]);
 
-	const r = $derived(size / 2 - 6);
-	const th = $derived(Math.max(14, size * 0.14));
-	const arcs = $derived.by(() => {
+	// height='fill': the svg = container height minus the frame's own chrome (title, legend, padding)
+	let wrap = $state<HTMLElement>();
+	let fillH = $state(200);
+	const fill = $derived(height === 'fill');
+	$effect(() => {
+		if (!fill || !wrap) return;
+		return watchFill(wrap, 'svg', (h) => (fillH = h));
+	});
+	const diameter = (w: number) => (height === 'fill' ? Math.max(120, Math.min(fillH, w)) : (height ?? size));
+
+	// geometry for a diameter of `size` px; built per render because 'fill' also depends on the available width
+	const arcsFor = (size: number) => {
+		const r = size / 2 - 6;
+		const th = Math.max(14, size * 0.14);
 		let a0 = -Math.PI / 2;
 		return vis.map((s) => {
 			const sweep = total ? (s.value / total) * Math.PI * 2 : 0;
@@ -50,7 +71,7 @@
 			a0 = a1;
 			return { ...s, d };
 		});
-	});
+};
 	const focus = $derived(vis.find((s) => s.name === active));
 	/** Share of the visible total; 0 (not NaN) when everything visible is 0. */
 	const pct = (v: number) => (total ? Math.round((v / total) * 100) : 0);
@@ -58,8 +79,11 @@
 	const sliceLabel = (a: { name: string; value: number }) => `${a.name}: ${str(format(a.value))} (${pct(a.value)}%)`;
 </script>
 
+{#snippet chart()}
 <ChartFrame {title} {subtitle} {items} ontoggle={toggle}>
-	{#snippet plot()}
+	{#snippet plot(w)}
+		{@const size = diameter(w)}
+		{@const arcs = arcsFor(size)}
 		<div class="wrap">
 			<svg width={size} height={size} role="img" aria-label="{title ?? 'Donut chart'}. A table view is available.">
 				{#each arcs as a (a.name)}
@@ -88,8 +112,16 @@
 		</table>
 	{/snippet}
 </ChartFrame>
+{/snippet}
+
+{#if fill}
+	<div class="fillwrap" bind:this={wrap}>{@render chart()}</div>
+{:else}
+	{@render chart()}
+{/if}
 
 <style>
+	.fillwrap { height: 100%; min-height: 0; overflow: hidden; }
 	.wrap { display: flex; justify-content: center; padding: 8px 0; }
 	/* 2px surface gap between adjacent fills */
 	.slice { stroke: var(--tr-surface-container-low); stroke-width: 2; outline: none; transition: opacity var(--tr-dur-fast) var(--tr-ease); }

package/dist/DonutChart.svelte.d.ts

@@ -5,7 +5,15 @@ type $$ComponentProps = {
     }[];
     title?: string;
     subtitle?: string;
+    /** Donut diameter in px (default 200). Capped to the available width when `height` is `'fill'`. */
     size?: number;
+    /**
+     * Overrides `size`: a number sets the diameter in px, or `'fill'` sizes the donut to the container's height
+     * (and never wider than the container). `'fill'` measures the parent with a ResizeObserver, so the parent
+     * needs a definite height (e.g. `height: 360px`, or a grid/flex track with a fixed size). A parent with
+     * `height: auto` collapses to the 120px minimum.
+     */
+    height?: number | 'fill';
     format?: (n: number) => string;
     centerLabel?: string;
 };

package/dist/Histogram.svelte

@@ -1,5 +1,6 @@
 <script lang="ts">
 	import ChartFrame from './ChartFrame.svelte';
+	import { watchFill } from './fill.js';
 	import Tooltip from './Tooltip.svelte';
 	import { barPath, fmtAxis, fmtValue, linear, niceTicks, seriesColor, str } from './util.js';
 
@@ -21,7 +22,12 @@
 		domain?: [number, number];
 		title?: string;
 		subtitle?: string;
-		height?: number;
+		/**
+		 * Plot height in px (default 240), or `'fill'` to size to the container's height. `'fill'` measures the
+		 * parent with a ResizeObserver, so the parent needs a definite height (e.g. `height: 360px`, or a grid/flex
+		 * track with a fixed size). A parent with `height: auto` collapses to the 120px minimum.
+		 */
+		height?: number | 'fill';
 		color?: string;
 		xFormat?: (n: number) => string;
 		/** Brushed selection [from, to] on the value axis (snaps to bin edges). Drag to select, click to clear. */
@@ -61,10 +67,22 @@
 	const span = (i: number) => `${str(xFormat(edges[i]))} – ${str(xFormat(edges[i + 1]))}`;
 	const snapLo = (v: number) => grid.min + Math.floor((v - grid.min) / step + 1e-9) * step;
 	const snapHi = (v: number) => grid.min + Math.ceil((v - grid.min) / step - 1e-9) * step;
+
+	// height='fill': plot = container height minus the frame's own chrome (title, legend, key, padding)
+	let wrap = $state<HTMLElement>();
+	let fillH = $state(240);
+	const fill = $derived(height === 'fill');
+	const H = $derived(height === 'fill' ? fillH : height);
+	$effect(() => {
+		if (!fill || !wrap) return;
+		return watchFill(wrap, 'svg', (h) => (fillH = h));
+	});
 </script>
 
+{#snippet chart()}
 <ChartFrame {title} {subtitle}>
 	{#snippet plot(w)}
+		{@const height = H}
 		{@const m = { top: 12, right: 12, bottom: 28, left: 46 }}
 		{@const X = linear(grid.min, grid.max, m.left, w - m.right)}
 		{@const Y = linear(yScale.min, yScale.max, height - m.bottom, m.top)}
@@ -147,8 +165,16 @@
 		</table>
 	{/snippet}
 </ChartFrame>
+{/snippet}
+
+{#if fill}
+	<div class="fillwrap" bind:this={wrap}>{@render chart()}</div>
+{:else}
+	{@render chart()}
+{/if}
 
 <style>
+	.fillwrap { height: 100%; min-height: 0; overflow: hidden; }
 	svg { display: block; outline: none; overflow: visible; }
 	svg:focus-visible { border-radius: var(--tr-radius-sm); box-shadow: var(--tr-focus-ring); }
 	.grid { stroke: var(--tr-outline-variant); stroke-opacity: 0.6; }

package/dist/Histogram.svelte.d.ts

@@ -5,7 +5,12 @@ type $$ComponentProps = {
     domain?: [number, number];
     title?: string;
     subtitle?: string;
-    height?: number;
+    /**
+     * Plot height in px (default 240), or `'fill'` to size to the container's height. `'fill'` measures the
+     * parent with a ResizeObserver, so the parent needs a definite height (e.g. `height: 360px`, or a grid/flex
+     * track with a fixed size). A parent with `height: auto` collapses to the 120px minimum.
+     */
+    height?: number | 'fill';
     color?: string;
     xFormat?: (n: number) => string;
     /** Brushed selection [from, to] on the value axis (snaps to bin edges). Drag to select, click to clear. */

package/dist/LineChart.svelte

@@ -1,6 +1,7 @@
 <script lang="ts">
 	import ChartFrame from './ChartFrame.svelte';
 	import Tooltip from './Tooltip.svelte';
+	import { watchFill } from './fill.js';
 	import type { Series, Band, ReferenceLine } from './types.js';
 	import { fmtAxis, fmtValue, fmtX, isPos, linear, logLinear, logTicks, niceTicks, seriesColor, str, spreadLabels, MAX_SERIES } from './util.js';
 
@@ -96,16 +97,7 @@
 	const H = $derived(height === 'fill' ? fillH : height);
 	$effect(() => {
 		if (!fill || !wrap) return;
-		const el = wrap;
-		const measure = () => {
-			const fig = el.querySelector('figure'), svg = el.querySelector('svg[role=group]');
-			if (!fig || !svg) return;
-			fillH = Math.max(120, Math.floor(el.clientHeight - (fig.getBoundingClientRect().height - svg.getBoundingClientRect().height)));
-		};
-		const ro = new ResizeObserver(measure);
-		ro.observe(el);
-		measure();
-		return () => ro.disconnect();
+		return watchFill(wrap, 'svg[role=group]', (h) => (fillH = h));
 	});
 	/** Per visible series: [lo, hi] band at each x (stacked), else lo = 0, hi = value. */
 	const bands = $derived.by(() => {

package/dist/ScatterChart.svelte

@@ -1,5 +1,6 @@
 <script lang="ts">
 	import ChartFrame from './ChartFrame.svelte';
+	import { watchFill } from './fill.js';
 	import Tooltip from './Tooltip.svelte';
 	import type { ScatterPoint } from './types.js';
 	import { fmtAxis, fmtValue, linear, niceTicks, seriesColor, MAX_SERIES } from './util.js';
@@ -21,7 +22,12 @@
 		points: ScatterPoint[];
 		title?: string;
 		subtitle?: string;
-		height?: number;
+		/**
+		 * Plot height in px (default 280), or `'fill'` to size to the container's height. `'fill'` measures the
+		 * parent with a ResizeObserver, so the parent needs a definite height (e.g. `height: 360px`, or a grid/flex
+		 * track with a fixed size). A parent with `height: auto` collapses to the 120px minimum.
+		 */
+		height?: number | 'fill';
 		xLabel?: string;
 		yLabel?: string;
 		/** Name of the size dimension in tooltips and the table. */
@@ -63,10 +69,22 @@
 	const cur = $derived(active != null ? (vis[active] ?? null) : null);
 	const readout = (p: (typeof vis)[number]) =>
 		`${p.label ?? 'Point'}${p.group ? `, ${p.group}` : ''}: ${xLabel ?? 'x'} ${xFormat(p.x)}, ${yLabel ?? 'y'} ${yFormat(p.y)}${p.size != null ? `, ${sizeLabel.toLowerCase()} ${sizeFormat(p.size)}` : ''}`;
+
+	// height='fill': plot = container height minus the frame's own chrome (title, legend, key, padding)
+	let wrap = $state<HTMLElement>();
+	let fillH = $state(280);
+	const fill = $derived(height === 'fill');
+	const H = $derived(height === 'fill' ? fillH : height);
+	$effect(() => {
+		if (!fill || !wrap) return;
+		return watchFill(wrap, 'svg[role=group]', (h) => (fillH = h));
+	});
 </script>
 
+{#snippet chart()}
 <ChartFrame {title} {subtitle} {items} ontoggle={toggle}>
 	{#snippet plot(w)}
+		{@const height = H}
 		{@const m = { top: 14, right: 16, bottom: xLabel ? 44 : 28, left: yLabel ? 62 : 48 }}
 		{@const X = linear(xScale.min, xScale.max, m.left, w - m.right)}
 		{@const Y = linear(yScale.min, yScale.max, height - m.bottom, m.top)}
@@ -136,8 +154,16 @@
 		</table>
 	{/snippet}
 </ChartFrame>
+{/snippet}
+
+{#if fill}
+	<div class="fillwrap" bind:this={wrap}>{@render chart()}</div>
+{:else}
+	{@render chart()}
+{/if}
 
 <style>
+	.fillwrap { height: 100%; min-height: 0; overflow: hidden; }
 	svg { display: block; outline: none; overflow: visible; }
 	svg:focus-visible { border-radius: var(--tr-radius-sm); box-shadow: var(--tr-focus-ring); }
 	.grid { stroke: var(--tr-outline-variant); stroke-opacity: 0.6; stroke-width: 1; }

package/dist/ScatterChart.svelte.d.ts

@@ -4,7 +4,12 @@ type $$ComponentProps = {
     points: ScatterPoint[];
     title?: string;
     subtitle?: string;
-    height?: number;
+    /**
+     * Plot height in px (default 280), or `'fill'` to size to the container's height. `'fill'` measures the
+     * parent with a ResizeObserver, so the parent needs a definite height (e.g. `height: 360px`, or a grid/flex
+     * track with a fixed size). A parent with `height: auto` collapses to the 120px minimum.
+     */
+    height?: number | 'fill';
     xLabel?: string;
     yLabel?: string;
     /** Name of the size dimension in tooltips and the table. */

package/dist/density.d.ts

@@ -24,6 +24,40 @@ export type Prepared = {
  * Groups beyond the 8 palette slots, and points without a group in a grouped set, take slot 0.
  */
 export declare function prepare(points: DensityPoint[] | undefined, xs: ArrayLike<number> | undefined, ys: ArrayLike<number> | undefined, groupIds?: Uint8Array, groupNames?: string[]): Prepared;
+/** Finite extent of the first `n` pairs, or `null` when none is finite. */
+export declare function extentOf(px: ArrayLike<number>, py: ArrayLike<number>, n: number): View | null;
+/** Smallest extent holding both (either may be `null`). */
+export declare function mergeExtent(a: View | null, b: View | null): View | null;
+/** What a custom `tooltip` snippet receives. */
+export type DensityHover = {
+    kind: 'point';
+    /** Index into the `points` / `xs` array, or into `highlight.xs` when `highlight` is true. */
+    index: number;
+    x: number;
+    y: number;
+    /** Group name (or the highlight name for a highlight). */
+    group?: string;
+    /** True for a point from the `highlight` set. */
+    highlight: boolean;
+    /** Per-point label of a highlight, when supplied. */
+    label?: string;
+} | {
+    kind: 'bin';
+    count: number;
+    x0: number;
+    x1: number;
+    y0: number;
+    y1: number;
+};
+/** A small set of notable points drawn as markers on top of the heatmap at every zoom. */
+export type DensityHighlight = {
+    xs: ArrayLike<number>;
+    ys: ArrayLike<number>;
+    /** Legend entry, default "Highlighted". */
+    name?: string;
+    /** Optional text per point, shown in the tooltip and the highlights table. */
+    labels?: ArrayLike<string>;
+};
 /**
  * Counts the points inside `v` into `out` (cols x rows, row 0 at the bottom, y up) in one pass, skipping hidden
  * groups and non-finite values. Returns how many points fell inside the view. No allocation.

package/dist/density.js

@@ -45,6 +45,10 @@ export function prepare(points, xs, ys, groupIds, groupNames) {
         names = [...ids.keys()];
     }
     const n = Math.min(px.length, py.length);
+    return { xs: px, ys: py, g, names, n, extent: extentOf(px, py, n) };
+}
+/** Finite extent of the first `n` pairs, or `null` when none is finite. */
+export function extentOf(px, py, n) {
     let x0 = Infinity, x1 = -Infinity, y0 = Infinity, y1 = -Infinity;
     for (let i = 0; i < n; i++) {
         const x = px[i], y = py[i];
@@ -59,7 +63,13 @@ export function prepare(points, xs, ys, groupIds, groupNames) {
         if (y > y1)
             y1 = y;
     }
-    return { xs: px, ys: py, g, names, n, extent: x0 <= x1 ? { x0, x1, y0, y1 } : null };
+    return x0 <= x1 ? { x0, x1, y0, y1 } : null;
+}
+/** Smallest extent holding both (either may be `null`). */
+export function mergeExtent(a, b) {
+    if (!a || !b)
+        return a ?? b;
+    return { x0: Math.min(a.x0, b.x0), x1: Math.max(a.x1, b.x1), y0: Math.min(a.y0, b.y0), y1: Math.max(a.y1, b.y1) };
 }
 /**
  * Counts the points inside `v` into `out` (cols x rows, row 0 at the bottom, y up) in one pass, skipping hidden

package/dist/fill.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Shared `height="fill"` measuring for the charts. Observes `el` (the fill wrapper) and reports the plot height:
+ * the wrapper's height minus the frame's own chrome (title, legend, key, padding), found by comparing the
+ * `<figure>` with the plot element matched by `probe`. The result is floored at 120px.
+ * Returns a disposer that disconnects the observer.
+ */
+export declare function watchFill(el: HTMLElement, probe: string, onHeight: (h: number) => void): () => void;

package/dist/fill.js

@@ -0,0 +1,18 @@
+/**
+ * Shared `height="fill"` measuring for the charts. Observes `el` (the fill wrapper) and reports the plot height:
+ * the wrapper's height minus the frame's own chrome (title, legend, key, padding), found by comparing the
+ * `<figure>` with the plot element matched by `probe`. The result is floored at 120px.
+ * Returns a disposer that disconnects the observer.
+ */
+export function watchFill(el, probe, onHeight) {
+    const measure = () => {
+        const fig = el.querySelector('figure'), plot = el.querySelector(probe);
+        if (!fig || !plot)
+            return;
+        onHeight(Math.max(120, Math.floor(el.clientHeight - (fig.getBoundingClientRect().height - plot.getBoundingClientRect().height))));
+    };
+    const ro = new ResizeObserver(measure);
+    ro.observe(el);
+    measure();
+    return () => ro.disconnect();
+}

package/dist/index.d.ts

@@ -10,4 +10,4 @@ export { default as ColorScale } from './ColorScale.svelte';
 export { seriesColor, niceTicks, linear, gradientFrom } from './util.js';
 export type { ScaleKind } from './util.js';
 export type { Series, ScatterPoint, Band, ReferenceLine } from './types.js';
-export type { DensityPoint } from './density.js';
+export type { DensityPoint, DensityHighlight, DensityHover } from './density.js';

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ruckc/truss-chart",
-	"version": "1.8.0",
+	"version": "1.10.0",
 	"description": "Zero-dependency SVG charts for Truss UI",
 	"type": "module",
 	"license": "MIT",