@rokkit/chart 1.7.0 → 1.8.0

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

package/dist/state/ScaleState.svelte.js

@@ -0,0 +1,121 @@
+import { buildUnifiedXScale, buildUnifiedYScale } from '../lib/plot/scales.js'
+import { sortedBandDomain, resolveValueDomain } from '../lib/plot/domains.js'
+
+/**
+ * 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 {
+	#config
+	#geoms
+	#channels
+	#orientation
+	#frame
+	#interaction
+
+	/**
+	 * @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 }) {
+		this.#config = config
+		this.#geoms = geoms
+		this.#channels = channels
+		this.#orientation = orientation
+		this.#frame = frame
+		this.#interaction = interaction
+	}
+
+	/** Every geom's rows (post-stat) — or the raw data before any geom mounts. Shared by both axes. */
+	#datasets = $derived(
+		this.#geoms.list.length > 0
+			? this.#geoms.list.map((g) => this.#geoms.data(g.id))
+			: [this.#config.data]
+	)
+
+	/**
+	 * x is a band when a banding geom is mounted — except a CONTINUOUS category axis (a bar
+	 * race's tweened rank), which stays linear so fractional positions tween.
+	 */
+	#bandX = $derived(
+		this.#orientation.hasBandGeom &&
+			!this.#config.continuousCategory &&
+			(this.#orientation.orientation !== 'horizontal' || this.#orientation.flipped)
+	)
+
+	/** The caller's x domain, else — on a band axis — categories sorted by value when asked. */
+	#xDomain = $derived(
+		this.#config.xDomain ??
+			(this.#bandX
+				? sortedBandDomain(
+						this.#datasets,
+						this.#channels.effective.x,
+						this.#channels.effective.y,
+						this.#config.sort
+					)
+				: null) ??
+			undefined
+	)
+
+	/** The x (category, when banded) scale. Includes zero only when x is the VALUE axis. */
+	x = $derived.by(() => {
+		const field = this.#channels.effective.x
+		if (!field) return null
+		const { orientation, flipped } = this.#orientation
+		const base = buildUnifiedXScale(this.#datasets, field, this.#frame.innerWidth, {
+			domain: this.#xDomain,
+			includeZero: orientation === 'horizontal' && !flipped,
+			band: this.#bandX,
+			// Flipped: the category axis stands up the screen.
+			range: flipped ? [this.#frame.innerHeight, 0] : undefined,
+			// A continuous category axis is deliberately padded — do not nice() it to whole numbers.
+			nice: !this.#config.continuousCategory
+		})
+		// A band cannot be zoomed; a continuous axis rescales through the transform.
+		return typeof base?.bandwidth === 'function' ? base : this.#zoomed(base, 'rescaleX')
+	})
+
+	/** The y (value) scale — a zero baseline whenever it is the value axis. */
+	y = $derived.by(() => {
+		const field = this.#channels.effective.y
+		if (!field) return null
+		const { orientation, flipped } = this.#orientation
+		const geomDomain = resolveValueDomain(
+			this.#geoms.list,
+			(id) => this.#geoms.data(id),
+			this.#channels.effective,
+			field
+		)
+		const base = buildUnifiedYScale(this.#datasets, field, this.#frame.innerHeight, {
+			domain: this.#config.yDomain ?? geomDomain ?? undefined,
+			includeZero: orientation === 'vertical' || flipped,
+			// Flipped: the value axis runs along the screen.
+			range: flipped ? [0, this.#frame.innerWidth] : undefined
+		})
+		return this.#zoomed(base, 'rescaleY')
+	})
+
+	/** @param {any} base @param {'rescaleX' | 'rescaleY'} method */
+	#zoomed(base, method) {
+		const zoom = this.#interaction.zoom
+		return zoom ? zoom[method](base) : base
+	}
+
+	/** The categorical scale, whichever screen axis it is on. */
+	get band() {
+		return this.#orientation.bandIsX ? this.x : this.y
+	}
+	/** The continuous (value) scale, whichever screen axis it is on. */
+	get value() {
+		return this.#orientation.bandIsX ? this.y : this.x
+	}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rokkit/chart",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "type": "module",
   "description": "Data-driven chart components",
   "repository": {
@@ -48,6 +48,7 @@
     "@rokkit/states": "latest",
     "d3-array": "^3.2.4",
     "d3-axis": "^3.0.0",
+    "d3-contour": "^4.0.2",
     "d3-format": "^3.1.2",
     "d3-scale": "^4.0.2",
     "d3-scale-chromatic": "^3.1.0",
@@ -65,6 +66,7 @@
     "@sveltejs/vite-plugin-svelte": "^6.2.4",
     "@types/d3-array": "^3.2.2",
     "@types/d3-axis": "^3.0.6",
+    "@types/d3-contour": "^3.0.6",
     "@types/d3-format": "^3.0.4",
     "@types/d3-scale": "^4.0.9",
     "@types/d3-scale-chromatic": "^3.1.0",
@@ -73,7 +75,7 @@
     "@types/d3-transition": "^3.0.9",
     "@types/d3-zoom": "^3.0.8",
     "@types/ramda": "^0.31.1",
-    "svelte-check": "^4.7.6",
-    "svelte": "^5.55.7"
+    "svelte": "^5.55.7",
+    "svelte-check": "^4.7.6"
   }
 }