@rokkit/chart 1.7.0 → 1.8.1

package/dist/SparkState.svelte.d.ts

@@ -111,6 +111,8 @@ export class SparkState {
             ribbon: number;
             waterfall: number;
             rule: number;
+            hull: number;
+            contour: number;
             radar: number;
         };
         patterns: string[];
@@ -133,6 +135,6 @@ export class SparkState {
     registerGeom(config: any): string;
     updateGeom(id: any, config: any): void;
     unregisterGeom(id: any): void;
-    geomData(id: any): any[];
+    geomData(id: any): Object[];
     #private;
 }

package/dist/SparkState.svelte.js

@@ -1,12 +1,9 @@
-import { untrack } from 'svelte'
 import { buildUnifiedXScale, buildUnifiedYScale } from './lib/plot/scales.js'
 import { defaultPreset } from './lib/preset.js'
-import { applyGeomStat } from './lib/plot/stat.js'
+import { GeomRegistry } from './state/GeomRegistry.svelte.js'
 import { distinct, assignColors } from './lib/brewing/colors.js'
 import { PATTERNS } from './patterns/patterns.js'
 
-let nextGeomId = 0
-
 /**
  * The full set of members a geom reads off its `'plot-state'` context — derived by
  * scanning every geom for `plotState.*` / `plot.*` / `state.*` reads (`geoms/*.svelte`,
@@ -117,7 +114,6 @@ export class SparkState {
 	#max = $state(undefined)
 	#baseline = $state(undefined)
 	#pattern = $state(undefined)
-	#geoms = $state([])
 
 	// Mirrors Sparkline's current yMin/yMax logic: an explicit min/max wins; otherwise
 	// the domain is the raw data extent, widened to include the baseline when one is
@@ -167,7 +163,12 @@ export class SparkState {
 		return assignColors(values, 'light', defaultPreset)
 	})
 
+	#registry
+
 	constructor(config = {}) {
+		// The registry reads rows and container channels live, through this state's own
+		// `data` / `channels` getters.
+		this.#registry = new GeomRegistry(this, 'spark-geom')
 		this.update(config)
 	}
 
@@ -284,48 +285,17 @@ export class SparkState {
 	clearHovered() {}
 	handleSelect() {}
 
-	// Mirrors PlotState.registerGeom at smaller scope: GeomState.register() (called
-	// from a geom's onMount) calls this once per mounted geom and keeps the returned id.
+	// The same registry PlotState composes — one lifecycle, so a fix to it lands in both.
 	registerGeom(config) {
-		const id = `spark-geom-${nextGeomId++}`
-		this.#geoms = [...this.#geoms, { id, ...config }]
-		return id
+		return this.#registry.register(config)
 	}
-
-	// untrack the read of #geoms, same as PlotState: GeomState.sync() calls this from
-	// a geom's `$effect`, which would otherwise track #geoms as a dependency and retrigger
-	// itself on every update (effect_update_depth_exceeded).
 	updateGeom(id, config) {
-		this.#geoms = untrack(() => this.#geoms).map((g) => (g.id === id ? { ...g, ...config } : g))
+		this.#registry.update(id, config)
 	}
-
-	// No untrack needed here (unlike updateGeom above): this only ever runs from a geom's
-	// onDestroy, which Svelte always executes outside any reactive tracking scope — there's
-	// no enclosing effect for a #geoms read to register against, so no self-retrigger risk
-	// exists. Mirrors PlotState.unregisterGeom, which is untrack-free for the same reason.
 	unregisterGeom(id) {
-		this.#geoms = this.#geoms.filter((g) => g.id !== id)
+		this.#registry.unregister(id)
 	}
-
-	// Identity stat returns `this.#data` itself, not a copy — geoms look up rows via
-	// `plotState.data.indexOf(row)` (see e.g. Line.svelte's selectPoint), which only
-	// works if geomData's rows are the exact same object instances as `data`.
 	geomData(id) {
-		const geom = this.#geoms.find((g) => g.id === id)
-		if (!geom) return []
-		const stat = geom.stat ?? 'identity'
-		if (stat === 'identity') return this.#data
-		// Strip explicit `undefined` values before spreading: geom components always pass
-		// every channel key (e.g. Line.svelte's `channels: { x, y, color, fill, symbol }`),
-		// so a geom that omits x/y to inherit them from the container sends
-		// `{ x: undefined, y: undefined }`, not `{}`. Left unstripped, that `undefined`
-		// becomes an own property that overrides the container's value in the spread below,
-		// silently clobbering an inherited channel (applyGeomStat's primary-key lookup then
-		// finds nothing and falls back to identity with no warning).
-		const geomChannels = Object.fromEntries(
-			Object.entries(geom.channels ?? {}).filter(([, v]) => v !== undefined)
-		)
-		const mergedChannels = { ...this.#channels, ...geomChannels }
-		return applyGeomStat(this.#data, { stat, channels: mergedChannels })
+		return this.#registry.data(id)
 	}
 }

package/dist/geoms/Arc.svelte

@@ -55,7 +55,7 @@
 {#if arcs.length > 0}
 	<g data-plot-geom="arc" transform="translate({w / 2}, {h / 2})">
 		<!-- svelte-ignore a11y_no_noninteractive_tabindex -->
-		{#each arcs as arc (arc.key)}
+		{#each arcs as arc (arc.id)}
 			<path
 				d={arc.d}
 				fill={arc.fill}

package/dist/geoms/Bar.svelte

@@ -91,26 +91,22 @@
 	const effectiveOrientation = $derived(options.orientation ?? plotState.orientation)
 	const seriesField = $derived(fill ?? color)
 
-	let dimmedByKey = $state<Record<string, boolean>>({})
-
-	$effect(() => {
-		if (!cf) {
-			dimmedByKey = {}
-			return
-		}
-		// cf.version is a $state counter that increments on every filter mutation.
-		// Reading it here establishes a reactive dependency so the effect re-runs
-		// whenever any filter changes — including changes from sibling FilterBars.
+	/** Bars the crossfilter dims, by key. A derivation, so it needs no effect writing state. */
+	const dimmedByKey = $derived.by((): Record<string, boolean> => {
+		if (!cf) return {}
+		// cf.version is a $state counter that increments on every filter mutation. Reading it
+		// makes this re-derive whenever any filter changes — including a sibling FilterBar's.
 		void cf.version
-		const next: Record<string, boolean> = {}
+		const dimmed: Record<string, boolean> = {}
 		for (const bar of bars) {
-			const dimmedByX = x ? cf.isDimmed(x, bar.data[x]) : false
-			const dimmedByY = y ? cf.isDimmed(y, bar.data[y]) : false
-			next[bar.key] = dimmedByX || dimmedByY
+			dimmed[bar.key] = (x ? cf.isDimmed(x, bar.data[x]) : false) || (y ? cf.isDimmed(y, bar.data[y]) : false)
 		}
-		dimmedByKey = next
+		return dimmed
 	})
 
+	/** Whether a bar takes clicks and keys at all. */
+	const activatable = $derived(filterable || Boolean(onselect) || keyboard || plotState.interactive)
+
 	function handleBarClick(barX: unknown) {
 		if (!filterable || !x || !cf) return
 		cf.toggleCategorical(x, barX)
@@ -130,20 +126,19 @@
 			)
 	}
 
-	function handleBarActivate(bar: { data: Row }, event: MouseEvent) {
+	/**
+	 * A bar activated by click, Enter or Space. A filterable bar FILTERS — it does not also emit
+	 * `onselect`, the rule the keyboard path always had and a click did not; otherwise it
+	 * selects. The plot-level selection (`selectBar`) runs either way.
+	 */
+	function activate(bar: { data: Row }, event: MouseEvent | KeyboardEvent) {
 		if (filterable && x) handleBarClick(bar.data[x])
-		onselect?.(bar.data)
+		else onselect?.(bar.data)
 		selectBar(bar, event)
 	}
 
 	function handleBarKeyActivate(bar: { data: Row }, event: KeyboardEvent) {
-		if (event.key !== 'Enter' && event.key !== ' ') return
-		if (filterable && x) {
-			handleBarClick(bar.data[x])
-		} else {
-			onselect?.(bar.data)
-		}
-		selectBar(bar, event)
+		if (event.key === 'Enter' || event.key === ' ') activate(bar, event)
 	}
 </script>
 
@@ -165,14 +160,10 @@
 				data-plot-category={bar.data[x ?? '']}
 				data-dimmed={dimmedByKey[bar.key] ? true : undefined}
 				style:cursor={filterable || onselect || plotState.interactive ? 'pointer' : undefined}
-				onclick={filterable || onselect || keyboard || plotState.interactive
-					? (e) => handleBarActivate(bar, e)
-					: undefined}
-				onkeydown={filterable || onselect || keyboard || plotState.interactive
-					? (e) => handleBarKeyActivate(bar, e)
-					: undefined}
-				role={filterable || onselect || keyboard || plotState.interactive ? 'button' : 'graphics-symbol'}
-				tabindex={filterable || onselect || keyboard || plotState.interactive ? 0 : undefined}
+				onclick={activatable ? (e) => activate(bar, e) : undefined}
+				onkeydown={activatable ? (e) => handleBarKeyActivate(bar, e) : undefined}
+				role={activatable ? 'button' : 'graphics-symbol'}
+				tabindex={activatable ? 0 : undefined}
 				use:keyboardNav={keyboard}
 				aria-label="{bar.data[x ?? '']}: {bar.data[y ?? '']}"
 				onmouseenter={() => plotState.setHovered(bar.data)}

package/dist/geoms/Contour.svelte

@@ -0,0 +1,88 @@
+<script lang="ts">
+	/**
+	 * Kernel-density contours — where points pile up, drawn as nested rings (or filled bands).
+	 *
+	 * A scatter of a few hundred modules hides its density: on a main-sequence plot most of
+	 * them sit on the A = 0 edge on top of each other. Contours show the pile-up without
+	 * binning it into cells the way `Hexbin` does, and they overlay the points instead of
+	 * replacing them. Grouped by `fill` (else `color`), each group contours separately.
+	 */
+	import { getContext, onMount, onDestroy } from 'svelte'
+	import type { PlotState } from '../PlotState.svelte.js'
+	import { GeomState } from './lib/GeomState.svelte.js'
+	import { buildContourMarks } from './lib/marks/contour.js'
+	import PlotAreaClip from './lib/PlotAreaClip.svelte'
+
+	type Props = {
+		x?: string
+		y?: string
+		/** Group field (and its colour). Wins over `color`. */
+		fill?: string
+		/** Group field (and its colour) when `fill` is not set. */
+		color?: string
+		/** Kernel bandwidth in pixels — larger is smoother. */
+		bandwidth?: number
+		/** Approximate number of density levels. */
+		thresholds?: number
+		/** Fill the bands instead of stroking the rings. */
+		filled?: boolean
+		/** Opacity of the densest band when filled, or of every ring when stroked. */
+		alpha?: number
+	}
+
+	let { x, y, fill, color, bandwidth = 20, thresholds = 8, filled = false, alpha }: Props = $props()
+
+	const plotState = getContext<PlotState>('plot-state')
+	const uid = $props.id()
+	const clipId = `plot-contour-clip-${uid}`
+	const geom = new GeomState(plotState, () => ({
+		type: 'contour',
+		channels: { x, y, fill, color },
+		options: { bandwidth, thresholds },
+		alpha,
+		build: buildContourMarks
+	}))
+	onMount(geom.register)
+	onDestroy(geom.destroy)
+	$effect(geom.sync)
+
+	const rings = $derived(geom.marks)
+	const grouped = $derived(Boolean(fill ?? color))
+</script>
+
+{#if rings.length > 0}
+	<PlotAreaClip id={clipId} />
+	<g
+		data-plot-geom="contour"
+		data-plot-contour-mode={filled ? 'filled' : 'lines'}
+		clip-path="url(#{clipId})"
+	>
+		{#each rings as r (r.key)}
+			<path
+				d={r.d}
+				fill={filled ? r.fill : 'none'}
+				fill-opacity={filled ? r.fillAlpha : undefined}
+				stroke={filled ? 'none' : grouped ? r.stroke : undefined}
+				stroke-opacity={!filled && alpha !== undefined ? alpha : undefined}
+				data-plot-element="contour"
+				data-plot-contour={r.group}
+				data-plot-contour-level={r.level}
+			/>
+		{/each}
+	</g>
+{/if}
+
+<style>
+	[data-plot-geom='contour'] {
+		pointer-events: none;
+	}
+	[data-plot-contour-mode='lines'] [data-plot-element='contour'] {
+		stroke-width: var(--chart-contour-width, 1);
+	}
+	[data-plot-contour-mode='lines'] [data-plot-element='contour']:not([stroke-opacity]) {
+		stroke-opacity: var(--chart-contour-opacity, 0.7);
+	}
+	[data-plot-contour-mode='lines'] [data-plot-element='contour']:not([stroke]) {
+		stroke: var(--chart-contour-color, currentColor);
+	}
+</style>

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

@@ -0,0 +1,19 @@
+type Props = {
+    x?: string;
+    y?: string;
+    /** Group field (and its colour). Wins over `color`. */
+    fill?: string;
+    /** Group field (and its colour) when `fill` is not set. */
+    color?: string;
+    /** Kernel bandwidth in pixels — larger is smoother. */
+    bandwidth?: number;
+    /** Approximate number of density levels. */
+    thresholds?: number;
+    /** Fill the bands instead of stroking the rings. */
+    filled?: boolean;
+    /** Opacity of the densest band when filled, or of every ring when stroked. */
+    alpha?: number;
+};
+declare const Contour: import("svelte").Component<Props, {}, "">;
+type Contour = ReturnType<typeof Contour>;
+export default Contour;

package/dist/geoms/Hull.svelte

@@ -0,0 +1,89 @@
+<script lang="ts">
+	/**
+	 * An outline around each group of points — the convex hull of the `fill` (else `color`)
+	 * field's rows, padded so the outline clears the points it encloses.
+	 *
+	 * Answers "how spread out is this group": a package whose modules span the zone of pain to
+	 * the zone of uselessness has a hull the size of the chart. The group field joins the
+	 * shared palette, so a hull and the points it encloses take the same colour — or, with
+	 * different fields, hulls group by package while points colour by community.
+	 *
+	 * Place it BEFORE the points so the fill sits behind them.
+	 */
+	import { getContext, onMount, onDestroy } from 'svelte'
+	import type { PlotState } from '../PlotState.svelte.js'
+	import { GeomState } from './lib/GeomState.svelte.js'
+	import { buildHullMarks } from './lib/marks/hull.js'
+
+	type Props = {
+		x?: string
+		y?: string
+		/** Group field (and its colour). Wins over `color`. */
+		fill?: string
+		/** Group field (and its colour) when `fill` is not set. */
+		color?: string
+		/** Pixels between the outermost points and the outline. */
+		padding?: number
+		/** Opacity 0–1 of the whole hull; defaults to the preset's `hull` opacity. */
+		alpha?: number
+		/** Draw the group's name at its centroid. */
+		label?: boolean
+	}
+
+	let { x, y, fill, color, padding = 10, alpha, label = false }: Props = $props()
+
+	const plotState = getContext<PlotState>('plot-state')
+	const geom = new GeomState(plotState, () => ({
+		type: 'hull',
+		channels: { x, y, fill, color },
+		alpha,
+		build: buildHullMarks
+	}))
+	onMount(geom.register)
+	onDestroy(geom.destroy)
+	$effect(geom.sync)
+
+	const hulls = $derived(geom.marks)
+</script>
+
+{#if hulls.length > 0}
+	<g data-plot-geom="hull">
+		{#each hulls as h (h.key)}
+			<!-- `opacity`, not fill-/stroke-opacity: the padding is a stroke that overlaps the
+				 fill, and only element opacity composites the two as one shape. -->
+			<path
+				d={h.d}
+				fill={h.fill}
+				stroke={h.fill}
+				stroke-width={padding * 2}
+				stroke-linejoin="round"
+				stroke-linecap="round"
+				opacity={h.alpha}
+				data-plot-element="hull"
+				data-plot-hull={h.group}
+			/>
+		{/each}
+		{#if label}
+			{#each hulls as h (h.key)}
+				<text
+					x={h.at.x}
+					y={h.at.y}
+					text-anchor="middle"
+					dominant-baseline="middle"
+					data-plot-element="hull-label">{h.group}</text
+				>
+			{/each}
+		{/if}
+	</g>
+{/if}
+
+<style>
+	[data-plot-geom='hull'] {
+		pointer-events: none;
+	}
+	[data-plot-element='hull-label'] {
+		fill: var(--chart-hull-label-color, currentColor);
+		font-size: var(--chart-hull-label-size, 11px);
+		font-weight: 600;
+	}
+</style>

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

@@ -0,0 +1,17 @@
+type Props = {
+    x?: string;
+    y?: string;
+    /** Group field (and its colour). Wins over `color`. */
+    fill?: string;
+    /** Group field (and its colour) when `fill` is not set. */
+    color?: string;
+    /** Pixels between the outermost points and the outline. */
+    padding?: number;
+    /** Opacity 0–1 of the whole hull; defaults to the preset's `hull` opacity. */
+    alpha?: number;
+    /** Draw the group's name at its centroid. */
+    label?: boolean;
+};
+declare const Hull: import("svelte").Component<Props, {}, "">;
+type Hull = ReturnType<typeof Hull>;
+export default Hull;

package/dist/geoms/Region.svelte

@@ -0,0 +1,107 @@
+<script lang="ts">
+	/**
+	 * A shaded region in DATA coordinates — a band (`x` and/or `y` as `[lo, hi]`) or a polygon
+	 * (`points`).
+	 *
+	 * The zones on a main-sequence diagram, the quadrants of a hotspot map, the threshold box
+	 * of a code-smell detection rule: each is a statement about the metric PLANE, not about
+	 * any row, so a region reads no data and registers no geom. It never moves the scales —
+	 * declare `xDomain`/`yDomain` on the chart when the region, not the data, defines the frame.
+	 *
+	 * SVG paints in document order, so place a Region BEFORE the marks it sits behind.
+	 */
+	import { getContext } from 'svelte'
+	import type { PlotState } from '../PlotState.svelte.js'
+	import { regionVertices, positionOf, centroid, polygonPath } from '../lib/region.js'
+	import PlotAreaClip from './lib/PlotAreaClip.svelte'
+
+	type Value = number | string
+	type Props = {
+		/**
+		 * `[lo, hi]` on the x axis. Omit to span the whole axis; a `null` end runs to that edge,
+		 * so `[p75, null]` is "the top quartile and beyond". A band category covers its band.
+		 */
+		x?: [Value | null, Value | null]
+		/** `[lo, hi]` on the y axis, with the same open-end rule. */
+		y?: [Value | null, Value | null]
+		/** Polygon vertices as `[x, y]` pairs in data coordinates. Wins over `x`/`y`. */
+		points?: Array<[Value, Value]>
+		/** Theming hook — rendered as `data-plot-region="<name>"`. */
+		name?: string
+		/** Text drawn at the region's centroid (or at `labelAt`). */
+		label?: string
+		/** `[x, y]` in data coordinates for the label, when the centroid is the wrong spot. */
+		labelAt?: [Value, Value]
+		/** Literal fill colour. Defaults to `--chart-region-fill`. */
+		fill?: string
+		/** Fill opacity 0–1. Defaults to `--chart-region-opacity`. */
+		alpha?: number
+		/** Optional outline colour. */
+		stroke?: string
+	}
+
+	let {
+		x = undefined,
+		y = undefined,
+		points = undefined,
+		name = undefined,
+		label = undefined,
+		labelAt = undefined,
+		fill = undefined,
+		alpha = undefined,
+		stroke = undefined
+	}: Props = $props()
+
+	const plotState = getContext<PlotState>('plot-state')
+	const uid = $props.id()
+	const clipId = `plot-region-clip-${uid}`
+
+	const shape = $derived.by(() => {
+		const xs = plotState.xScale
+		const ys = plotState.yScale
+		if (!xs || !ys) return null
+		const uv = regionVertices({ x, y, points }, xs, ys)
+		if (uv.length === 0) return null
+		const pts = uv.map(([u, v]) => plotState.place(u, v))
+		const at = labelAt
+			? plotState.place(positionOf(xs, labelAt[0]), positionOf(ys, labelAt[1]))
+			: centroid(pts)
+		return { d: polygonPath(pts), at }
+	})
+</script>
+
+{#if shape}
+	<PlotAreaClip id={clipId} />
+	<g data-plot-geom="region" data-plot-region={name} clip-path="url(#{clipId})">
+		<path d={shape.d} {fill} fill-opacity={alpha} {stroke} data-plot-element="region" />
+		{#if label}
+			<text
+				x={shape.at.x}
+				y={shape.at.y}
+				text-anchor="middle"
+				dominant-baseline="middle"
+				data-plot-element="region-label">{label}</text
+			>
+		{/if}
+	</g>
+{/if}
+
+<style>
+	[data-plot-geom='region'] {
+		pointer-events: none;
+	}
+	[data-plot-element='region']:not([fill]) {
+		fill: var(--chart-region-fill, currentColor);
+	}
+	[data-plot-element='region']:not([fill-opacity]) {
+		fill-opacity: var(--chart-region-opacity, 0.08);
+	}
+	[data-plot-element='region']:not([stroke]) {
+		stroke: none;
+	}
+	[data-plot-element='region-label'] {
+		fill: var(--chart-region-label-color, currentColor);
+		font-size: var(--chart-region-label-size, 11px);
+		opacity: var(--chart-region-label-opacity, 0.75);
+	}
+</style>

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

@@ -0,0 +1,27 @@
+type Value = number | string;
+type Props = {
+    /**
+     * `[lo, hi]` on the x axis. Omit to span the whole axis; a `null` end runs to that edge,
+     * so `[p75, null]` is "the top quartile and beyond". A band category covers its band.
+     */
+    x?: [Value | null, Value | null];
+    /** `[lo, hi]` on the y axis, with the same open-end rule. */
+    y?: [Value | null, Value | null];
+    /** Polygon vertices as `[x, y]` pairs in data coordinates. Wins over `x`/`y`. */
+    points?: Array<[Value, Value]>;
+    /** Theming hook — rendered as `data-plot-region="<name>"`. */
+    name?: string;
+    /** Text drawn at the region's centroid (or at `labelAt`). */
+    label?: string;
+    /** `[x, y]` in data coordinates for the label, when the centroid is the wrong spot. */
+    labelAt?: [Value, Value];
+    /** Literal fill colour. Defaults to `--chart-region-fill`. */
+    fill?: string;
+    /** Fill opacity 0–1. Defaults to `--chart-region-opacity`. */
+    alpha?: number;
+    /** Optional outline colour. */
+    stroke?: string;
+};
+declare const Region: import("svelte").Component<Props, {}, "">;
+type Region = ReturnType<typeof Region>;
+export default Region;