@rokkit/chart 1.0.0-next.147 → 1.0.0-next.149

package/src/lib/plot/frames.js

@@ -0,0 +1,80 @@
+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,53 @@
+import palette from '../brewing/palette.json'
+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:   palette.map((p) => p.shades.light.fill),
+  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,56 @@
+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 allValues = datasets.flatMap((d) => d.map((r) => Number(r[field]))).filter((v) => !isNaN(v))
+  const [minVal, maxVal] = extent(allValues)
+  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 {}

package/src/lib/scales.svelte.js

@@ -1,32 +1,8 @@
 import { SvelteSet } from 'svelte/reactivity'
-import { scaleBand, scaleLinear, scaleTime, scaleOrdinal } from 'd3-scale'
+import { scaleLinear, scaleOrdinal } from 'd3-scale'
 import { schemeCategory10 } from 'd3-scale-chromatic'
 import { min, max } from 'd3-array'
-
-/**
- * @param {Array} xValues
- * @param {Object} dimensions
- * @param {number} padding
- * @returns {Object}
- */
-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)
-}
+import { buildXScale } from './xscale.js'
 
 /**
  * Creates appropriate scales based on data and dimensions

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/utils.js

@@ -139,3 +139,12 @@ export function createTooltipFormatter(options = {}) {
 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 }}
+		{#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

@@ -1,14 +1,4 @@
-export { default as Brick } from './Brick.svelte'
-export { default as Circles } from './Circles.svelte'
-export { default as Dots } from './Dots.svelte'
-export { default as CrossHatch } from './CrossHatch.svelte'
-export { default as Waves } from './Waves.svelte'
-// export { default as Squares } from './Squares.svelte'
-export { default as Tile } from './Tile.svelte'
-export { default as Triangles } from './Triangles.svelte'
-// export { default as Waves } from './Waves.svelte'
-// export { default as ZigZag } from './ZigZag.svelte'
-// export { default as Flower } from './Flower.svelte'
-// export { default as NamedPath } from './NamedPath.svelte'
-export { default as CurvedWave } from './CurvedWave.svelte'
-export { default as OutlineCircles } from './OutlineCircles.svelte'
+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'