@rokkit/chart 1.0.0-next.16 → 1.0.0-next.161

package/src/lib/grid.js

@@ -0,0 +1,85 @@
+/**
+ * @typedef GridPoint
+ * @property {number} x - x-coordinate of the point
+ * @property {number} y - y-coordinate of the point
+ * @property {number} r - radius of the point
+ */
+
+/**
+ * @typedef SwatchGrid
+ * @property {number}      width  - width of the grid
+ * @property {number}      height - height of the grid
+ * @property {GridPoint[]} data   - data points of the grid
+ */
+
+/**
+ * @tyoedef {Object} GridOptions
+ * @property {number} [pad=0]     - The padding between the items
+ * @property {number} [columns=0] - The number of columns
+ * @property {number} [rows=0]    - The number of rows
+ */
+
+/**
+ * Calculates a grid of centres to fit a list of items of `size` within the number of `columns` and `rows`.
+ *
+ * - Attempts to find a best fit square if both columns and rows are not specified
+ * - Value in columns is prioritized over rows for recalculating the grid
+ * - Supports padding between the items
+ *
+ * @param {number}      count   - number of items
+ * @param {number}      size    - size of the items
+ * @param {GridOptions} options - options for the grid
+ * @returns {SwatchGrid}
+ */
+export function swatchGrid(count, size, options) {
+	const { pad = 0 } = options || {}
+	let { columns = 0, rows = 0 } = options || {}
+	if (columns > 0) {
+		rows = Math.ceil(count / columns)
+	} else if (rows > 0) {
+		columns = Math.ceil(count / rows)
+	} else {
+		columns = Math.ceil(Math.sqrt(count))
+		rows = Math.ceil(count / columns)
+	}
+
+	const width = (size + pad) * columns + pad
+	const height = (size + pad) * rows + pad
+	const radius = size / 2
+	const data = [...Array(count).keys()].map((index) => ({
+		x: pad + radius + (index % columns) * (size + pad),
+		y: pad + radius + Math.floor(index / columns) * (size + pad),
+		r: radius
+	}))
+
+	return { width, height, data }
+}
+
+/**
+ * Spreads values as patterns with colors from a palette
+ *
+ * @param {number[]} values   - values to spread
+ * @param {string[]} patterns - patterns to spread
+ * @param {string[]} palette  - colors to spread
+ * @returns {Record<number, { id: string, pattern: string, color: string }>}
+ */
+export function spreadValuesAsPatterns(values, patterns, palette) {
+	const result = values
+		.map((value, index) => ({
+			pattern: patterns[index % patterns.length],
+			color: palette[index % palette.length],
+			value
+		}))
+		.reduce(
+			(acc, { value, pattern, color }) => ({
+				...acc,
+				[value]: {
+					id: `${pattern}_${color}`,
+					pattern,
+					color
+				}
+			}),
+			{}
+		)
+	return result
+}

package/src/lib/keyboard-nav.js

@@ -0,0 +1,37 @@
+/**
+ * Svelte action: arrow key navigation between sibling data elements within a geom.
+ *
+ * When applied to a focusable SVG element with `enabled=true`, ArrowLeft/ArrowRight
+ * move focus between elements sharing the same `[data-plot-geom]` container.
+ *
+ * Usage: `<circle use:keyboardNav={keyboard} ...>`
+ *
+ * @param {Element} node
+ * @param {boolean} enabled
+ */
+export function keyboardNav(node, enabled) {
+	function handleKeydown(e) {
+		if (!enabled) return
+		if (e.key !== 'ArrowLeft' && e.key !== 'ArrowRight') return
+		const container = node.closest('[data-plot-geom]')
+		if (!container) return
+		const elements = [...container.querySelectorAll('[data-plot-element]')].filter(
+			(el) => /** @type {HTMLElement|SVGElement} */ (el).tabIndex >= 0
+		)
+		const idx = elements.indexOf(node)
+		if (idx === -1) return
+		const nextIdx =
+			e.key === 'ArrowRight' ? Math.min(idx + 1, elements.length - 1) : Math.max(idx - 1, 0)
+		if (nextIdx !== idx) {
+			e.preventDefault()
+			/** @type {HTMLElement|SVGElement} */ (elements[nextIdx]).focus()
+		}
+	}
+	node.addEventListener('keydown', handleKeydown)
+	return {
+		update(newEnabled) {
+			enabled = newEnabled
+		},
+		destroy: () => node.removeEventListener('keydown', handleKeydown)
+	}
+}

package/src/lib/plot/chartProps.js

@@ -0,0 +1,76 @@
+/**
+ * Shared JSDoc type definitions for chart component props.
+ * Import these in chart components with:
+ *   @type {import('./lib/plot/chartProps.js').ChartProps}
+ */
+
+/**
+ * @typedef {Object} ChartProps
+ * Common props shared by all high-level chart wrappers.
+ *
+ * @property {Object[]} [data=[]]        - Data array to visualize
+ * @property {string}   [x]              - Field name for the X axis
+ * @property {string}   [y]              - Field name for the Y axis
+ * @property {string}   [fill]           - Field name for fill color grouping (alias for color)
+ * @property {string}   [color]          - Field name for color grouping
+ * @property {string}   [pattern]        - Field name for pattern fill grouping
+ * @property {string}   [stat='identity']- Aggregation stat: 'identity' | 'sum' | 'mean' | 'count' | 'min' | 'max' | 'median' | 'boxplot'
+ * @property {number}   [width=600]      - SVG width in pixels
+ * @property {number}   [height=400]     - SVG height in pixels
+ * @property {string}   [mode='light']   - Color mode: 'light' | 'dark'
+ * @property {boolean}  [grid=true]      - Whether to show grid lines
+ * @property {boolean}  [legend=false]   - Whether to show the legend
+ */
+
+/**
+ * @typedef {Object} BarChartProps
+ * @extends ChartProps
+ * @property {boolean} [stack=false]     - Stack bars (true) or group them (false)
+ */
+
+/**
+ * @typedef {Object} PieChartProps
+ * @property {Object[]} [data=[]]        - Data array to visualize
+ * @property {string}   [label]          - Field name for slice labels (drives color key)
+ * @property {string}   [y]              - Field name for slice values (theta)
+ * @property {string}   [fill]           - Alternative to label for color grouping
+ * @property {number}   [innerRadius=0]  - Inner radius as fraction of outer (0=pie, 0.5=donut)
+ * @property {string}   [stat='sum']     - Aggregation stat (default sum for pie charts)
+ * @property {number}   [width=400]      - SVG width in pixels
+ * @property {number}   [height=400]     - SVG height in pixels
+ * @property {string}   [mode='light']   - Color mode: 'light' | 'dark'
+ * @property {boolean}  [legend=false]   - Whether to show the legend
+ */
+
+/**
+ * @typedef {Object} BoxViolinChartProps
+ * @property {Object[]} [data=[]]        - Data array to visualize
+ * @property {string}   [x]              - Field name for the category axis (groups)
+ * @property {string}   [y]              - Field name for the value axis (raw observations)
+ * @property {string}   [fill]           - Field name for fill color; when different from x, sub-groups within each x-band (like grouped bars); lighter shade used for body, darker shade for whiskers/outline
+ * @property {number}   [width=600]      - SVG width in pixels
+ * @property {number}   [height=400]     - SVG height in pixels
+ * @property {string}   [mode='light']   - Color mode: 'light' | 'dark'
+ * @property {boolean}  [grid=true]      - Whether to show grid lines
+ * @property {boolean}  [legend=false]   - Whether to show the legend
+ */
+
+/**
+ * @typedef {Object} ScatterBubbleChartProps
+ * @property {Object[]} [data=[]]        - Data array to visualize
+ * @property {string}   [x]              - Field name for X position
+ * @property {string}   [y]              - Field name for Y position
+ * @property {string}   [color]          - Field name for color grouping
+ * @property {string}   [size]           - Field name for point radius (BubbleChart: required)
+ * @property {number}   [width=600]      - SVG width in pixels
+ * @property {number}   [height=400]     - SVG height in pixels
+ * @property {string}   [mode='light']   - Color mode: 'light' | 'dark'
+ * @property {boolean}  [grid=true]      - Whether to show grid lines
+ * @property {boolean}  [legend=false]   - Whether to show the legend
+ */
+
+/**
+ * @typedef {Object} LineAreaChartProps
+ * @extends ChartProps
+ * @property {string}   [curve]          - Line interpolation: 'linear' | 'smooth' | 'step'
+ */

package/src/lib/plot/crossfilter.js

@@ -0,0 +1,16 @@
+/**
+ * Applies dimming state to data rows using crossfilter instance.
+ * Maps each row to { data: row, dimmed: boolean }.
+ *
+ * @param {Object[]} data - raw data array
+ * @param {Object} cf - crossfilter instance (from createCrossFilter)
+ * @param {Object} channels - { x, y, color, ... } field name mapping
+ * @returns {{ data: Object, dimmed: boolean }[]}
+ */
+export function applyDimming(data, cf, channels) {
+	const fields = Object.values(channels).filter(Boolean)
+	return data.map((row) => {
+		const dimmed = fields.some((field) => cf.isDimmed(field, row[field]))
+		return { data: row, dimmed }
+	})
+}

package/src/lib/plot/facet.js

@@ -0,0 +1,58 @@
+import { extent } from 'd3-array'
+
+/**
+ * Splits data into a Map of panels keyed by facet field value.
+ * Preserves insertion order of first occurrence.
+ *
+ * @param {Object[]} data
+ * @param {string} field
+ * @returns {Map<unknown, Object[]>}
+ */
+export function splitByField(data, field) {
+	const map = new Map()
+	for (const row of data) {
+		const key = row[field]
+		if (!map.has(key)) map.set(key, [])
+		map.get(key).push(row)
+	}
+	return map
+}
+
+/**
+ * Computes x/y domains for each panel.
+ *
+ * @param {Map<unknown, Object[]>} panels
+ * @param {{ x: string, y: string }} channels
+ * @param {'fixed'|'free'|'free_x'|'free_y'} scalesMode
+ * @returns {Map<unknown, { xDomain: unknown[], yDomain: [number, number] }>}
+ */
+export function getFacetDomains(panels, channels, scalesMode = 'fixed') {
+	const { x: xf, y: yf } = channels
+	const allData = [...panels.values()].flat()
+
+	// Determine if x is categorical (string) or numeric
+	const sampleXVal = allData.find((d) => d[xf] !== null && d[xf] !== undefined)?.[xf]
+	const xIsCategorical = typeof sampleXVal === 'string'
+
+	// Global domains (for fixed mode)
+	const globalXDomain = xIsCategorical
+		? [...new Set(allData.map((d) => d[xf]))]
+		: extent(allData, (d) => Number(d[xf]))
+	const globalYDomain = extent(allData, (d) => Number(d[yf]))
+
+	const result = new Map()
+	for (const [key, rows] of panels.entries()) {
+		const freeX = scalesMode === 'free' || scalesMode === 'free_x'
+		const freeY = scalesMode === 'free' || scalesMode === 'free_y'
+
+		const xDomain = freeX
+			? xIsCategorical
+				? [...new Set(rows.map((d) => d[xf]))]
+				: extent(rows, (d) => Number(d[xf]))
+			: globalXDomain
+		const yDomain = freeY ? extent(rows, (d) => Number(d[yf])) : globalYDomain
+
+		result.set(key, { xDomain, yDomain })
+	}
+	return result
+}

package/src/lib/plot/frames.js

@@ -0,0 +1,81 @@
+import { extent } from 'd3-array'
+import { dataset } from '@rokkit/data'
+
+/**
+ * Extracts animation frames from data, keyed by time field value.
+ * Preserves insertion order of time values.
+ *
+ * @param {Object[]} data
+ * @param {string} timeField
+ * @returns {Map<unknown, Object[]>}
+ */
+export function extractFrames(data, timeField) {
+	const map = new Map()
+	for (const row of data) {
+		const key = row[timeField]
+		if (!map.has(key)) map.set(key, [])
+		map.get(key).push(row)
+	}
+	return map
+}
+
+/**
+ * Ensures all frame values (byField) appear for every (x, color?) combination.
+ * Uses dataset alignBy to fill missing frame-value combos with y=0 so bars
+ * animate smoothly rather than disappearing between frames.
+ *
+ * Call after pre-aggregation. The result can be split directly by extractFrames
+ * with no further per-frame normalization needed.
+ *
+ * @param {Object[]} data - pre-aggregated rows, one per (x, color?, byField)
+ * @param {{ x?: string, y: string, color?: string }} channels
+ * @param {string} byField - the frame field (e.g. 'year')
+ * @returns {Object[]}
+ */
+export function completeFrames(data, channels, byField) {
+	const { x: xf, y: yf, color: cf } = channels
+	const groupFields = [xf, ...(cf ? [cf] : [])].filter(Boolean)
+
+	if (groupFields.length === 0) return data
+
+	const nested = dataset(data)
+		.groupBy(...groupFields)
+		.alignBy(byField)
+		.usingTemplate({ [yf]: 0 })
+		.rollup()
+		.select()
+
+	return nested.flatMap((row) => {
+		const groupKey = groupFields.reduce((acc, f) => ({ ...acc, [f]: row[f] }), {})
+		// strip the actual_flag marker added by alignBy
+		return row.children.map(({ actual_flag: _af, ...child }) => ({ ...groupKey, ...child }))
+	})
+}
+
+/**
+ * Computes static x/y domains from the full (pre-split) data array.
+ * These domains stay constant throughout the animation so values are
+ * always comparable across frames.
+ *
+ * NOTE: y domain is pinned to [0, max] — assumes bar chart semantics.
+ * Pass an explicit yDomain override for scatter/line charts where y can
+ * be negative.
+ *
+ * @param {Object[]} data - full dataset (before frame extraction)
+ * @param {{ x: string, y: string }} channels
+ * @returns {{ xDomain: unknown[], yDomain: [number, number] }}
+ */
+export function computeStaticDomains(data, channels) {
+	const { x: xf, y: yf } = channels
+
+	const sampleX = data[0]?.[xf]
+	const xDomain =
+		typeof sampleX === 'string'
+			? [...new Set(data.map((d) => d[xf]))]
+			: extent(data, (d) => Number(d[xf]))
+
+	const [, yMax] = extent(data, (d) => Number(d[yf]))
+	const yDomain = [0, yMax ?? 0]
+
+	return { xDomain, yDomain }
+}

package/src/lib/plot/helpers.js

@@ -0,0 +1,14 @@
+const BUILT_IN_GEOMS = new Set(['bar', 'line', 'area', 'point', 'box', 'violin', 'arc'])
+
+export function resolveFormat(field, helpers = {}) {
+	return helpers?.format?.[field] ?? ((v) => String(v))
+}
+
+export function resolveTooltip(helpers = {}) {
+	return helpers?.tooltip ?? null
+}
+
+export function resolveGeom(type, helpers = {}) {
+	if (BUILT_IN_GEOMS.has(type)) return null
+	return helpers?.geoms?.[type] ?? null
+}

package/src/lib/plot/preset.js

@@ -0,0 +1,67 @@
+import masterPalette from '../palette.json'
+import { defaultPreset } from '../preset.js'
+import { PATTERN_ORDER } from '../brewing/patterns.js'
+import { SYMBOL_ORDER } from '../brewing/symbols.js'
+
+/** @typedef {{ colors: string[], patterns: string[], symbols: string[] }} PlotPreset */
+
+export const DEFAULT_PRESET = {
+	colors: defaultPreset.colors.map((name) => {
+		const group = masterPalette[name]
+		return group?.[defaultPreset.shades.light.fill] ?? '#888'
+	}),
+	patterns: PATTERN_ORDER,
+	symbols: SYMBOL_ORDER
+}
+
+export const ACCESSIBLE_PRESET = {
+	colors: ['#66c2a5', '#fc8d62', '#8da0cb', '#e78ac3', '#a6d854', '#ffd92f', '#e5c494', '#b3b3b3'],
+	patterns: PATTERN_ORDER,
+	symbols: SYMBOL_ORDER
+}
+
+export const PRINT_PRESET = {
+	colors: ['#f0f0f0', '#bdbdbd', '#969696', '#737373', '#525252', '#252525', '#000000'],
+	patterns: [
+		'CrossHatch',
+		'DiagonalLines',
+		'Dots',
+		'Brick',
+		'Waves',
+		'Triangles',
+		'HorizontalLines'
+	],
+	symbols: SYMBOL_ORDER
+}
+
+const BUILT_IN_PRESETS = {
+	default: DEFAULT_PRESET,
+	accessible: ACCESSIBLE_PRESET,
+	print: PRINT_PRESET
+}
+
+export function resolvePreset(name, helpers = {}) {
+	let resolved = null
+
+	if (name && BUILT_IN_PRESETS[name]) {
+		resolved = BUILT_IN_PRESETS[name]
+	} else if (name && helpers?.presets?.[name]) {
+		resolved = helpers.presets[name]
+	} else if (name) {
+		// eslint-disable-next-line no-console
+		console.warn(
+			`[Plot] Unknown preset "${name}" — falling back to default. Add it to helpers.presets to suppress this warning.`
+		)
+		resolved = DEFAULT_PRESET
+	} else if (helpers?.preset) {
+		resolved = helpers.preset
+	} else {
+		resolved = DEFAULT_PRESET
+	}
+
+	return {
+		colors: resolved.colors ?? DEFAULT_PRESET.colors,
+		patterns: resolved.patterns ?? DEFAULT_PRESET.patterns,
+		symbols: resolved.symbols ?? DEFAULT_PRESET.symbols
+	}
+}

package/src/lib/plot/scales.js

@@ -0,0 +1,81 @@
+import { scaleBand, scaleLinear } from 'd3-scale'
+import { extent } from 'd3-array'
+
+export function inferFieldType(data, field) {
+	const values = data.map((d) => d[field]).filter((v) => v !== null && v !== undefined)
+	if (values.length === 0) return 'band'
+	const isNumeric = values.every(
+		(v) => typeof v === 'number' || (!isNaN(Number(v)) && String(v).trim() !== '')
+	)
+	return isNumeric ? 'continuous' : 'band'
+}
+
+export function inferOrientation(xType, yType) {
+	if (xType === 'band' && yType === 'continuous') return 'vertical'
+	if (yType === 'band' && xType === 'continuous') return 'horizontal'
+	return 'none'
+}
+
+export function buildUnifiedXScale(datasets, field, width, opts = {}) {
+	const allValues = datasets.flatMap((d) => d.map((r) => r[field]))
+	const isNumeric = allValues.every(
+		(v) => typeof v === 'number' || (!isNaN(Number(v)) && String(v).trim() !== '')
+	)
+
+	// opts.band forces scaleBand even for numeric data (e.g. bar charts with year on X).
+	if (opts.domain) {
+		const domainIsNumeric = opts.domain.every((v) => typeof v === 'number')
+		if (!opts.band && (domainIsNumeric || isNumeric)) {
+			return scaleLinear().domain(opts.domain).range([0, width]).nice()
+		}
+		return scaleBand()
+			.domain(opts.domain)
+			.range([0, width])
+			.padding(opts.padding ?? 0.2)
+	}
+
+	if (isNumeric && !opts.band) {
+		const numericValues = allValues.map(Number)
+		const [minVal, maxVal] = extent(numericValues)
+		const domainMin = (opts.includeZero ?? false) ? 0 : (minVal ?? 0)
+		return scaleLinear()
+			.domain([domainMin, maxVal ?? 0])
+			.range([0, width])
+			.nice()
+	}
+
+	const domain = [...new Set(allValues)].filter((v) => v !== null && v !== undefined)
+	return scaleBand()
+		.domain(domain)
+		.range([0, width])
+		.padding(opts.padding ?? 0.2)
+}
+
+export function buildUnifiedYScale(datasets, field, height, opts = {}) {
+	if (opts.domain) {
+		return scaleLinear().domain(opts.domain).range([height, 0]).nice()
+	}
+	const rawValues = datasets.flatMap((d) => d.map((r) => r[field])).filter((v) => v !== null && v !== undefined)
+	const isNumeric = rawValues.length > 0 && rawValues.every(
+		(v) => typeof v === 'number' || (!isNaN(Number(v)) && String(v).trim() !== '')
+	)
+	if (!isNumeric) {
+		// Categorical y-axis (e.g. horizontal bar chart) — use scaleBand
+		const domain = [...new Set(rawValues.map(String))]
+		return scaleBand().domain(domain).range([height, 0]).padding(0.2)
+	}
+	const numericValues = rawValues.map(Number)
+	const [minVal, maxVal] = extent(numericValues)
+	const domainMin = (opts.includeZero ?? true) ? 0 : (minVal ?? 0)
+	return scaleLinear()
+		.domain([domainMin, maxVal ?? 0])
+		.range([height, 0])
+		.nice()
+}
+
+export function inferColorScaleType(data, field, spec = {}) {
+	if (spec.colorScale) return spec.colorScale
+	if (spec.colorMidpoint !== undefined) return 'diverging'
+	const type = inferFieldType(data, field)
+	return type === 'continuous' ? 'sequential' : 'categorical'
+}

package/src/lib/plot/stat.js

@@ -0,0 +1,92 @@
+import { sum, mean, min, max, median } from 'd3-array'
+import { applyAggregate, applyBoxStat } from '../brewing/stats.js'
+
+const BUILT_IN_STATS = {
+	sum,
+	mean,
+	min,
+	max,
+	count: (values) => values.length,
+	median
+}
+
+/**
+ * Resolves a stat name to an aggregation function.
+ * Checks built-ins first, then helpers.stats, then warns and falls back to identity.
+ *
+ * @param {string} name
+ * @param {Object} helpers
+ * @returns {Function}
+ */
+export function resolveStat(name, helpers = {}) {
+	if (name === 'identity') return (data) => data
+	if (BUILT_IN_STATS[name]) return BUILT_IN_STATS[name]
+	if (helpers?.stats?.[name]) return helpers.stats[name]
+	// eslint-disable-next-line no-console
+	console.warn(
+		`[Plot] Unknown stat "${name}" — falling back to identity. Add it to helpers.stats to suppress this warning.`
+	)
+	return (data) => data
+}
+
+/**
+ * Infers group-by fields from channels by excluding value fields.
+ * valueFields may contain channel keys (e.g. ['y', 'size']) OR field values (e.g. ['cty']).
+ * A channel's field is excluded if either the channel key OR the field value is in valueFields.
+ *
+ * @param {Record<string, string|undefined>} channels
+ * @param {string[]} valueFields
+ * @returns {string[]}
+ */
+export function inferGroupByFields(channels, valueFields) {
+	const seen = new Set()
+	const result = []
+	for (const [key, field] of Object.entries(channels)) {
+		if (!field) continue
+		if (valueFields.includes(key) || valueFields.includes(field)) continue
+		if (seen.has(field)) continue
+		seen.add(field)
+		result.push(field)
+	}
+	return result
+}
+
+/**
+ * Applies a stat aggregation to data based on a geom config.
+ * Returns data unchanged for identity stat.
+ *
+ * @param {Object[]} data
+ * @param {{ stat?: string, channels?: Record<string, string> }} geomConfig
+ * @param {Object} helpers
+ * @returns {Object[]}
+ */
+export function applyGeomStat(data, geomConfig, helpers = {}) {
+	const { stat = 'identity', channels = {} } = geomConfig
+	if (stat === 'identity') return data
+	if (stat === 'boxplot') return applyBoxStat(data, channels)
+
+	const statFn = resolveStat(stat, helpers)
+
+	const VALUE_CHANNEL_KEYS = ['y', 'size', 'theta']
+	const groupByFields = inferGroupByFields(channels, VALUE_CHANNEL_KEYS)
+	const primaryKey = VALUE_CHANNEL_KEYS.find((k) => channels[k])
+	if (!primaryKey) return data
+
+	let result = applyAggregate(data, {
+		by: groupByFields,
+		value: channels[primaryKey],
+		stat: statFn
+	})
+
+	for (const key of VALUE_CHANNEL_KEYS.filter((k) => k !== primaryKey && channels[k])) {
+		const extra = applyAggregate(data, { by: groupByFields, value: channels[key], stat: statFn })
+		const index = new Map(extra.map((r) => [groupByFields.map((f) => r[f]).join('|'), r]))
+		result = result.map((r) => {
+			const mapKey = groupByFields.map((f) => r[f]).join('|')
+			const extraRow = index.get(mapKey)
+			return extraRow ? { ...r, [channels[key]]: extraRow[channels[key]] } : r
+		})
+	}
+
+	return result
+}

package/src/lib/plot/types.js

@@ -0,0 +1,65 @@
+// packages/chart/src/lib/plot/types.js
+// JSDoc typedefs for the Plot system. No runtime code.
+
+/**
+ * @typedef {Object} GeomSpec
+ * @property {string} type - Geom type: 'bar'|'line'|'area'|'point'|'box'|'violin'|'arc' or custom
+ * @property {string} [x]
+ * @property {string} [y]
+ * @property {string} [color]
+ * @property {string} [fill]
+ * @property {string} [size]
+ * @property {string} [symbol]
+ * @property {string} [pattern]
+ * @property {string} [stat] - Built-in or helpers.stats key
+ * @property {Record<string, unknown>} [options]
+ */
+
+/**
+ * @typedef {Object} PlotSpec
+ * @property {Record<string, unknown>[]} data
+ * @property {string} [x]
+ * @property {string} [y]
+ * @property {string} [color]
+ * @property {string} [fill]
+ * @property {string} [size]
+ * @property {string} [symbol]
+ * @property {string} [pattern]
+ * @property {string} [theta]
+ * @property {Record<string, string>} [labels]
+ * @property {unknown[]} [xDomain]
+ * @property {number[]} [yDomain]
+ * @property {string} [xLabel]
+ * @property {string} [yLabel]
+ * @property {[number, number]} [axisOrigin]
+ * @property {'categorical'|'sequential'|'diverging'} [colorScale]
+ * @property {string} [colorScheme]
+ * @property {number} [colorMidpoint]
+ * @property {unknown[]} [colorDomain]
+ * @property {GeomSpec[]} geoms
+ * @property {{ by: string, cols?: number, scales?: 'fixed'|'free'|'free_x'|'free_y' }} [facet]
+ * @property {{ by: string, duration?: number, loop?: boolean }} [animate]
+ * @property {boolean} [grid]
+ * @property {boolean} [legend]
+ * @property {boolean} [tooltip]
+ * @property {string} [title]
+ * @property {string} [preset]
+ * @property {number} [width]
+ * @property {number} [height]
+ * @property {'light'|'dark'} [mode]
+ */
+
+/**
+ * @typedef {Object} PlotHelpers
+ * @property {Record<string, (values: unknown[]) => unknown>} [stats]
+ * @property {Record<string, (v: unknown) => string>} [format]
+ * @property {(d: Record<string, unknown>) => string} [tooltip]
+ * @property {Record<string, unknown>} [geoms]  Svelte components keyed by type name
+ * @property {unknown} [colorScale]  d3 scale override
+ * @property {{ colors: string[], patterns: string[], symbols: string[] }} [preset]
+ * @property {Record<string, { colors: string[], patterns: string[], symbols: string[] }>} [presets]
+ * @property {Record<string, unknown>} [patterns]  custom SVG pattern components keyed by name
+ * @property {Record<string, unknown>} [symbols]   custom symbol shape components keyed by name
+ */
+
+export {}