@rokkit/chart 1.7.0 → 1.8.0

package/dist/geoms/lib/bars.js

@@ -1,7 +1,8 @@
 import { scaleBand } from 'd3-scale'
 import { stack, stackOffsetExpand } from 'd3-shape'
 import { toPatternId } from '../../lib/brewing/patterns.js'
-import { isLiteralColor, literalColor, markEntry } from '../../lib/brewing/colors.js'
+import { literalColor, markEntry } from '../../lib/brewing/colors.js'
+import { subBandFields } from '../../lib/plot/stacking.js'
 
 /**
  * Returns a band scale suitable for bar x-positioning.
@@ -16,24 +17,6 @@ function ensureBandX(xScale, data, xField) {
 	return scaleBand().domain(domain).range([r0, r1]).padding(0.2)
 }
 
-/**
- * Returns the sub-band fields: distinct non-x fields among [group, color, pattern].
- * These are the fields that cause multiple bars within a single x-band (dodge/grouping).
- * `group` (the explicit grouping channel) takes precedence as the first sub-band.
- */
-function subBandFields(channels) {
-	const { x: xf, group: gf, color: cf, pattern: pf } = channels
-	const seen = new Set()
-	const out = []
-	for (const f of [gf, cf, pf]) {
-		if (f && f !== xf && !seen.has(f) && !isLiteralColor(f)) {
-			seen.add(f)
-			out.push(f)
-		}
-	}
-	return out
-}
-
 /**
  * The one bar builder. Expresses each bar in abstract (category, value) space and maps it to
  * screen via `place()`, so it renders vertical or horizontal (flip) with the same code.
@@ -141,7 +124,17 @@ export function buildBars(
 	})
 }
 
-export function buildStackedBars(data, channels, xScale, yScale, colors, innerHeight, patterns, place = (x, y) => ({ x, y }), normalize = false) {
+export function buildStackedBars(
+	data,
+	channels,
+	xScale,
+	yScale,
+	colors,
+	innerHeight,
+	patterns,
+	place = (x, y) => ({ x, y }),
+	normalize = false
+) {
 	const { x: xf, y: yf, color: cf, pattern: pf } = channels
 	const lit = literalColor(cf)
 	const field = lit ? undefined : cf

package/dist/geoms/lib/grouping.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Shared by the geoms that summarise GROUPS of points (Hull, Contour) rather than drawing one
+ * mark per row: bucket rows by the group field, and place each row on screen — or drop it
+ * when it has no usable coordinate, which is a normal state in a partially-measured dataset.
+ */
+/**
+ * Screen position of one value on a scale, or null when the row has no usable coordinate
+ * (null / empty / a category the scale does not know / NaN). A band category resolves to its
+ * centre, where a point in that category is drawn.
+ *
+ * @param {any} scale
+ * @param {unknown} v
+ * @returns {number | null}
+ */
+export function coordOf(scale: any, v: unknown): number | null;
+/**
+ * Rows bucketed by `field`, in first-seen order. One bucket (key `null`) without a field.
+ *
+ * @param {Record<string, unknown>[]} data
+ * @param {string | undefined} field
+ * @returns {Map<unknown, Record<string, unknown>[]>}
+ */
+export function groupRows(data: Record<string, unknown>[], field: string | undefined): Map<unknown, Record<string, unknown>[]>;
+/**
+ * Screen points for rows, after orientation `place`, skipping rows with no coordinate.
+ *
+ * @param {Record<string, unknown>[]} rows
+ * @param {any} plot
+ * @param {{ x?: string, y?: string }} channels
+ * @returns {Array<[number, number]>}
+ */
+export function screenPoints(rows: Record<string, unknown>[], plot: any, channels: {
+    x?: string;
+    y?: string;
+}): Array<[number, number]>;

package/dist/geoms/lib/grouping.js

@@ -0,0 +1,59 @@
+/**
+ * Shared by the geoms that summarise GROUPS of points (Hull, Contour) rather than drawing one
+ * mark per row: bucket rows by the group field, and place each row on screen — or drop it
+ * when it has no usable coordinate, which is a normal state in a partially-measured dataset.
+ */
+
+/**
+ * Screen position of one value on a scale, or null when the row has no usable coordinate
+ * (null / empty / a category the scale does not know / NaN). A band category resolves to its
+ * centre, where a point in that category is drawn.
+ *
+ * @param {any} scale
+ * @param {unknown} v
+ * @returns {number | null}
+ */
+export function coordOf(scale, v) {
+	if (v === null || v === undefined || v === '') return null
+	const s = scale(v)
+	if (s === null || s === undefined || Number.isNaN(s)) return null
+	return typeof scale.bandwidth === 'function' ? s + scale.bandwidth() / 2 : s
+}
+
+/**
+ * Rows bucketed by `field`, in first-seen order. One bucket (key `null`) without a field.
+ *
+ * @param {Record<string, unknown>[]} data
+ * @param {string | undefined} field
+ * @returns {Map<unknown, Record<string, unknown>[]>}
+ */
+export function groupRows(data, field) {
+	const groups = new Map()
+	for (const row of data) {
+		const key = field ? row[field] : null
+		if (!groups.has(key)) groups.set(key, [])
+		groups.get(key).push(row)
+	}
+	return groups
+}
+
+/**
+ * Screen points for rows, after orientation `place`, skipping rows with no coordinate.
+ *
+ * @param {Record<string, unknown>[]} rows
+ * @param {any} plot
+ * @param {{ x?: string, y?: string }} channels
+ * @returns {Array<[number, number]>}
+ */
+export function screenPoints(rows, plot, channels) {
+	/** @type {Array<[number, number]>} */
+	const pts = []
+	for (const row of rows) {
+		const u = coordOf(plot.xScale, row[channels.x ?? ''])
+		const v = coordOf(plot.yScale, row[channels.y ?? ''])
+		if (u === null || v === null) continue
+		const p = plot.place(u, v)
+		pts.push([p.x, p.y])
+	}
+	return pts
+}

package/dist/geoms/lib/marks/contour.d.ts

@@ -0,0 +1,26 @@
+/**
+ * SVG path data for a GeoJSON MultiPolygon's coordinates — every ring of every polygon a
+ * closed subpath, so holes cut out under the default nonzero/evenodd rules d3-contour's
+ * winding produces.
+ *
+ * @param {number[][][][]} coordinates
+ */
+export function multiPolygonPath(coordinates: number[][][][]): string;
+/**
+ * Kernel-density contours per group of the `fill` (else `color`) field.
+ *
+ * Density is estimated in SCREEN space over the plot area, so `bandwidth` is in pixels — the
+ * unit a reader judges smoothness in — and the result is the same at any data scale. Level 0
+ * is the outermost (lowest-density) ring; filled bands ramp opacity toward `alpha` at the
+ * densest core, so pile-ups read darkest.
+ *
+ * @param {{ data: any[], plot: any, channels: any, options?: any, alpha?: number, type?: string }} ctx
+ */
+export function buildContourMarks({ data, plot, channels, options, alpha, type }: {
+    data: any[];
+    plot: any;
+    channels: any;
+    options?: any;
+    alpha?: number;
+    type?: string;
+}): any[];

package/dist/geoms/lib/marks/contour.js

@@ -0,0 +1,67 @@
+import { contourDensity } from 'd3-contour'
+import { resolveFillStroke, resolveAlpha } from '../aesthetics.js'
+import { groupRows, screenPoints } from '../grouping.js'
+
+/**
+ * SVG path data for a GeoJSON MultiPolygon's coordinates — every ring of every polygon a
+ * closed subpath, so holes cut out under the default nonzero/evenodd rules d3-contour's
+ * winding produces.
+ *
+ * @param {number[][][][]} coordinates
+ */
+export function multiPolygonPath(coordinates) {
+	const fmt = (/** @type {number} */ n) => Math.round(n * 100) / 100
+	return coordinates
+		.flatMap((polygon) =>
+			polygon.map((ring) => `M${ring.map(([x, y]) => `${fmt(x)},${fmt(y)}`).join('L')}Z`)
+		)
+		.join('')
+}
+
+/**
+ * Kernel-density contours per group of the `fill` (else `color`) field.
+ *
+ * Density is estimated in SCREEN space over the plot area, so `bandwidth` is in pixels — the
+ * unit a reader judges smoothness in — and the result is the same at any data scale. Level 0
+ * is the outermost (lowest-density) ring; filled bands ramp opacity toward `alpha` at the
+ * densest core, so pile-ups read darkest.
+ *
+ * @param {{ data: any[], plot: any, channels: any, options?: any, alpha?: number, type?: string }} ctx
+ */
+export function buildContourMarks({ data, plot, channels, options = {}, alpha, type = 'contour' }) {
+	if (!data?.length || !plot.xScale || !plot.yScale) return []
+	const groupField = channels.fill ?? channels.color
+	const a = resolveAlpha(alpha, type, plot.chartPreset)
+	const w = Math.max(1, Math.round(plot.innerWidth))
+	const h = Math.max(1, Math.round(plot.innerHeight))
+
+	const marks = []
+	for (const [key, rows] of groupRows(data, groupField)) {
+		const pts = screenPoints(rows, plot, channels)
+		if (pts.length === 0) continue
+		const density = contourDensity()
+			.x((d) => d[0])
+			.y((d) => d[1])
+			.size([w, h])
+			.bandwidth(options.bandwidth ?? 20)
+			.thresholds(options.thresholds ?? 8)(pts)
+		const { fill, stroke } = resolveFillStroke(
+			rows[0],
+			{ fill: channels.fill, color: channels.color },
+			plot.colors
+		)
+		density.forEach((level, i) => {
+			marks.push({
+				key: `contour-${String(key)}-${i}`,
+				group: key,
+				level: i,
+				value: level.value,
+				d: multiPolygonPath(level.coordinates),
+				fill,
+				stroke,
+				fillAlpha: (a * (i + 1)) / density.length
+			})
+		})
+	}
+	return marks
+}

package/dist/geoms/lib/marks/hull.d.ts

@@ -0,0 +1,26 @@
+/**
+ * One outline per group of the `fill` (else `color`) channel — ggplot's discrete-colour
+ * grouping. The hull is computed in SCREEN space after `place`, so it is convex as drawn,
+ * whatever the scales (a hull in data space is not convex on a log axis).
+ *
+ * @param {{ data: any[], plot: any, channels: any, options?: any, alpha?: number, type?: string }} ctx
+ */
+export function buildHullMarks({ data, plot, channels, alpha, type }: {
+    data: any[];
+    plot: any;
+    channels: any;
+    options?: any;
+    alpha?: number;
+    type?: string;
+}): {
+    key: string;
+    group: unknown;
+    d: string;
+    fill: string;
+    alpha: number;
+    at: {
+        x: number;
+        y: number;
+    };
+    count: number;
+}[];

package/dist/geoms/lib/marks/hull.js

@@ -0,0 +1,36 @@
+import { convexHull, hullPath } from '../../../lib/hull.js'
+import { centroid } from '../../../lib/region.js'
+import { resolveFillStroke, resolveAlpha } from '../aesthetics.js'
+import { groupRows, screenPoints } from '../grouping.js'
+
+/**
+ * One outline per group of the `fill` (else `color`) channel — ggplot's discrete-colour
+ * grouping. The hull is computed in SCREEN space after `place`, so it is convex as drawn,
+ * whatever the scales (a hull in data space is not convex on a log axis).
+ *
+ * @param {{ data: any[], plot: any, channels: any, options?: any, alpha?: number, type?: string }} ctx
+ */
+export function buildHullMarks({ data, plot, channels, alpha, type = 'hull' }) {
+	const { xScale, yScale, colors } = plot
+	if (!data?.length || !xScale || !yScale) return []
+	const groupField = channels.fill ?? channels.color
+	const a = resolveAlpha(alpha, type, plot.chartPreset)
+
+	const marks = []
+	for (const [key, rows] of groupRows(data, groupField)) {
+		const pts = screenPoints(rows, plot, channels)
+		if (pts.length === 0) continue
+		const hull = convexHull(pts)
+		const { fill } = resolveFillStroke(rows[0], { fill: groupField }, colors)
+		marks.push({
+			key: `hull-${String(key)}`,
+			group: key,
+			d: hullPath(hull),
+			fill,
+			alpha: a,
+			at: centroid(hull.map(([x, y]) => ({ x, y }))),
+			count: rows.length
+		})
+	}
+	return marks
+}

package/dist/geoms/lib/marks/waterfall.js

@@ -1,11 +1,19 @@
 import { resolveAlpha } from '../aesthetics.js'
+import { runningSpans } from '../../../lib/plot/running.js'
 
 /**
  * Build renderable waterfall bars. Bar color is semantic (positive/negative/total from
  * options), not the shared palette. Adds fixed `alpha` and carries connector anchors.
  * @param {{ data: any[], plot: any, channels: any, options?: any, alpha?: number, type?: string }} ctx
  */
-export function buildWaterfallMarks({ data, plot, channels, options = {}, alpha, type = 'waterfall' }) {
+export function buildWaterfallMarks({
+	data,
+	plot,
+	channels,
+	options = {},
+	alpha,
+	type = 'waterfall'
+}) {
 	const { xScale, yScale } = plot
 	if (!data?.length || !xScale || !yScale) return []
 
@@ -16,28 +24,15 @@ export function buildWaterfallMarks({ data, plot, channels, options = {}, alpha,
 	const a = resolveAlpha(alpha, type, plot.chartPreset)
 
 	const bw = typeof xScale.bandwidth === 'function' ? xScale.bandwidth() : 10
-	let cumulative = 0
+	const spans = runningSpans(data, channels.y ?? '', totalField)
 
 	return data.map((d, i) => {
 		const xVal = d[channels.x ?? '']
-		const yVal = Number(d[channels.y ?? ''])
-		const isTotal = totalField ? Boolean(d[totalField]) : false
+		const { lo, hi, total, isTotal, delta } = spans[i]
 		const xPos = xScale(xVal) ?? 0
-		let barTop
-		let barBottom
-		let fill
-
-		if (isTotal) {
-			barTop = yScale(Math.max(0, cumulative)) ?? 0
-			barBottom = yScale(0) ?? 0
-			fill = totalColor
-		} else {
-			const start = cumulative
-			cumulative += yVal
-			barTop = yScale(Math.max(start, cumulative)) ?? 0
-			barBottom = yScale(Math.min(start, cumulative)) ?? 0
-			fill = yVal >= 0 ? positiveColor : negativeColor
-		}
+		const barTop = yScale(hi) ?? 0
+		const barBottom = yScale(lo) ?? 0
+		const fill = isTotal ? totalColor : delta >= 0 ? positiveColor : negativeColor
 
 		const c1 = plot.place(xPos, barTop)
 		const c2 = plot.place(xPos + bw, barBottom)
@@ -51,7 +46,7 @@ export function buildWaterfallMarks({ data, plot, channels, options = {}, alpha,
 			alpha: a,
 			bandStart: xPos,
 			bandEnd: xPos + bw,
-			cumY: yScale(cumulative) ?? 0,
+			cumY: yScale(total) ?? 0,
 			data: d
 		}
 	})

package/dist/index.d.ts

@@ -19,6 +19,9 @@ export namespace Plot {
     export { Ribbon };
     export { Waterfall };
     export { Rule };
+    export { Region };
+    export { Hull };
+    export { Contour };
     export { Radar };
 }
 export namespace PlotLayers { }
@@ -45,6 +48,9 @@ export { default as GeomHighlight } from "./geoms/Highlight.svelte";
 export { default as GeomTrend } from "./geoms/Trend.svelte";
 export { default as GeomJitter } from "./geoms/Jitter.svelte";
 export { default as GeomRule } from "./geoms/Rule.svelte";
+export { default as GeomRegion } from "./geoms/Region.svelte";
+export { default as GeomHull } from "./geoms/Hull.svelte";
+export { default as GeomContour } from "./geoms/Contour.svelte";
 export { default as Chart } from "./Chart.svelte";
 export { default as Sparkline } from "./Sparkline.svelte";
 export { default as Spark } from "./Spark.svelte";
@@ -83,6 +89,9 @@ import Hexbin from './geoms/Hexbin.svelte';
 import Ribbon from './geoms/Ribbon.svelte';
 import Waterfall from './geoms/Waterfall.svelte';
 import Rule from './geoms/Rule.svelte';
+import Region from './geoms/Region.svelte';
+import Hull from './geoms/Hull.svelte';
+import Contour from './geoms/Contour.svelte';
 import Radar from './geoms/Radar.svelte';
 export { createChartPreset, defaultPreset } from "./lib/preset.js";
 export { SparkState, GEOM_CONTRACT } from "./SparkState.svelte.js";

package/dist/index.js

@@ -18,6 +18,9 @@ import Hexbin from './geoms/Hexbin.svelte'
 import Ribbon from './geoms/Ribbon.svelte'
 import Waterfall from './geoms/Waterfall.svelte'
 import Rule from './geoms/Rule.svelte'
+import Region from './geoms/Region.svelte'
+import Hull from './geoms/Hull.svelte'
+import Contour from './geoms/Contour.svelte'
 import Radar from './geoms/Radar.svelte'
 
 // Composable Plot primitives — use as <Plot.Root>, <Plot.Axis>, <Plot.Bar>, etc.
@@ -42,6 +45,9 @@ export const Plot = {
 	Ribbon,
 	Waterfall,
 	Rule,
+	Region,
+	Hull,
+	Contour,
 	Radar
 }
 
@@ -77,6 +83,9 @@ export { default as GeomHighlight } from './geoms/Highlight.svelte'
 export { default as GeomTrend } from './geoms/Trend.svelte'
 export { default as GeomJitter } from './geoms/Jitter.svelte'
 export { default as GeomRule } from './geoms/Rule.svelte'
+export { default as GeomRegion } from './geoms/Region.svelte'
+export { default as GeomHull } from './geoms/Hull.svelte'
+export { default as GeomContour } from './geoms/Contour.svelte'
 
 // Export standalone components
 export { default as Chart } from './Chart.svelte'

package/dist/lib/abline.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The segment of `y = slope·x + intercept` that lies inside a rectangular domain, or null
+ * when the line misses it.
+ *
+ * Clipping in DATA space, not pixels, is what keeps a reference line honest under zoom: the
+ * scales' domains are already the visible window, so the same call is correct at any zoom.
+ * A line that merely touches a corner returns a zero-length segment rather than null — it is
+ * inside the domain, just barely.
+ *
+ * @param {number} slope
+ * @param {number} intercept
+ * @param {[number, number]} xDomain
+ * @param {[number, number]} yDomain
+ * @returns {{ x1: number, y1: number, x2: number, y2: number } | null}
+ */
+export function clipAbline(slope: number, intercept: number, xDomain: [number, number], yDomain: [number, number]): {
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+} | null;
+/**
+ * Where a sloped line's label goes: its midpoint, rotated to run along it.
+ *
+ * Not the end, where an axis-aligned rule puts its label — a sloped line's ends are corners
+ * of the plot, exactly where points and axis ticks crowd. The angle is folded into
+ * (-90°, 90°] so the text never reads upside down, whichever way the line was drawn.
+ *
+ * @param {{ x1: number, y1: number, x2: number, y2: number }} seg  screen coordinates
+ * @returns {{ x: number, y: number, angle: number }}
+ */
+export function slopeLabel({ x1, y1, x2, y2 }: {
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+}): {
+    x: number;
+    y: number;
+    angle: number;
+};

package/dist/lib/abline.js

@@ -0,0 +1,51 @@
+/**
+ * The segment of `y = slope·x + intercept` that lies inside a rectangular domain, or null
+ * when the line misses it.
+ *
+ * Clipping in DATA space, not pixels, is what keeps a reference line honest under zoom: the
+ * scales' domains are already the visible window, so the same call is correct at any zoom.
+ * A line that merely touches a corner returns a zero-length segment rather than null — it is
+ * inside the domain, just barely.
+ *
+ * @param {number} slope
+ * @param {number} intercept
+ * @param {[number, number]} xDomain
+ * @param {[number, number]} yDomain
+ * @returns {{ x1: number, y1: number, x2: number, y2: number } | null}
+ */
+export function clipAbline(slope, intercept, xDomain, yDomain) {
+	const [x0, x1] = [Math.min(...xDomain), Math.max(...xDomain)]
+	const [y0, y1] = [Math.min(...yDomain), Math.max(...yDomain)]
+	const at = (x) => slope * x + intercept
+
+	if (slope === 0) {
+		return intercept < y0 || intercept > y1
+			? null
+			: { x1: x0, y1: intercept, x2: x1, y2: intercept }
+	}
+
+	// Where the line crosses the lower and upper y bounds, ordered along x.
+	const xAtY0 = (y0 - intercept) / slope
+	const xAtY1 = (y1 - intercept) / slope
+	const lo = Math.max(x0, Math.min(xAtY0, xAtY1))
+	const hi = Math.min(x1, Math.max(xAtY0, xAtY1))
+	if (lo > hi) return null
+	return { x1: lo, y1: at(lo), x2: hi, y2: at(hi) }
+}
+
+/**
+ * Where a sloped line's label goes: its midpoint, rotated to run along it.
+ *
+ * Not the end, where an axis-aligned rule puts its label — a sloped line's ends are corners
+ * of the plot, exactly where points and axis ticks crowd. The angle is folded into
+ * (-90°, 90°] so the text never reads upside down, whichever way the line was drawn.
+ *
+ * @param {{ x1: number, y1: number, x2: number, y2: number }} seg  screen coordinates
+ * @returns {{ x: number, y: number, angle: number }}
+ */
+export function slopeLabel({ x1, y1, x2, y2 }) {
+	let angle = (Math.atan2(y2 - y1, x2 - x1) * 180) / Math.PI
+	if (angle > 90) angle -= 180
+	if (angle <= -90) angle += 180
+	return { x: (x1 + x2) / 2, y: (y1 + y2) / 2, angle }
+}

package/dist/lib/hull.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Hull vertices, counter-clockwise in a y-up frame, starting from the lowest-x point.
+ * Collinear edge points are dropped; duplicates collapse; one or two distinct points come
+ * back as-is (a dot, a segment).
+ *
+ * @param {Pt[]} points
+ * @returns {Pt[]}
+ */
+export function convexHull(points: Pt[]): Pt[];
+/**
+ * Closed SVG path through hull vertices. One vertex is a zero-length subpath and two are a
+ * segment — with a round cap and a wide stroke those render as a dot and a capsule, which is
+ * how `Hull` pads every group, whatever its size, with one element.
+ *
+ * @param {Pt[]} hull
+ */
+export function hullPath(hull: Pt[]): string;
+export type Pt = [number, number];

package/dist/lib/hull.js

@@ -0,0 +1,64 @@
+/**
+ * Convex hull (Andrew's monotone chain), O(n log n), and its SVG path.
+ *
+ * Hand-rolled rather than `d3-polygon` because the degenerate cases matter here and d3 returns
+ * null for them: a group with one or two members is still a group, and an outline that
+ * silently disappears for a small package is the same lie as an edge that disappears for an
+ * unresolved call.
+ */
+
+/** @typedef {[number, number]} Pt */
+
+/** z of (b - a) × (c - a): > 0 is a left (counter-clockwise) turn. */
+const cross = (/** @type {Pt} */ a, /** @type {Pt} */ b, /** @type {Pt} */ c) =>
+	(b[0] - a[0]) * (c[1] - a[1]) - (b[1] - a[1]) * (c[0] - a[0])
+
+/**
+ * Hull vertices, counter-clockwise in a y-up frame, starting from the lowest-x point.
+ * Collinear edge points are dropped; duplicates collapse; one or two distinct points come
+ * back as-is (a dot, a segment).
+ *
+ * @param {Pt[]} points
+ * @returns {Pt[]}
+ */
+export function convexHull(points) {
+	const seen = new Set()
+	const pts = []
+	for (const p of points) {
+		const key = `${p[0]},${p[1]}`
+		if (!seen.has(key)) {
+			seen.add(key)
+			pts.push(p)
+		}
+	}
+	pts.sort((a, b) => a[0] - b[0] || a[1] - b[1])
+	if (pts.length < 3) return pts
+
+	/** @param {Pt[]} seq */
+	const chain = (seq) => {
+		/** @type {Pt[]} */
+		const out = []
+		for (const p of seq) {
+			while (out.length >= 2 && cross(out[out.length - 2], out[out.length - 1], p) <= 0) out.pop()
+			out.push(p)
+		}
+		out.pop()
+		return out
+	}
+	const hull = [...chain(pts), ...chain([...pts].reverse())]
+	// All points collinear: both chains collapse to the two extremes.
+	return hull.length < 2 ? [pts[0], pts[pts.length - 1]] : hull
+}
+
+/**
+ * Closed SVG path through hull vertices. One vertex is a zero-length subpath and two are a
+ * segment — with a round cap and a wide stroke those render as a dot and a capsule, which is
+ * how `Hull` pads every group, whatever its size, with one element.
+ *
+ * @param {Pt[]} hull
+ */
+export function hullPath(hull) {
+	if (hull.length === 0) return ''
+	const fmt = (/** @type {number} */ n) => Math.round(n * 1000) / 1000
+	return `M${hull.map(([x, y]) => `${fmt(x)},${fmt(y)}`).join('L')}Z`
+}

package/dist/lib/plot/domains.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Band categories ordered by their summed value — "sort bars by size". Null when not sorting.
+ *
+ * @param {Record<string, unknown>[][]} datasets - every geom's rows
+ * @param {string | undefined} xf
+ * @param {string | undefined} yf
+ * @param {'asc' | 'desc' | undefined} sort
+ */
+export function sortedBandDomain(datasets: Record<string, unknown>[][], xf: string | undefined, yf: string | undefined, sort: "asc" | "desc" | undefined): any[] | null;
+/**
+ * A box/violin spans its whiskers (`iqr_min` / `iqr_max`) and every outlier.
+ *
+ * @param {Record<string, any>[]} rows - box-stat rows
+ */
+export function boxDomain(rows: Record<string, any>[]): number[] | null;
+/**
+ * A stacked bar reaches its column total; a 100%-filled one reaches 1.
+ *
+ * Summed per (x, stack key), keeping the LAST value per key — the builder's own lookup does the
+ * same, so rows sharing a key under an identity stat do not double-count. The stack key is the
+ * builder's (`stackFieldOf`); with none, the builder draws plain bars, so there is no total to
+ * size to and the normal extent applies (null).
+ *
+ * @param {Record<string, unknown>[]} rows
+ * @param {{ x?: string, y?: string, group?: string, fill?: string, color?: string, pattern?: string }} channels
+ * @param {'stack' | 'fill' | undefined} position
+ */
+export function stackDomain(rows: Record<string, unknown>[], channels: {
+    x?: string;
+    y?: string;
+    group?: string;
+    fill?: string;
+    color?: string;
+    pattern?: string;
+}, position: "stack" | "fill" | undefined): number[] | null;
+/**
+ * A waterfall spans its running total: each step from where the last ended, a total row from 0.
+ *
+ * @param {Record<string, unknown>[]} rows
+ * @param {string} field
+ * @param {string} [totalField] - rows flagged here are totals, drawn from zero
+ */
+export function waterfallDomain(rows: Record<string, unknown>[], field: string, totalField?: string): number[] | null;
+/**
+ * The value-axis domain the mounted geoms' geometry demands, or null for the plain extent.
+ *
+ * @param {Array<{ id: string, type: string, options?: Record<string, any> }>} geoms
+ * @param {(id: string) => Record<string, unknown>[]} rowsOf - a geom's rows (post-stat)
+ * @param {{ x?: string, fill?: string, color?: string, pattern?: string }} channels - effective
+ * @param {string} field - the value channel
+ */
+export function resolveValueDomain(geoms: Array<{
+    id: string;
+    type: string;
+    options?: Record<string, any>;
+}>, rowsOf: (id: string) => Record<string, unknown>[], channels: {
+    x?: string;
+    fill?: string;
+    color?: string;
+    pattern?: string;
+}, field: string): number[] | null;