@rokkit/chart 1.3.15 → 1.4.1

package/dist/geoms/Radar.svelte

@@ -0,0 +1,352 @@
+<script lang="ts">
+	import { getContext, onMount, onDestroy } from 'svelte'
+	import type { PlotState } from '../PlotState.svelte.js'
+	import { GeomState } from './lib/GeomState.svelte.js'
+	import { buildRadarMarks, resolveRadarRadius } from './lib/marks/radar.js'
+	import { buildRadarLayout } from '../lib/brewing/polar.js'
+	import { buildSelectDetail } from '../lib/select.js'
+
+	type Row = Record<string, unknown>
+
+	type AxisSpec = {
+		key: string
+		label?: string
+		unit?: string
+		domain?: [number, number]
+		ticks?: number
+		tickLabels?: string[]
+		format?: (value: number) => unknown
+		weight?: number
+	}
+
+	// The shape `buildRadarMarks` documents in its `@returns`. Other geoms leave `geom.marks`
+	// untyped because they only ever spread it in a template; this one also reads it in script
+	// (see `strokeBySeries`), which needs a real element type.
+	type RadarMark = {
+		d: string
+		fill: string
+		stroke: string
+		alpha: number
+		key: string
+		patternId: string | null
+	}
+
+	type Options = {
+		grid?: boolean
+		rings?: number
+		sharedDomain?: boolean
+		radiusScale?: 'linear' | 'sqrt' | 'auto'
+		/** Alias for the `axes` prop, for callers that can only reach `options` — notably
+		 *  Plot's spec-driven path, whose passthrough is a fixed prop list. */
+		axes?: (string | AxisSpec)[]
+	}
+
+	type Props = {
+		axes?: (string | AxisSpec)[]
+		axis?: string
+		value?: string
+		series?: string
+		/** Generic-pipeline aliases for `axis`/`value`/`series`. Radar's own names say what
+		 *  the channels mean here (an axis is not an x position), but Plot's spec-driven
+		 *  path passes only the generic set, so these let a spec drive radar too. The
+		 *  specific names win when both are given. */
+		x?: string
+		y?: string
+		color?: string
+		pattern?: string
+		/** Fixed area opacity 0–1; defaults to the per-geom preset (radar = 0.25). */
+		alpha?: number
+		stat?: string
+		options?: Options
+		onselect?: (data: Row) => void
+	}
+
+	let {
+		axes: axesProp,
+		axis: axisProp,
+		value: valueProp,
+		series: seriesProp,
+		x = undefined,
+		y = undefined,
+		color = undefined,
+		pattern,
+		alpha,
+		stat = 'identity',
+		options = {},
+		onselect = undefined
+	}: Props = $props()
+
+	// Radar's own channel names take precedence; the generic ones are the fallback so a
+	// spec-driven <Plot> (which passes only x/y/color) can drive this geom too.
+	const axis = $derived(axisProp ?? x)
+	const value = $derived(valueProp ?? y)
+	const series = $derived(seriesProp ?? color)
+	const axes = $derived(axesProp ?? options.axes)
+
+	const LABEL_GAP = 12
+	const ZERO_MARKER_HALF_SPAN_DEG = 6
+	const VERTEX_RADIUS = 3
+
+	const plotState = getContext<PlotState>('plot-state')
+
+	const geom = new GeomState(plotState, () => ({
+		type: 'radar',
+		channels: { x: axis, y: value, color: series, pattern },
+		stat,
+		options: {
+			axes,
+			sharedDomain: options.sharedDomain,
+			rings: options.rings,
+			radiusScale: options.radiusScale
+		},
+		alpha,
+		build: buildRadarMarks
+	}))
+	onMount(geom.register)
+	onDestroy(geom.destroy)
+	$effect(geom.sync)
+
+	const marks: RadarMark[] = $derived(geom.marks)
+	const w = $derived(plotState.innerWidth)
+	const h = $derived(plotState.innerHeight)
+
+	// One shared definition of the radius AND of which form we're drawing — the adapter
+	// builds its polygons from the very same call, so the grid can no longer disagree
+	// with them. `micro` is derived from the space actually available rather than from
+	// "am I inside a Spark": that keeps the geom free of any container-specific branch
+	// (the spec's requirement) and correctly also covers a Plot too small for chrome.
+	//
+	// Deliberately NOT `plotState.interactive`, which the plan proposed: that is
+	// `Boolean(onselect) || selectable`, so an ordinary static <Plot> reads false too and
+	// would silently lose its rings, spokes and axis labels.
+	const geometry = $derived(resolveRadarRadius(w, h))
+	const R = $derived(geometry.R)
+	const micro = $derived(geometry.micro)
+
+	// Radar takes its own channel props — like `GeomState.marks`, this never falls back to the
+	// container's `x`/`y`. Without both `axis` and `value` there is nothing coherent to lay a
+	// polar grid out against, so no layout is computed at all (mirrors `buildRadarMarks`'s own
+	// `!channels?.x || !channels?.y` guard for the polygons).
+	const layout = $derived(
+		axis !== undefined && value !== undefined
+			? buildRadarLayout(
+					geom.data,
+					{ x: axis, y: value, color: series },
+					{
+						axes,
+						sharedDomain: options.sharedDomain,
+						rings: options.rings,
+						radiusScale: options.radiusScale,
+						R
+					}
+				)
+			: null
+	)
+
+	function toXY(angleDeg: number, radius: number) {
+		const rad = (angleDeg * Math.PI) / 180
+		return { x: radius * Math.cos(rad), y: radius * Math.sin(rad) }
+	}
+
+	// cos(angle) is within float error of 0 only at true vertical (±90°, top/bottom); every
+	// other axis angle sits comfortably to one side, so a tight epsilon can't misclassify a
+	// real left/right axis as 'middle'.
+	function anchorFor(angleDeg: number): 'start' | 'middle' | 'end' {
+		const cosA = Math.cos((angleDeg * Math.PI) / 180)
+		if (Math.abs(cosA) < 1e-6) return 'middle'
+		return cosA > 0 ? 'start' : 'end'
+	}
+
+	// `buildRadarMarks` keys every mark `${seriesKey}::fill` / `${seriesKey}::stroke` so paint
+	// order (all fills, then all strokes) is inspectable from the key alone; this recovers the
+	// series value from that key for the `data-plot-series` hook.
+	function seriesOf(key: string) {
+		return key.slice(0, key.lastIndexOf('::'))
+	}
+
+	// Series stroke colour, recovered from the adapter's stroke marks (the ones with no fill)
+	// rather than re-resolving the palette here. A vertex dot has to match its own polygon's
+	// outline, and the only way to guarantee that is to read the same value the outline used.
+	const strokeBySeries = $derived(
+		new Map(
+			marks.filter((mark) => mark.fill === 'none').map((mark) => [seriesOf(mark.key), mark.stroke])
+		)
+	)
+
+	// A vertex is reachable when either the geom was handed its own callback or the plot is
+	// running interactively. Deliberately NOT the `keyboardNav` action: that walks a 1-D
+	// category list in DOM order, and radar's vertices are a 2-D series × axis grid, so
+	// left/right traversal has no meaning here. Tab reach plus Enter/Space, like Point/Arc.
+	const reachable = $derived(Boolean(onselect) || plotState.interactive)
+
+	function selectVertex(row: Row, seriesKey: unknown, event: MouseEvent | KeyboardEvent) {
+		onselect?.(row)
+		if (plotState.interactive)
+			plotState.handleSelect(
+				buildSelectDetail({
+					datum: row,
+					// `row` is one of the container's original row objects — averaging happens
+					// inside polar.js precisely so this lookup resolves instead of returning -1.
+					index: plotState.data.indexOf(row),
+					channels: { x: axis, y: value },
+					geom: 'radar',
+					series: seriesKey,
+					event
+				})
+			)
+	}
+
+	// A short dashed arc at the radius where value 0 sits on this one spoke — see
+	// `zeroRingFor`'s doc comment for why this can't just be a shared ring.
+	function zeroMarkerPath(angleDeg: number, radius: number) {
+		const p1 = toXY(angleDeg - ZERO_MARKER_HALF_SPAN_DEG, radius)
+		const p2 = toXY(angleDeg + ZERO_MARKER_HALF_SPAN_DEG, radius)
+		return `M${p1.x},${p1.y} A${radius},${radius} 0 0 1 ${p2.x},${p2.y}`
+	}
+</script>
+
+<g data-plot-geom="radar" transform="translate({w / 2}, {h / 2})">
+	{#if layout && options.grid && !micro}
+		{#each layout.rings as ring, i (i)}
+			<circle data-plot-element="radar-grid-ring" cx="0" cy="0" r={ring.radius} />
+		{/each}
+		{#each layout.axes as ax, i (ax.key)}
+			{@const { x: sx, y: sy } = toXY(layout.angles[i], layout.radius)}
+			<line
+				data-plot-element="radar-grid-spoke"
+				data-plot-axis={ax.key}
+				x1="0"
+				y1="0"
+				x2={sx}
+				y2={sy}
+			/>
+		{/each}
+		{#each layout.zeroRings as zr, i (i)}
+			{#if zr !== null}
+				<path data-plot-element="radar-zero-ring" d={zeroMarkerPath(layout.angles[i], zr)} />
+			{/if}
+		{/each}
+		{#if layout.axes.length > 0}
+			{#each layout.rings as ring, ringIndex (ringIndex)}
+				{@const { x: lx, y: ly } = toXY(layout.angles[0], ring.radius)}
+				<text class="radar-ring-label" x={lx} y={ly} dy="-2">{ring.labels[0]}</text>
+			{/each}
+		{/if}
+	{/if}
+
+	{#each marks as mark (mark.key)}
+		{#if mark.fill !== 'none'}
+			<path
+				d={mark.d}
+				fill={mark.fill}
+				fill-opacity={mark.alpha}
+				stroke="none"
+				data-plot-element="radar-area"
+				data-plot-series={seriesOf(mark.key)}
+			/>
+			{#if mark.patternId}
+				<path
+					d={mark.d}
+					fill="url(#{mark.patternId})"
+					stroke="none"
+					pointer-events="none"
+					data-plot-element="radar-area"
+					data-plot-series={seriesOf(mark.key)}
+				/>
+			{/if}
+		{:else}
+			<path
+				d={mark.d}
+				fill="none"
+				stroke={mark.stroke}
+				stroke-width="2"
+				data-plot-element="radar-outline"
+				data-plot-series={seriesOf(mark.key)}
+			/>
+		{/if}
+	{/each}
+
+	{#if layout && !micro}
+		{#each [...layout.series] as [seriesKey, seriesVertices] (seriesKey)}
+			{#each seriesVertices as vertex, i (i)}
+				<!-- A null vertex is a genuine gap in the data — no reading for this (series, axis)
+				     cell — so it renders as nothing at all. Plotting it at the centre would invent
+				     a zero the source never contained. -->
+				{#if vertex}
+					{@const { x: vx, y: vy } = toXY(vertex.angle, vertex.radius)}
+					<!-- svelte-ignore a11y_no_noninteractive_tabindex -->
+					<circle
+						data-plot-element="radar-vertex"
+						data-plot-series={String(seriesKey)}
+						data-plot-axis={vertex.axisKey}
+						cx={vx}
+						cy={vy}
+						r={VERTEX_RADIUS}
+						fill={strokeBySeries.get(String(seriesKey))}
+						role={reachable ? 'button' : 'graphics-symbol'}
+						tabindex={reachable ? 0 : undefined}
+						style:cursor={reachable ? 'pointer' : undefined}
+						aria-label="{layout.axes[i].displayLabel}, {vertex.value}"
+						onmouseenter={() => plotState.setHovered(vertex.row)}
+						onmouseleave={() => plotState.clearHovered()}
+						onclick={reachable ? (e) => selectVertex(vertex.row, seriesKey, e) : undefined}
+						onkeydown={reachable
+							? (e) =>
+									(e.key === 'Enter' || e.key === ' ') && selectVertex(vertex.row, seriesKey, e)
+							: undefined}
+					/>
+				{/if}
+			{/each}
+		{/each}
+	{/if}
+
+	{#if layout && !micro}
+		{#each layout.axes as ax, i (ax.key)}
+			{@const { x: lx, y: ly } = toXY(layout.angles[i], layout.radius + LABEL_GAP)}
+			<text
+				data-plot-element="radar-axis-label"
+				data-plot-axis={ax.key}
+				x={lx}
+				y={ly}
+				text-anchor={anchorFor(layout.angles[i])}
+				dominant-baseline="central">{ax.displayLabel}</text
+			>
+		{/each}
+	{/if}
+</g>
+
+<style>
+	[data-plot-element='radar-grid-ring'] {
+		fill: none;
+		stroke: var(--chart-grid-color, currentColor);
+		stroke-width: var(--chart-grid-width, 1);
+		stroke-dasharray: var(--chart-grid-dash, 2 4);
+		opacity: var(--chart-grid-opacity, 0.15);
+		pointer-events: none;
+	}
+	[data-plot-element='radar-grid-spoke'] {
+		stroke: var(--chart-grid-color, currentColor);
+		stroke-width: var(--chart-grid-width, 1);
+		opacity: var(--chart-grid-opacity, 0.15);
+		pointer-events: none;
+	}
+	[data-plot-element='radar-zero-ring'] {
+		fill: none;
+		stroke: var(--chart-grid-color, currentColor);
+		stroke-width: var(--chart-grid-width, 1);
+		stroke-dasharray: 3 3;
+		opacity: 0.5;
+		pointer-events: none;
+	}
+	[data-plot-element='radar-axis-label'] {
+		font-size: 11px;
+		fill: currentColor;
+		pointer-events: none;
+	}
+	.radar-ring-label {
+		font-size: 9px;
+		fill: currentColor;
+		opacity: 0.6;
+		pointer-events: none;
+	}
+</style>

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

@@ -0,0 +1,42 @@
+type Row = Record<string, unknown>;
+type AxisSpec = {
+    key: string;
+    label?: string;
+    unit?: string;
+    domain?: [number, number];
+    ticks?: number;
+    tickLabels?: string[];
+    format?: (value: number) => unknown;
+    weight?: number;
+};
+type Options = {
+    grid?: boolean;
+    rings?: number;
+    sharedDomain?: boolean;
+    radiusScale?: 'linear' | 'sqrt' | 'auto';
+    /** Alias for the `axes` prop, for callers that can only reach `options` — notably
+     *  Plot's spec-driven path, whose passthrough is a fixed prop list. */
+    axes?: (string | AxisSpec)[];
+};
+type Props = {
+    axes?: (string | AxisSpec)[];
+    axis?: string;
+    value?: string;
+    series?: string;
+    /** Generic-pipeline aliases for `axis`/`value`/`series`. Radar's own names say what
+     *  the channels mean here (an axis is not an x position), but Plot's spec-driven
+     *  path passes only the generic set, so these let a spec drive radar too. The
+     *  specific names win when both are given. */
+    x?: string;
+    y?: string;
+    color?: string;
+    pattern?: string;
+    /** Fixed area opacity 0–1; defaults to the per-geom preset (radar = 0.25). */
+    alpha?: number;
+    stat?: string;
+    options?: Options;
+    onselect?: (data: Row) => void;
+};
+declare const Radar: import("svelte").Component<Props, {}, "">;
+type Radar = ReturnType<typeof Radar>;
+export default Radar;

package/dist/geoms/Trend.svelte

@@ -20,30 +20,53 @@
 		return t === 'mean' ? 'avg' : t
 	}
 
+	/** Everything a path builder needs, resolved once per derivation. */
+	type Ctx = {
+		rows: Record<string, unknown>[]
+		// Scales come from PlotState (untyped JS), so they stay loose here.
+		xs: (v: unknown) => number
+		ys: (v: number) => number
+		x: string
+		y: string
+		innerWidth: number
+	}
+
+	const isDrawable = (s: PlotState | undefined) =>
+		Boolean(s?.xScale && s?.yScale && s?.data?.length)
+
+	/** Null until the plot has data, both scales, both channels and at least one method. */
+	const ctx = $derived.by((): Ctx | null => {
+		if (!isDrawable(state) || !x || !y || !methods.length) return null
+		return { rows: state.data, xs: state.xScale, ys: state.yScale, x, y, innerWidth: state.innerWidth }
+	})
+
+	/** A flat rule spanning the plot — what every `constant` trend (avg, median, min…) draws. */
+	const constantPath = (c: Ctx, value: number) => {
+		const yy = c.ys(value)
+		return `M0,${yy} L${c.innerWidth},${yy}`
+	}
+
+	/** A polyline through the trend's per-row values, dropping points that don't place. */
+	function seriesPath(c: Ctx, values: number[]): string | null {
+		const pts = values
+			.map((v, i) => ({ vx: scalePos(c.xs, c.rows[i][c.x]), vy: c.ys(v) }))
+			.filter((p) => Number.isFinite(p.vx) && Number.isFinite(p.vy))
+		return d3line<{ vx: number; vy: number }>()
+			.x((p) => p.vx)
+			.y((p) => p.vy)(pts)
+	}
+
+	/** One method → one path, or null when the method doesn't resolve for this data. */
+	function trendPath(c: Ctx, m: Method, i: number) {
+		const res = computeTrend(c.rows, { x: c.x, y: c.y }, m)
+		if (!res) return null
+		const d = res.kind === 'constant' ? constantPath(c, res.value) : seriesPath(c, res.values)
+		return d ? { d, type: typeOf(m), i } : null
+	}
+
 	const paths = $derived.by(() => {
-		const rows = state?.data ?? []
-		const xs = state?.xScale
-		const ys = state?.yScale
-		if (!rows.length || !xs || !ys || !x || !y || !methods.length) return []
-		const out: { d: string; type: string; i: number }[] = []
-		methods.forEach((m, idx) => {
-			const res = computeTrend(rows, { x, y }, m)
-			if (!res) return
-			if (res.kind === 'constant') {
-				const yy = ys(res.value)
-				out.push({ d: `M0,${yy} L${state.innerWidth},${yy}`, type: typeOf(m), i: idx })
-			} else {
-				const pts = res.values
-					.map((v, i) => ({ vx: scalePos(xs, rows[i][x]), vy: ys(v) }))
-					.filter((p) => Number.isFinite(p.vx) && Number.isFinite(p.vy))
-				const gen = d3line<{ vx: number; vy: number }>()
-					.x((p) => p.vx)
-					.y((p) => p.vy)
-				const d = gen(pts)
-				if (d) out.push({ d, type: typeOf(m), i: idx })
-			}
-		})
-		return out
+		if (!ctx) return []
+		return methods.map((m, i) => trendPath(ctx, m, i)).filter((p) => p !== null)
 	})
 </script>
 

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

@@ -34,3 +34,17 @@ export function resolveFillStroke(row: Record<string, unknown>, channels: {
 export function resolveAlpha(alpha: number | undefined, type: string, preset?: {
     opacity?: Record<string, number>;
 }): number;
+/**
+ * Resolve a mark's text label from the geom's `label` prop.
+ *
+ *  - falsy      → no label
+ *  - `true`     → the row's value in `defaultField` (usually the geom's y channel)
+ *  - function   → its return value, stringified
+ *  - string     → the row's value in that field
+ *
+ * @param {boolean|string|((row: Record<string, unknown>) => unknown)|undefined} label
+ * @param {Record<string, unknown>} row
+ * @param {string} [defaultField] - field used when `label` is `true`
+ * @returns {string|null}
+ */
+export function resolveLabel(label: boolean | string | ((row: Record<string, unknown>) => unknown) | undefined, row: Record<string, unknown>, defaultField?: string): string | null;

package/dist/geoms/lib/aesthetics.js

@@ -43,3 +43,24 @@ export function resolveAlpha(alpha, type, preset) {
 	if (typeof alpha === 'number') return alpha
 	return preset?.opacity?.[type] ?? 1
 }
+
+/**
+ * Resolve a mark's text label from the geom's `label` prop.
+ *
+ *  - falsy      → no label
+ *  - `true`     → the row's value in `defaultField` (usually the geom's y channel)
+ *  - function   → its return value, stringified
+ *  - string     → the row's value in that field
+ *
+ * @param {boolean|string|((row: Record<string, unknown>) => unknown)|undefined} label
+ * @param {Record<string, unknown>} row
+ * @param {string} [defaultField] - field used when `label` is `true`
+ * @returns {string|null}
+ */
+export function resolveLabel(label, row, defaultField) {
+	if (!label) return null
+	if (label === true) return String((defaultField ? row[defaultField] : undefined) ?? '')
+	if (typeof label === 'function') return String(label(row) ?? '')
+	if (typeof label === 'string') return String(row[label] ?? '')
+	return null
+}

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

@@ -9,7 +9,12 @@
  * @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 }[]}
+ * @param {number} [baselineValue] - data-space value to anchor/split the fill at. When set,
+ *   each segment is emitted twice (sign: 'above' | 'below'), both anchored at this value's
+ *   pixel position instead of the chart bottom, so themes can colour the two independently.
+ *   Fed straight into `yScale()`, so a value outside the scale's domain extrapolates (e.g.
+ *   100 against a domain of [-5, 5] gives pixel -475) rather than clamping to the chart edge.
+ * @returns {{ d: string, fill: string, stroke: string, key: unknown, groupKey: unknown, patternId: string|null, sign?: 'above'|'below' }[]}
  */
 export function buildAreas(data: Object[], channels: {
     x: string;
@@ -19,12 +24,14 @@ 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>, place?: Function): {
+}>, curve?: "linear" | "smooth" | "step", patterns?: Map<unknown, string>, place?: Function, baselineValue?: number): {
     d: string;
     fill: string;
     stroke: string;
     key: unknown;
+    groupKey: unknown;
     patternId: string | null;
+    sign?: "above" | "below";
 }[];
 /**
  * Builds stacked area paths using d3 stack layout.

package/dist/geoms/lib/areas.js

@@ -13,23 +13,41 @@ import { literalColor, markEntry } from '../../lib/brewing/colors.js'
  * @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 }[]}
+ * @param {number} [baselineValue] - data-space value to anchor/split the fill at. When set,
+ *   each segment is emitted twice (sign: 'above' | 'below'), both anchored at this value's
+ *   pixel position instead of the chart bottom, so themes can colour the two independently.
+ *   Fed straight into `yScale()`, so a value outside the scale's domain extrapolates (e.g.
+ *   100 against a domain of [-5, 5] gives pixel -475) rather than clamping to the chart edge.
+ * @returns {{ d: string, fill: string, stroke: string, key: unknown, groupKey: unknown, patternId: string|null, sign?: 'above'|'below' }[]}
  */
-export function buildAreas(data, channels, xScale, yScale, colors, curve, patterns, place = (x, y) => ({ x, y })) {
+export function buildAreas(data, channels, xScale, yScale, colors, curve, patterns, place = (x, y) => ({ x, y }), baselineValue = undefined) {
 	const { x: xf, y: yf, pattern: pf } = channels
 	// A literal color (var()/oklch()/hex/currentColor) isn't a data field — it's the exact
 	// fill the caller wants for THIS area. Don't group on it, and don't fall back to the
 	// shared color scale (one value across all geoms); use it directly.
 	const lit = literalColor(channels.color)
 	const cf = lit ? undefined : channels.color
-	const baseline = yScale.range()[0] // bottom of the chart (y pixel max)
+	// Number.isFinite (not a loose !=null check) also rejects NaN/Infinity — a caller-computed
+	// stat (e.g. a mean over an empty group) can easily produce NaN, which would otherwise sail
+	// through and emit literal "NaN" path commands.
+	const hasBaseline = Number.isFinite(baselineValue)
+	const baseline = hasBaseline ? yScale(baselineValue) : yScale.range()[0] // bottom of the chart (y pixel max) unless an explicit baseline value is given
 
 	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.
-	// `v` carries the raw y-value so the generator can break the area at a gap (null).
-	const toEdge = (d) => ({ base: place(xPos(d), baseline), top: place(xPos(d), yScale(d[yf])), v: d[yf] })
+	// `sign` clamps the top edge to one side of the baseline — 'above' never dips below it,
+	// 'below' never rises above it — the same technique proven in Sparkline (#148). This MUST
+	// happen here, in value space, before `place()` runs: `place` is how horizontal/flipped
+	// orientation is implemented (it can swap x/y), so clamping the post-place coordinate would
+	// clamp whatever axis ends up there — including the category axis on a flipped chart. `v`
+	// carries the raw y-value so the generator can break the area at a gap (null).
+	const toEdge = (d, sign) => {
+		const rawTop = yScale(d[yf])
+		const clampedTop = sign === 'above' ? Math.min(rawTop, baseline) : sign === 'below' ? Math.max(rawTop, baseline) : rawTop
+		return { base: place(xPos(d), baseline), top: place(xPos(d), clampedTop), v: d[yf] }
+	}
 	const makeGen = () => {
 		const gen = area()
 			// A null y-value is a GAP (a missing period): break the area there instead of
@@ -43,6 +61,29 @@ export function buildAreas(data, channels, xScale, yScale, colors, curve, patter
 		else if (curve === 'step') gen.curve(curveStep)
 		return gen
 	}
+	// One unsigned segment normally; with a baseline, an above and a below copy so themes can
+	// colour positive vs negative fill independently. Mirrors the approach proven in Sparkline
+	// (#148). Also owns the "no baseline" `d` computation so both call sites just hand over rows.
+	const splitBySign = (segBase, rows, grouped) => {
+		if (!hasBaseline) return [{ ...segBase, d: makeGen()(rows.map((d) => toEdge(d))) }]
+		return ['above', 'below'].map((sign) => ({
+			...segBase,
+			d: makeGen()(rows.map((d) => toEdge(d, sign))),
+			sign,
+			// Only the genuinely ungrouped case (no color/fill channel at all) may use a bare
+			// sign — there's exactly one segment set in that case, so 'above'/'below' are
+			// already unique. A grouped segment must ALWAYS get a discriminated key, even when
+			// its group's value happens to be null/undefined: that's a real, distinct group,
+			// not "no grouping" — collapsing the two onto the same bare key is exactly the bug
+			// this branches around. `typeof` alone already keeps null (typeof 'object') and
+			// undefined (typeof 'undefined') apart, no extra special-casing needed for them.
+			// This assumes group values are primitives (string/number/boolean/null/undefined),
+			// true for every color/fill channel today; two distinct objects (or two Dates with
+			// equal timestamps) stringifying to the same "type:value" could still collide —
+			// an accepted, documented bound, not an oversight.
+			key: grouped ? `${typeof segBase.key}:${segBase.key}::${sign}` : sign
+		}))
+	}
 
 	// For band (categorical) x scales, sort by domain index to preserve intended ordering.
 	// For continuous scales, sort numerically so the path draws left-to-right.
@@ -62,7 +103,11 @@ 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).map(toEdge)), fill: entry.fill, stroke: 'none', key: null, patternId }]
+		// `groupKey` is the untouched, unsigned group discriminator (here always null): callers
+		// that need to look a segment back up in a colors/patterns Map (keyed by the raw group
+		// value, not by our render key) should use this instead of `key`, since `key` gets a
+		// sign suffix once a baseline is in effect.
+		return splitBySign({ fill: entry.fill, stroke: 'none', key: null, groupKey: null, patternId }, sortByX(data), false)
 	}
 
 	// Group by color field
@@ -75,7 +120,7 @@ export function buildAreas(data, channels, xScale, yScale, colors, curve, patter
 	// For different-field patterns, assign positionally so each area gets a distinct pattern
 	const orderedPatternKeys = pf && pf !== cf ? [...(patterns?.keys() ?? [])] : null
 
-	return [...groups.entries()].map(([key, rows], i) => {
+	return [...groups.entries()].flatMap(([key, rows], i) => {
 		const entry = colors?.get(key) ?? { fill: '#888', stroke: '#888' }
 		// Same field or no pf: look up by colorKey. Different field: assign positionally.
 		const patternKey = !pf
@@ -87,7 +132,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).map(toEdge)), fill: entry.fill, stroke: 'none', key, patternId }
+		return splitBySign({ fill: entry.fill, stroke: 'none', key, groupKey: key, patternId }, sortByX(rows), true)
 	})
 }
 

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

@@ -4,6 +4,9 @@
  * are set — so an old `color`-only area stays border-less (backward compatible); the
  * border uses the interior group's darker stroke shade. Per-field border coloring
  * (fill ≠ color, two legends) is the deferred dual-scale follow-up.
+ * `options.baseline`, when set, is passed straight to `buildAreas` (identity-position charts
+ * only — stacked/100% areas ignore it) and splits each segment into signed above/below copies
+ * (#148).
  * @param {{ data: any[], plot: any, channels: any, options?: any, alpha?: number, type?: string }} ctx
  */
 export function buildAreaMarks({ data, plot, channels, options, alpha, type }: {