@rokkit/chart 1.3.8 → 1.3.10

package/dist/geoms/lib/marks/hexbin.js

@@ -0,0 +1,62 @@
+import { resolveAlpha } from '../aesthetics.js'
+
+/** SVG path for a pointy-top hexagon of radius r, centered at the origin. */
+export function hexPath(r) {
+	const angles = [0, 1, 2, 3, 4, 5].map((i) => ((i * 60 - 30) * Math.PI) / 180)
+	return `${angles.map((a, i) => `${i === 0 ? 'M' : 'L'}${r * Math.cos(a)},${r * Math.sin(a)}`).join('')}Z`
+}
+
+/** Group points into hexagonal bins and count per bin. */
+function hexBin(rows, xField, yField, xScale, yScale, r) {
+	const dx = r * 2 * Math.sin(Math.PI / 3)
+	const dy = r * 1.5
+	const bins = new Map()
+	for (const d of rows) {
+		const px = xScale(d[xField ?? ''])
+		const py = yScale(d[yField ?? ''])
+		if (px === null || px === undefined || py === null || py === undefined) continue
+		const col = Math.round(px / dx)
+		const row = Math.round(py / dy)
+		const cx = col * dx + (row % 2 ? dx / 2 : 0)
+		const cy = row * dy
+		const key = `${col},${row}`
+		let bin = bins.get(key)
+		if (!bin) {
+			bin = { cx, cy, count: 0, points: [] }
+			bins.set(key, bin)
+		}
+		bin.count++
+		bin.points.push(d)
+	}
+	return [...bins.values()]
+}
+
+/**
+ * Build renderable hex bins. Fill is the continuous color scale (by count) or a density-ramp
+ * rgba fallback. `alpha` is a flat multiplier on top (default 1 → unchanged).
+ * @param {{ data: any[], plot: any, channels: any, options?: any, alpha?: number, type?: string }} ctx
+ */
+export function buildHexbinMarks({ data, plot, channels, options = {}, alpha, type = 'hexbin' }) {
+	const { xScale, yScale } = plot
+	if (!data?.length || !xScale || !yScale) return []
+
+	const radius = options.radius ?? 20
+	const bins = hexBin(data, channels.x, channels.y, xScale, yScale, radius)
+	const maxCount = Math.max(1, ...bins.map((b) => b.count))
+	const colorScale = plot.continuousColorScale?.scale
+	const a = resolveAlpha(alpha, type, plot.chartPreset)
+
+	return bins.map((bin, i) => ({
+		key: `hex-${i}`,
+		cx: bin.cx,
+		cy: bin.cy,
+		count: bin.count,
+		fill: colorScale
+			? colorScale(bin.count)
+			: `rgba(66, 133, 244, ${0.1 + 0.9 * (bin.count / maxCount)})`,
+		alpha: a,
+		value: bin.count,
+		display: `${bin.count}`,
+		data: { count: bin.count, x: bin.cx, y: bin.cy }
+	}))
+}

package/dist/geoms/lib/marks/jitter.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Build renderable jitter/swarm points. Fill + outline come from `fill` (defaulting to
+ * `x`); an explicit `color` channel overrides the outline stroke. Adds fixed `alpha`.
+ * Horizontal orientation swaps each point's screen coords via place().
+ * @param {{ data: any[], plot: any, channels: any, options?: any, alpha?: number, type?: string }} ctx
+ */
+export function buildJitterMarks({ data, plot, channels, options, alpha, type }: {
+    data: any[];
+    plot: any;
+    channels: any;
+    options?: any;
+    alpha?: number;
+    type?: string;
+}): {
+    cx: any;
+    cy: any;
+    stroke: any;
+    alpha: number;
+    fill: string;
+    data: Record<string, unknown>;
+}[];

package/dist/geoms/lib/marks/jitter.js

@@ -0,0 +1,36 @@
+import { buildSwarm } from '../../../lib/brewing/marks/swarm.js'
+import { resolveAlpha } from '../aesthetics.js'
+
+/**
+ * Build renderable jitter/swarm points. Fill + outline come from `fill` (defaulting to
+ * `x`); an explicit `color` channel overrides the outline stroke. Adds fixed `alpha`.
+ * Horizontal orientation swaps each point's screen coords via place().
+ * @param {{ data: any[], plot: any, channels: any, options?: any, alpha?: number, type?: string }} ctx
+ */
+export function buildJitterMarks({ data, plot, channels, options = {}, alpha, type = 'jitter' }) {
+	const { xScale, yScale, colors } = plot
+	if (!data?.length || !xScale || !yScale) return []
+
+	const fillField = channels.fill ?? channels.x
+	const raw = buildSwarm(
+		data,
+		{ x: channels.x, y: channels.y, fill: fillField },
+		xScale,
+		yScale,
+		colors,
+		{ method: options.method, r: options.r, side: options.side }
+	)
+	const a = resolveAlpha(alpha, type, plot.chartPreset)
+	const colorField = channels.color
+	const flip = plot.isFlipped
+	return raw.map((p) => {
+		const s = flip ? plot.place(p.cx, p.cy) : { x: p.cx, y: p.cy }
+		return {
+			...p,
+			cx: s.x,
+			cy: s.y,
+			stroke: colorField ? (colors.get(p.data[colorField])?.stroke ?? p.stroke) : p.stroke,
+			alpha: a
+		}
+	})
+}

package/dist/geoms/lib/marks/line.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Build renderable line segments. A line has no interior, so its single aesthetic is
+ * the stroke — driven by `color`, with `fill` accepted as an alias (ggplot geom_line
+ * uses `colour`). Each segment gets the geom's fixed `alpha`.
+ * @param {{ data: any[], plot: any, channels: any, options?: any, alpha?: number, type?: string }} ctx
+ */
+export function buildLineMarks({ data, plot, channels, options, alpha, type }: {
+    data: any[];
+    plot: any;
+    channels: any;
+    options?: any;
+    alpha?: number;
+    type?: string;
+}): {
+    alpha: number;
+    d: string | null;
+    fill: string;
+    stroke: string;
+    points: {
+        x: number;
+        y: number;
+        data: Record<string, unknown>;
+        i: number;
+    }[];
+    key?: unknown;
+}[];

package/dist/geoms/lib/marks/line.js

@@ -0,0 +1,25 @@
+import { buildLines } from '../../../lib/brewing/marks/lines.js'
+import { resolveAlpha } from '../aesthetics.js'
+
+/**
+ * Build renderable line segments. A line has no interior, so its single aesthetic is
+ * the stroke — driven by `color`, with `fill` accepted as an alias (ggplot geom_line
+ * uses `colour`). Each segment gets the geom's fixed `alpha`.
+ * @param {{ data: any[], plot: any, channels: any, options?: any, alpha?: number, type?: string }} ctx
+ */
+export function buildLineMarks({ data, plot, channels, options = {}, alpha, type = 'line' }) {
+	const { xScale, yScale, colors } = plot
+	if (!data?.length || !xScale || !yScale) return []
+	const lineColor = channels.color ?? channels.fill
+	const segs = buildLines(
+		data,
+		{ x: channels.x, y: channels.y, color: lineColor },
+		xScale,
+		yScale,
+		colors,
+		options.curve,
+		plot.place.bind(plot)
+	)
+	const a = resolveAlpha(alpha, type, plot.chartPreset)
+	return segs.map((seg) => ({ ...seg, alpha: a }))
+}

package/dist/geoms/lib/marks/point.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Build renderable point marks: geometry (from buildPoints) + shared aesthetics
+ * (fill/color split + alpha) + value/display. The geom template just renders these.
+ * @param {{ data: any[], plot: any, channels: any, options?: any, alpha?: number, type?: string }} ctx
+ */
+export function buildPointMarks({ data, plot, channels, options, alpha, type }: {
+    data: any[];
+    plot: any;
+    channels: any;
+    options?: any;
+    alpha?: number;
+    type?: string;
+}): {
+    cx: any;
+    cy: any;
+    fill: string;
+    stroke: string;
+    alpha: number;
+    value: unknown;
+    display: string;
+    key: string;
+    data: Record<string, unknown>;
+    r: number;
+    symbolPath: string | null;
+}[];

package/dist/geoms/lib/marks/point.js

@@ -0,0 +1,58 @@
+import { scaleSqrt } from 'd3-scale'
+import { buildPoints } from '../../../lib/brewing/marks/points.js'
+import { resolveFillStroke, resolveAlpha } from '../aesthetics.js'
+
+/**
+ * Size scale for a bubble/size channel — sqrt so area (not radius) is proportional.
+ * @returns {import('d3-scale').ScalePower<number, number> | null}
+ */
+function buildSizeScale(data, sizeField, options) {
+	if (!sizeField || !data?.length) return null
+	const vals = data.map((d) => Number(d[sizeField])).filter((v) => !isNaN(v))
+	if (!vals.length) return null
+	return scaleSqrt()
+		.domain([Math.min(...vals), Math.max(...vals)])
+		.range([options?.minRadius ?? 3, options?.maxRadius ?? 20])
+}
+
+/**
+ * Build renderable point marks: geometry (from buildPoints) + shared aesthetics
+ * (fill/color split + alpha) + value/display. The geom template just renders these.
+ * @param {{ data: any[], plot: any, channels: any, options?: any, alpha?: number, type?: string }} ctx
+ */
+export function buildPointMarks({ data, plot, channels, options = {}, alpha, type = 'point' }) {
+	const { xScale, yScale, colors } = plot
+	if (!data?.length || !xScale || !yScale) return []
+
+	const sizeScale = buildSizeScale(data, channels.size, options)
+	const raw = buildPoints(
+		data,
+		channels,
+		xScale,
+		yScale,
+		colors,
+		sizeScale,
+		plot.symbols,
+		options.radius ?? 4,
+		options.jitter ?? null
+	)
+	const a = resolveAlpha(alpha, type, plot.chartPreset)
+	const yf = channels.y
+
+	return raw.map((p, i) => {
+		const { fill, stroke } = resolveFillStroke(p.data, channels, colors)
+		// Horizontal orientation: swap each point's screen coords via place().
+		const s = plot.isFlipped ? plot.place(p.cx, p.cy) : { x: p.cx, y: p.cy }
+		return {
+			...p,
+			cx: s.x,
+			cy: s.y,
+			fill,
+			stroke,
+			alpha: a,
+			value: yf ? p.data[yf] : undefined,
+			display: yf ? String(p.data[yf] ?? '') : '',
+			key: `${i}::${p.data[channels.x ?? '']}::${p.data[yf ?? '']}`
+		}
+	})
+}

package/dist/geoms/lib/marks/ribbon.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Build a Sankey-style ribbon layout: links (flows) + source/target node boxes. Link fill
+ * comes from the source (then target) palette entry; `alpha` is fixed (default 0.5). Returns
+ * an object rather than a flat array, so the geom template renders links + node labels.
+ * @param {{ data: any[], plot: any, channels?: any, options?: any, alpha?: number, type?: string }} ctx
+ */
+export function buildRibbonMarks({ data, plot, channels, options, alpha, type }: {
+    data: any[];
+    plot: any;
+    channels?: any;
+    options?: any;
+    alpha?: number;
+    type?: string;
+}): {
+    links: {
+        key: string;
+        d: string;
+        fill: any;
+        alpha: number;
+        data: any;
+    }[];
+    sourceNodes: {
+        name: any;
+        y: number;
+        height: number;
+    }[];
+    targetNodes: {
+        name: any;
+        y: number;
+        height: number;
+    }[];
+};

package/dist/geoms/lib/marks/ribbon.js

@@ -0,0 +1,80 @@
+import { resolveAlpha } from '../aesthetics.js'
+import { literalColor } from '../../../lib/brewing/colors.js'
+
+/**
+ * Build a Sankey-style ribbon layout: links (flows) + source/target node boxes. Link fill
+ * comes from the source (then target) palette entry; `alpha` is fixed (default 0.5). Returns
+ * an object rather than a flat array, so the geom template renders links + node labels.
+ * @param {{ data: any[], plot: any, channels?: any, options?: any, alpha?: number, type?: string }} ctx
+ */
+export function buildRibbonMarks({ data, plot, channels = {}, options = {}, alpha, type = 'ribbon' }) {
+	const empty = { links: [], sourceNodes: [], targetNodes: [] }
+	if (!data?.length) return empty
+
+	const { colors, innerHeight, innerWidth } = plot
+	const sourceField = options.source ?? 'source'
+	const targetField = options.target ?? 'target'
+	const valueField = options.value ?? 'value'
+	// A literal color/fill paints every ribbon directly (else fill comes from the node palette).
+	const lit = literalColor(channels.color ?? channels.fill)
+	const a = resolveAlpha(alpha, type, plot.chartPreset)
+
+	const flows = data.map((d) => ({
+		source: String(d[sourceField]),
+		target: String(d[targetField]),
+		value: Number(d[valueField]) || 0,
+		data: d
+	}))
+
+	const sourceMap = new Map()
+	const targetMap = new Map()
+	for (const f of flows) {
+		sourceMap.set(f.source, (sourceMap.get(f.source) ?? 0) + f.value)
+		targetMap.set(f.target, (targetMap.get(f.target) ?? 0) + f.value)
+	}
+
+	const totalSource = Math.max(1, [...sourceMap.values()].reduce((s, v) => s + v, 0))
+	const totalTarget = Math.max(1, [...targetMap.values()].reduce((s, v) => s + v, 0))
+	const padding = 4
+	const availHeight = innerHeight - padding * (Math.max(sourceMap.size, targetMap.size) - 1)
+
+	let sourceY = 0
+	const sourceNodes = []
+	for (const [name, value] of sourceMap) {
+		const h = (value / totalSource) * availHeight
+		sourceNodes.push({ name, y: sourceY, height: h })
+		sourceY += h + padding
+	}
+
+	let targetY = 0
+	const targetNodes = []
+	for (const [name, value] of targetMap) {
+		const h = (value / totalTarget) * availHeight
+		targetNodes.push({ name, y: targetY, height: h })
+		targetY += h + padding
+	}
+
+	const sourceOffsets = new Map(sourceNodes.map((n) => [n.name, n.y]))
+	const targetOffsets = new Map(targetNodes.map((n) => [n.name, n.y]))
+	const x0 = 0
+	const x1 = innerWidth
+
+	const links = flows.map((f, i) => {
+		const sy0 = sourceOffsets.get(f.source) ?? 0
+		const ty0 = targetOffsets.get(f.target) ?? 0
+		const sourceTotal = sourceMap.get(f.source) ?? 1
+		const targetTotal = targetMap.get(f.target) ?? 1
+		const sh = (f.value / sourceTotal) * (sourceNodes.find((n) => n.name === f.source)?.height ?? 0)
+		const th = (f.value / targetTotal) * (targetNodes.find((n) => n.name === f.target)?.height ?? 0)
+
+		const path = `M${x0},${sy0} C${innerWidth * 0.4},${sy0} ${innerWidth * 0.6},${ty0} ${x1},${ty0} L${x1},${ty0 + th} C${innerWidth * 0.6},${ty0 + th} ${innerWidth * 0.4},${sy0 + sh} ${x0},${sy0 + sh} Z`
+
+		sourceOffsets.set(f.source, sy0 + sh)
+		targetOffsets.set(f.target, ty0 + th)
+
+		const fill = lit ?? (colors?.get(f.source)?.fill ?? colors?.get(f.target)?.fill ?? '#888')
+		return { key: `ribbon-${i}`, d: path, fill, alpha: a, data: f.data }
+	})
+
+	return { links, sourceNodes, targetNodes }
+}

package/dist/geoms/lib/marks/violin.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Build renderable violin silhouettes. Interior + outline come from `fill` (defaulting to
+ * `x`); an explicit `color` channel overrides the outline stroke. Adds fixed `alpha`.
+ * @param {{ data: any[], plot: any, channels: any, options?: any, alpha?: number, type?: string }} ctx
+ */
+export function buildViolinMarks({ data, plot, channels, options, alpha, type }: {
+    data: any[];
+    plot: any;
+    channels: any;
+    options?: any;
+    alpha?: number;
+    type?: string;
+}): any;

package/dist/geoms/lib/marks/violin.js

@@ -0,0 +1,31 @@
+import { buildViolins } from '../../../lib/brewing/marks/violins.js'
+import { resolveAlpha } from '../aesthetics.js'
+
+/**
+ * Build renderable violin silhouettes. Interior + outline come from `fill` (defaulting to
+ * `x`); an explicit `color` channel overrides the outline stroke. Adds fixed `alpha`.
+ * @param {{ data: any[], plot: any, channels: any, options?: any, alpha?: number, type?: string }} ctx
+ */
+export function buildViolinMarks({ data, plot, channels, options = {}, alpha, type = 'violin' }) {
+	const { xScale, yScale, colors } = plot
+	if (!data?.length || !xScale || !yScale) return []
+
+	const fillField = channels.fill ?? channels.x
+	const violins = buildViolins(
+		data,
+		{ x: channels.x, fill: fillField, pattern: channels.pattern },
+		xScale,
+		yScale,
+		colors,
+		plot.place.bind(plot),
+		options.side,
+		plot.patterns
+	)
+	const a = resolveAlpha(alpha, type, plot.chartPreset)
+	const colorField = channels.color
+	return violins.map((v) => ({
+		...v,
+		stroke: colorField ? (colors.get(v.data[colorField])?.stroke ?? v.stroke) : v.stroke,
+		alpha: a
+	}))
+}

package/dist/geoms/lib/marks/waterfall.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Build renderable waterfall bars. Bar color is semantic (positive/negative/total from
+ * options), not the shared palette. Adds fixed `alpha` and carries connector anchors.
+ * @param {{ data: any[], plot: any, channels: any, options?: any, alpha?: number, type?: string }} ctx
+ */
+export function buildWaterfallMarks({ data, plot, channels, options, alpha, type }: {
+    data: any[];
+    plot: any;
+    channels: any;
+    options?: any;
+    alpha?: number;
+    type?: string;
+}): {
+    key: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    fill: any;
+    alpha: number;
+    bandStart: any;
+    bandEnd: any;
+    cumY: any;
+    data: any;
+}[];

package/dist/geoms/lib/marks/waterfall.js

@@ -0,0 +1,58 @@
+import { resolveAlpha } from '../aesthetics.js'
+
+/**
+ * Build renderable waterfall bars. Bar color is semantic (positive/negative/total from
+ * options), not the shared palette. Adds fixed `alpha` and carries connector anchors.
+ * @param {{ data: any[], plot: any, channels: any, options?: any, alpha?: number, type?: string }} ctx
+ */
+export function buildWaterfallMarks({ data, plot, channels, options = {}, alpha, type = 'waterfall' }) {
+	const { xScale, yScale } = plot
+	if (!data?.length || !xScale || !yScale) return []
+
+	const positiveColor = options.positiveColor ?? '#22c55e'
+	const negativeColor = options.negativeColor ?? '#ef4444'
+	const totalColor = options.totalColor ?? '#3b82f6'
+	const totalField = options.totalField ?? undefined
+	const a = resolveAlpha(alpha, type, plot.chartPreset)
+
+	const bw = typeof xScale.bandwidth === 'function' ? xScale.bandwidth() : 10
+	let cumulative = 0
+
+	return data.map((d, i) => {
+		const xVal = d[channels.x ?? '']
+		const yVal = Number(d[channels.y ?? ''])
+		const isTotal = totalField ? Boolean(d[totalField]) : false
+		const xPos = xScale(xVal) ?? 0
+		let barTop
+		let barBottom
+		let fill
+
+		if (isTotal) {
+			barTop = yScale(Math.max(0, cumulative)) ?? 0
+			barBottom = yScale(0) ?? 0
+			fill = totalColor
+		} else {
+			const start = cumulative
+			cumulative += yVal
+			barTop = yScale(Math.max(start, cumulative)) ?? 0
+			barBottom = yScale(Math.min(start, cumulative)) ?? 0
+			fill = yVal >= 0 ? positiveColor : negativeColor
+		}
+
+		const c1 = plot.place(xPos, barTop)
+		const c2 = plot.place(xPos + bw, barBottom)
+		return {
+			key: `${xVal}-${i}`,
+			x: Math.min(c1.x, c2.x),
+			y: Math.min(c1.y, c2.y),
+			width: Math.abs(c2.x - c1.x),
+			height: Math.max(1, Math.abs(c2.y - c1.y)),
+			fill,
+			alpha: a,
+			bandStart: xPos,
+			bandEnd: xPos + bw,
+			cumY: yScale(cumulative) ?? 0,
+			data: d
+		}
+	})
+}

package/dist/index.d.ts

@@ -54,13 +54,6 @@ export { default as BoxPlot } from "./charts/BoxPlot.svelte";
 export { default as ViolinPlot } from "./charts/ViolinPlot.svelte";
 export { default as BubbleChart } from "./charts/BubbleChart.svelte";
 export { PlotState } from "./PlotState.svelte.js";
-export { ChartBrewer } from "./lib/brewing/index.svelte.js";
-export * from "./lib/brewing/index.svelte.js";
-export { CartesianBrewer } from "./lib/brewing/CartesianBrewer.svelte.js";
-export { PieBrewer } from "./lib/brewing/PieBrewer.svelte.js";
-export { QuartileBrewer } from "./lib/brewing/QuartileBrewer.svelte.js";
-export { BoxBrewer } from "./lib/brewing/BoxBrewer.svelte.js";
-export { ViolinBrewer } from "./lib/brewing/ViolinBrewer.svelte.js";
 export { createCrossFilter } from "./crossfilter/createCrossFilter.svelte.js";
 export { default as CrossFilter } from "./crossfilter/CrossFilter.svelte";
 export { default as FilterBar } from "./crossfilter/FilterBar.svelte";
@@ -74,7 +67,7 @@ import Legend from './Plot/Legend.svelte';
 import Line from './geoms/Line.svelte';
 import Area from './geoms/Area.svelte';
 import Point from './geoms/Point.svelte';
-import Arc from './Plot/Arc.svelte';
+import Arc from './geoms/Arc.svelte';
 import Highlight from './geoms/Highlight.svelte';
 import Trend from './geoms/Trend.svelte';
 import Box from './geoms/Box.svelte';

package/dist/index.js

@@ -6,7 +6,7 @@ import Legend from './Plot/Legend.svelte'
 import Line from './geoms/Line.svelte'
 import Area from './geoms/Area.svelte'
 import Point from './geoms/Point.svelte'
-import Arc from './Plot/Arc.svelte'
+import Arc from './geoms/Arc.svelte'
 import Highlight from './geoms/Highlight.svelte'
 import Trend from './geoms/Trend.svelte'
 import Box from './geoms/Box.svelte'
@@ -91,14 +91,7 @@ export { default as BubbleChart } from './charts/BubbleChart.svelte'
 export { PlotState } from './PlotState.svelte.js'
 
 // Export utilities
-export { ChartBrewer } from './lib/brewing/index.svelte.js'
-export * from './lib/brewing/index.svelte.js'
 export { buildSequentialScale, buildDivergingScale } from './lib/brewing/colors.js'
-export { CartesianBrewer } from './lib/brewing/CartesianBrewer.svelte.js'
-export { PieBrewer } from './lib/brewing/PieBrewer.svelte.js'
-export { QuartileBrewer } from './lib/brewing/QuartileBrewer.svelte.js'
-export { BoxBrewer } from './lib/brewing/BoxBrewer.svelte.js'
-export { ViolinBrewer } from './lib/brewing/ViolinBrewer.svelte.js'
 
 // CrossFilter system
 export { createCrossFilter } from './crossfilter/createCrossFilter.svelte.js'

package/dist/lib/brewing/colors.d.ts

@@ -1,10 +1,40 @@
 /**
  * Returns true if the value looks like a CSS color literal (not a field name).
- * Supports hex (#rgb, #rrggbb, #rrggbbaa), and functional notations (rgb, hsl, oklch, etc.).
+ * Supports hex (#rgb, #rrggbb, #rrggbbaa), functional notations (rgb, hsl, oklch, etc.),
+ * CSS custom-property refs (var(--token)), and the `currentColor` keyword.
  * @param {unknown} value
  * @returns {boolean}
  */
 export function isLiteralColor(value: unknown): boolean;
+/**
+ * A color-channel value as a literal CSS color (var()/oklch()/#hex/currentColor),
+ * or undefined when it names a data field. Pair with {@link markEntry}: a literal is
+ * painted directly on every mark; a field is grouped and looked up in the color scale.
+ * @param {unknown} value
+ * @returns {string | undefined}
+ */
+export function literalColor(value: unknown): string | undefined;
+/**
+ * Resolves the `{fill, stroke}` for one mark. A `literal` color IS the paint for every
+ * mark — applied directly, never grouped as a field or run through the shared `colors`
+ * scale (which holds a single value across all geoms). Otherwise `key` is looked up in
+ * `colors`, falling back to `fallback`.
+ * @param {string | undefined} literal
+ * @param {unknown} key
+ * @param {Map<unknown, {fill: string, stroke: string}> | undefined} colors
+ * @param {{fill: string, stroke: string}} fallback
+ * @returns {{fill: string, stroke: string}}
+ */
+export function markEntry(literal: string | undefined, key: unknown, colors: Map<unknown, {
+    fill: string;
+    stroke: string;
+}> | undefined, fallback: {
+    fill: string;
+    stroke: string;
+}): {
+    fill: string;
+    stroke: string;
+};
 /**
  * Extracts distinct values for a given field from the data array.
  * @param {Object[]} data

package/dist/lib/brewing/colors.js

@@ -6,7 +6,8 @@ import { defaultPreset } from '../preset.js'
 
 /**
  * Returns true if the value looks like a CSS color literal (not a field name).
- * Supports hex (#rgb, #rrggbb, #rrggbbaa), and functional notations (rgb, hsl, oklch, etc.).
+ * Supports hex (#rgb, #rrggbb, #rrggbbaa), functional notations (rgb, hsl, oklch, etc.),
+ * CSS custom-property refs (var(--token)), and the `currentColor` keyword.
  * @param {unknown} value
  * @returns {boolean}
  */
@@ -14,9 +15,41 @@ export function isLiteralColor(value) {
 	if (!value || typeof value !== 'string') return false
 	if (/^#([0-9a-fA-F]{3,8})$/.test(value)) return true
 	if (/^(rgb|rgba|hsl|hsla|oklch|oklab|hwb|lab|lch|color)\s*\(/i.test(value)) return true
+	// A `var(--token)` ref or `currentColor` resolves to a concrete color at paint time
+	// (and stays theme-reactive under [data-mode]), so it means "use this color", not
+	// "map the field with this name" — pass it straight through to fill/stroke.
+	if (/^var\(\s*--/.test(value)) return true
+	if (/^currentcolor$/i.test(value)) return true
 	return false
 }
 
+/**
+ * A color-channel value as a literal CSS color (var()/oklch()/#hex/currentColor),
+ * or undefined when it names a data field. Pair with {@link markEntry}: a literal is
+ * painted directly on every mark; a field is grouped and looked up in the color scale.
+ * @param {unknown} value
+ * @returns {string | undefined}
+ */
+export function literalColor(value) {
+	return isLiteralColor(value) ? /** @type {string} */ (value) : undefined
+}
+
+/**
+ * Resolves the `{fill, stroke}` for one mark. A `literal` color IS the paint for every
+ * mark — applied directly, never grouped as a field or run through the shared `colors`
+ * scale (which holds a single value across all geoms). Otherwise `key` is looked up in
+ * `colors`, falling back to `fallback`.
+ * @param {string | undefined} literal
+ * @param {unknown} key
+ * @param {Map<unknown, {fill: string, stroke: string}> | undefined} colors
+ * @param {{fill: string, stroke: string}} fallback
+ * @returns {{fill: string, stroke: string}}
+ */
+export function markEntry(literal, key, colors, fallback) {
+	if (literal) return { fill: literal, stroke: literal }
+	return colors?.get(key) ?? fallback
+}
+
 /**
  * Extracts distinct values for a given field from the data array.
  * @param {Object[]} data