@rokkit/chart 1.0.0-next.15 → 1.0.0-next.151

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

package/src/lib/scales.svelte.js

@@ -0,0 +1,151 @@
+import { SvelteSet } from 'svelte/reactivity'
+import { scaleLinear, scaleOrdinal } from 'd3-scale'
+import { schemeCategory10 } from 'd3-scale-chromatic'
+import { min, max } from 'd3-array'
+import { buildXScale } from './xscale.js'
+
+/**
+ * Creates appropriate scales based on data and dimensions
+ *
+ * @param {Array} data The dataset
+ * @param {Object} dimensions Chart dimensions
+ * @param {Object} options Additional options
+ * @param {string} options.xKey Field to use for x-axis
+ * @param {string} options.yKey Field to use for y-axis
+ * @param {string} [options.colorKey] Field to use for color mapping
+ * @param {number} [options.padding=0.2] Padding for band scales
+ * @returns {Object} Object containing xScale, yScale, and colorScale
+ */
+/**
+ * @param {Array} data
+ * @param {string} colorKey
+ * @returns {Object}
+ */
+function buildColorScale(data, colorKey) {
+	const uniqueCategories = [...new SvelteSet(data.map((d) => d[colorKey]))]
+	return scaleOrdinal().domain(uniqueCategories).range(schemeCategory10)
+}
+
+/**
+ * @param {Object} options
+ * @returns {{ xKey: string, yKey: string, colorKey: string|undefined, padding: number }}
+ */
+function parseScaleOptions(options) {
+	const opts = options || {}
+	return {
+		xKey: opts.xKey,
+		yKey: opts.yKey,
+		colorKey: opts.colorKey,
+		padding: opts.padding !== undefined ? opts.padding : 0.2
+	}
+}
+
+export function createScales(data, dimensions, options) {
+	if (!data || !data.length) return {}
+
+	const { xKey, yKey, colorKey, padding } = parseScaleOptions(options)
+	const xValues = data.map((d) => d[xKey])
+	const yValues = data.map((d) => d[yKey])
+	const colorScale = colorKey ? buildColorScale(data, colorKey) : null
+
+	return {
+		xScale: buildXScale(xValues, dimensions, padding),
+		yScale: scaleLinear()
+			.domain([0, max(yValues) * 1.1])
+			.nice()
+			.range([dimensions.innerHeight, 0]),
+		colorScale
+	}
+}
+
+/**
+ * Calculates the actual chart dimensions after applying margins
+ *
+ * @param {number} width
+ * @param {number} height
+ * @param {Object} margin
+ * @returns {Object} Dimensions with calculated inner width and height
+ */
+export function calculateChartDimensions(width, height, margin) {
+	return {
+		width,
+		height,
+		margin,
+		innerWidth: width - margin.left - margin.right,
+		innerHeight: height - margin.top - margin.bottom
+	}
+}
+
+/**
+ * Gets the axis origin value
+ *
+ * @param {Object} scale D3 scale
+ * @returns {number} Origin value
+ */
+export function getOriginValue(scale) {
+	return scale.ticks ? scale(Math.max(0, min(scale.domain()))) : scale.range()[0]
+}
+
+/**
+ * Resolve tick values for a band scale, applying downsampling when needed
+ * @param {Object} scale
+ * @param {number} count
+ * @returns {{ ticks: Array, offset: number }}
+ */
+function bandTicks(scale, count) {
+	const offset = scale.bandwidth() / 2
+	const domain = scale.domain()
+	const cappedCount = Math.min(Math.round(count), domain.length)
+	const step = Math.ceil(domain.length / cappedCount)
+	const ticks = cappedCount < domain.length ? domain.filter((_, i) => i % step === 0) : domain
+	return { ticks, offset }
+}
+
+/**
+ * @param {number} rangeSize
+ * @param {string} axis
+ * @param {number} fontSize
+ * @returns {number}
+ */
+function defaultTickCount(rangeSize, axis, fontSize) {
+	const divisor = fontSize * (axis === 'y' ? 3 : 6)
+	return Math.abs(rangeSize / divisor)
+}
+
+/**
+ * @param {Array} ticks
+ * @param {Object} scale
+ * @param {number} offset
+ * @param {boolean} isXAxis
+ * @returns {Array}
+ */
+function formatTicks(ticks, scale, offset, isXAxis) {
+	const pos = isXAxis ? offset : 0
+	return ticks.map((t) => ({ value: t, position: scale(t) + pos }))
+}
+
+/**
+ * Creates axis ticks
+ *
+ * @param {Object} scale D3 scale
+ * @param {string} axis Axis type ('x' or 'y')
+ * @param {number} count Number of ticks
+ * @param {number} fontSize Font size for determining tick density
+ * @returns {Array} Array of tick objects
+ */
+export function createTicks(scale, axis, count = null, fontSize = 12) {
+	const [minRange, maxRange] = scale.range()
+	const tickCount = count ?? defaultTickCount(maxRange - minRange, axis, fontSize)
+
+	let ticks, offset
+	if (scale.ticks) {
+		ticks = scale.ticks(Math.round(tickCount))
+		offset = 0
+	} else {
+		const band = bandTicks(scale, tickCount)
+		ticks = band.ticks
+		offset = band.offset
+	}
+
+	return formatTicks(ticks, scale, offset, axis === 'x')
+}

package/src/lib/swatch.js

@@ -0,0 +1,13 @@
+import palette from './palette.json'
+import { PATTERN_ORDER } from './brewing/patterns.js'
+import { shapes } from '../symbols'
+
+export const swatch = {
+	palette,
+	keys: {
+		gray: ['gray'],
+		color: Object.keys(palette).filter((name) => name !== 'gray'),
+		symbol: shapes,
+		pattern: PATTERN_ORDER
+	}
+}

package/src/lib/ticks.js

@@ -0,0 +1,46 @@
+/**
+ * @typedef {Object} TickSteps
+ * @property {number} major - count of major ticks
+ * @property {number} minor - count of minor ticks
+ */
+
+/**
+ * Generate an array of ticks for a given axis and the tick type
+ *
+ * @param {number}    lower - The lower bound of the axis
+ * @param {number}    upper - The upper bound of the axis
+ * @param {TickSteps} steps - The number of steps between major and minor ticks
+ * @param {string}    type  - The type of tick to generate
+ *
+ * @returns {Array} - An array of objects representing the ticks
+ */
+export function ticksByType(lower, upper, steps, type) {
+	if (steps <= 0) return []
+	return Array.from({ length: Math.floor((upper - lower) / steps) + 1 }, (_, i) => ({
+		position: i * steps,
+		label: i * steps,
+		type
+	})).filter((tick) => tick.position > lower && tick.position < upper)
+}
+
+/**
+ * Generate an array of ticks for a given axis
+ *
+ * @param {number}    lower - The lower bound of the axis
+ * @param {number}    upper - The upper bound of the axis
+ * @param {TickSteps} steps - The number of steps between major and minor ticks
+ *
+ * @returns {Array} - An array of objects representing the ticks
+ */
+export function getTicks(lower, upper, steps = { major: 10, minor: 0 }) {
+	const majorTicks = ticksByType(lower, upper, steps.major, 'major')
+	const minorTicks = ticksByType(lower, upper, steps.minor, 'minor').filter(
+		(tick) => !majorTicks.find((major) => major.position === tick.position)
+	)
+	const end = [
+		{ position: upper, label: upper, type: 'end' },
+		{ position: lower, label: lower, type: 'end' }
+	]
+
+	return [...minorTicks, ...majorTicks, ...end].sort((a, b) => a.position - b.position)
+}

package/src/lib/utils.js

@@ -1,157 +1,150 @@
-import { scaleBand, scaleLinear } from 'd3-scale'
-import { min, max } from 'd3-array'
-import { ascending, quantile } from 'd3-array'
-import { nest } from 'd3-collection'
-import { omit } from 'ramda'
+import { scaleBand, scaleLinear, scaleOrdinal } from 'd3-scale'
+import { schemeCategory10 } from 'd3-scale-chromatic'
+import { max } from 'd3-array'
 
 /**
- * Calculates a grid of centres to fit a list of items of `size` within the number of `columns` and `rows`.
+ * Creates appropriate scales based on data and dimensions
  *
- * - 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
- * @param {number} size
- * @param {number} pad
- * @param {number} columns
- * @param {number} rows
- * @returns
+ * @param {Array} data The dataset
+ * @param {Object} dimensions Chart dimensions
+ * @param {Object} [options] Additional options
+ * @param {string} options.xKey Field to use for x-axis
+ * @param {string} options.yKey Field to use for y-axis
+ * @param {string} [options.colorKey] Field to use for color mapping
+ * @returns {Object} Object containing xScale, yScale, and colorScale
  */
-export function swatch(count, size, pad = 0, columns, rows) {
-	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)
-	}
+export function createScales(data, dimensions, options = {}) {
+	if (!data || data.length === 0) return {}
+
+	const { xKey, yKey, colorKey } = options
+
+	const xScale = scaleBand()
+		.domain(data.map((d) => d[xKey]))
+		.range([0, dimensions.width])
+		.padding(0.2)
 
-	const width = (size + pad) * columns + pad
-	const height = (size + pad) * rows + pad
-	const data = [...Array(count).keys()].map((index) => ({
-		cx: (size + pad) / 2 + (index % columns) * (size + pad),
-		cy: (size + pad) / 2 + Math.floor(index / columns) * (size + pad),
-		r: size / 2
-	}))
+	const yScale = scaleLinear()
+		.domain([0, max(data, (d) => d[yKey]) * 1.1]) // Add 10% padding on top
+		.nice()
+		.range([dimensions.height, 0])
 
-	return { width, height, data }
+	let colorScale = null
+
+	if (colorKey) {
+		const uniqueCategories = [...new Set(data.map((d) => d[colorKey]))]
+		colorScale = scaleOrdinal().domain(uniqueCategories).range(schemeCategory10)
+	}
+
+	return { xScale, yScale, colorScale }
 }
+
 /**
- * Get a scale function mapping the values between a range of lower and upper values
+ * Calculates the actual chart dimensions after applying margins
  *
- * @param {Array} values
- * @param {Array[2]} bounds
- * @param {number} buffer
- * @returns
+ * @param {Object} dimensions Original dimensions
+ * @returns {Object} Dimensions with calculated inner width and height
  */
-export function getScale(values, bounds, buffer = 0, ordinal = false) {
-	if (ordinal || values.some(isNaN)) {
-		return scaleBand().range(bounds).domain(values).padding(0.5)
-	} else {
-		values = values.map((x) => +x)
-
-		let minValue = min([...values, 0])
-		let maxValue = max(values)
-
-		if (minValue < 0 && maxValue > 0) {
-			maxValue = max([-1 * minValue, maxValue])
-			minValue = -1 * maxValue
-		}
-		const margin = (maxValue - minValue) * buffer
-		return scaleLinear()
-			.domain([minValue - margin, maxValue + margin])
-			.range(bounds)
+export function calculateChartDimensions(dimensions) {
+	const { width, height, margin } = dimensions
+
+	return {
+		...dimensions,
+		innerWidth: width - margin.left - margin.right,
+		innerHeight: height - margin.top - margin.bottom
 	}
 }
+
 /**
- * Obtain the scale function for the `x` and `y` fields in the data set.
+ * Normalizes data for use with D3 charts
  *
- * @param {array<dict>} data
- * @param {string} x
- * @param {string} y
- * @param {number} width
- * @param {number} height
- * @returns
+ * @param {Array|Object} inputData Raw data or dataset object
+ * @returns {Array} Normalized data array
  */
-export function getScales(data, x, y, width, height, margin, ordinal) {
-	const xValues = [...new Set(data.map((item) => item[x]))]
-	const yValues = [...new Set(data.map((item) => item[y]))]
+export function normalizeData(inputData) {
+	if (!inputData) return []
 
-	return {
-		x: getScale(xValues, [0 + margin.left, width - margin.right], 0, ordinal.x),
-		y: getScale(yValues, [height - margin.top, margin.bottom], 0.1, ordinal.y)
+	// If it's a dataset class instance, call select() to get the data
+	if (inputData.select && typeof inputData.select === 'function') {
+		return inputData.select()
 	}
+
+	// If it's already an array, return as is
+	if (Array.isArray(inputData)) {
+		return inputData
+	}
+
+	return []
 }
 
 /**
- * Summarize `data` by fields `x` and `y` and return a nested array with
- * key as unique `x` values and value as statistical summaries of `y` values
+ * Generates a unique ID for SVG elements
  *
- * @param {*} data
- * @param {*} x
- * @param {*} y
- * @returns
+ * @param {string} prefix Prefix for the ID
+ * @returns {string} A unique ID
  */
-export function aggregate(data, x, y) {
-	const summary = nest()
-		.key((d) => d[x])
-		.rollup((d) => {
-			let values = d.map((g) => g[y]).sort(ascending)
-			let q1 = quantile(values, 0.25)
-			let q3 = quantile(values, 0.75)
-			let median = quantile(values, 0.5)
-			let interQuantileRange = q3 - q1
-			let min = q1 - 1.5 * interQuantileRange
-			let max = q3 + 1.5 * interQuantileRange
-			return { q1, q3, median, interQuantileRange, min, max }
-		})
-		.entries(data)
-	return summary
+export function uniqueId(prefix = 'chart') {
+	return `${prefix}-${Math.random().toString(36).substring(2, 10)}`
 }
 
 /**
- * Generate a palette with same size as input data containing values from palette array.
- * After the palette array is exhausted the fallback value is used
+ * Format a single key-value pair for tooltip
+ * @param {string} key
+ * @param {unknown} value
+ * @param {Function|undefined} formatter
+ * @returns {string}
+ */
+function formatField(key, value, formatter) {
+	const formatted = formatter ? formatter(value) : value
+	return `${key}: ${formatted}`
+}
+
+/**
+ * Formats tooltip content for a data point
  *
- * @param {Array} values
- * @param {Array} palette
- * @param {*}     fallback
- * @returns
+ * @param {Object} d Data point
+ * @param {Object} options Tooltip format options
+ * @returns {string} Formatted tooltip HTML content
  */
-export function getPaletteForValues(values, palette, fallback) {
-	return values.map((_, index) =>
-		index < palette.length ? palette[index] : fallback
-	)
+export function formatTooltipContent(d, options = {}) {
+	if (!d) return ''
+
+	const { xKey, yKey, xFormat, yFormat } = options
+
+	if (xKey && yKey) {
+		return [formatField(xKey, d[xKey], xFormat), formatField(yKey, d[yKey], yFormat)].join('<br>')
+	}
+
+	return Object.entries(d)
+		.map(([key, value]) => `${key}: ${value}`)
+		.join('<br>')
 }
 
 /**
- * Converts input object array into a nested key,value array.
- * 'key' contains unique values for the attribute specified by the key parameter
- * and value contains array of all remaining attributes in an array.
+ * Generates a tooltip formatter function
  *
- * @param {Array<Object>} data
- * @param {string} key
- * @param {string} label
- * @returns
+ * @param {Object} options Tooltip format options
+ * @returns {Function} A function that formats tooltip content
  */
-export function toNested(data, key, label) {
-	return nest()
-		.key((d) => d[key])
-		.rollup((values) => values.map((value) => omit([key], value)))
-		.entries(data.sort((a, b) => ascending(a[label], b[label])))
+export function createTooltipFormatter(options = {}) {
+	return (d) => formatTooltipContent(d, options)
 }
+
 /**
- * Repeats array items of b using array items of a ask keys
+ * Calculates the transform attribute for SVG elements
  *
- * @param {Array} b
- * @param {Array} a
- * @returns {Object} with keys as items in a and values as items in b
+ * @param {number} x X position
+ * @param {number} y Y position
+ * @returns {string} Transform attribute value
  */
-export function repeatAcross(b, a) {
-	return a.reduce(
-		(acc, item, index) => ({ ...acc, [item]: b[index % b.length] }),
+export function transform(x, y) {
+	return `translate(${x}, ${y})`
+}
+
+import { scaledPath } from '@rokkit/core'
+
+export function scaledPathCollection(paths) {
+	return Object.entries(paths).reduce(
+		(acc, [key, value]) => ({ ...acc, [key]: (s) => scaledPath(s, value) }),
 		{}
 	)
 }

package/src/lib/xscale.js

@@ -0,0 +1,31 @@
+import { scaleBand, scaleLinear, scaleTime } from 'd3-scale'
+import { min, max } from 'd3-array'
+
+/**
+ * Builds an appropriate D3 x-axis scale based on value types.
+ * Returns scaleTime for Date values, scaleLinear for numeric values,
+ * or scaleBand for categorical values.
+ *
+ * @param {Array} xValues
+ * @param {Object} dimensions
+ * @param {number} padding
+ * @returns {import('d3-scale').ScaleContinuousNumeric|import('d3-scale').ScaleBand}
+ */
+export function buildXScale(xValues, dimensions, padding) {
+	const xIsDate = xValues.some((v) => v instanceof Date)
+	const xIsNumeric = !xIsDate && xValues.every((v) => !isNaN(parseFloat(v)))
+
+	if (xIsDate) {
+		return scaleTime()
+			.domain([min(xValues), max(xValues)])
+			.range([0, dimensions.innerWidth])
+			.nice()
+	}
+	if (xIsNumeric) {
+		return scaleLinear()
+			.domain([min([0, ...xValues]), max(xValues)])
+			.range([0, dimensions.innerWidth])
+			.nice()
+	}
+	return scaleBand().domain(xValues).range([0, dimensions.innerWidth]).padding(padding)
+}

package/src/patterns/DefinePatterns.svelte

@@ -0,0 +1,32 @@
+<script>
+  import { getContext } from 'svelte'
+  import { toPatternId } from '../lib/brewing/patterns.js'
+  import { PATTERNS } from './patterns.js'
+  import PatternDef from './PatternDef.svelte'
+
+  /** @type {{ patterns?: Record<string, import('./patterns.js').PatternMark[]> }} */
+  let { patterns = PATTERNS } = $props()
+
+  const state = getContext('plot-state')
+
+  const patternDefs = $derived.by(() => {
+    const defs = []
+    for (const [key, patternName] of (state.patterns ?? new Map()).entries()) {
+      const colorEntry = state.colors?.get(key) ?? { stroke: '#444' }
+      defs.push({
+        id: toPatternId(String(key)),
+        marks: patterns[patternName] ?? [],
+        stroke: colorEntry.stroke ?? '#444'
+      })
+    }
+    return defs
+  })
+</script>
+
+{#if patternDefs.length > 0}
+  <defs data-plot-pattern-defs>
+    {#each patternDefs as def (def.id)}
+      <PatternDef id={def.id} marks={def.marks} stroke={def.stroke} />
+    {/each}
+  </defs>
+{/if}

package/src/patterns/PatternDef.svelte

@@ -0,0 +1,27 @@
+<script>
+	import { scaleMark, resolveMarkAttrs } from './scale.js'
+
+	/** @type {{ id: string, marks?: import('./patterns.js').PatternMark[], size?: number, stroke?: string, thickness?: number }} */
+	let { id, marks = [], size = 10, stroke = '#444', thickness = 0.5 } = $props()
+
+	const resolvedMarks = $derived(
+		marks.map((m) => resolveMarkAttrs(scaleMark(m, size), { fill: stroke, stroke, thickness }))
+	)
+</script>
+
+<pattern {id} patternUnits="userSpaceOnUse" width={size} height={size}>
+	<rect width={size} height={size} fill="none" />
+	{#each resolvedMarks as { type, attrs }, i (i)}
+		{#if type === 'line'}
+			<line {...attrs} />
+		{:else if type === 'circle'}
+			<circle {...attrs} />
+		{:else if type === 'rect'}
+			<rect {...attrs} />
+		{:else if type === 'polygon'}
+			<polygon {...attrs} />
+		{:else if type === 'path'}
+			<path {...attrs} />
+		{/if}
+	{/each}
+</pattern>

package/src/patterns/index.js

@@ -0,0 +1,4 @@
+export { default as PatternDef } from './PatternDef.svelte'
+export { default as DefinePatterns } from './DefinePatterns.svelte'
+export { PATTERNS } from './patterns.js'
+export { scaleMark, resolveMarkAttrs } from './scale.js'