@rokkit/chart 1.3.14 → 1.4.0

package/dist/AnimatedPlot.svelte

@@ -202,7 +202,10 @@
 	})
 
 	onDestroy(() => {
-		cancelAnimationFrame(rafId)
+		// onDestroy is the one lifecycle hook that also runs during SSR, where
+		// cancelAnimationFrame is undefined — guard it so the component can be
+		// server-rendered / prerendered (rafId is only ever set in the browser).
+		if (typeof cancelAnimationFrame !== 'undefined') cancelAnimationFrame(rafId)
 		clearInterval(reducedInterval)
 	})
 

package/dist/Plot.svelte

@@ -20,6 +20,7 @@
 	import Waterfall from './geoms/Waterfall.svelte'
 	import Hexbin from './geoms/Hexbin.svelte'
 	import Ribbon from './geoms/Ribbon.svelte'
+	import Radar from './geoms/Radar.svelte'
 	import Highlight from './geoms/Highlight.svelte'
 	import Trend from './geoms/Trend.svelte'
 
@@ -58,6 +59,13 @@
 		onselect?: (detail: unknown) => void
 		selectable?: boolean
 		selected?: Row[]
+		/** Data-coordinate crossing point of the axes: `[xCross, yCross]`. Drives
+		 *  quadrant mode — where the origin sits relative to the domain makes a chart
+		 *  1- / 2- / 4-quadrant. Omit a component to leave that axis auto (crosses at 0
+		 *  when the domain spans it, else edge-pinned). Also settable via `spec.axisOrigin`. */
+		axisOrigin?: [number | undefined, number | undefined]
+		/** Nudge an edge-pinned axis outward by N px (Q1 only). Also via `spec.axisOffset`. */
+		axisOffset?: number
 		/** Animate marks on data/flip changes (opt-out for e.g. AnimatedPlot, which
 		 *  tweens its own frames). Enabled one frame after the width settles so the
 		 *  initial layout paints un-animated. Default `true`. */
@@ -94,6 +102,8 @@
 		onselect = undefined,
 		selectable = false,
 		selected = $bindable([]),
+		axisOrigin = undefined,
+		axisOffset = undefined,
 		animate = true,
 		children
 	}: Props = $props()
@@ -103,9 +113,7 @@
 
 	const gridValue = $derived(spec?.grid ?? grid)
 	const showGrid = $derived(gridValue !== false)
-	const gridLines = $derived(
-		gridValue === true || gridValue === false ? 'auto' : gridValue
-	)
+	const gridLines = $derived(gridValue === true || gridValue === false ? 'auto' : gridValue)
 	const showLegend = $derived(spec?.legend ?? legend)
 	const chartTitle = $derived(spec?.title ?? title)
 	const chartSummary = $derived(spec?.summary ?? summary)
@@ -115,9 +123,11 @@
 	const tableColumns = $derived.by(() => {
 		// Dedupe: a channel may repeat (e.g. x === color), and the table's keyed each
 		// requires unique column names.
-		const cols = [...new Set(
-			[spec?.x, spec?.y, spec?.color ?? spec?.fill].filter((c): c is string => Boolean(c))
-		)]
+		const cols = [
+			...new Set(
+				[spec?.x, spec?.y, spec?.color ?? spec?.fill].filter((c): c is string => Boolean(c))
+			)
+		]
 		if (cols.length > 0) return cols
 		const first = tableData[0]
 		return first ? Object.keys(first) : []
@@ -142,6 +152,8 @@
 			colorScheme: spec?.colorScheme,
 			colorMidpoint: spec?.colorMidpoint,
 			orientation: orientation ?? spec?.orientation,
+			axisOrigin: spec?.axisOrigin ?? axisOrigin,
+			axisOffset: spec?.axisOffset ?? axisOffset,
 			sort: spec?.sort,
 			continuousCategory: spec?.continuousCategory,
 			chartPreset,
@@ -169,7 +181,10 @@
 		candlestick: Candlestick,
 		waterfall: Waterfall,
 		hexbin: Hexbin,
-		ribbon: Ribbon
+		ribbon: Ribbon,
+		// Radar reads the generic x/y/color this path passes via its own aliases, and takes
+		// its axis order from `options.axes` — see Radar.svelte's Props.
+		radar: Radar
 	}
 
 	function resolveGeomComponent(type: string) {
@@ -224,8 +239,20 @@
 
 		<!-- Axes -->
 		{#if axes}
-			<Axis type="x" label={spec?.labels?.[spec?.x ?? ''] ?? ''} format={xFormat} ticks={xTicks} {minorTicks} />
-			<Axis type="y" label={spec?.labels?.[spec?.y ?? ''] ?? ''} format={yFormat} ticks={yTicks} {minorTicks} />
+			<Axis
+				type="x"
+				label={spec?.labels?.[spec?.x ?? ''] ?? ''}
+				format={xFormat}
+				ticks={xTicks}
+				{minorTicks}
+			/>
+			<Axis
+				type="y"
+				label={spec?.labels?.[spec?.y ?? ''] ?? ''}
+				format={yFormat}
+				ticks={yTicks}
+				{minorTicks}
+			/>
 		{/if}
 
 		{#if trend !== null && trend !== undefined}

package/dist/Plot.svelte.d.ts

@@ -41,6 +41,13 @@ type Props = {
     onselect?: (detail: unknown) => void;
     selectable?: boolean;
     selected?: Row[];
+    /** Data-coordinate crossing point of the axes: `[xCross, yCross]`. Drives
+     *  quadrant mode — where the origin sits relative to the domain makes a chart
+     *  1- / 2- / 4-quadrant. Omit a component to leave that axis auto (crosses at 0
+     *  when the domain spans it, else edge-pinned). Also settable via `spec.axisOrigin`. */
+    axisOrigin?: [number | undefined, number | undefined];
+    /** Nudge an edge-pinned axis outward by N px (Q1 only). Also via `spec.axisOffset`. */
+    axisOffset?: number;
     /** Animate marks on data/flip changes (opt-out for e.g. AnimatedPlot, which
      *  tweens its own frames). Enabled one frame after the width settles so the
      *  initial layout paints un-animated. Default `true`. */

package/dist/PlotState.svelte.d.ts

@@ -95,6 +95,7 @@ export class PlotState {
             ribbon: number;
             waterfall: number;
             rule: number;
+            radar: number;
         };
         patterns: string[];
         symbols: string[];

package/dist/PlotState.svelte.js

@@ -425,6 +425,7 @@ export class PlotState {
 		this.#selectable = config.selectable ?? false
 		if (config.selected) this.#selected = new SvelteSet(config.selected)
 		this.#axisOffset = config.axisOffset ?? 0
+		this.axisOrigin = config.axisOrigin ?? [undefined, undefined]
 		this.#marginOverride = config.margin ?? undefined
 		this.#orientationOverride = config.orientation ?? undefined
 		this.#continuousCategory = config.continuousCategory ?? false
@@ -453,6 +454,7 @@ export class PlotState {
 		if (config.onselect !== undefined) this.#onselect = config.onselect
 		if (config.selectable !== undefined) this.#selectable = config.selectable
 		if (config.axisOffset !== undefined) this.#axisOffset = config.axisOffset
+		this.axisOrigin = config.axisOrigin ?? [undefined, undefined]
 		this.#marginOverride = config.margin ?? undefined
 		this.#orientationOverride = config.orientation ?? undefined
 		this.#continuousCategory = config.continuousCategory ?? false
@@ -480,7 +482,14 @@ export class PlotState {
 		if (!geom) return []
 		const stat = geom.stat ?? 'identity'
 		if (stat === 'identity') return this.#rawData
-		const mergedChannels = { ...this.#channels, ...geom.channels }
+		// Strip explicit `undefined` values before spreading: a geom that omits a channel
+		// to inherit it from the container sends `{ x: undefined }`, not `{}`, which would
+		// otherwise become an own property that clobbers the container's value below (see
+		// SparkState.geomData for the fuller writeup — same bug, same fix, both classes).
+		const geomChannels = Object.fromEntries(
+			Object.entries(geom.channels ?? {}).filter(([, v]) => v !== undefined)
+		)
+		const mergedChannels = { ...this.#channels, ...geomChannels }
 		return applyGeomStat(this.#rawData, { stat, channels: mergedChannels }, this.#helpers)
 	}
 

package/dist/Spark.svelte

@@ -0,0 +1,165 @@
+<script lang="ts">
+	import { setContext, untrack } from 'svelte'
+	import type { Snippet } from 'svelte'
+	import { SparkState } from './SparkState.svelte.js'
+	import DefinePatterns from './patterns/DefinePatterns.svelte'
+
+	type Row = Record<string, unknown>
+
+	type Props = {
+		data?: Row[]
+		x?: string
+		y?: string
+		/** Categorical color/series channel — same meaning as a geom's `color`/`fill` prop. */
+		color?: string
+		width?: number
+		height?: number
+		min?: number
+		max?: number
+		/** Anchor value: extends the y-domain to include it AND draws a `[data-plot-baseline]`
+		 *  reference line at its pixel. Owned by the container, not a geom — it already owns
+		 *  the domain extension, and it applies to bar sparks too, not just area. */
+		baseline?: number
+		/** Literal pattern name (e.g. 'diagonal') to texture the composed geom's fill with.
+		 *  A spark is single-series, so unlike a Plot's pattern CHANNEL (which assigns a
+		 *  distinct pattern per distinct field value), there's no grouping to assign — this
+		 *  names the one pattern to use directly. See `SparkState.patterns` for the mechanism. */
+		pattern?: string
+		/** Accessible name for the glyph. Omit and one is generated from the series — see
+		 *  `summary` below. Pass a real one whenever the surrounding copy doesn't already
+		 *  say what the sparkline is measuring. */
+		label?: string
+		/** The geom(s) to compose inside — e.g. `<Line />`, `<Area />`, `<Trend />`. */
+		children?: Snippet
+	}
+
+	let {
+		data = [],
+		x = undefined,
+		y = undefined,
+		color = undefined,
+		width = 80,
+		height = 24,
+		min = undefined,
+		max = undefined,
+		baseline = undefined,
+		pattern = undefined,
+		label = undefined,
+		children
+	}: Props = $props()
+
+	// A getter thunk (not a plain object) so every reactive prop it closes over is re-read on
+	// each call — used both by the untracked initial construction and the live $effect below.
+	const config = () => ({
+		data,
+		channels: { x, y, color },
+		width,
+		height,
+		min,
+		max,
+		baseline,
+		pattern
+	})
+
+	// untrack: the constructor's initial read of config() must not register as a dependency of
+	// whatever scope creates <Spark> — mirrors PlotSurface's
+	// `untrack(() => new PlotState(fullConfig()))`. The $effect below is the sole mechanism
+	// that keeps the state live.
+	const state = untrack(() => new SparkState(config()))
+
+	// SAME context key PlotState publishes on — this is what lets a geom compose inside a
+	// Spark with zero changes: it never knows, or branches on, which container it resolved.
+	setContext('plot-state', state)
+
+	// Keeps props live: SparkState.update() is designed to be re-callable (see its doc
+	// comment) and fully re-applies config rather than merging deltas, so every prop change
+	// here — including ones read only inside a composed geom's channels — flows through.
+	$effect(() => {
+		state.update(config())
+	})
+
+	/** Round for speech: drops a pointless `.00` without truncating real precision. */
+	function speak(n: number) {
+		return String(Math.round(n * 100) / 100)
+	}
+
+	// A sparkline carries meaning purely visually, so without this it is not merely
+	// unlabelled — it is unreadable to a screen reader. Cycle 1 shipped every spark as a
+	// bare <svg> with no role or name at all.
+	//
+	// Generated from the series rather than a fixed "sparkline" string: a constant would
+	// satisfy an axe rule while still telling the user nothing. Count, direction, endpoints
+	// and extent are what someone reads off the shape visually, so they are what the text
+	// alternative says.
+	const summary = $derived.by(() => {
+		const values = y ? data.map((row) => Number(row[y])).filter((v) => Number.isFinite(v)) : []
+		if (!values.length) return 'Sparkline with no data'
+
+		const first = values[0]
+		const last = values[values.length - 1]
+		// reduce rather than Math.min(...values): spread on a long series risks a stack
+		// overflow, and a spark is free to be handed thousands of points.
+		const lo = values.reduce((a, b) => (b < a ? b : a), first)
+		const hi = values.reduce((a, b) => (b > a ? b : a), first)
+		const direction = last > first ? 'rising' : last < first ? 'falling' : 'flat'
+
+		return (
+			`Sparkline: ${values.length} values, ${direction} from ${speak(first)} to ` +
+			`${speak(last)}, ranging ${speak(lo)} to ${speak(hi)}.`
+		)
+	})
+
+	const accessibleName = $derived(label ?? summary)
+
+	// The baseline line is the container's concern, not a geom's: it already owns the domain
+	// extension (SparkState's y-domain widening), and it applies to bar sparks too, not just
+	// area — so a single reference line lives here rather than duplicated inside every geom.
+	const baselineY = $derived.by(() => {
+		if (baseline === undefined) return null
+		const scale = state.yScale
+		// buildUnifiedYScale's return type is a union (linear | band) because a PlotState y
+		// channel *can* be categorical — a spark's never is (SparkState's #yDomain is always
+		// numeric), so this is always the linear branch in practice. `'ticks' in scale` narrows
+		// the union for the compiler without a bare property access on a member (ScaleBand)
+		// that doesn't have it at all (same union Plot/Grid.svelte narrows for xScale/yScale).
+		return 'ticks' in scale ? scale(baseline) : null
+	})
+</script>
+
+<svg
+	{width}
+	{height}
+	data-spark
+	role="img"
+	aria-label={accessibleName}
+	style="overflow: visible; display: block;"
+>
+	<!-- role="img" + aria-label is what actually gets announced; title/desc are the
+	     SVG-native equivalents, kept for tooling and non-ARIA consumers. `desc` always
+	     holds the generated data summary even when `label` overrides the name, so the
+	     numbers stay available rather than being replaced by the caller's wording. -->
+	<title>{accessibleName}</title>
+	<desc>{summary}</desc>
+
+	<!-- SVG <pattern> defs for texture fills — the same mechanism PlotSurface wires up, so a
+	     geom's pattern channel resolves inside a Spark exactly as it does inside a Plot. -->
+	<defs>
+		<DefinePatterns />
+	</defs>
+
+	{#if baselineY !== null}
+		<line x1={0} y1={baselineY} x2={width} y2={baselineY} data-plot-baseline />
+	{/if}
+
+	{@render children?.()}
+</svg>
+
+<style>
+	[data-plot-baseline] {
+		stroke: var(--chart-baseline-color, currentColor);
+		stroke-width: var(--chart-baseline-width, 1);
+		stroke-dasharray: var(--chart-baseline-dash, 4 4);
+		opacity: var(--chart-baseline-opacity, 0.5);
+		pointer-events: none;
+	}
+</style>

package/dist/Spark.svelte.d.ts

@@ -0,0 +1,31 @@
+import type { Snippet } from 'svelte';
+type Row = Record<string, unknown>;
+type Props = {
+    data?: Row[];
+    x?: string;
+    y?: string;
+    /** Categorical color/series channel — same meaning as a geom's `color`/`fill` prop. */
+    color?: string;
+    width?: number;
+    height?: number;
+    min?: number;
+    max?: number;
+    /** Anchor value: extends the y-domain to include it AND draws a `[data-plot-baseline]`
+     *  reference line at its pixel. Owned by the container, not a geom — it already owns
+     *  the domain extension, and it applies to bar sparks too, not just area. */
+    baseline?: number;
+    /** Literal pattern name (e.g. 'diagonal') to texture the composed geom's fill with.
+     *  A spark is single-series, so unlike a Plot's pattern CHANNEL (which assigns a
+     *  distinct pattern per distinct field value), there's no grouping to assign — this
+     *  names the one pattern to use directly. See `SparkState.patterns` for the mechanism. */
+    pattern?: string;
+    /** Accessible name for the glyph. Omit and one is generated from the series — see
+     *  `summary` below. Pass a real one whenever the surrounding copy doesn't already
+     *  say what the sparkline is measuring. */
+    label?: string;
+    /** The geom(s) to compose inside — e.g. `<Line />`, `<Area />`, `<Trend />`. */
+    children?: Snippet;
+};
+declare const Spark: import("svelte").Component<Props, {}, "">;
+type Spark = ReturnType<typeof Spark>;
+export default Spark;

package/dist/SparkState.svelte.d.ts

@@ -0,0 +1,138 @@
+/**
+ * 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`,
+ * `geoms/lib/**`, including the `marks/*.js` adapters). `SparkState` must implement
+ * every one of these: a `<Spark>` composes the SAME geom components a `<Plot>` does,
+ * and no geom branches on which container it's inside — so a member missing here is a
+ * member that throws inside a `<Spark>` at runtime, not at the point that grew it.
+ *
+ * This is the ONE place to update when that surface legitimately changes. Adding a
+ * geom (or a new context read inside an existing one) that needs a `PlotState` member
+ * means adding it here too. `spec/spark-contract.spec.js` asserts `SparkState` and
+ * `PlotState` both satisfy this exact list and agree on each member's kind (function /
+ * Map / array / null / primitive). If that test goes red after you add a member here,
+ * that is the signal working as intended — it means `SparkState` is missing the
+ * member, not that the test is wrong. Do not "fix" a red conformance test by deleting
+ * the entry you just added.
+ *
+ * Deliberately excluded — read only by `Plot`'s chrome (`Axis`/`Legend`/`Tooltip`/
+ * `Grid`) or by `PlotSurface`'s own wiring, never by a geom: `xAxisY`, `yAxisX`,
+ * `hovered`, `mode`, `colorScaleType`, `geomTypes`, `colorField`, `patternField`,
+ * `symbolField`, `format`, `label`, `tooltip`, `margin`, `bandScale`, `valueScale`,
+ * `preset`, `geomComponent`. A `<Spark>` has no axis, legend, tooltip or grid to
+ * drive, so none of these ever apply.
+ *
+ * Also excluded: `selectedRows` / `isSelected` / `setSelected` / `clearSelected` /
+ * `applyZoom` / `resetZoom`. `geoms/Highlight.svelte` is the one geom that reads
+ * `state?.selectedRows`, but it does so defensively (`?? []`) — multi-select and zoom
+ * are explicit non-goals for a spark (see
+ * docs/superpowers/specs/2026-08-20-spark-plot-geom-architecture-design.md), so their
+ * absence degrades Highlight to "nothing selected", not a runtime error. That's a
+ * different failure mode than every member below, where absence throws.
+ */
+export const GEOM_CONTRACT: string[];
+/**
+ * SparkState — the lean, PlotState-compatible context that lets a sparkline compose
+ * real geoms (`<Spark><Line /></Spark>`) instead of Sparkline's own hand-rolled
+ * line/area/bar rendering. It publishes on the same 'plot-state' context key as
+ * PlotState, so geoms (Line/Area/Bar) read scales, channels and data through the
+ * identical interface and never know whether they're inside a spark or a full Plot.
+ *
+ * An 80×24 glyph has no use for most of what PlotState carries, so this is a thin
+ * composition of the same pure scale modules PlotState uses — not a re-implementation
+ * of PlotState's scope. It publishes the same registerGeom/updateGeom/unregisterGeom/
+ * geomData lifecycle as PlotState (see those methods below), at smaller scope, so
+ * GeomState — and therefore any geom component — drives a spark unchanged. Deliberately
+ * omitted, permanently (a <Spark> container is a later slice, but none of these ever
+ * apply to an 80×24 glyph):
+ *  - zoom/pan transforms — a spark is a static glyph, never panned or zoomed.
+ *  - crossfilter/selection — nothing to click or brush at this size.
+ *  - facets — a spark is always a single small panel, never a grid of panels.
+ *  - axis/legend chrome and margins — width/height ARE the inner box.
+ *
+ * This class also carries the rest of the surface a geom reads off `plot-state`:
+ * `colors` — a real categorical palette, built from the same brewing helpers PlotState
+ * uses, keyed off `channels.color ?? channels.fill` — plus a set of members geoms read
+ * but a spark has no use for (symbols/isFlipped/orientation/continuousCategory/
+ * continuousColorScale/interactive/place/setHovered/clearHovered/handleSelect). Those are
+ * kept present and explicit — empty Maps, false/null/identity, no-op methods — rather
+ * than simply absent, so a geom never needs a spark-specific branch and a later
+ * conformance test can pin the full contract. `patterns` is the one exception with a real,
+ * non-empty case — see its own doc comment below for why a literal name is the only
+ * sensible spark case.
+ *
+ * `data` deliberately holds ONE array (`$state.raw`, not a proxying `$state`), unlike
+ * PlotState's `#data`/`#rawData` pair. That split gave PlotState's data two distinct
+ * proxy identities for the same source array, breaking identity-based lookups like
+ * `plotState.data.indexOf(row)` (see journal 2026-08-13). Geoms will later read rows
+ * from this same array, so its identity must be exactly what the caller passed in.
+ */
+export class SparkState {
+    constructor(config?: {});
+    xScale: import("d3-scale").ScaleLinear<number, number, never> | import("d3-scale").ScaleBand<string>;
+    yScale: import("d3-scale").ScaleLinear<number, number, never> | import("d3-scale").ScaleBand<string>;
+    colors: Map<unknown, {
+        fill: string;
+        stroke: string;
+    }>;
+    update(config?: {}): void;
+    get data(): any[];
+    /** @returns {{ x?: string, y?: string }} */
+    get channels(): {
+        x?: string;
+        y?: string;
+    };
+    get innerWidth(): number;
+    get innerHeight(): number;
+    get chartPreset(): {
+        colors: string[];
+        shades: {
+            light: {
+                fill: string;
+                stroke: string;
+            };
+            dark: {
+                fill: string;
+                stroke: string;
+            };
+        };
+        opacity: {
+            area: number;
+            bar: number;
+            line: number;
+            point: number;
+            arc: number;
+            box: number;
+            violin: number;
+            jitter: number;
+            heatmap: number;
+            candlestick: number;
+            hexbin: number;
+            ribbon: number;
+            waterfall: number;
+            rule: number;
+            radar: number;
+        };
+        patterns: string[];
+        symbols: string[];
+    };
+    get patterns(): Map<any, any>;
+    get symbols(): Map<any, any>;
+    get isFlipped(): boolean;
+    get orientation(): string;
+    get continuousCategory(): boolean;
+    get continuousColorScale(): null;
+    get interactive(): boolean;
+    place(u: any, v: any): {
+        x: any;
+        y: any;
+    };
+    setHovered(): void;
+    clearHovered(): void;
+    handleSelect(): void;
+    registerGeom(config: any): string;
+    updateGeom(id: any, config: any): void;
+    unregisterGeom(id: any): void;
+    geomData(id: any): any[];
+    #private;
+}