@rokkit/chart 1.6.0 → 1.8.0

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 }
+	}
+}

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

@@ -0,0 +1,179 @@
+/** The frame's margin when the caller sets none. */
+export const DEFAULT_MARGIN: Readonly<{
+    top: 20;
+    right: 20;
+    bottom: 40;
+    left: 50;
+}>;
+/**
+ * Every input a plot takes, and what `update()` does when a field is omitted.
+ *
+ * - `keep`: the previous value stays. These are the chart's data and settings; a partial
+ *   update (`{ width }` after a resize) must not wipe the rest.
+ * - `reset`: the default comes back. These are OVERRIDES — a fixed domain, a forced
+ *   orientation, a margin — and an override the caller stopped passing must stop applying.
+ *
+ * This table is the whole contract; `PlotState-update-contract.spec.js` pins it field by field.
+ *
+ * @type {ReadonlyArray<{ key: string, fallback: () => unknown, whenOmitted: 'keep' | 'reset' }>}
+ */
+export const CONFIG_FIELDS: ReadonlyArray<{
+    key: string;
+    fallback: () => unknown;
+    whenOmitted: "keep" | "reset";
+}>;
+/**
+ * @typedef {Record<string, unknown>} Row
+ * @typedef {{ top: number, right: number, bottom: number, left: number }} Margin
+ * @typedef {{ x?: string, y?: string, color?: string, fill?: string, pattern?: string, symbol?: string, size?: string }} Channels
+ * @typedef {Object} PlotConfigValues
+ * @property {Row[]} data
+ * @property {Channels} channels
+ * @property {Record<string, string>} labels
+ * @property {import('../lib/plot/types.js').PlotHelpers} helpers
+ * @property {string | undefined} preset
+ * @property {number | undefined} colorMidpoint
+ * @property {string | undefined} colorScale
+ * @property {string | undefined} colorScheme
+ * @property {unknown[] | undefined} colorDomain
+ * @property {unknown[] | undefined} xDomain
+ * @property {unknown[] | undefined} yDomain
+ * @property {number} width
+ * @property {number} height
+ * @property {'light' | 'dark'} mode
+ * @property {typeof defaultPreset} chartPreset
+ * @property {((detail: unknown) => void) | undefined} onselect
+ * @property {boolean} selectable
+ * @property {number} axisOffset
+ * @property {[number | undefined, number | undefined]} axisOrigin
+ * @property {Margin | undefined} margin
+ * @property {'horizontal' | 'vertical' | undefined} orientation
+ * @property {boolean} continuousCategory
+ * @property {'asc' | 'desc' | undefined} sort
+ */
+/**
+ * The plot's inputs — the one job `update()` has. Every other state class reads from here and
+ * writes nothing back.
+ *
+ * One `$state` object rather than a field per input: Svelte proxies it per property, so each
+ * reader still tracks only the fields it touches, and the table above can drive construction
+ * and update without a hand-written line per field. Values are proxied deeply exactly as the
+ * per-field `$state`s before were, which is what row identity (`data.indexOf(row)`) relies on.
+ */
+export class PlotConfig {
+    /** @param {Record<string, unknown>} [config] */
+    constructor(config?: Record<string, unknown>);
+    /** @param {Record<string, unknown>} [config] */
+    update(config?: Record<string, unknown>): void;
+    get data(): Row[];
+    get channels(): Channels;
+    get helpers(): import("../lib/plot/types.js").PlotHelpers;
+    get colorMidpoint(): number | undefined;
+    get colorScale(): string | undefined;
+    get colorScheme(): string | undefined;
+    get colorDomain(): unknown[] | undefined;
+    get xDomain(): unknown[] | undefined;
+    get yDomain(): unknown[] | undefined;
+    get width(): number;
+    get height(): number;
+    get mode(): "light" | "dark";
+    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;
+            hull: number;
+            contour: number;
+            radar: number;
+        };
+        patterns: string[];
+        symbols: string[];
+    };
+    get onselect(): ((detail: unknown) => void) | undefined;
+    get selectable(): boolean;
+    get axisOffset(): number;
+    /** Settable directly as well as through `update()` — callers (and specs) pin a crossing. */
+    set axisOrigin(value: [number | undefined, number | undefined]);
+    get axisOrigin(): [number | undefined, number | undefined];
+    get margin(): Margin | undefined;
+    get orientation(): "horizontal" | "vertical" | undefined;
+    get continuousCategory(): boolean;
+    get sort(): "asc" | "desc" | undefined;
+    /** @param {string} field */
+    label(field: string): string;
+    /** @param {string} field */
+    format(field: string): any;
+    tooltip(): any;
+    /** @param {string} type */
+    geomComponent(type: string): any;
+    resolvedPreset(): {
+        colors: any;
+        patterns: any;
+        symbols: any;
+    };
+    #private;
+}
+export type Row = Record<string, unknown>;
+export type Margin = {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+};
+export type Channels = {
+    x?: string;
+    y?: string;
+    color?: string;
+    fill?: string;
+    pattern?: string;
+    symbol?: string;
+    size?: string;
+};
+export type PlotConfigValues = {
+    data: Row[];
+    channels: Channels;
+    labels: Record<string, string>;
+    helpers: import("../lib/plot/types.js").PlotHelpers;
+    preset: string | undefined;
+    colorMidpoint: number | undefined;
+    colorScale: string | undefined;
+    colorScheme: string | undefined;
+    colorDomain: unknown[] | undefined;
+    xDomain: unknown[] | undefined;
+    yDomain: unknown[] | undefined;
+    width: number;
+    height: number;
+    mode: "light" | "dark";
+    chartPreset: typeof defaultPreset;
+    onselect: ((detail: unknown) => void) | undefined;
+    selectable: boolean;
+    axisOffset: number;
+    axisOrigin: [number | undefined, number | undefined];
+    margin: Margin | undefined;
+    orientation: "horizontal" | "vertical" | undefined;
+    continuousCategory: boolean;
+    sort: "asc" | "desc" | undefined;
+};
+import { defaultPreset } from '../lib/preset.js';

package/dist/state/PlotConfig.svelte.js

@@ -0,0 +1,195 @@
+import { defaultPreset } from '../lib/preset.js'
+import { resolvePreset } from '../lib/plot/preset.js'
+import { resolveFormat, resolveTooltip, resolveGeom } from '../lib/plot/helpers.js'
+
+/** The frame's margin when the caller sets none. */
+export const DEFAULT_MARGIN = Object.freeze({ top: 20, right: 20, bottom: 40, left: 50 })
+
+/**
+ * Every input a plot takes, and what `update()` does when a field is omitted.
+ *
+ * - `keep`: the previous value stays. These are the chart's data and settings; a partial
+ *   update (`{ width }` after a resize) must not wipe the rest.
+ * - `reset`: the default comes back. These are OVERRIDES — a fixed domain, a forced
+ *   orientation, a margin — and an override the caller stopped passing must stop applying.
+ *
+ * This table is the whole contract; `PlotState-update-contract.spec.js` pins it field by field.
+ *
+ * @type {ReadonlyArray<{ key: string, fallback: () => unknown, whenOmitted: 'keep' | 'reset' }>}
+ */
+export const CONFIG_FIELDS = Object.freeze([
+	{ key: 'data', fallback: () => [], whenOmitted: 'keep' },
+	{ key: 'channels', fallback: () => ({}), whenOmitted: 'keep' },
+	{ key: 'labels', fallback: () => ({}), whenOmitted: 'keep' },
+	{ key: 'helpers', fallback: () => ({}), whenOmitted: 'keep' },
+	{ key: 'preset', fallback: () => undefined, whenOmitted: 'keep' },
+	{ key: 'colorMidpoint', fallback: () => undefined, whenOmitted: 'keep' },
+	{ key: 'colorScale', fallback: () => undefined, whenOmitted: 'keep' },
+	{ key: 'colorScheme', fallback: () => undefined, whenOmitted: 'keep' },
+	{ key: 'colorDomain', fallback: () => undefined, whenOmitted: 'reset' },
+	{ key: 'xDomain', fallback: () => undefined, whenOmitted: 'reset' },
+	{ key: 'yDomain', fallback: () => undefined, whenOmitted: 'reset' },
+	{ key: 'width', fallback: () => 600, whenOmitted: 'keep' },
+	{ key: 'height', fallback: () => 400, whenOmitted: 'keep' },
+	{ key: 'mode', fallback: () => 'light', whenOmitted: 'keep' },
+	{ key: 'chartPreset', fallback: () => defaultPreset, whenOmitted: 'keep' },
+	{ key: 'onselect', fallback: () => undefined, whenOmitted: 'keep' },
+	{ key: 'selectable', fallback: () => false, whenOmitted: 'keep' },
+	{ key: 'axisOffset', fallback: () => 0, whenOmitted: 'keep' },
+	{ key: 'axisOrigin', fallback: () => [undefined, undefined], whenOmitted: 'reset' },
+	{ key: 'margin', fallback: () => undefined, whenOmitted: 'reset' },
+	{ key: 'orientation', fallback: () => undefined, whenOmitted: 'reset' },
+	{ key: 'continuousCategory', fallback: () => false, whenOmitted: 'reset' },
+	{ key: 'sort', fallback: () => undefined, whenOmitted: 'reset' }
+])
+
+/**
+ * @typedef {Record<string, unknown>} Row
+ * @typedef {{ top: number, right: number, bottom: number, left: number }} Margin
+ * @typedef {{ x?: string, y?: string, color?: string, fill?: string, pattern?: string, symbol?: string, size?: string }} Channels
+ * @typedef {Object} PlotConfigValues
+ * @property {Row[]} data
+ * @property {Channels} channels
+ * @property {Record<string, string>} labels
+ * @property {import('../lib/plot/types.js').PlotHelpers} helpers
+ * @property {string | undefined} preset
+ * @property {number | undefined} colorMidpoint
+ * @property {string | undefined} colorScale
+ * @property {string | undefined} colorScheme
+ * @property {unknown[] | undefined} colorDomain
+ * @property {unknown[] | undefined} xDomain
+ * @property {unknown[] | undefined} yDomain
+ * @property {number} width
+ * @property {number} height
+ * @property {'light' | 'dark'} mode
+ * @property {typeof defaultPreset} chartPreset
+ * @property {((detail: unknown) => void) | undefined} onselect
+ * @property {boolean} selectable
+ * @property {number} axisOffset
+ * @property {[number | undefined, number | undefined]} axisOrigin
+ * @property {Margin | undefined} margin
+ * @property {'horizontal' | 'vertical' | undefined} orientation
+ * @property {boolean} continuousCategory
+ * @property {'asc' | 'desc' | undefined} sort
+ */
+
+/**
+ * The plot's inputs — the one job `update()` has. Every other state class reads from here and
+ * writes nothing back.
+ *
+ * One `$state` object rather than a field per input: Svelte proxies it per property, so each
+ * reader still tracks only the fields it touches, and the table above can drive construction
+ * and update without a hand-written line per field. Values are proxied deeply exactly as the
+ * per-field `$state`s before were, which is what row identity (`data.indexOf(row)`) relies on.
+ */
+export class PlotConfig {
+	/** @type {PlotConfigValues} */
+	#v = $state(
+		/** @type {PlotConfigValues} */ (
+			Object.fromEntries(CONFIG_FIELDS.map((f) => [f.key, f.fallback()]))
+		)
+	)
+
+	/** @param {Record<string, unknown>} [config] */
+	constructor(config = {}) {
+		const v = /** @type {Record<string, unknown>} */ (this.#v)
+		for (const f of CONFIG_FIELDS) v[f.key] = config[f.key] ?? f.fallback()
+	}
+
+	/** @param {Record<string, unknown>} [config] */
+	update(config = {}) {
+		const v = /** @type {Record<string, unknown>} */ (this.#v)
+		for (const f of CONFIG_FIELDS) {
+			if (config[f.key] !== undefined) v[f.key] = config[f.key]
+			else if (f.whenOmitted === 'reset') v[f.key] = f.fallback()
+		}
+	}
+
+	get data() {
+		return this.#v.data
+	}
+	get channels() {
+		return this.#v.channels
+	}
+	get helpers() {
+		return this.#v.helpers
+	}
+	get colorMidpoint() {
+		return this.#v.colorMidpoint
+	}
+	get colorScale() {
+		return this.#v.colorScale
+	}
+	get colorScheme() {
+		return this.#v.colorScheme
+	}
+	get colorDomain() {
+		return this.#v.colorDomain
+	}
+	get xDomain() {
+		return this.#v.xDomain
+	}
+	get yDomain() {
+		return this.#v.yDomain
+	}
+	get width() {
+		return this.#v.width
+	}
+	get height() {
+		return this.#v.height
+	}
+	get mode() {
+		return this.#v.mode
+	}
+	get chartPreset() {
+		return this.#v.chartPreset
+	}
+	get onselect() {
+		return this.#v.onselect
+	}
+	get selectable() {
+		return this.#v.selectable
+	}
+	get axisOffset() {
+		return this.#v.axisOffset
+	}
+	get axisOrigin() {
+		return this.#v.axisOrigin
+	}
+	/** Settable directly as well as through `update()` — callers (and specs) pin a crossing. */
+	set axisOrigin(value) {
+		this.#v.axisOrigin = value
+	}
+	get margin() {
+		return this.#v.margin
+	}
+	get orientation() {
+		return this.#v.orientation
+	}
+	get continuousCategory() {
+		return this.#v.continuousCategory
+	}
+	get sort() {
+		return this.#v.sort
+	}
+
+	// ─── Helper resolution — these read nothing but the inputs ─────────────────
+	/** @param {string} field */
+	label(field) {
+		return this.#v.labels?.[field] ?? field
+	}
+	/** @param {string} field */
+	format(field) {
+		return resolveFormat(field, this.#v.helpers)
+	}
+	tooltip() {
+		return resolveTooltip(this.#v.helpers)
+	}
+	/** @param {string} type */
+	geomComponent(type) {
+		return resolveGeom(type, this.#v.helpers)
+	}
+	resolvedPreset() {
+		return resolvePreset(this.#v.preset, this.#v.helpers)
+	}
+}

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

@@ -0,0 +1,17 @@
+/**
+ * The drawing area: the plot's size less its margin. Every scale's range comes from here.
+ */
+export class PlotFrame {
+    /** @param {import('./PlotConfig.svelte.js').PlotConfig} config */
+    constructor(config: import("./PlotConfig.svelte.js").PlotConfig);
+    /** The caller's margin override, else the default. */
+    margin: Readonly<{
+        top: 20;
+        right: 20;
+        bottom: 40;
+        left: 50;
+    }> | import("./PlotConfig.svelte.js").Margin;
+    innerWidth: number;
+    innerHeight: number;
+    #private;
+}

package/dist/state/PlotFrame.svelte.js

@@ -0,0 +1,18 @@
+import { DEFAULT_MARGIN } from './PlotConfig.svelte.js'
+
+/**
+ * The drawing area: the plot's size less its margin. Every scale's range comes from here.
+ */
+export class PlotFrame {
+	#config
+
+	/** @param {import('./PlotConfig.svelte.js').PlotConfig} config */
+	constructor(config) {
+		this.#config = config
+	}
+
+	/** The caller's margin override, else the default. */
+	margin = $derived(this.#config.margin ?? DEFAULT_MARGIN)
+	innerWidth = $derived(this.#config.width - this.margin.left - this.margin.right)
+	innerHeight = $derived(this.#config.height - this.margin.top - this.margin.bottom)
+}

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

@@ -0,0 +1,36 @@
+/**
+ * The x and y position scales.
+ *
+ * Domains come, in order, from: the caller's override; for the value axis, the geometry of the
+ * mounted geoms (`resolveValueDomain` — box whiskers, stacked totals, running totals); then the
+ * extent of every geom's rows. Ranges come from the frame, oriented by the flip.
+ */
+export class ScaleState {
+    /**
+     * @param {{
+     *   config: import('./PlotConfig.svelte.js').PlotConfig,
+     *   geoms: import('./GeomRegistry.svelte.js').GeomRegistry,
+     *   channels: import('./ChannelState.svelte.js').ChannelState,
+     *   orientation: import('./OrientationState.svelte.js').OrientationState,
+     *   frame: import('./PlotFrame.svelte.js').PlotFrame,
+     *   interaction: import('./InteractionState.svelte.js').InteractionState
+     * }} parts
+     */
+    constructor({ config, geoms, channels, orientation, frame, interaction }: {
+        config: import("./PlotConfig.svelte.js").PlotConfig;
+        geoms: import("./GeomRegistry.svelte.js").GeomRegistry;
+        channels: import("./ChannelState.svelte.js").ChannelState;
+        orientation: import("./OrientationState.svelte.js").OrientationState;
+        frame: import("./PlotFrame.svelte.js").PlotFrame;
+        interaction: import("./InteractionState.svelte.js").InteractionState;
+    });
+    /** The x (category, when banded) scale. Includes zero only when x is the VALUE axis. */
+    x: any;
+    /** The y (value) scale — a zero baseline whenever it is the value axis. */
+    y: any;
+    /** The categorical scale, whichever screen axis it is on. */
+    get band(): any;
+    /** The continuous (value) scale, whichever screen axis it is on. */
+    get value(): any;
+    #private;
+}