@mstone6969/graph 0.0.0-stage → 0.1.0

package/dist/charts/distribution/HistogramChart.js

@@ -0,0 +1,146 @@
+import { ChartFamily, DataShape, Dimension, Orientation } from "../../core/enums.js";
+import { BinnedChart } from "./BinnedChart.js";
+import { readable } from "./DistributionChart.js";
+import { DistributionSamples } from "./DistributionSamples.js";
+import { DistributionStats } from "./DistributionStats.js";
+import { BinRule, DistributionFit, DistributionLayout, FrequencyScale, HistogramShape, KernelKind, KernelSmoothing } from "./enums.js";
+import { max } from "d3";
+// src/charts/distribution/HistogramChart.ts
+/** Shows the shape of a distribution by counting values into bins; the first chart to reach for with one numeric column. */
+var HistogramChart = class extends BinnedChart {
+	static meta = {
+		id: "histogram",
+		name: "Histogram",
+		family: ChartFamily.Distribution,
+		dimension: Dimension.Two,
+		shape: DataShape.Table,
+		description: "Counts values into equal-width bins to show the shape, spread and modes of a distribution.",
+		tags: [
+			"frequency",
+			"bins",
+			"stacked histogram",
+			"normal curve"
+		],
+		sample: (seed) => DistributionSamples.uneven(seed, 180, 3),
+		variants: {
+			orientation: [Orientation.Vertical, Orientation.Horizontal],
+			bins: [
+				BinRule.FreedmanDiaconis,
+				BinRule.Sturges,
+				BinRule.SquareRoot
+			],
+			frequency: [
+				FrequencyScale.Count,
+				FrequencyScale.Percent,
+				FrequencyScale.Density,
+				FrequencyScale.Cumulative
+			],
+			layout: [
+				DistributionLayout.Pooled,
+				DistributionLayout.Overlaid,
+				DistributionLayout.Stacked,
+				DistributionLayout.Dodged
+			],
+			shape: [HistogramShape.Bars, HistogramShape.Outline],
+			fit: [
+				DistributionFit.None,
+				DistributionFit.Normal,
+				DistributionFit.Kde
+			]
+		},
+		valid: ({ frequency, layout, shape, fit }) => {
+			const stacks = layout === DistributionLayout.Stacked || layout === DistributionLayout.Dodged;
+			if (stacks && shape !== HistogramShape.Bars) return false;
+			if (stacks && frequency === FrequencyScale.Cumulative) return false;
+			if (fit === DistributionFit.None) return true;
+			return layout === DistributionLayout.Pooled && shape === HistogramShape.Bars && (frequency === FrequencyScale.Count || frequency === FrequencyScale.Density);
+		}
+	};
+	defaults() {
+		return {
+			...super.defaults(),
+			layout: DistributionLayout.Pooled,
+			shape: HistogramShape.Bars,
+			fit: DistributionFit.None
+		};
+	}
+	get pooled() {
+		return this.options.layout === DistributionLayout.Pooled;
+	}
+	showsLegend() {
+		return !this.pooled;
+	}
+	blocks(samples) {
+		const { layout } = this.options;
+		const edges = this.edges(samples);
+		const stacked = layout === DistributionLayout.Stacked;
+		const total = stacked ? this.grandTotal(samples) : void 0;
+		const floors = new Array(edges.length - 1).fill(0);
+		return samples.flatMap((sample, slot) => this.bins(sample, edges, total).map((bin, i) => {
+			const base = stacked ? floors[i] : 0;
+			if (stacked) floors[i] += bin.height;
+			return {
+				...bin,
+				key: `${sample.name}/${i}`,
+				sample,
+				base,
+				slot
+			};
+		}));
+	}
+	fitLine(samples) {
+		const { fit, frequency } = this.options;
+		const sample = samples[0];
+		if (!sample || fit === DistributionFit.None) return [];
+		const edges = this.edges(samples), s = sample.summary;
+		const unit = frequency === FrequencyScale.Density ? 1 : s.n * (edges[1] - edges[0]);
+		const curve = fit === DistributionFit.Kde ? DistributionStats.density(sample.values, KernelKind.Gaussian, KernelSmoothing.Balanced) : [];
+		const steps = 80;
+		return Array.from({ length: 81 }, (_, i) => {
+			const v = s.min + (s.max - s.min) * i / steps;
+			return [v, (fit === DistributionFit.Kde ? DistributionStats.at(curve, v) : DistributionStats.normal(v, s.mean, s.sd)) * unit];
+		});
+	}
+	measureDomain(samples) {
+		const top = max(this.blocks(samples), (b) => b.base + b.height) ?? 1;
+		return [0, Math.max(top, max(this.fitLine(samples), (p) => p[1]) ?? 0)];
+	}
+	plotSeries(ctx, frame, samples) {
+		const { shape, layout, frequency } = this.options;
+		const blocks = this.blocks(samples);
+		const m = frame.measure, slots = layout === DistributionLayout.Dodged ? Math.max(1, samples.length) : 1;
+		const bars = shape === HistogramShape.Bars ? blocks.filter((b) => b.count) : [];
+		const span = (b) => {
+			const a = frame.value(b.lo), width = (frame.value(b.hi) - a) / slots, gap = Math.min(2, Math.abs(width) * .2) * Math.sign(width);
+			const start = a + width * (slots > 1 ? b.slot : 0);
+			return [start + gap / 2, start + width - gap / 2];
+		};
+		const marks = ctx.marks("hist-bars", "path", bars, (b) => b.key).attr("fill", (b) => ctx.palette.color(b.sample.name)).attr("fill-opacity", layout === DistributionLayout.Overlaid ? .5 : 1);
+		ctx.set(marks, { d: (b) => frame.bar(...span(b), m(b.base), m(b.base + b.height)) }, { d: (b) => frame.bar(...span(b), m(b.base), m(b.base)) }, 4);
+		const shown = frequency === FrequencyScale.Count ? "Count" : "Share";
+		ctx.hover(marks, (b) => ({
+			title: `${readable(b.lo)} – ${readable(b.hi)}`,
+			color: ctx.palette.color(b.sample.name),
+			rows: [[b.sample.name || shown, b.count], ...frequency === FrequencyScale.Count ? [] : [[frequency, readable(b.height)]]]
+		}));
+		const outlines = shape === HistogramShape.Outline ? samples : [];
+		const path = (sample, scale) => {
+			const own = blocks.filter((b) => b.sample === sample);
+			const steps = own.flatMap((b) => [[b.lo, m(b.height * scale)], [b.hi, m(b.height * scale)]]);
+			const first = own[0], last = own[own.length - 1];
+			if (!first || !last) return "";
+			return frame.path(frequency === FrequencyScale.Cumulative ? [[first.lo, m(0)], ...steps] : [
+				[first.lo, m(0)],
+				...steps,
+				[last.hi, m(0)]
+			]);
+		};
+		const lines = ctx.marks("hist-outline", "path", outlines, (s) => s.name).attr("fill", (s) => frequency === FrequencyScale.Cumulative ? "none" : ctx.palette.color(s.name)).attr("fill-opacity", .14).attr("stroke", (s) => ctx.palette.color(s.name)).attr("stroke-width", 2).attr("stroke-linejoin", "round");
+		ctx.set(lines, { d: (s) => path(s, 1) }, { d: (s) => path(s, 0) });
+		ctx.hover(lines, (s) => this.summaryTip(s, ctx));
+		const fit = this.fitLine(samples);
+		const curve = ctx.marks("hist-fit", "path", fit.length ? [fit] : [], () => "fit").attr("fill", "none").attr("stroke", ctx.theme.ink).attr("stroke-width", 2).attr("stroke-linecap", "round").attr("d", (points) => frame.path(points.map(([v, y]) => [v, m(y)])));
+		ctx.drawOn(curve);
+	}
+};
+export { HistogramChart };

package/dist/charts/distribution/KdeBand.js

@@ -0,0 +1,56 @@
+import { BandDistribution } from "./DistributionChart.js";
+import { DistributionStats } from "./DistributionStats.js";
+import { DensityScaling, DensitySide, KernelKind, KernelSmoothing } from "./enums.js";
+// src/charts/distribution/KdeBand.ts
+/** Band charts built on a kernel density per group; owns the shared density curves and width scaling. */
+var KdeBand = class extends BandDistribution {
+	curves = /* @__PURE__ */ new Map();
+	defaults() {
+		return {
+			...super.defaults(),
+			kernel: KernelKind.Gaussian,
+			smoothing: KernelSmoothing.Balanced,
+			trim: false,
+			scaling: DensityScaling.Area
+		};
+	}
+	valueDomain(samples) {
+		const { kernel, smoothing, trim } = this.options;
+		this.curves = new Map(samples.map((s) => [s.name, DistributionStats.density(s.values, kernel, smoothing, trim)]));
+		const all = [...this.curves.values()].filter((curve) => curve.length);
+		return all.length ? [Math.min(...all.map((c) => c[0].v)), Math.max(...all.map((c) => c[c.length - 1].v))] : [0, 1];
+	}
+	peak(name) {
+		return Math.max(...(this.curves.get(name) ?? []).map((p) => p.d), 0);
+	}
+	/** Maps a raw density to 0..1 of the available width, under the chosen scaling. */
+	widthOf(sample) {
+		const { scaling } = this.options;
+		const peaks = this.pool.map((s) => this.peak(s.name) * (scaling === DensityScaling.Count ? s.summary.n : 1));
+		const top = scaling === DensityScaling.Width ? this.peak(sample.name) : Math.max(...peaks);
+		const weight = scaling === DensityScaling.Count ? sample.summary.n : 1;
+		return (density) => top ? density * weight / top : 0;
+	}
+	profile(sample) {
+		const width = this.widthOf(sample);
+		return (this.curves.get(sample.name) ?? []).map((p) => ({
+			v: p.v,
+			r: width(p.d)
+		}));
+	}
+	/** Closed outline of a density around a band. `Half` grows from one edge of the band. */
+	outline(frame, sample, side, stretch, base = frame.center(sample.name)) {
+		const sign = side === DensitySide.Half && frame.valueOnX ? -1 : 1;
+		const profile = this.profile(sample);
+		const half = side === DensitySide.Half;
+		const anchor = half ? base - sign * frame.half : base;
+		const out = profile.map(({ v, r }) => [v, anchor + sign * r * stretch * frame.half * (half ? 2 : 1)]);
+		const back = (half ? profile.map(({ v }) => [v, anchor]) : profile.map(({ v, r }) => [v, anchor - sign * r * stretch * frame.half])).reverse();
+		return frame.path([...out, ...back], true);
+	}
+	/** Dots share one treatment across swarm-like charts. */
+	ring(dots, radius) {
+		return dots.attr("stroke", this.theme.surface).attr("stroke-width", radius >= 3 ? 1.5 : .75);
+	}
+};
+export { KdeBand };

package/dist/charts/distribution/LetterValueBase.js

@@ -0,0 +1,51 @@
+import { BandDistribution, readable } from "./DistributionChart.js";
+import { DistributionStats } from "./DistributionStats.js";
+import { LetterDepth } from "./enums.js";
+// src/charts/distribution/LetterValueBase.ts
+/** Shared letter-value computation and tail drawing for large-sample box relatives. */
+var LetterValueBase = class extends BandDistribution {
+	defaults() {
+		return {
+			...super.defaults(),
+			depth: LetterDepth.Tukey,
+			outliers: true
+		};
+	}
+	letters(sample) {
+		return DistributionStats.letterValues(sample.values, this.options.depth);
+	}
+	letterTip(sample, letter, ctx) {
+		return {
+			title: `${this.title(sample)} · ${letter.letter}`,
+			color: ctx.palette.color(sample.name),
+			rows: [
+				["Lower", readable(letter.lower)],
+				["Upper", readable(letter.upper)],
+				["Tail", `1/${Math.round(1 / letter.share) * 2}`]
+			]
+		};
+	}
+	drawStrays(ctx, frame, samples) {
+		const strays = this.options.outliers ? samples.flatMap((sample) => {
+			const last = this.letters(sample).at(-1);
+			if (!last) return [];
+			return sample.values.filter((v) => v < last.lower || v > last.upper).map((v, i) => ({
+				key: `${sample.name}/${i}`,
+				sample,
+				v
+			}));
+		}) : [];
+		const dots = ctx.marks("letter-strays", "circle", strays, (d) => d.key).attr("fill", (d) => ctx.palette.color(d.sample.name)).attr("fill-opacity", .7).attr("stroke", ctx.theme.surface).attr("stroke-width", 1);
+		ctx.set(dots, {
+			r: 3,
+			cx: (d) => frame.at(d.v, frame.center(d.sample.name))[0],
+			cy: (d) => frame.at(d.v, frame.center(d.sample.name))[1]
+		});
+		ctx.hover(dots, (d) => ({
+			title: this.title(d.sample),
+			color: ctx.palette.color(d.sample.name),
+			rows: [["Tail value", readable(d.v)]]
+		}));
+	}
+};
+export { LetterValueBase };

package/dist/charts/distribution/LetterValuePlot.js

@@ -0,0 +1,103 @@
+import { ChartFamily, DataShape, Dimension, Orientation } from "../../core/enums.js";
+import { DistributionSamples } from "./DistributionSamples.js";
+import { GroupOrder, LetterDepth, LetterForm } from "./enums.js";
+import { LetterValueBase } from "./LetterValueBase.js";
+// src/charts/distribution/LetterValuePlot.ts
+/** Tukey's letter values as one stepped outline: for reading exactly where each tail fraction falls. */
+var LetterValuePlot = class extends LetterValueBase {
+	static meta = {
+		id: "letter-value",
+		name: "Letter-value plot",
+		family: ChartFamily.Distribution,
+		dimension: Dimension.Two,
+		shape: DataShape.Table,
+		description: "Draws each named depth (median, fourths, eighths and beyond) as a stepped silhouette or ladder of rungs.",
+		tags: [
+			"letter values",
+			"depth",
+			"tukey",
+			"lv"
+		],
+		sample: (seed) => DistributionSamples.uneven(seed, 200, 4),
+		variants: {
+			orientation: [Orientation.Vertical, Orientation.Horizontal],
+			form: [LetterForm.Silhouette, LetterForm.Ladder],
+			depth: [
+				LetterDepth.Tukey,
+				LetterDepth.Proportion,
+				LetterDepth.Trustworthy
+			],
+			labels: [true, false],
+			outliers: [true, false],
+			order: [GroupOrder.Given, GroupOrder.Ascending]
+		},
+		valid: ({ labels, order }) => labels === true || order === GroupOrder.Given
+	};
+	defaults() {
+		return {
+			...super.defaults(),
+			form: LetterForm.Silhouette,
+			labels: true,
+			padding: .3
+		};
+	}
+	reach(letters, index, half) {
+		return half * (1 - index / Math.max(1, letters.length));
+	}
+	/** One side of the stepped outline, from the low tail through the widest tier to the high tail. */
+	side(levels, width) {
+		const down = levels.flatMap((level, i) => [[level.lower, width(i)], ...i ? [[levels[i - 1].lower, width(i)]] : []]).reverse();
+		const up = levels.flatMap((level, i) => [...i ? [[levels[i - 1].upper, width(i)]] : [], [level.upper, width(i)]]);
+		return [...down, ...up];
+	}
+	silhouette(frame, sample) {
+		const letters = this.letters(sample), c = frame.center(sample.name);
+		const side = this.side(letters.slice(1), (i) => this.reach(letters, i, frame.half));
+		return frame.path([...side.map(([v, w]) => [v, c + w]), ...side.map(([v, w]) => [v, c - w]).reverse()], true);
+	}
+	plotSamples(ctx, frame, samples) {
+		const { form, labels } = this.options;
+		const { palette, theme } = ctx;
+		const ladder = form === LetterForm.Ladder;
+		const bodies = ctx.marks("letter-body", "path", ladder ? [] : samples, (s) => s.name).attr("fill", (s) => palette.color(s.name)).attr("stroke-linejoin", "round");
+		ctx.set(bodies, { d: (s) => this.silhouette(frame, s) });
+		ctx.hover(bodies, (s) => this.summaryTip(s, ctx));
+		const rungs = samples.flatMap((sample) => {
+			const letters = this.letters(sample), c = frame.center(sample.name);
+			return letters.flatMap((letter, index) => {
+				const w = this.reach(letters, index, frame.half);
+				return (index ? [letter.lower, letter.upper] : [letter.lower]).map((v, side) => ({
+					key: `${sample.name}/${letter.letter}/${side}`,
+					sample,
+					letter,
+					g: frame.line(v, c - w, v, c + w),
+					index
+				}));
+			});
+		});
+		const lines = ctx.marks("letter-rungs", "line", ladder ? rungs : rungs.filter((r) => !r.index), (r) => r.key).attr("stroke", (r) => ladder ? palette.color(r.sample.name) : theme.surface).attr("stroke-width", (r) => r.index ? 2 : 3).attr("stroke-linecap", "round");
+		ctx.set(lines, {
+			x1: (r) => r.g.x1,
+			x2: (r) => r.g.x2,
+			y1: (r) => r.g.y1,
+			y2: (r) => r.g.y2
+		});
+		ctx.hover(lines, (r) => this.letterTip(r.sample, r.letter, ctx));
+		const first = samples[0];
+		let placed = -Infinity;
+		const tags = labels && first ? this.letters(first).filter((l) => {
+			const fits = Math.abs(frame.value(l.upper) - placed) >= 12;
+			if (fits) placed = frame.value(l.upper);
+			return fits;
+		}) : [];
+		const c = frame.center(first?.name ?? "") + frame.half + 7;
+		const text = ctx.marks("letter-tags", "text", tags, (l) => l.letter).text((l) => l.letter).attr("text-anchor", frame.valueOnX ? "middle" : "start").attr("dominant-baseline", "central");
+		ctx.text(text, 10, "muted");
+		ctx.set(text, {
+			x: (l) => frame.at(l.upper, c)[0],
+			y: (l) => frame.at(l.upper, c)[1]
+		});
+		this.drawStrays(ctx, frame, samples);
+	}
+};
+export { LetterValuePlot };

package/dist/charts/distribution/ParetoChart.js

@@ -0,0 +1,248 @@
+import { CartesianChart } from "../../core/CartesianChart.js";
+import { ChartFamily, DataShape, Dimension, Orientation } from "../../core/enums.js";
+import { ZoomAxis } from "../../core/ChartViewport.js";
+import { SampleData } from "../../data/SampleData.js";
+import { readable, thinLabels } from "./DistributionChart.js";
+import { ParetoCutoff, ParetoLine, ParetoTail } from "./enums.js";
+import { axisRight, axisTop, format, group, scaleBand, scaleLinear, sum } from "d3";
+// src/charts/distribution/ParetoChart.ts
+var OTHER = "Other";
+var CHAR = 6.2;
+var LONGEST = 10;
+var LEAN = 35 * Math.PI / 180;
+/** Sorted causes with their running share: for deciding which few categories to act on first. */
+var ParetoChart = class extends CartesianChart {
+	static meta = {
+		id: "pareto",
+		name: "Pareto chart",
+		family: ChartFamily.Distribution,
+		dimension: Dimension.Two,
+		shape: DataShape.Table,
+		description: "Sorts categories by size and adds their running share, showing which few account for most of the total.",
+		tags: [
+			"80/20",
+			"quality",
+			"cumulative"
+		],
+		sample: (seed) => SampleData.categories(seed, 12, 1),
+		variants: {
+			orientation: [Orientation.Vertical, Orientation.Horizontal],
+			cutoff: [
+				ParetoCutoff.Highlight,
+				ParetoCutoff.Line,
+				ParetoCutoff.None
+			],
+			line: [
+				ParetoLine.Line,
+				ParetoLine.Step,
+				ParetoLine.None
+			],
+			tail: [ParetoTail.All, ParetoTail.Other],
+			threshold: [.8, .5]
+		},
+		valid: ({ cutoff, threshold, line }) => {
+			if (line === ParetoLine.None) return cutoff === ParetoCutoff.Highlight && threshold === .8;
+			return cutoff !== ParetoCutoff.None || threshold === .8;
+		}
+	};
+	ranks = [];
+	share;
+	zoomAxes() {
+		return this.vertical ? ZoomAxis.X : ZoomAxis.Y;
+	}
+	defaults() {
+		return {
+			category: "category",
+			value: "value",
+			orientation: Orientation.Vertical,
+			cutoff: ParetoCutoff.Highlight,
+			threshold: .8,
+			line: ParetoLine.Line,
+			tail: ParetoTail.All,
+			keep: 7
+		};
+	}
+	get vertical() {
+		return this.options.orientation === Orientation.Vertical;
+	}
+	/** Height the bottom labels need once they lean; zero when they fit flat. */
+	get lean() {
+		if (!this.vertical) return 0;
+		const names = this.rank().map((r) => r.name);
+		const longest = Math.min(LONGEST, Math.max(0, ...names.map((name) => name.length))) * CHAR;
+		const step = (this.size.width - 110) / Math.max(1, names.length);
+		return longest + 6 > step ? Math.ceil(longest * Math.sin(LEAN)) : 0;
+	}
+	plotMargin() {
+		const base = super.plotMargin();
+		return this.vertical ? {
+			...base,
+			right: 44,
+			bottom: base.bottom + this.lean
+		} : {
+			...base,
+			top: base.top + 18
+		};
+	}
+	rank() {
+		const { data, category, value, tail, keep, threshold } = this.options;
+		const totals = [...group(Array.isArray(data) ? data : [], (row) => String(row[category] ?? ""))].map(([name, rows]) => ({
+			name,
+			value: sum(rows, (row) => Math.max(0, Number(row[value]) || 0))
+		})).filter((row) => row.value > 0).sort((a, b) => b.value - a.value);
+		const kept = tail === ParetoTail.Other && totals.length > keep + 1 ? totals.slice(0, keep) : totals;
+		const rest = sum(totals.slice(kept.length), (row) => row.value);
+		const rows = rest ? [...kept, {
+			name: OTHER,
+			value: rest
+		}] : kept;
+		const total = sum(rows, (row) => row.value) || 1;
+		let running = 0, crossed = false;
+		return rows.map((row, i) => {
+			running += row.value;
+			const vital = !crossed;
+			crossed = running / total >= threshold;
+			return {
+				...row,
+				cumulative: running / total,
+				vital,
+				folded: !!rest && i === rows.length - 1
+			};
+		});
+	}
+	scales(ctx) {
+		this.ranks = this.rank();
+		const { width, height } = ctx.plot;
+		const band = scaleBand(this.ranks.map((r) => r.name), this.vertical ? [0, width] : [0, height]).paddingInner(.14).paddingOuter(.06);
+		const top = Math.max(1e-9, ...this.ranks.map((r) => r.value));
+		const total = sum(this.ranks, (r) => r.value) || 1;
+		const value = scaleLinear([0, this.options.line === ParetoLine.None ? top : total], this.vertical ? [height, 0] : [0, width]);
+		if (this.options.line === ParetoLine.None) value.nice();
+		this.share = scaleLinear([0, 1], this.vertical ? [height, 0] : [0, width]);
+		return this.vertical ? {
+			x: band,
+			y: value
+		} : {
+			x: value,
+			y: band
+		};
+	}
+	tickFormat(scale) {
+		if (typeof (scale.domain?.() ?? [])[0] !== "string") return super.tickFormat(scale);
+		const room = 11;
+		return (value) => {
+			const text = String(value);
+			return text.length > room ? `${text.slice(0, 10)}…` : text;
+		};
+	}
+	plotMarks(ctx, axes) {
+		const { palette, theme } = ctx;
+		const { cutoff, threshold, line } = this.options;
+		const vertical = this.vertical;
+		const band = vertical ? axes.x : axes.y;
+		const value = vertical ? axes.y : axes.x;
+		const { width, height } = ctx.plot;
+		const lean = this.lean;
+		const names = ctx.root.select(".m-axis-x").selectAll("text");
+		const every = Math.ceil(20 / band.step());
+		names.attr("display", (_, i) => i % every ? "none" : "inline");
+		if (lean) names.attr("text-anchor", "end").attr("transform", "rotate(-35)").attr("dx", -2).attr("dy", 8);
+		else names.attr("text-anchor", "middle").attr("transform", null).attr("dx", null);
+		thinLabels(ctx, "y", 1);
+		if (!vertical) thinLabels(ctx, "x", 6);
+		const main = palette.color(this.options.value.replace(/^./, (c) => c.toUpperCase()));
+		const highlight = cutoff === ParetoCutoff.Highlight;
+		const fill = (r) => highlight && !r.vital ? theme.axis : main;
+		if (!vertical) {
+			ctx.root.select(".m-grid").selectAll("line").remove();
+			this.grid(ctx, value);
+		} else ctx.marks("grid-x", "line", []);
+		const bars = ctx.marks("pareto-bars", "rect", this.ranks, (r) => r.name).attr("fill", fill).attr("rx", Math.min(4, band.bandwidth() / 2));
+		const zero = value(0);
+		ctx.set(bars, vertical ? {
+			x: (r) => band(r.name),
+			width: band.bandwidth(),
+			y: (r) => value(r.value),
+			height: (r) => zero - value(r.value)
+		} : {
+			y: (r) => band(r.name),
+			height: band.bandwidth(),
+			x: zero,
+			width: (r) => value(r.value) - zero
+		}, vertical ? {
+			x: (r) => band(r.name),
+			width: band.bandwidth(),
+			y: zero,
+			height: 0
+		} : {
+			y: (r) => band(r.name),
+			height: band.bandwidth(),
+			x: zero,
+			width: 0
+		}, 25);
+		const percent = format(".1%");
+		ctx.hover(bars, (r) => ({
+			title: r.name,
+			color: fill(r),
+			rows: [["Value", readable(r.value)], ["Share to here", percent(r.cumulative)]]
+		}));
+		const show = line !== ParetoLine.None;
+		const accent = show ? palette.color("Cumulative share") : "";
+		const at = (r, p = r.cumulative) => vertical ? [band(r.name) + band.bandwidth() / 2, this.share(p)] : [this.share(p), band(r.name) + band.bandwidth() / 2];
+		const path = this.path(this.ranks.map((r) => at(r)), line === ParetoLine.Step, vertical);
+		const curve = ctx.marks("pareto-line", "path", show ? [path] : [], () => "line").attr("fill", "none").attr("stroke", accent).attr("stroke-width", 2).attr("stroke-linejoin", "round").attr("d", (d) => d);
+		ctx.drawOn(curve);
+		const dots = ctx.marks("pareto-dots", "circle", show ? this.ranks : [], (r) => r.name).attr("fill", accent).attr("stroke", theme.surface).attr("stroke-width", 2);
+		ctx.set(dots, {
+			r: 4,
+			cx: (r) => at(r)[0],
+			cy: (r) => at(r)[1]
+		}, {
+			r: 0,
+			cx: (r) => at(r)[0],
+			cy: (r) => at(r)[1]
+		}, 25);
+		ctx.hover(dots, (r) => ({
+			title: r.name,
+			color: accent,
+			rows: [["Running share", percent(r.cumulative)]]
+		}));
+		const vital = this.ranks.filter((r) => r.vital), last = vital[vital.length - 1];
+		const reach = last ? band(last.name) + band.bandwidth() + (band.step() - band.bandwidth()) / 2 : 0;
+		ctx.marks("pareto-zone", "rect", highlight && last ? [reach] : [], () => "zone").attr("fill", theme.grid).attr("fill-opacity", .45).attr("rx", 4).attr("x", 0).attr("y", 0).attr("width", vertical ? reach : width).attr("height", vertical ? height : reach);
+		ctx.group("pareto-zone").lower();
+		const crossing = cutoff !== ParetoCutoff.Line ? null : this.ranks.find((r) => r.cumulative >= threshold);
+		const p = this.share(threshold);
+		ctx.marks("pareto-threshold", "line", crossing ? [p] : [], () => "rule").attr("stroke", theme.inkMuted).attr("stroke-width", 1).attr("stroke-dasharray", "4 4").attr("x1", vertical ? 0 : p).attr("x2", vertical ? width : p).attr("y1", vertical ? p : 0).attr("y2", vertical ? p : height);
+		const label = ctx.marks("pareto-threshold-label", "text", crossing ? [crossing] : [], () => "label").text(`${Math.round(threshold * 100)}%`);
+		ctx.text(label, 11, "secondary").attr("x", vertical ? 4 : p + 4).attr("y", vertical ? p - 5 : height - 4);
+		const axis = ctx.group("axis-share");
+		const percentAxis = (vertical ? axisRight(this.share).tickValues([
+			0,
+			.25,
+			.5,
+			.75,
+			1
+		]).tickSize(0) : axisTop(this.share).tickValues([
+			0,
+			.25,
+			.5,
+			.75,
+			1
+		]).tickSize(0)).tickFormat(format(".0%"));
+		axis.attr("transform", vertical ? `translate(${width},0)` : "").call(show ? percentAxis : (selection) => selection.selectAll("*").remove());
+		axis.select(".domain").attr("stroke", "none");
+		axis.selectAll("text").attr("fill", theme.inkSecondary).attr("font-size", 11).attr("font-family", theme.fontFamily);
+	}
+	grid(ctx, value) {
+		const lines = ctx.marks("grid-x", "line", this.options.grid === false ? [] : value.ticks(5));
+		ctx.group("grid-x").lower();
+		lines.attr("x1", (t) => value(t)).attr("x2", (t) => value(t)).attr("y1", 0).attr("y2", ctx.plot.height).attr("stroke", ctx.theme.grid).attr("stroke-width", 1);
+	}
+	path(points, step, vertical) {
+		if (!points.length) return "";
+		if (!step) return `M${points.map((p) => p.join(",")).join("L")}`;
+		return `M${points.flatMap((p, i) => i ? [vertical ? [p[0], points[i - 1][1]] : [points[i - 1][0], p[1]], p] : [p]).map((p) => p.join(",")).join("L")}`;
+	}
+};
+export { ParetoChart };

package/dist/charts/distribution/QuantileDotplot.js

@@ -0,0 +1,62 @@
+import { ChartFamily, DataShape, Dimension, Orientation } from "../../core/enums.js";
+import { readable } from "./DistributionChart.js";
+import { DistributionSamples } from "./DistributionSamples.js";
+import { DistributionStats } from "./DistributionStats.js";
+import { DotBinning, DotStackDirection, GroupOrder } from "./enums.js";
+import { DotStackBase } from "./DotStackBase.js";
+// src/charts/distribution/QuantileDotplot.ts
+/** Turns a probability distribution into countable outcomes: "7 of 20 dots are late" is easy to read. */
+var QuantileDotplot = class extends DotStackBase {
+	static meta = {
+		id: "quantile-dotplot",
+		name: "Quantile dotplot",
+		family: ChartFamily.Distribution,
+		dimension: Dimension.Two,
+		shape: DataShape.Table,
+		description: "Represents a distribution as a fixed number of equally likely dots, making probabilities countable.",
+		tags: [
+			"uncertainty",
+			"frequency framing",
+			"forecast",
+			"outcomes"
+		],
+		sample: (seed) => DistributionSamples.uneven(seed, 200, 3),
+		variants: {
+			orientation: [Orientation.Horizontal, Orientation.Vertical],
+			quantiles: [
+				50,
+				20,
+				100
+			],
+			binning: [DotBinning.Wilkinson, DotBinning.Histodot],
+			stack: [DotStackDirection.Up, DotStackDirection.Center],
+			squares: [false, true],
+			order: [GroupOrder.Given, GroupOrder.Ascending]
+		},
+		valid: ({ squares, stack }) => !(squares && stack === DotStackDirection.Center)
+	};
+	defaults() {
+		return {
+			...super.defaults(),
+			orientation: Orientation.Horizontal,
+			quantiles: 50
+		};
+	}
+	plotSamples(ctx, frame, samples) {
+		const { quantiles, threshold, value } = this.options;
+		const dots = samples.flatMap((sample) => {
+			const values = DistributionStats.quantileDots(sample.values, quantiles), color = ctx.palette.color(sample.name);
+			return this.stackDots(frame, sample, values, (i) => threshold === void 0 || values[i] >= threshold ? color : ctx.theme.axis);
+		});
+		this.drawDots(ctx, dots, (dot) => ({
+			title: this.title(dot.sample),
+			color: dot.color,
+			rows: [[value, readable(dot.datum)], ["Each dot", `${readable(100 / quantiles)}% chance`]]
+		}));
+		const rules = ctx.marks("quantile-threshold", "line", threshold === void 0 ? [] : [threshold], () => "rule").attr("stroke", ctx.theme.ink).attr("stroke-width", 2).attr("stroke-dasharray", "4 4");
+		const span = frame.valueOnX ? ctx.plot.height : ctx.plot.width;
+		const at = threshold === void 0 ? null : frame.line(threshold, 0, threshold, span);
+		if (at) rules.attr("x1", at.x1).attr("x2", at.x2).attr("y1", at.y1).attr("y2", at.y2);
+	}
+};
+export { QuantileDotplot };