@rokkit/chart 1.3.7 → 1.3.9

package/dist/geoms/Waterfall.svelte

@@ -1,6 +1,8 @@
 <script lang="ts">
 	import { getContext, onMount, onDestroy } from 'svelte'
 	import type { PlotState } from '../PlotState.svelte.js'
+	import { GeomState } from './lib/GeomState.svelte.js'
+	import { buildWaterfallMarks } from './lib/marks/waterfall.js'
 
 	type Options = {
 		positiveColor?: string
@@ -15,90 +17,31 @@
 		y?: string
 		color?: string
 		fill?: string
+		/** Fixed bar opacity 0–1; defaults to the per-geom preset (waterfall = 1). */
+		alpha?: number
 		stat?: string
 		options?: Options
 	}
 
-	let {
-		x,
-		y,
-		color = undefined,
-		fill: fillProp = undefined,
-		stat = 'identity',
-		options = {}
-	}: Props = $props()
+	let { x, y, color, fill, alpha, stat = 'identity', options = {} }: Props = $props()
 
-	const positiveColor = $derived(options.positiveColor ?? '#22c55e')
-	const negativeColor = $derived(options.negativeColor ?? '#ef4444')
-	const totalColor = $derived(options.totalColor ?? '#3b82f6')
-	const totalField = $derived(options.totalField ?? undefined)
+	const colorField = $derived(fill ?? color)
 	const connectorWidth = $derived(options.connectorWidth ?? 0.5)
-
 	const plotState = getContext<PlotState>('plot-state')
-	let id = $state<string | null>(null)
-
-	onMount(() => {
-		id = plotState.registerGeom({
-			type: 'waterfall',
-			channels: { x, y, color: fillProp ?? color },
-			stat
-		})
-	})
-	onDestroy(() => {
-		if (id) plotState.unregisterGeom(id)
-	})
-
-	$effect(() => {
-		if (id)
-			plotState.updateGeom(id, {
-				channels: { x, y, color: fillProp ?? color },
-				stat
-			})
-	})
-
-	const data = $derived(id ? plotState.geomData(id) : [])
-	const xScale = $derived(plotState.xScale)
-	const yScale = $derived(plotState.yScale)
-
-	// eslint-disable-next-line max-lines-per-function
-	const bars = $derived.by(() => {
-		if (!data?.length || !xScale || !yScale) return []
-		const bw = typeof xScale.bandwidth === 'function' ? xScale.bandwidth() : 10
-
-		let cumulative = 0
-		return data.map((d, i) => {
-			const xVal = d[x ?? '']
-			const yVal = Number(d[y ?? ''])
-			const isTotal = totalField ? Boolean(d[totalField]) : false
-			const xPos = xScale(xVal) ?? 0
-			let barTop: number
-			let barBottom: number
-			let fill: string
 
-			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 geom = new GeomState(plotState, () => ({
+		type: 'waterfall',
+		channels: { x, y, color: colorField },
+		stat,
+		options,
+		alpha,
+		build: buildWaterfallMarks
+	}))
+	onMount(geom.register)
+	onDestroy(geom.destroy)
+	$effect(geom.sync)
 
-			return {
-				key: `${xVal}-${i}`,
-				x: xPos,
-				y: barTop,
-				width: bw,
-				height: Math.max(1, barBottom - barTop),
-				fill,
-				cumulative,
-				data: d
-			}
-		})
-	})
+	const bars = $derived(geom.marks)
 </script>
 
 {#if bars.length > 0}
@@ -110,6 +53,7 @@
 				width={Math.max(0, bar.width)}
 				height={bar.height}
 				fill={bar.fill}
+				fill-opacity={bar.alpha}
 				data-plot-element="waterfall-bar"
 				role="img"
 				onmouseenter={() => plotState.setHovered(bar.data)}
@@ -119,11 +63,13 @@
 			</rect>
 			<!-- Connector line to next bar -->
 			{#if i < bars.length - 1}
+				{@const cs = plotState.place(bar.bandEnd, bar.cumY)}
+				{@const ce = plotState.place(bars[i + 1].bandStart, bar.cumY)}
 				<line
-					x1={bar.x + bar.width}
-					y1={yScale(bar.cumulative)}
-					x2={bars[i + 1].x}
-					y2={yScale(bar.cumulative)}
+					x1={cs.x}
+					y1={cs.y}
+					x2={ce.x}
+					y2={ce.y}
 					stroke="currentColor"
 					stroke-width={connectorWidth}
 					stroke-dasharray="3 2"

package/dist/geoms/Waterfall.svelte.d.ts

@@ -10,6 +10,8 @@ type Props = {
     y?: string;
     color?: string;
     fill?: string;
+    /** Fixed bar opacity 0–1; defaults to the per-geom preset (waterfall = 1). */
+    alpha?: number;
     stat?: string;
     options?: Options;
 };

package/dist/geoms/lib/GeomState.svelte.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Per-geom reactive state, fed by the shared `PlotState` context. Owns the geom's
+ * registration lifecycle and derives the renderable `marks` array, so a geom component
+ * only has to render marks + wire interactivity. This is the integrated version of the
+ * old brewer idea — one shared path, not a parallel one.
+ * See docs/backlog/2026-08-17-chart-aesthetics-unification.md §11.
+ *
+ * @typedef {Object} GeomConfig
+ * @property {string} type
+ * @property {Record<string, string | undefined>} channels
+ * @property {string} [stat]
+ * @property {Record<string, unknown>} [options]
+ * @property {number} [alpha]
+ * @property {(ctx: { data: any[], plot: any, channels: any, options: any, alpha: number|undefined, type: string }) => any} build
+ */
+export class GeomState {
+    /**
+     * @param {any} plot - the PlotState from context
+     * @param {() => GeomConfig} config - a getter thunk (Svelte passes reactive values to
+     *   classes via getters), read reactively on every marks recompute.
+     */
+    constructor(plot: any, config: () => GeomConfig);
+    register: () => void;
+    sync: () => void;
+    destroy: () => void;
+    get data(): any;
+    marks: any;
+    #private;
+}
+/**
+ * Per-geom reactive state, fed by the shared `PlotState` context. Owns the geom's
+ * registration lifecycle and derives the renderable `marks` array, so a geom component
+ * only has to render marks + wire interactivity. This is the integrated version of the
+ * old brewer idea — one shared path, not a parallel one.
+ * See docs/backlog/2026-08-17-chart-aesthetics-unification.md §11.
+ */
+export type GeomConfig = {
+    type: string;
+    channels: Record<string, string | undefined>;
+    stat?: string | undefined;
+    options?: Record<string, unknown> | undefined;
+    alpha?: number | undefined;
+    build: (ctx: {
+        data: any[];
+        plot: any;
+        channels: any;
+        options: any;
+        alpha: number | undefined;
+        type: string;
+    }) => any;
+};

package/dist/geoms/lib/GeomState.svelte.js

@@ -0,0 +1,79 @@
+/**
+ * Per-geom reactive state, fed by the shared `PlotState` context. Owns the geom's
+ * registration lifecycle and derives the renderable `marks` array, so a geom component
+ * only has to render marks + wire interactivity. This is the integrated version of the
+ * old brewer idea — one shared path, not a parallel one.
+ * See docs/backlog/2026-08-17-chart-aesthetics-unification.md §11.
+ *
+ * @typedef {Object} GeomConfig
+ * @property {string} type
+ * @property {Record<string, string | undefined>} channels
+ * @property {string} [stat]
+ * @property {Record<string, unknown>} [options]
+ * @property {number} [alpha]
+ * @property {(ctx: { data: any[], plot: any, channels: any, options: any, alpha: number|undefined, type: string }) => any} build
+ */
+export class GeomState {
+	#plot
+	#config
+	#id = $state(null)
+
+	/**
+	 * @param {any} plot - the PlotState from context
+	 * @param {() => GeomConfig} config - a getter thunk (Svelte passes reactive values to
+	 *   classes via getters), read reactively on every marks recompute.
+	 */
+	constructor(plot, config) {
+		this.#plot = plot
+		this.#config = config
+	}
+
+	// Arrow methods so they can be passed straight to onMount/onDestroy/$effect without
+	// losing `this` (see Svelte $state "Classes" docs).
+	register = () => {
+		const c = this.#config()
+		this.#id = this.#plot.registerGeom({
+			type: c.type,
+			channels: c.channels,
+			stat: c.stat ?? 'identity',
+			options: c.options ?? {}
+		})
+	}
+
+	sync = () => {
+		if (this.#id === null) return
+		const c = this.#config()
+		this.#plot.updateGeom(this.#id, {
+			channels: c.channels,
+			stat: c.stat ?? 'identity',
+			options: c.options ?? {}
+		})
+	}
+
+	destroy = () => {
+		if (this.#id !== null) this.#plot.unregisterGeom(this.#id)
+	}
+
+	#data = $derived(this.#id !== null ? this.#plot.geomData(this.#id) : [])
+
+	// The geom's rows (post-stat). Exposed for templates that render per-row overlays
+	// (e.g. an area's invisible tooltip hit-circles) alongside the computed `marks`.
+	get data() {
+		return this.#data
+	}
+
+	// The renderable array. `build` reads scales/colors/preset from `plot` synchronously,
+	// so those reads register as dependencies and `marks` recomputes on any change.
+	marks = $derived.by(() => {
+		const c = this.#config()
+		if (!this.#data.length) return []
+		return c.build({
+			data: this.#data,
+			plot: this.#plot,
+			channels: c.channels,
+			options: c.options ?? {},
+			alpha: c.alpha,
+			type: c.type
+		})
+	})
+}

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

@@ -0,0 +1,36 @@
+/**
+ * Resolve a mark's interior (fill) and outline (stroke) from the `fill` and `color`
+ * channels through the shared categorical `colors` palette (Map<value, {fill, stroke}>).
+ *
+ * ggplot fallback:
+ *  - color-only → fill AND stroke from the color value's entry (backward compatible)
+ *  - fill-only  → fill AND stroke from the fill value's entry
+ *  - both       → interior from the fill value, outline from the color value
+ *  - neither    → the first palette entry (single-series)
+ *
+ * @param {Record<string, unknown>} row
+ * @param {{ fill?: string, color?: string }} channels
+ * @param {Map<unknown, { fill: string, stroke: string }>} colors
+ * @returns {{ fill: string, stroke: string }}
+ */
+export function resolveFillStroke(row: Record<string, unknown>, channels: {
+    fill?: string;
+    color?: string;
+}, colors: Map<unknown, {
+    fill: string;
+    stroke: string;
+}>): {
+    fill: string;
+    stroke: string;
+};
+/**
+ * Resolve a geom's mark opacity: an explicit fixed `alpha`, else the per-geom preset
+ * default, else fully opaque.
+ * @param {number|undefined} alpha
+ * @param {string} type - geom type key into preset.opacity
+ * @param {{ opacity?: Record<string, number> }} [preset]
+ * @returns {number}
+ */
+export function resolveAlpha(alpha: number | undefined, type: string, preset?: {
+    opacity?: Record<string, number>;
+}): number;

package/dist/geoms/lib/aesthetics.js

@@ -0,0 +1,45 @@
+// Shared aesthetic resolution for all geoms. Done ONCE here so every geom's build
+// function inherits the same ggplot-aligned fill/color and alpha rules.
+// See docs/backlog/2026-08-17-chart-aesthetics-unification.md §2, §3, §11.
+
+const GRAY = { fill: '#888', stroke: '#888' }
+
+/**
+ * Resolve a mark's interior (fill) and outline (stroke) from the `fill` and `color`
+ * channels through the shared categorical `colors` palette (Map<value, {fill, stroke}>).
+ *
+ * ggplot fallback:
+ *  - color-only → fill AND stroke from the color value's entry (backward compatible)
+ *  - fill-only  → fill AND stroke from the fill value's entry
+ *  - both       → interior from the fill value, outline from the color value
+ *  - neither    → the first palette entry (single-series)
+ *
+ * @param {Record<string, unknown>} row
+ * @param {{ fill?: string, color?: string }} channels
+ * @param {Map<unknown, { fill: string, stroke: string }>} colors
+ * @returns {{ fill: string, stroke: string }}
+ */
+export function resolveFillStroke(row, channels, colors) {
+	const { fill, color } = channels ?? {}
+	const first = colors?.values?.().next?.().value ?? GRAY
+	const fillEntry = fill ? (colors?.get(row?.[fill]) ?? first) : null
+	const colorEntry = color ? (colors?.get(row?.[color]) ?? first) : null
+	const base = fillEntry ?? colorEntry ?? first
+	return {
+		fill: (fillEntry ?? base).fill,
+		stroke: (colorEntry ?? base).stroke
+	}
+}
+
+/**
+ * Resolve a geom's mark opacity: an explicit fixed `alpha`, else the per-geom preset
+ * default, else fully opaque.
+ * @param {number|undefined} alpha
+ * @param {string} type - geom type key into preset.opacity
+ * @param {{ opacity?: Record<string, number> }} [preset]
+ * @returns {number}
+ */
+export function resolveAlpha(alpha, type, preset) {
+	if (typeof alpha === 'number') return alpha
+	return preset?.opacity?.[type] ?? 1
+}

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

@@ -8,6 +8,7 @@
  * @param {Map<unknown, {fill: string, stroke: string}>} colors
  * @param {'linear'|'smooth'|'step'} [curve]
  * @param {Map<unknown, string>} [patterns]
+ * @param {Function} [place] - orientation mapper (x, y) => {x, y}
  * @returns {{ d: string, fill: string, stroke: string, key: unknown, patternId: string|null }[]}
  */
 export function buildAreas(data: Object[], channels: {
@@ -18,7 +19,7 @@ export function buildAreas(data: Object[], channels: {
 }, xScale: Function, yScale: Function, colors: Map<unknown, {
     fill: string;
     stroke: string;
-}>, curve?: "linear" | "smooth" | "step", patterns?: Map<unknown, string>): {
+}>, curve?: "linear" | "smooth" | "step", patterns?: Map<unknown, string>, place?: Function): {
     d: string;
     fill: string;
     stroke: string;
@@ -45,7 +46,10 @@ export function buildStackedAreas(data: Object[], channels: {
 }, xScale: Function, yScale: Function, colors: Map<unknown, {
     fill: string;
     stroke: string;
-}>, curve?: "linear" | "smooth" | "step", patterns?: Map<unknown, string>): {
+}>, curve?: "linear" | "smooth" | "step", patterns?: Map<unknown, string>, place?: (x: any, y: any) => {
+    x: any;
+    y: any;
+}, normalize?: boolean): {
     d: string;
     fill: string;
     stroke: string;

package/dist/geoms/lib/areas.js

@@ -1,4 +1,4 @@
-import { area, stack, curveCatmullRom, curveStep } from 'd3-shape'
+import { area, stack, stackOffsetExpand, curveCatmullRom, curveStep } from 'd3-shape'
 import { toPatternId } from '../../lib/brewing/patterns.js'
 
 /**
@@ -11,20 +11,24 @@ import { toPatternId } from '../../lib/brewing/patterns.js'
  * @param {Map<unknown, {fill: string, stroke: string}>} colors
  * @param {'linear'|'smooth'|'step'} [curve]
  * @param {Map<unknown, string>} [patterns]
+ * @param {Function} [place] - orientation mapper (x, y) => {x, y}
  * @returns {{ d: string, fill: string, stroke: string, key: unknown, patternId: string|null }[]}
  */
-export function buildAreas(data, channels, xScale, yScale, colors, curve, patterns) {
+export function buildAreas(data, channels, xScale, yScale, colors, curve, patterns, place = (x, y) => ({ x, y })) {
 	const { x: xf, y: yf, color: cf, pattern: pf } = channels
 	const baseline = yScale.range()[0] // bottom of the chart (y pixel max)
 
 	const xPos = (d) =>
 		typeof xScale.bandwidth === 'function' ? xScale(d[xf]) + xScale.bandwidth() / 2 : xScale(d[xf])
 
+	// Each area edge (baseline + top) is placed so the area transposes under orientation.
+	const toEdge = (d) => ({ base: place(xPos(d), baseline), top: place(xPos(d), yScale(d[yf])) })
 	const makeGen = () => {
 		const gen = area()
-			.x(xPos)
-			.y0(baseline)
-			.y1((d) => yScale(d[yf]))
+			.x0((p) => p.base.x)
+			.y0((p) => p.base.y)
+			.x1((p) => p.top.x)
+			.y1((p) => p.top.y)
 		if (curve === 'smooth') gen.curve(curveCatmullRom)
 		else if (curve === 'step') gen.curve(curveStep)
 		return gen
@@ -47,7 +51,7 @@ export function buildAreas(data, channels, xScale, yScale, colors, curve, patter
 			patternKey !== null && patternKey !== undefined && patterns?.has(patternKey)
 				? toPatternId(String(patternKey))
 				: null
-		return [{ d: makeGen()(sortByX(data)), fill: entry.fill, stroke: 'none', key: null, patternId }]
+		return [{ d: makeGen()(sortByX(data).map(toEdge)), fill: entry.fill, stroke: 'none', key: null, patternId }]
 	}
 
 	// Group by color field
@@ -72,7 +76,7 @@ export function buildAreas(data, channels, xScale, yScale, colors, curve, patter
 			patternKey !== null && patternKey !== undefined && patterns?.has(patternKey)
 				? toPatternId(String(patternKey))
 				: null
-		return { d: makeGen()(sortByX(rows)), fill: entry.fill, stroke: 'none', key, patternId }
+		return { d: makeGen()(sortByX(rows).map(toEdge)), fill: entry.fill, stroke: 'none', key, patternId }
 	})
 }
 
@@ -88,7 +92,7 @@ export function buildAreas(data, channels, xScale, yScale, colors, curve, patter
  * @param {Map<unknown, string>} [patterns]
  * @returns {{ d: string, fill: string, stroke: string, key: unknown, patternId: string|null }[]}
  */
-export function buildStackedAreas(data, channels, xScale, yScale, colors, curve, patterns) {
+export function buildStackedAreas(data, channels, xScale, yScale, colors, curve, patterns, place = (x, y) => ({ x, y }), normalize = false) {
 	const { x: xf, y: yf, color: cf, pattern: pf } = channels
 	if (!cf) return buildAreas(data, channels, xScale, yScale, colors, curve, patterns)
 
@@ -115,17 +119,21 @@ export function buildStackedAreas(data, channels, xScale, yScale, colors, curve,
 			? xScale(d.data[xf]) + xScale.bandwidth() / 2
 			: xScale(d.data[xf])
 
+	const toEdge = (d) => ({ base: place(xPos(d), yScale(d[0])), top: place(xPos(d), yScale(d[1])) })
 	const makeGen = () => {
 		const gen = area()
-			.x(xPos)
-			.y0((d) => yScale(d[0]))
-			.y1((d) => yScale(d[1]))
+			.x0((p) => p.base.x)
+			.y0((p) => p.base.y)
+			.x1((p) => p.top.x)
+			.y1((p) => p.top.y)
 		if (curve === 'smooth') gen.curve(curveCatmullRom)
 		else if (curve === 'step') gen.curve(curveStep)
 		return gen
 	}
 
 	const stackGen = stack().keys(colorCategories)
+	// position='fill' → normalize each x column to [0,1] (100% stacked area).
+	if (normalize) stackGen.offset(stackOffsetExpand)
 	const layers = stackGen(wide)
 
 	const orderedPatternKeys = pf && pf !== cf ? [...(patterns?.keys() ?? [])] : null
@@ -144,7 +152,7 @@ export function buildStackedAreas(data, channels, xScale, yScale, colors, curve,
 				? toPatternId(String(patternKey))
 				: null
 		return {
-			d: makeGen()(layer) ?? '',
+			d: makeGen()(layer.map(toEdge)) ?? '',
 			fill: entry.fill,
 			stroke: 'none',
 			key: colorKey,

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

@@ -1,3 +1,18 @@
-export function buildGroupedBars(data: any, channels: any, xScale: any, yScale: any, colors: any, innerHeight: any, patterns: any): any;
-export function buildStackedBars(data: any, channels: any, xScale: any, yScale: any, colors: any, innerHeight: any, patterns: any): any;
-export function buildHorizontalBars(data: any, channels: any, xScale: any, yScale: any, colors: any, _innerHeight: any): any;
+/**
+ * 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.
+ *
+ * Category (x) positioning has two modes:
+ * - band (default): a scaleBand slots each category; sub-bands split grouped series.
+ * - continuous (`continuousCategory`): a LINEAR position scale (e.g. a bar-chart race's tweened
+ *   `_rank`). Each bar centres on `xScale(pos)` with a fixed thickness from the scale step, so a
+ *   fractional position tweens smoothly (a band scale can only jump between slots). No sub-banding.
+ */
+export function buildBars(data: any, channels: any, xScale: any, yScale: any, colors: any, innerHeight: any, patterns: any, place?: (x: any, y: any) => {
+    x: any;
+    y: any;
+}, continuousCategory?: boolean, dodge?: boolean): any;
+export function buildStackedBars(data: any, channels: any, xScale: any, yScale: any, colors: any, innerHeight: any, patterns: any, place?: (x: any, y: any) => {
+    x: any;
+    y: any;
+}, normalize?: boolean): any;