@rokkit/chart 1.3.7 → 1.3.9

package/dist/lib/brewing/marks/boxes.d.ts

@@ -8,17 +8,26 @@
  * Box body uses the lighter fill shade; whiskers and median use the darker stroke shade.
  *
  * @param {Object[]} data - Pre-aggregated rows with quartile fields
- * @param {{ x?: string, fill?: string }} channels
+ * @param {{ x?: string, fill?: string, pattern?: string }} channels
  *   `fill` drives the box and whisker color (defaults to x-field).
  * @param {import('d3-scale').ScaleBand} xScale
  * @param {import('d3-scale').ScaleLinear} yScale
  * @param {Map<unknown, {fill:string, stroke:string}>} colors
+ * @param {{ side?: 'left'|'right'|'center', width?: number, patterns?: Map<unknown, string> }} [opts]
+ *   `side` offsets the box to one half of the band; `width` is the box thickness as a
+ *   fraction of the (sub-)band (for a thin raincloud box); `patterns` maps a pattern-channel
+ *   value to a pattern name for texture fills. Defaults preserve the full box.
  * @returns {Array}
  */
 export function buildBoxes(data: Object[], channels: {
     x?: string;
     fill?: string;
+    pattern?: string;
 }, xScale: import("d3-scale").ScaleBand<any>, yScale: import("d3-scale").ScaleLinear<any, any, never>, colors: Map<unknown, {
     fill: string;
     stroke: string;
-}>): any[];
+}>, opts?: {
+    side?: "left" | "right" | "center";
+    width?: number;
+    patterns?: Map<unknown, string>;
+}): any[];

package/dist/lib/brewing/marks/boxes.js

@@ -1,3 +1,5 @@
+import { toPatternId } from '../patterns.js'
+
 /**
  * Builds box geometry for box plot charts.
  * Input data rows must already contain { q1, median, q3, iqr_min, iqr_max } —
@@ -8,30 +10,42 @@
  * Box body uses the lighter fill shade; whiskers and median use the darker stroke shade.
  *
  * @param {Object[]} data - Pre-aggregated rows with quartile fields
- * @param {{ x?: string, fill?: string }} channels
+ * @param {{ x?: string, fill?: string, pattern?: string }} channels
  *   `fill` drives the box and whisker color (defaults to x-field).
  * @param {import('d3-scale').ScaleBand} xScale
  * @param {import('d3-scale').ScaleLinear} yScale
  * @param {Map<unknown, {fill:string, stroke:string}>} colors
+ * @param {{ side?: 'left'|'right'|'center', width?: number, patterns?: Map<unknown, string> }} [opts]
+ *   `side` offsets the box to one half of the band; `width` is the box thickness as a
+ *   fraction of the (sub-)band (for a thin raincloud box); `patterns` maps a pattern-channel
+ *   value to a pattern name for texture fills. Defaults preserve the full box.
  * @returns {Array}
  */
-export function buildBoxes(data, channels, xScale, yScale, colors) {
-	const { x: xf, fill: ff } = channels
+export function buildBoxes(data, channels, xScale, yScale, colors, opts = {}) {
+	const { x: xf, fill: ff, pattern: pf } = channels
+	const { side = 'center', width, patterns } = opts
 	const bw = typeof xScale.bandwidth === 'function' ? xScale.bandwidth() : 20
 	const grouped = ff && ff !== xf
+	// Offset the box centre to the middle of the chosen half-lane.
+	const laneOffset = (unit) => (side === 'left' ? -unit / 4 : side === 'right' ? unit / 4 : 0)
+	// Texture fill: patternId per box from the pattern channel value (null = solid fill).
+	const patternIdFor = (d) => {
+		const key = pf ? d[pf] : null
+		return key !== null && key !== undefined && patterns?.has(key) ? toPatternId(String(key)) : null
+	}
 
 	if (grouped) {
 		const fillValues = [...new Set(data.map((d) => d[ff]))]
 		const n = fillValues.length
 		const subBandWidth = bw / n
-		const boxWidth = subBandWidth * 0.75
-		const whiskerWidth = subBandWidth * 0.4
+		const boxWidth = width !== undefined ? subBandWidth * width : subBandWidth * 0.75
+		const whiskerWidth = width !== undefined ? boxWidth * 0.53 : subBandWidth * 0.4
 
 		return data.map((d) => {
 			const fillVal = d[ff]
 			const subIndex = fillValues.indexOf(fillVal)
 			const bandStart = xScale(d[xf]) ?? 0
-			const cx = bandStart + subIndex * subBandWidth + subBandWidth / 2
+			const cx = bandStart + subIndex * subBandWidth + subBandWidth / 2 + laneOffset(subBandWidth)
 			const colorEntry = colors?.get(fillVal) ?? { fill: '#aaa', stroke: '#666' }
 
 			return {
@@ -42,22 +56,27 @@ export function buildBoxes(data, channels, xScale, yScale, colors) {
 				q3: yScale(d.q3),
 				iqr_min: yScale(d.iqr_min),
 				iqr_max: yScale(d.iqr_max),
+				outliers: (d.outliers ?? []).map((v) => ({ cy: yScale(v), value: v })),
 				width: boxWidth,
 				whiskerWidth,
 				fill: colorEntry.fill,
-				stroke: colorEntry.stroke
+				stroke: colorEntry.stroke,
+				patternId: patternIdFor(d)
 			}
 		})
 	}
 
 	// Non-grouped: one box per x category
-	const boxWidth = bw * 0.6
-	const whiskerWidth = bw * 0.3
+	const boxWidth = width !== undefined ? bw * width : bw * 0.6
+	const whiskerWidth = width !== undefined ? boxWidth * 0.5 : bw * 0.3
 
 	return data.map((d) => {
 		const fillKey = ff ? d[ff] : d[xf]
 		const colorEntry = colors?.get(fillKey) ?? { fill: '#aaa', stroke: '#666' }
-		const cx = (xScale(d[xf]) ?? 0) + (typeof xScale.bandwidth === 'function' ? bw / 2 : 0)
+		const cx =
+			(xScale(d[xf]) ?? 0) +
+			(typeof xScale.bandwidth === 'function' ? bw / 2 : 0) +
+			laneOffset(bw)
 		return {
 			data: d,
 			cx,
@@ -66,10 +85,12 @@ export function buildBoxes(data, channels, xScale, yScale, colors) {
 			q3: yScale(d.q3),
 			iqr_min: yScale(d.iqr_min),
 			iqr_max: yScale(d.iqr_max),
+			outliers: (d.outliers ?? []).map((v) => ({ cy: yScale(v), value: v })),
 			width: boxWidth,
 			whiskerWidth,
 			fill: colorEntry.fill,
-			stroke: colorEntry.stroke
+			stroke: colorEntry.stroke,
+			patternId: patternIdFor(d)
 		}
 	})
 }

package/dist/lib/brewing/marks/lines.d.ts

@@ -11,7 +11,10 @@ export function buildLines(data: Object[], channels: {
     x?: string;
     y?: string;
     color?: string;
-}, xScale: Function, yScale: Function, colors: Map<any, any>, curve?: "linear" | "smooth" | "step"): {
+}, xScale: Function, yScale: Function, colors: Map<any, any>, curve?: "linear" | "smooth" | "step", place?: (x: any, y: any) => {
+    x: any;
+    y: any;
+}): {
     d: string | null;
     fill: string;
     stroke: string;

package/dist/lib/brewing/marks/lines.js

@@ -9,40 +9,43 @@ import { line, curveCatmullRom, curveStep } from 'd3-shape'
  * @param {'linear'|'smooth'|'step'} [curve]
  * @returns {{ d: string | null, fill: string, stroke: string, points: {x:number, y:number, data: Record<string, unknown>, i: number}[], key?: unknown }[]}
  */
-export function buildLines(data, channels, xScale, yScale, colors, curve) {
+export function buildLines(data, channels, xScale, yScale, colors, curve, place = (x, y) => ({ x, y })) {
 	const { x: xf, y: yf, color: cf } = channels
 	const xPos = (d) =>
 		typeof xScale.bandwidth === 'function' ? xScale(d[xf]) + xScale.bandwidth() / 2 : xScale(d[xf])
+	// Screen points, sorted by the x-channel position, each mapped through place() so the
+	// whole line transposes under orientation='horizontal' (identity default → unchanged).
+	const screenPoints = (rows) => {
+		const withIndices = rows.map((d, i) => ({ data: d, i }))
+		withIndices.sort((a, b) => xPos(a.data) - xPos(b.data))
+		return withIndices.map(({ data: d, i }) => {
+			const p = place(xPos(d), yScale(d[yf]))
+			return { x: p.x, y: p.y, data: d, i }
+		})
+	}
 	const makeGen = () => {
 		const gen = line()
-			.x((d) => xPos(d.data ?? d))
-			.y((d) => yScale((d.data ?? d)[yf]))
+			.x((p) => p.x)
+			.y((p) => p.y)
 		if (curve === 'smooth') gen.curve(curveCatmullRom)
 		else if (curve === 'step') gen.curve(curveStep)
 		return gen
 	}
-	const toPoints = (rowsWithIndices) => rowsWithIndices.map(({ data: d, i }) => ({ x: xPos(d), y: yScale(d[yf]), data: d, i }))
-
-	const sortByX = (rows) => {
-		const withIndices = rows.map((d, i) => ({ data: d, i }))
-		withIndices.sort((a, b) => xPos(a.data) - xPos(b.data))
-		return withIndices
-	}
 
 	if (!cf) {
-		const sorted = sortByX(data)
+		const pts = screenPoints(data)
 		const stroke = colors?.values().next().value?.stroke ?? '#888'
-		return [{ d: makeGen()(sorted.map(d => d.data)), fill: 'none', stroke, points: toPoints(sorted) }]
+		return [{ d: makeGen()(pts), fill: 'none', stroke, points: pts }]
 	}
 	const groups = groupBy(data, cf)
 	return [...groups.entries()].map(([key, rows]) => {
-		const sorted = sortByX(rows)
+		const pts = screenPoints(rows)
 		const colorEntry = colors?.get(key) ?? { fill: 'none', stroke: '#888' }
 		return {
-			d: makeGen()(sorted.map(d => d.data)),
+			d: makeGen()(pts),
 			fill: 'none',
 			stroke: colorEntry.stroke,
-			points: toPoints(sorted),
+			points: pts,
 			key
 		}
 	})

package/dist/lib/brewing/marks/swarm.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Places one point per datum within each x-band. Two layouts:
+ *  - 'jitter': deterministic horizontal offset seeded by index-in-group.
+ *  - 'swarm':  1-D beeswarm — sort by y, dodge horizontally to avoid overlap.
+ *
+ * @param {Object[]} data - raw rows (stat=identity)
+ * @param {{ x?: string, y?: string, fill?: string }} channels
+ * @param {import('d3-scale').ScaleBand} xScale
+ * @param {import('d3-scale').ScaleLinear} yScale
+ * @param {Map<unknown, {fill:string, stroke:string}>} colors
+ * @param {{ method?: 'jitter'|'swarm', r?: number, side?: 'left'|'right'|'center' }} opts
+ *   `side` confines points to one half of the band (for raincloud/half-plots).
+ * @returns {Array<{ cx:number, cy:number, fill:string, stroke:string, data:Record<string, unknown> }>}
+ */
+export function buildSwarm(data: Object[], channels: {
+    x?: string;
+    y?: string;
+    fill?: string;
+}, xScale: import("d3-scale").ScaleBand<any>, yScale: import("d3-scale").ScaleLinear<any, any, never>, colors: Map<unknown, {
+    fill: string;
+    stroke: string;
+}>, opts?: {
+    method?: "jitter" | "swarm";
+    r?: number;
+    side?: "left" | "right" | "center";
+}): Array<{
+    cx: number;
+    cy: number;
+    fill: string;
+    stroke: string;
+    data: Record<string, unknown>;
+}>;

package/dist/lib/brewing/marks/swarm.js

@@ -0,0 +1,125 @@
+import { ascending } from 'd3-array'
+
+/**
+ * Deterministic pseudo-random in [0, 1) from a non-negative integer seed.
+ * Avoids Math.random so layouts are stable across renders (repo rule).
+ *
+ * @param {number} n
+ * @returns {number}
+ */
+function hashUnit(n) {
+	const x = Math.sin(n + 1) * 43758.5453
+	return x - Math.floor(x)
+}
+
+/**
+ * Places one point per datum within each x-band. Two layouts:
+ *  - 'jitter': deterministic horizontal offset seeded by index-in-group.
+ *  - 'swarm':  1-D beeswarm — sort by y, dodge horizontally to avoid overlap.
+ *
+ * @param {Object[]} data - raw rows (stat=identity)
+ * @param {{ x?: string, y?: string, fill?: string }} channels
+ * @param {import('d3-scale').ScaleBand} xScale
+ * @param {import('d3-scale').ScaleLinear} yScale
+ * @param {Map<unknown, {fill:string, stroke:string}>} colors
+ * @param {{ method?: 'jitter'|'swarm', r?: number, side?: 'left'|'right'|'center' }} opts
+ *   `side` confines points to one half of the band (for raincloud/half-plots).
+ * @returns {Array<{ cx:number, cy:number, fill:string, stroke:string, data:Record<string, unknown> }>}
+ */
+export function buildSwarm(data, channels, xScale, yScale, colors, opts = {}) {
+	const { x: xf, y: yf, fill: ff } = channels
+	const { method = 'jitter', r = 2, side = 'center' } = opts
+	const bw = typeof xScale.bandwidth === 'function' ? xScale.bandwidth() : 40
+	// One-sided layouts get the full half-band on their side; centred straddles ±halfBand.
+	const halfBand = (bw / 2) * 0.8 // leave a small gutter
+
+	// Group rows by x value, preserving first-seen order.
+	const groups = new Map()
+	for (const d of data) {
+		const key = d[xf]
+		if (!groups.has(key)) groups.set(key, [])
+		groups.get(key).push(d)
+	}
+
+	const result = []
+	for (const [xVal, rows] of groups) {
+		const bandStart = typeof xScale.bandwidth === 'function' ? (xScale(xVal) ?? 0) : (xScale(xVal) ?? 0) - bw / 2
+		const center = bandStart + bw / 2
+		const offsets =
+			method === 'swarm'
+				? swarmOffsets(rows, yf, yScale, r, halfBand, side)
+				: rows.map((_, i) => jitterOffset(hashUnit(i), halfBand, side))
+
+		rows.forEach((d, i) => {
+			const fillKey = ff ? d[ff] : xVal
+			const colorEntry = colors?.get(fillKey) ?? { fill: '#aaa', stroke: '#666' }
+			result.push({
+				data: d,
+				cx: center + offsets[i],
+				cy: yScale(d[yf]),
+				fill: colorEntry.fill,
+				stroke: colorEntry.stroke
+			})
+		})
+	}
+	return result
+}
+
+// Map a [0,1) hash to a horizontal offset, confined to the requested side.
+//  center → [-halfBand, halfBand];  right → [0, halfBand];  left → [-halfBand, 0]
+function jitterOffset(u, halfBand, side) {
+	if (side === 'right') return u * halfBand
+	if (side === 'left') return -u * halfBand
+	return (u * 2 - 1) * halfBand
+}
+
+/**
+ * Computes horizontal offsets for a beeswarm: sort by y, then for each point
+ * pick the smallest-magnitude offset that doesn't collide (distance >= 2r) with
+ * any already-placed point in the group. When the band is over capacity (more
+ * points than fit at 2r spacing), fall back to the least-crowded slot (max
+ * separation) so overflow points spread across the band instead of stacking at
+ * the center — a best-effort layout, not a hard non-overlap guarantee.
+ * `side` confines candidates to one half of the band. Returns offsets in INPUT order.
+ */
+function swarmOffsets(rows, yf, yScale, r, halfBand, side = 'center') {
+	const order = rows
+		.map((d, i) => ({ i, cy: yScale(d[yf]) }))
+		.sort((a, b) => ascending(a.cy, b.cy))
+	const placed = []
+	const offsetByIndex = new Array(rows.length).fill(0)
+	const step = r / 2
+	const kMax = Math.ceil((2 * halfBand) / step)
+
+	for (const { i, cy } of order) {
+		let chosen = 0
+		let placedOne = false
+		let best = { offset: 0, sep: -Infinity }
+		for (let k = 0; k <= kMax; k++) {
+			const candidate =
+				side === 'right'
+					? k * step
+					: side === 'left'
+						? -k * step
+						: k === 0
+							? 0
+							: (k % 2 === 1 ? 1 : -1) * Math.ceil(k / 2) * step
+			if (Math.abs(candidate) > halfBand) continue
+			const sep = placed.length
+				? Math.min(...placed.map((p) => Math.hypot(candidate - p.offset, cy - p.cy)))
+				: Infinity
+			if (sep >= 2 * r) {
+				chosen = candidate
+				placedOne = true
+				break
+			}
+			if (sep > best.sep) best = { offset: candidate, sep }
+		}
+		// Band over capacity: fall back to the least-crowded slot (max separation)
+		// rather than stacking every overflow point at the center.
+		if (!placedOne) chosen = best.offset
+		placed.push({ offset: chosen, cy })
+		offsetByIndex[i] = chosen
+	}
+	return offsetByIndex
+}

package/dist/lib/brewing/marks/violins.d.ts

@@ -1,20 +1,4 @@
-/**
- * Builds a closed violin shape path for each group.
- * Input rows must have { q1, median, q3, iqr_min, iqr_max } from applyBoxStat.
- *
- * When `fill` differs from `x`, violins are sub-grouped within each x-band
- * (one narrower violin per fill value per x category, like grouped bars).
- * Violin body uses the lighter fill shade; outline uses the darker stroke shade.
- *
- * @param {Object[]} data
- * @param {{ x?: string, fill?: string }} channels
- *   `fill` drives violin interior and outline (defaults to x-field).
- * @param {import('d3-scale').ScaleBand} xScale
- * @param {import('d3-scale').ScaleLinear} yScale
- * @param {Map} colors
- * @returns {Array}
- */
-export function buildViolins(data: Object[], channels: {
-    x?: string;
-    fill?: string;
-}, xScale: import("d3-scale").ScaleBand<any>, yScale: import("d3-scale").ScaleLinear<any, any, never>, colors: Map<any, any>): any[];
+export function buildViolins(data: any, channels: any, xScale: any, yScale: any, colors: any, place: (x: any, y: any) => {
+    x: any;
+    y: any;
+}, side: string | undefined, patterns: any): any;

package/dist/lib/brewing/marks/violins.js

@@ -1,4 +1,5 @@
 import { line, curveCatmullRom } from 'd3-shape'
+import { toPatternId } from '../patterns.js'
 
 // Relative widths at each stat anchor (fraction of max half-width)
 const DENSITY_AT = { iqr_min: 0.08, q1: 0.55, median: 1.0, q3: 0.55, iqr_max: 0.08 }
@@ -13,17 +14,48 @@ const ANCHOR_ORDER = ['iqr_max', 'q3', 'median', 'q1', 'iqr_min']
  * Violin body uses the lighter fill shade; outline uses the darker stroke shade.
  *
  * @param {Object[]} data
- * @param {{ x?: string, fill?: string }} channels
+ * @param {{ x?: string, fill?: string, pattern?: string }} channels
  *   `fill` drives violin interior and outline (defaults to x-field).
  * @param {import('d3-scale').ScaleBand} xScale
  * @param {import('d3-scale').ScaleLinear} yScale
  * @param {Map} colors
  * @returns {Array}
  */
-export function buildViolins(data, channels, xScale, yScale, colors) {
-	const { x: xf, fill: ff } = channels
+// Build the silhouette points for one violin. `side` selects half vs full:
+//  'right'  → density bulges right of the centre line, flat edge at cx
+//  'left'   → density bulges left, flat edge at cx
+//  'center' → symmetric (both sides) — the default
+function violinPoints(cx, halfMax, d, yScale, side) {
+	const right = ANCHOR_ORDER.map((key) => ({ x: cx + halfMax * DENSITY_AT[key], y: yScale(d[key]) }))
+	const left = [...ANCHOR_ORDER].reverse().map((key) => ({
+		x: cx - halfMax * DENSITY_AT[key],
+		y: yScale(d[key])
+	}))
+	const topY = yScale(d.iqr_max)
+	const botY = yScale(d.iqr_min)
+	if (side === 'right') return [...right, { x: cx, y: botY }, { x: cx, y: topY }]
+	if (side === 'left') return [...left, { x: cx, y: topY }, { x: cx, y: botY }]
+	return [...right, ...left, right[0]]
+}
+
+export function buildViolins(
+	data,
+	channels,
+	xScale,
+	yScale,
+	colors,
+	place = (x, y) => ({ x, y }),
+	side = 'center',
+	patterns
+) {
+	const { x: xf, fill: ff, pattern: pf } = channels
 	const bw = typeof xScale.bandwidth === 'function' ? xScale.bandwidth() : 40
 	const grouped = ff && ff !== xf
+	// Texture fill: patternId per violin from the pattern channel value (null = solid fill).
+	const patternIdFor = (d) => {
+		const key = pf ? d[pf] : null
+		return key !== null && key !== undefined && patterns?.has(key) ? toPatternId(String(key)) : null
+	}
 
 	const pathGen = line()
 		.x((pt) => pt.x)
@@ -43,21 +75,13 @@ export function buildViolins(data, channels, xScale, yScale, colors) {
 			const cx = bandStart + subIndex * subBandWidth + subBandWidth / 2
 			const colorEntry = colors?.get(fillVal) ?? { fill: '#aaa', stroke: '#666' }
 
-			const rightPts = ANCHOR_ORDER.map((key) => ({
-				x: cx + halfMax * DENSITY_AT[key],
-				y: yScale(d[key])
-			}))
-			const leftPts = [...ANCHOR_ORDER].reverse().map((key) => ({
-				x: cx - halfMax * DENSITY_AT[key],
-				y: yScale(d[key])
-			}))
-
 			return {
 				data: d,
 				cx,
-				d: pathGen([...rightPts, ...leftPts, rightPts[0]]),
+				d: pathGen(violinPoints(cx, halfMax, d, yScale, side).map((pt) => place(pt.x, pt.y))),
 				fill: colorEntry.fill,
-				stroke: colorEntry.stroke
+				stroke: colorEntry.stroke,
+				patternId: patternIdFor(d)
 			}
 		})
 	}
@@ -70,21 +94,13 @@ export function buildViolins(data, channels, xScale, yScale, colors) {
 		const colorEntry = colors?.get(fillKey) ?? { fill: '#aaa', stroke: '#666' }
 		const cx = (xScale(d[xf]) ?? 0) + (typeof xScale.bandwidth === 'function' ? bw / 2 : 0)
 
-		const rightPts = ANCHOR_ORDER.map((key) => ({
-			x: cx + halfMax * DENSITY_AT[key],
-			y: yScale(d[key])
-		}))
-		const leftPts = [...ANCHOR_ORDER].reverse().map((key) => ({
-			x: cx - halfMax * DENSITY_AT[key],
-			y: yScale(d[key])
-		}))
-
 		return {
 			data: d,
 			cx,
-			d: pathGen([...rightPts, ...leftPts, rightPts[0]]),
+			d: pathGen(violinPoints(cx, halfMax, d, yScale, side).map((pt) => place(pt.x, pt.y))),
 			fill: colorEntry.fill,
-			stroke: colorEntry.stroke
+			stroke: colorEntry.stroke,
+			patternId: patternIdFor(d)
 		}
 	})
 }

package/dist/lib/brewing/stats.d.ts

@@ -1,6 +1,8 @@
 /**
  * Computes box plot quartile statistics grouped by x (and optionally color).
- * Output rows have { q1, median, q3, iqr_min, iqr_max } replacing the raw y values.
+ * Output rows have { q1, median, q3, iqr_min, iqr_max, outliers } replacing the raw y values.
+ * iqr_min/iqr_max are Tukey-clamped whisker endpoints (most extreme datum within
+ * the 1.5·IQR fence); outliers holds values outside the fence.
  *
  * @param {Object[]} data
  * @param {{ x?: string, y?: string, color?: string }} channels

package/dist/lib/brewing/stats.js

@@ -5,6 +5,28 @@ function sortedQuantile(values, p) {
 	return quantile([...values].sort(ascending), p)
 }
 
+/**
+ * Tukey whisker bounds for a group of numeric values.
+ * Whiskers clamp to the most extreme datum within the 1.5·IQR fence;
+ * values outside the fence are outliers.
+ *
+ * @param {number[]} values
+ * @returns {{ min: number, max: number, outliers: number[] }}
+ */
+function whiskerBounds(values) {
+	const q1 = sortedQuantile(values, 0.25)
+	const q3 = sortedQuantile(values, 0.75)
+	const iqr = q3 - q1
+	const lo = q1 - 1.5 * iqr
+	const hi = q3 + 1.5 * iqr
+	const within = values.filter((v) => v >= lo && v <= hi)
+	return {
+		min: within.length ? min(within) : q1,
+		max: within.length ? max(within) : q3,
+		outliers: values.filter((v) => v < lo || v > hi)
+	}
+}
+
 /**
  * Built-in reduction functions. Each receives an array of numeric values.
  * @type {Record<string, (values: number[]) => number>}
@@ -19,7 +41,9 @@ export const STAT_FNS = {
 
 /**
  * Computes box plot quartile statistics grouped by x (and optionally color).
- * Output rows have { q1, median, q3, iqr_min, iqr_max } replacing the raw y values.
+ * Output rows have { q1, median, q3, iqr_min, iqr_max, outliers } replacing the raw y values.
+ * iqr_min/iqr_max are Tukey-clamped whisker endpoints (most extreme datum within
+ * the 1.5·IQR fence); outliers holds values outside the fence.
  *
  * @param {Object[]} data
  * @param {{ x?: string, y?: string, color?: string }} channels
@@ -35,16 +59,9 @@ export function applyBoxStat(data, channels) {
 			q1: (v) => sortedQuantile(v, 0.25),
 			median: (v) => sortedQuantile(v, 0.5),
 			q3: (v) => sortedQuantile(v, 0.75),
-			iqr_min: (v) => {
-				const q1 = sortedQuantile(v, 0.25)
-				const q3 = sortedQuantile(v, 0.75)
-				return q1 - 1.5 * (q3 - q1)
-			},
-			iqr_max: (v) => {
-				const q1 = sortedQuantile(v, 0.25)
-				const q3 = sortedQuantile(v, 0.75)
-				return q3 + 1.5 * (q3 - q1)
-			}
+			iqr_min: (v) => whiskerBounds(v).min,
+			iqr_max: (v) => whiskerBounds(v).max,
+			outliers: (v) => whiskerBounds(v).outliers
 		})
 		.rollup()
 		.select()

package/dist/lib/plot/scales.js

@@ -17,6 +17,7 @@ export function inferOrientation(xType, yType) {
 }
 
 export function buildUnifiedXScale(datasets, field, width, opts = {}) {
+	const range = opts.range ?? [0, width]
 	const allValues = datasets.flatMap((d) => d.map((r) => r[field]))
 	const isNumeric = allValues.every(
 		(v) => typeof v === 'number' || (!isNaN(Number(v)) && String(v).trim() !== '')
@@ -26,11 +27,14 @@ export function buildUnifiedXScale(datasets, field, width, opts = {}) {
 	if (opts.domain) {
 		const domainIsNumeric = opts.domain.every((v) => typeof v === 'number')
 		if (!opts.band && (domainIsNumeric || isNumeric)) {
-			return scaleLinear().domain(opts.domain).range([0, width]).nice()
+			const s = scaleLinear().domain(opts.domain).range(range)
+			// nice() rounds the domain to pretty numbers — wrong for a synthetic position axis
+			// (a bar-race rank) whose domain is deliberately padded (e.g. [-0.5, N-0.5]).
+			return opts.nice === false ? s : s.nice()
 		}
 		return scaleBand()
 			.domain(opts.domain)
-			.range([0, width])
+			.range(range)
 			.padding(opts.padding ?? 0.2)
 	}
 
@@ -40,20 +44,21 @@ export function buildUnifiedXScale(datasets, field, width, opts = {}) {
 		const domainMin = (opts.includeZero ?? false) ? 0 : (minVal ?? 0)
 		return scaleLinear()
 			.domain([domainMin, maxVal ?? 0])
-			.range([0, width])
+			.range(range)
 			.nice()
 	}
 
 	const domain = [...new Set(allValues)].filter((v) => v !== null && v !== undefined)
 	return scaleBand()
 		.domain(domain)
-		.range([0, width])
+		.range(range)
 		.padding(opts.padding ?? 0.2)
 }
 
 export function buildUnifiedYScale(datasets, field, height, opts = {}) {
+	const yrange = opts.range ?? [height, 0]
 	if (opts.domain) {
-		return scaleLinear().domain(opts.domain).range([height, 0]).nice()
+		return scaleLinear().domain(opts.domain).range(yrange).nice()
 	}
 	const rawValues = datasets.flatMap((d) => d.map((r) => r[field])).filter((v) => v !== null && v !== undefined)
 	const isNumeric = rawValues.length > 0 && rawValues.every(
@@ -62,14 +67,14 @@ export function buildUnifiedYScale(datasets, field, height, opts = {}) {
 	if (!isNumeric) {
 		// Categorical y-axis (e.g. horizontal bar chart) — use scaleBand
 		const domain = [...new Set(rawValues.map(String))]
-		return scaleBand().domain(domain).range([height, 0]).padding(0.2)
+		return scaleBand().domain(domain).range(yrange).padding(0.2)
 	}
 	const numericValues = rawValues.map(Number)
 	const [minVal, maxVal] = extent(numericValues)
 	const domainMin = (opts.includeZero ?? true) ? 0 : (minVal ?? 0)
 	return scaleLinear()
 		.domain([domainMin, maxVal ?? 0])
-		.range([height, 0])
+		.range(yrange)
 		.nice()
 }
 

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

@@ -29,7 +29,7 @@ export type PlotSpec = {
     theta?: string | undefined;
     labels?: Record<string, string> | undefined;
     xDomain?: unknown[] | undefined;
-    yDomain?: number[] | undefined;
+    yDomain?: unknown[] | undefined;
     xLabel?: string | undefined;
     yLabel?: string | undefined;
     axisOrigin?: [number, number] | undefined;
@@ -54,6 +54,14 @@ export type PlotSpec = {
     title?: string | undefined;
     summary?: string | undefined;
     orientation?: "horizontal" | "vertical" | undefined;
+    /**
+     * Order the category (band) axis by aggregated value — bars sorted by size (histogram-style).
+     */
+    sort?: "asc" | "desc" | undefined;
+    /**
+     * Keep the category (x) axis linear (a continuous position scale) instead of band-forcing it — a bar-chart race's tweened rank. Set only by AnimatedPlot; not a public authoring flag.
+     */
+    continuousCategory?: boolean | undefined;
     /**
      * Stack (true) or group (false) multi-series bars. Forwarded to spec-driven bar geoms via `options.stack`. Default: false.
      */

package/dist/lib/plot/types.js

@@ -29,7 +29,7 @@
  * @property {string} [theta]
  * @property {Record<string, string>} [labels]
  * @property {unknown[]} [xDomain]
- * @property {number[]} [yDomain]
+ * @property {unknown[]} [yDomain]
  * @property {string} [xLabel]
  * @property {string} [yLabel]
  * @property {[number, number]} [axisOrigin]
@@ -46,6 +46,8 @@
  * @property {string} [title]
  * @property {string} [summary]
  * @property {'horizontal'|'vertical'} [orientation]
+ * @property {'asc'|'desc'} [sort]  Order the category (band) axis by aggregated value — bars sorted by size (histogram-style).
+ * @property {boolean} [continuousCategory]  Keep the category (x) axis linear (a continuous position scale) instead of band-forcing it — a bar-chart race's tweened rank. Set only by AnimatedPlot; not a public authoring flag.
  * @property {boolean} [stack]  Stack (true) or group (false) multi-series bars. Forwarded to spec-driven bar geoms via `options.stack`. Default: false.
  * @property {string} [preset]
  * @property {number} [width]