@rokkit/chart 1.7.0 → 1.8.0

package/dist/state/AestheticState.svelte.js

@@ -0,0 +1,84 @@
+import { SvelteMap } from 'svelte/reactivity'
+import { inferFieldType, inferColorScaleType } from '../lib/plot/scales.js'
+import {
+	distinct,
+	assignColors,
+	isLiteralColor,
+	buildSequentialScale,
+	buildDivergingScale
+} from '../lib/brewing/colors.js'
+import { assignPatterns } from '../lib/brewing/patterns.js'
+import { assignSymbols } from '../lib/brewing/marks/points.js'
+
+/**
+ * What each category looks like: its palette entry, pattern and symbol — and, for a numeric
+ * colour field, the continuous (sequential or diverging) colour scale.
+ */
+export class AestheticState {
+	#config
+	#channels
+
+	/**
+	 * @param {import('./PlotConfig.svelte.js').PlotConfig} config
+	 * @param {import('./ChannelState.svelte.js').ChannelState} channels
+	 */
+	constructor(config, channels) {
+		this.#config = config
+		this.#channels = channels
+	}
+
+	/** 'categorical' | 'sequential' | 'diverging' — inferred from the colour field and the spec. */
+	colorScaleType = $derived.by(() => {
+		const field = this.#channels.effective.color
+		if (!field) return 'categorical'
+		return inferColorScaleType(this.#config.data, field, {
+			colorScale: this.#config.colorScale,
+			colorMidpoint: this.#config.colorMidpoint
+		})
+	})
+
+	/** The sequential or diverging colour scale, or null for a categorical colour field. */
+	continuousColorScale = $derived.by(() => {
+		const field = this.#channels.effective.color
+		if (!field || this.colorScaleType === 'categorical') return null
+		const opts = {
+			colorScheme: this.#config.colorScheme,
+			colorDomain: this.#config.colorDomain,
+			colorMidpoint: this.#config.colorMidpoint
+		}
+		const build = this.colorScaleType === 'diverging' ? buildDivergingScale : buildSequentialScale
+		return build(this.#config.data, field, opts)
+	})
+
+	/**
+	 * Map<category, { fill, stroke }> — one shared palette across the colour and fill channels.
+	 *
+	 * A literal CSS colour is a singleton keyed by null, which every mark falls back to. A
+	 * `colorDomain` (FacetPlot passes one so panels agree) wins over the local categories. With
+	 * no colour field at all, a single series takes the first palette entry rather than grey.
+	 */
+	colors = $derived.by(() => {
+		const field = this.#channels.effective.color
+		if (isLiteralColor(field)) {
+			// eslint-disable-next-line svelte/prefer-svelte-reactivity -- a derived value, rebuilt whole; nothing mutates it
+			return new Map([[null, { fill: field, stroke: field }]])
+		}
+		const values = this.#config.colorDomain ?? this.#channels.colorValues
+		const keys = values.length === 0 && this.#config.data.length > 0 ? [null] : values
+		return assignColors(keys, this.#config.mode, this.#config.chartPreset)
+	})
+
+	/** Map<category, pattern name> — only for a categorical pattern field. */
+	patterns = $derived.by(() => {
+		const pf = this.#channels.effective.pattern
+		if (!pf || inferFieldType(this.#config.data, pf) === 'continuous') return new SvelteMap()
+		return assignPatterns(distinct(this.#config.data, pf))
+	})
+
+	/** Map<category, symbol shape>. */
+	symbols = $derived.by(() => {
+		const sf = this.#channels.effective.symbol
+		if (!sf) return new SvelteMap()
+		return assignSymbols(distinct(this.#config.data, sf), this.#config.chartPreset)
+	})
+}

package/dist/state/AxisState.svelte.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Where the axes cross, in screen coordinates.
+ *
+ * At an explicit `axisOrigin` (a BCG or risk matrix); else at zero when the domain spans it
+ * (two- and four-quadrant charts fall out of where zero sits); else pinned to the bottom / left
+ * edge, pushed outward by `axisOffset`. A band x axis always pins left.
+ */
+export class AxisState {
+    /**
+     * @param {import('./PlotConfig.svelte.js').PlotConfig} config
+     * @param {{ x: any, y: any }} scales
+     * @param {{ innerWidth: number, innerHeight: number }} frame
+     */
+    constructor(config: import("./PlotConfig.svelte.js").PlotConfig, scales: {
+        x: any;
+        y: any;
+    }, frame: {
+        innerWidth: number;
+        innerHeight: number;
+    });
+    /** The x axis's screen y. */
+    xAxisY: any;
+    /** The y axis's screen x. */
+    yAxisX: any;
+    #private;
+}

package/dist/state/AxisState.svelte.js

@@ -0,0 +1,56 @@
+/**
+ * Where the axes cross, in screen coordinates.
+ *
+ * At an explicit `axisOrigin` (a BCG or risk matrix); else at zero when the domain spans it
+ * (two- and four-quadrant charts fall out of where zero sits); else pinned to the bottom / left
+ * edge, pushed outward by `axisOffset`. A band x axis always pins left.
+ */
+export class AxisState {
+	#config
+	#scales
+	#frame
+
+	/**
+	 * @param {import('./PlotConfig.svelte.js').PlotConfig} config
+	 * @param {{ x: any, y: any }} scales
+	 * @param {{ innerWidth: number, innerHeight: number }} frame
+	 */
+	constructor(config, scales, frame) {
+		this.#config = config
+		this.#scales = scales
+		this.#frame = frame
+	}
+
+	/** The x axis's screen y. */
+	xAxisY = $derived.by(() => {
+		const y = this.#scales.y
+		if (typeof y !== 'function') return this.#frame.innerHeight
+		const cross = this.#config.axisOrigin[1]
+		if (cross !== undefined) return y(cross)
+		const domain = y.domain()
+		if (domain[0] <= 0 && domain[domain.length - 1] >= 0) return y(0)
+		return this.#offset(y(domain[0]), 1)
+	})
+
+	/** The y axis's screen x. */
+	yAxisX = $derived.by(() => {
+		const x = this.#scales.x
+		if (typeof x !== 'function') return 0
+		const cross = this.#config.axisOrigin[0]
+		if (cross !== undefined) return x(cross)
+		if (typeof x.bandwidth === 'function') return 0
+		const domain = x.domain()
+		if (domain[0] <= 0 && domain[domain.length - 1] >= 0) return x(0)
+		return this.#offset(x(domain[0]), -1)
+	})
+
+	/**
+	 * Push an edge-pinned axis outward by `axisOffset`. Only when there IS an offset: a scale with
+	 * an empty domain (a race's first frame, before any rows) returns undefined, and
+	 * `undefined + 0` is NaN — which lands in the axis transform as `translate(NaN, 0)`.
+	 */
+	#offset(base, direction) {
+		const offset = this.#config.axisOffset
+		return offset ? base + direction * offset : base
+	}
+}

package/dist/state/ChannelState.svelte.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Which data field feeds each aesthetic, once the container and its geoms are merged.
+ */
+export class ChannelState {
+    /**
+     * @param {import('./PlotConfig.svelte.js').PlotConfig} config
+     * @param {import('./GeomRegistry.svelte.js').GeomRegistry} geoms
+     */
+    constructor(config: import("./PlotConfig.svelte.js").PlotConfig, geoms: import("./GeomRegistry.svelte.js").GeomRegistry);
+    /**
+     * The container's channels, with each field it omits taken from the FIRST geom — per field,
+     * not all-or-nothing, so a `<Plot.Root x y>` that omits `color` still picks up
+     * `<Plot.Box color=x>`'s, and the palette gets per-category entries instead of grey.
+     */
+    effective: import("./PlotConfig.svelte.js").Channels | {
+        [k: string]: any;
+    };
+    /** The colour field, or null when `color` is a literal CSS colour rather than a field. */
+    colorField: any;
+    /** The fill field, or null for a literal colour. */
+    fillField: any;
+    patternField: any;
+    symbolField: any;
+    /**
+     * The category values feeding ONE shared palette and legend: every `color` and `fill` field
+     * of the container and of every geom (literal colours excluded), their values unioned in
+     * order. See docs/backlog/2026-08-17-chart-aesthetics-unification.md §2.
+     *
+     * `includes` rather than a Set: a domain of dozens of categories, not rows, so the scan
+     * costs nothing and there is no collection for the reactivity linter to flag.
+     */
+    colorValues: unknown[];
+    #private;
+}

package/dist/state/ChannelState.svelte.js

@@ -0,0 +1,67 @@
+import { distinct, isLiteralColor } from '../lib/brewing/colors.js'
+
+/** The positional and aesthetic channels a container can inherit from its first geom. */
+const INHERITED = ['x', 'y', 'color', 'fill', 'pattern', 'symbol']
+
+/**
+ * Which data field feeds each aesthetic, once the container and its geoms are merged.
+ */
+export class ChannelState {
+	#config
+	#geoms
+
+	/**
+	 * @param {import('./PlotConfig.svelte.js').PlotConfig} config
+	 * @param {import('./GeomRegistry.svelte.js').GeomRegistry} geoms
+	 */
+	constructor(config, geoms) {
+		this.#config = config
+		this.#geoms = geoms
+	}
+
+	/**
+	 * The container's channels, with each field it omits taken from the FIRST geom — per field,
+	 * not all-or-nothing, so a `<Plot.Root x y>` that omits `color` still picks up
+	 * `<Plot.Box color=x>`'s, and the palette gets per-category entries instead of grey.
+	 */
+	effective = $derived.by(() => {
+		const tc = this.#config.channels
+		const geom = this.#geoms.first
+		if (!geom) return tc
+		const own = geom.channels ?? {}
+		return Object.fromEntries(INHERITED.map((key) => [key, tc[key] ?? own[key]]))
+	})
+
+	/** The colour field, or null when `color` is a literal CSS colour rather than a field. */
+	colorField = $derived(isLiteralColor(this.effective.color) ? null : this.effective.color)
+	/** The fill field, or null for a literal colour. */
+	fillField = $derived(isLiteralColor(this.effective.fill) ? null : this.effective.fill)
+	patternField = $derived(this.effective.pattern)
+	symbolField = $derived(this.effective.symbol)
+
+	/**
+	 * The category values feeding ONE shared palette and legend: every `color` and `fill` field
+	 * of the container and of every geom (literal colours excluded), their values unioned in
+	 * order. See docs/backlog/2026-08-17-chart-aesthetics-unification.md §2.
+	 *
+	 * `includes` rather than a Set: a domain of dozens of categories, not rows, so the scan
+	 * costs nothing and there is no collection for the reactivity linter to flag.
+	 */
+	colorValues = $derived.by(() => {
+		const fields = []
+		const add = (f) => {
+			if (f && !isLiteralColor(f) && !fields.includes(f)) fields.push(f)
+		}
+		add(this.#config.channels.color)
+		add(this.#config.channels.fill)
+		for (const g of this.#geoms.list) {
+			add(g.channels?.color)
+			add(g.channels?.fill)
+		}
+		const values = []
+		for (const f of fields) {
+			for (const v of distinct(this.#config.data, f)) if (!values.includes(v)) values.push(v)
+		}
+		return values
+	})
+}

package/dist/state/GeomRegistry.svelte.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The geoms mounted in one plot, and the rows each one draws.
+ *
+ * Shared by `PlotState` and `SparkState`, which used to carry a copy each — and so needed the
+ * undefined-channel fix below made twice. `source` is whatever owns the rows and the container
+ * channels: `{ data, channels, helpers? }`, read live through its getters.
+ */
+export class GeomRegistry {
+    /**
+     * @param {{ data: Record<string, unknown>[], channels: Record<string, string | undefined>, helpers?: Record<string, unknown> }} source
+     * @param {string} [prefix] - id prefix, so a plot's geom ids and a spark's never collide
+     */
+    constructor(source: {
+        data: Record<string, unknown>[];
+        channels: Record<string, string | undefined>;
+        helpers?: Record<string, unknown>;
+    }, prefix?: string);
+    /** Every mounted geom's config, in mount order. */
+    get list(): any[];
+    /** The first mounted geom — the one a container without channels borrows them from. */
+    get first(): any;
+    /** Distinct geom types mounted (the legend picks a swatch style from these). */
+    types: SvelteSet<any>;
+    /** @param {(g: any) => boolean} predicate */
+    find(predicate: (g: any) => boolean): any;
+    /** Called once per geom from its onMount; the returned id is its handle. */
+    register(config: any): string;
+    /**
+     * Called from a geom's `$effect`. The read of the list is untracked: tracked, the effect
+     * would re-run on its own write (effect_update_depth_exceeded).
+     */
+    update(id: any, config: any): void;
+    /** Called from a geom's onDestroy, which Svelte runs outside any tracking scope. */
+    unregister(id: any): void;
+    /**
+     * The rows one geom draws.
+     *
+     * Identity stat returns the source rows THEMSELVES, not a copy: geoms look a row up with
+     * `plotState.data.indexOf(row)`, which only matches the same object.
+     */
+    data(id: any): Object[];
+    #private;
+}
+import { SvelteSet } from 'svelte/reactivity';

package/dist/state/GeomRegistry.svelte.js

@@ -0,0 +1,86 @@
+import { untrack } from 'svelte'
+import { SvelteSet } from 'svelte/reactivity'
+import { applyGeomStat } from '../lib/plot/stat.js'
+
+/** Module-wide so ids stay unique across every plot and spark on the page. */
+let nextId = 0
+
+/**
+ * The geoms mounted in one plot, and the rows each one draws.
+ *
+ * Shared by `PlotState` and `SparkState`, which used to carry a copy each — and so needed the
+ * undefined-channel fix below made twice. `source` is whatever owns the rows and the container
+ * channels: `{ data, channels, helpers? }`, read live through its getters.
+ */
+export class GeomRegistry {
+	#source
+	#prefix
+	#geoms = $state([])
+
+	/**
+	 * @param {{ data: Record<string, unknown>[], channels: Record<string, string | undefined>, helpers?: Record<string, unknown> }} source
+	 * @param {string} [prefix] - id prefix, so a plot's geom ids and a spark's never collide
+	 */
+	constructor(source, prefix = 'geom') {
+		this.#source = source
+		this.#prefix = prefix
+	}
+
+	/** Every mounted geom's config, in mount order. */
+	get list() {
+		return this.#geoms
+	}
+	/** The first mounted geom — the one a container without channels borrows them from. */
+	get first() {
+		return this.#geoms[0]
+	}
+	/** Distinct geom types mounted (the legend picks a swatch style from these). */
+	types = $derived(new SvelteSet(this.#geoms.map((g) => g.type)))
+
+	/** @param {(g: any) => boolean} predicate */
+	find(predicate) {
+		return this.#geoms.find(predicate)
+	}
+
+	/** Called once per geom from its onMount; the returned id is its handle. */
+	register(config) {
+		const id = `${this.#prefix}-${nextId++}`
+		this.#geoms = [...this.#geoms, { id, ...config }]
+		return id
+	}
+
+	/**
+	 * Called from a geom's `$effect`. The read of the list is untracked: tracked, the effect
+	 * would re-run on its own write (effect_update_depth_exceeded).
+	 */
+	update(id, config) {
+		this.#geoms = untrack(() => this.#geoms).map((g) => (g.id === id ? { ...g, ...config } : g))
+	}
+
+	/** Called from a geom's onDestroy, which Svelte runs outside any tracking scope. */
+	unregister(id) {
+		this.#geoms = this.#geoms.filter((g) => g.id !== id)
+	}
+
+	/**
+	 * The rows one geom draws.
+	 *
+	 * Identity stat returns the source rows THEMSELVES, not a copy: geoms look a row up with
+	 * `plotState.data.indexOf(row)`, which only matches the same object.
+	 */
+	data(id) {
+		const geom = this.#geoms.find((g) => g.id === id)
+		if (!geom) return []
+		const stat = geom.stat ?? 'identity'
+		const rows = this.#source.data
+		if (stat === 'identity') return rows
+		// A geom that omits a channel to inherit it from the container sends
+		// `{ x: undefined }`, not `{}`. Spread as-is, that own `undefined` would clobber the
+		// container's value and the stat would silently fall back to identity.
+		const geomChannels = Object.fromEntries(
+			Object.entries(geom.channels ?? {}).filter(([, v]) => v !== undefined)
+		)
+		const channels = { ...this.#source.channels, ...geomChannels }
+		return applyGeomStat(rows, { stat, channels }, this.#source.helpers)
+	}
+}

package/dist/state/InteractionState.svelte.d.ts

@@ -0,0 +1,30 @@
+/**
+ * What the reader is doing to the chart: the hovered row, the selected rows, the zoom.
+ *
+ * The selection is a set of ROW objects, compared by identity — they must be the rows the
+ * geoms were handed (`PlotState.data`), which is why the plot keeps one proxy for its data.
+ */
+export class InteractionState {
+    /**
+     * @param {import('./PlotConfig.svelte.js').PlotConfig} config
+     * @param {unknown[]} [selected] - the initial selection; afterwards the caller drives it
+     *   through `setSelected` (PlotSurface syncs its bindable prop that way)
+     */
+    constructor(config: import("./PlotConfig.svelte.js").PlotConfig, selected?: unknown[]);
+    get hovered(): null;
+    setHovered(row: any): void;
+    clearHovered(): void;
+    /** Marks are clickable: the caller listens, or selection is on. */
+    get interactive(): boolean;
+    get selectedRows(): any[];
+    isSelected(row: any): boolean;
+    setSelected(rows: any): void;
+    clearSelected(): void;
+    /** An activation: always reported; toggles the row in the selection when selectable. */
+    handleSelect(detail: any): void;
+    /** The d3-zoom transform, or null at rest. Scales rescale through it. */
+    get zoom(): null;
+    applyZoom(transform: any): void;
+    resetZoom(): void;
+    #private;
+}

package/dist/state/InteractionState.svelte.js

@@ -0,0 +1,69 @@
+import { SvelteSet } from 'svelte/reactivity'
+
+/**
+ * What the reader is doing to the chart: the hovered row, the selected rows, the zoom.
+ *
+ * The selection is a set of ROW objects, compared by identity — they must be the rows the
+ * geoms were handed (`PlotState.data`), which is why the plot keeps one proxy for its data.
+ */
+export class InteractionState {
+	#config
+	#hovered = $state(null)
+	#selected = $state(new SvelteSet())
+	#zoom = $state(null)
+
+	/**
+	 * @param {import('./PlotConfig.svelte.js').PlotConfig} config
+	 * @param {unknown[]} [selected] - the initial selection; afterwards the caller drives it
+	 *   through `setSelected` (PlotSurface syncs its bindable prop that way)
+	 */
+	constructor(config, selected) {
+		this.#config = config
+		if (selected) this.#selected = new SvelteSet(selected)
+	}
+
+	get hovered() {
+		return this.#hovered
+	}
+	setHovered(row) {
+		this.#hovered = row
+	}
+	clearHovered() {
+		this.#hovered = null
+	}
+
+	/** Marks are clickable: the caller listens, or selection is on. */
+	get interactive() {
+		return Boolean(this.#config.onselect) || this.#config.selectable
+	}
+	get selectedRows() {
+		return [...this.#selected]
+	}
+	isSelected(row) {
+		return this.#selected.has(row)
+	}
+	setSelected(rows) {
+		this.#selected = new SvelteSet(rows ?? [])
+	}
+	clearSelected() {
+		this.#selected = new SvelteSet()
+	}
+	/** An activation: always reported; toggles the row in the selection when selectable. */
+	handleSelect(detail) {
+		this.#config.onselect?.(detail)
+		if (!this.#config.selectable || detail?.datum === undefined) return
+		if (this.#selected.has(detail.datum)) this.#selected.delete(detail.datum)
+		else this.#selected.add(detail.datum)
+	}
+
+	/** The d3-zoom transform, or null at rest. Scales rescale through it. */
+	get zoom() {
+		return this.#zoom
+	}
+	applyZoom(transform) {
+		this.#zoom = transform
+	}
+	resetZoom() {
+		this.#zoom = null
+	}
+}

package/dist/state/OrientationState.svelte.d.ts

@@ -0,0 +1,34 @@
+/** Geoms that band the x channel even when it is numeric (a year, a week, a race rank). */
+export const CATEGORICAL_X: readonly string[];
+/**
+ * Which way the chart reads, and how abstract (x-channel, y-channel) positions map to screen.
+ *
+ * Only a category-on-x chart flips: horizontal stands the band axis up the screen and lays the
+ * value axis along it, with the x/y channels unchanged. A plain scatter has no band, so
+ * `orientation` is a no-op for it.
+ */
+export class OrientationState {
+    /**
+     * @param {import('./PlotConfig.svelte.js').PlotConfig} config
+     * @param {import('./ChannelState.svelte.js').ChannelState} channels
+     * @param {import('./GeomRegistry.svelte.js').GeomRegistry} geoms
+     */
+    constructor(config: import("./PlotConfig.svelte.js").PlotConfig, channels: import("./ChannelState.svelte.js").ChannelState, geoms: import("./GeomRegistry.svelte.js").GeomRegistry);
+    /** A mounted geom bands the x channel. */
+    hasBandGeom: boolean;
+    /** The caller's override, else inferred: 'vertical' | 'horizontal' | 'none'. */
+    orientation: string;
+    /** The x channel is the categorical (band) axis. */
+    bandIsX: boolean;
+    /** Rendered horizontally: the band axis stands up the screen. */
+    flipped: boolean;
+    /**
+     * Abstract (x-channel, y-channel) scale outputs to screen coordinates. Geoms compute
+     * `u = xScale(d[x])`, `v = yScale(d[y])`, then place them.
+     */
+    place(u: any, v: any): {
+        x: any;
+        y: any;
+    };
+    #private;
+}

package/dist/state/OrientationState.svelte.js

@@ -0,0 +1,64 @@
+import { inferFieldType, inferOrientation } from '../lib/plot/scales.js'
+
+/** Geoms that band the x channel even when it is numeric (a year, a week, a race rank). */
+export const CATEGORICAL_X = Object.freeze(['bar', 'box', 'violin', 'jitter'])
+
+/**
+ * Which way the chart reads, and how abstract (x-channel, y-channel) positions map to screen.
+ *
+ * Only a category-on-x chart flips: horizontal stands the band axis up the screen and lays the
+ * value axis along it, with the x/y channels unchanged. A plain scatter has no band, so
+ * `orientation` is a no-op for it.
+ */
+export class OrientationState {
+	#config
+	#channels
+	#geoms
+
+	/**
+	 * @param {import('./PlotConfig.svelte.js').PlotConfig} config
+	 * @param {import('./ChannelState.svelte.js').ChannelState} channels
+	 * @param {import('./GeomRegistry.svelte.js').GeomRegistry} geoms
+	 */
+	constructor(config, channels, geoms) {
+		this.#config = config
+		this.#channels = channels
+		this.#geoms = geoms
+	}
+
+	/** A mounted geom bands the x channel. */
+	hasBandGeom = $derived(this.#geoms.list.some((g) => CATEGORICAL_X.includes(g.type)))
+
+	/**
+	 * Field types of the effective x and y, with x forced to `band` when a banding geom sits on
+	 * a continuous x/y pair. Null until both channels exist. Computed once for orientation and
+	 * `bandIsX` both — they used to infer the same types twice.
+	 */
+	#types = $derived.by(() => {
+		const { x, y } = this.#channels.effective
+		if (!x || !y) return null
+		const rawX = inferFieldType(this.#config.data, x)
+		const yType = inferFieldType(this.#config.data, y)
+		const xType =
+			this.hasBandGeom && rawX === 'continuous' && yType === 'continuous' ? 'band' : rawX
+		return { xType, yType }
+	})
+
+	/** The caller's override, else inferred: 'vertical' | 'horizontal' | 'none'. */
+	orientation = $derived(
+		this.#config.orientation ??
+			(this.#types ? inferOrientation(this.#types.xType, this.#types.yType) : 'none')
+	)
+	/** The x channel is the categorical (band) axis. */
+	bandIsX = $derived(this.#types?.xType === 'band')
+	/** Rendered horizontally: the band axis stands up the screen. */
+	flipped = $derived(this.orientation === 'horizontal' && this.bandIsX)
+
+	/**
+	 * Abstract (x-channel, y-channel) scale outputs to screen coordinates. Geoms compute
+	 * `u = xScale(d[x])`, `v = yScale(d[y])`, then place them.
+	 */
+	place(u, v) {
+		return this.flipped ? { x: v, y: u } : { x: u, y: v }
+	}
+}