@rokkit/chart 1.8.0 → 1.8.2

package/dist/Plot/DataTable.svelte

@@ -0,0 +1,54 @@
+<script lang="ts">
+	type Row = Record<string, unknown>
+
+	type Props = {
+		/** The plotted rows. */
+		rows: Row[]
+		/** Column fields, in order (`tableColumns` in lib/plot/spec.js). */
+		columns: string[]
+		/** The chart's title — names the table and becomes its caption. */
+		title?: string
+	}
+
+	let { rows, columns, title = '' }: Props = $props()
+</script>
+
+<!-- The chart's data as a table: in the DOM for screen readers, never visible. -->
+{#if rows.length > 0 && columns.length > 0}
+	<table class="plot-sr-table" aria-label={title || 'Chart data'}>
+		{#if title}
+			<caption>{title}</caption>
+		{/if}
+		<thead>
+			<tr>
+				{#each columns as col (col)}
+					<th scope="col">{col}</th>
+				{/each}
+			</tr>
+		</thead>
+		<tbody>
+			{#each rows as row, i (i)}
+				<tr>
+					{#each columns as col (col)}
+						<td>{row[col] ?? ''}</td>
+					{/each}
+				</tr>
+			{/each}
+		</tbody>
+	</table>
+{/if}
+
+<style>
+	/* Visually hidden — in DOM for screen readers, not visible */
+	.plot-sr-table {
+		position: absolute;
+		width: 1px;
+		height: 1px;
+		padding: 0;
+		margin: -1px;
+		overflow: hidden;
+		clip: rect(0, 0, 0, 0);
+		white-space: nowrap;
+		border: 0;
+	}
+</style>

package/dist/Plot/DataTable.svelte.d.ts

@@ -0,0 +1,12 @@
+type Row = Record<string, unknown>;
+type Props = {
+    /** The plotted rows. */
+    rows: Row[];
+    /** Column fields, in order (`tableColumns` in lib/plot/spec.js). */
+    columns: string[];
+    /** The chart's title — names the table and becomes its caption. */
+    title?: string;
+};
+declare const DataTable: import("svelte").Component<Props, {}, "">;
+type DataTable = ReturnType<typeof DataTable>;
+export default DataTable;

package/dist/Plot/SpecGeoms.svelte

@@ -0,0 +1,78 @@
+<script lang="ts">
+	import type { Component } from 'svelte'
+	import type { PlotSpec, PlotHelpers } from '../lib/plot/types.js'
+	import { specGeomProps } from '../lib/plot/spec.js'
+	import Bar from '../geoms/Bar.svelte'
+	import Line from '../geoms/Line.svelte'
+	import Area from '../geoms/Area.svelte'
+	import Point from '../geoms/Point.svelte'
+	import Arc from '../geoms/Arc.svelte'
+	import Box from '../geoms/Box.svelte'
+	import Violin from '../geoms/Violin.svelte'
+	import Heatmap from '../geoms/Heatmap.svelte'
+	import Candlestick from '../geoms/Candlestick.svelte'
+	import Waterfall from '../geoms/Waterfall.svelte'
+	import Hexbin from '../geoms/Hexbin.svelte'
+	import Ribbon from '../geoms/Ribbon.svelte'
+	import Radar from '../geoms/Radar.svelte'
+	import Rule from '../geoms/Rule.svelte'
+	import Region from '../geoms/Region.svelte'
+	import Hull from '../geoms/Hull.svelte'
+	import Contour from '../geoms/Contour.svelte'
+
+	type Props = {
+		/** The chart spec; its `geoms` are drawn, and its channels are what each one inherits. */
+		spec?: PlotSpec
+		/** `helpers.geoms` replaces a built-in (or an annotation) by type name. */
+		helpers?: PlotHelpers
+	}
+
+	let { spec = undefined, helpers = {} }: Props = $props()
+
+	// Geom component resolver for spec-driven mode. Typed as a lookup table, not the union of
+	// its members: a spec names geoms by string at runtime, exactly like `helpers.geoms`, and the
+	// union of every geom's Props has no single shape a generic call site can satisfy.
+	// `any` is the honest type for a heterogeneous table resolved by name — the same one the
+	// public `PlotHelpers.geoms` already declares in lib/plot/types.js.
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	const GEOM_COMPONENTS: Record<string, Component<any>> = {
+		bar: Bar,
+		line: Line,
+		area: Area,
+		point: Point,
+		arc: Arc,
+		box: Box,
+		violin: Violin,
+		heatmap: Heatmap,
+		candlestick: Candlestick,
+		waterfall: Waterfall,
+		hexbin: Hexbin,
+		ribbon: Ribbon,
+		// Radar reads the generic x/y/color this path passes via its own aliases, and takes
+		// its axis order from `options.axes` — see Radar.svelte's Props.
+		radar: Radar,
+		hull: Hull,
+		contour: Contour
+	}
+
+	// Plane annotations read no data, so they take ONLY their own `props` — never the spec's
+	// field channels: a Region's `x`/`y` are ranges, and handing it the field name 'instability'
+	// would be a range of one string. A helper registered under the same name is a geom again.
+	const ANNOTATIONS = { rule: Rule, region: Region }
+
+	function resolveGeomComponent(type: string) {
+		return helpers?.geoms?.[type] ?? GEOM_COMPONENTS[type]
+	}
+</script>
+
+<!-- Keyed by position, not type: two regions in one spec are normal, and a type key would be a
+     duplicate that aborts the whole render. An unknown type renders nothing. -->
+{#each spec?.geoms ?? [] as geomSpec, i (`${geomSpec.type}-${i}`)}
+	{@const Annotation = ANNOTATIONS[geomSpec.type as keyof typeof ANNOTATIONS]}
+	{@const GeomComponent = resolveGeomComponent(geomSpec.type)}
+	{#if Annotation && !helpers?.geoms?.[geomSpec.type]}
+		<Annotation {...geomSpec.props ?? {}} />
+	{:else if GeomComponent}
+		<GeomComponent {...specGeomProps(geomSpec, spec)} />
+	{/if}
+{/each}

package/dist/Plot/SpecGeoms.svelte.d.ts

@@ -0,0 +1,11 @@
+import type { Component } from 'svelte';
+import type { PlotSpec, PlotHelpers } from '../lib/plot/types.js';
+type Props = {
+    /** The chart spec; its `geoms` are drawn, and its channels are what each one inherits. */
+    spec?: PlotSpec;
+    /** `helpers.geoms` replaces a built-in (or an annotation) by type name. */
+    helpers?: PlotHelpers;
+};
+declare const SpecGeoms: Component<Props, {}, "">;
+type SpecGeoms = ReturnType<typeof SpecGeoms>;
+export default SpecGeoms;

package/dist/Plot.svelte

@@ -1,30 +1,16 @@
 <script lang="ts">
 	import { getContext } from 'svelte'
-	import type { Component, Snippet } from 'svelte'
+	import type { Snippet } from 'svelte'
 	import { defaultPreset } from './lib/preset.js'
 	import type { PlotSpec, PlotHelpers } from './lib/plot/types.js'
+	import { resolvePlotConfig, resolveChrome, tableColumns } from './lib/plot/spec.js'
 	import PlotSurface from './PlotSurface.svelte'
 	import Axis from './Plot/Axis.svelte'
 	import Grid from './Plot/Grid.svelte'
 	import Legend from './Plot/Legend.svelte'
 	import Tooltip from './Plot/Tooltip.svelte'
-	import Bar from './geoms/Bar.svelte'
-	import Line from './geoms/Line.svelte'
-	import Area from './geoms/Area.svelte'
-	import Point from './geoms/Point.svelte'
-	import Arc from './geoms/Arc.svelte'
-	import Box from './geoms/Box.svelte'
-	import Violin from './geoms/Violin.svelte'
-	import Heatmap from './geoms/Heatmap.svelte'
-	import Candlestick from './geoms/Candlestick.svelte'
-	import Waterfall from './geoms/Waterfall.svelte'
-	import Hexbin from './geoms/Hexbin.svelte'
-	import Ribbon from './geoms/Ribbon.svelte'
-	import Radar from './geoms/Radar.svelte'
-	import Rule from './geoms/Rule.svelte'
-	import Region from './geoms/Region.svelte'
-	import Hull from './geoms/Hull.svelte'
-	import Contour from './geoms/Contour.svelte'
+	import SpecGeoms from './Plot/SpecGeoms.svelte'
+	import DataTable from './Plot/DataTable.svelte'
 	import Highlight from './geoms/Highlight.svelte'
 	import Trend from './geoms/Trend.svelte'
 
@@ -122,102 +108,43 @@
 	const chartPresetCtx = getContext<ChartPresetCtx | undefined>('chart-preset')
 	const chartPreset = $derived(chartPresetCtx?.current ?? defaultPreset)
 
-	const gridValue = $derived(spec?.grid ?? grid)
-	const showGrid = $derived(gridValue !== false)
-	const gridLines = $derived(gridValue === true || gridValue === false ? 'auto' : gridValue)
-	const showLegend = $derived(spec?.legend ?? legend)
-	const chartTitle = $derived(spec?.title ?? title)
-	const chartSummary = $derived(spec?.summary ?? summary)
+	// Spec-over-prop precedence lives in lib/plot/spec.js — one table, not a `??` per field.
+	const chrome = $derived(
+		resolveChrome(spec, { grid, legend, title, summary, x, y })
+	)
 
 	// Accessible data table — screen reader fallback
 	const tableData = $derived(spec?.data ?? data)
-	const tableColumns = $derived.by(() => {
-		// Dedupe: a channel may repeat (e.g. x === color), and the table's keyed each
-		// requires unique column names.
-		const cols = [
-			...new Set(
-				[spec?.x, spec?.y, spec?.color ?? spec?.fill].filter((c): c is string => Boolean(c))
-			)
-		]
-		if (cols.length > 0) return cols
-		const first = tableData[0]
-		return first ? Object.keys(first) : []
-	})
+	const columns = $derived(tableColumns(spec, tableData))
 
 	// Config for the shared PlotSurface (which owns PlotState, the responsive width, context,
 	// animation, patterns, and zoom). `width` is the fallback — PlotSurface observes the container.
 	function buildPlotConfig() {
-		return {
-			data: spec?.data ?? data,
-			width: spec?.width ?? width,
-			height: spec?.height ?? height,
-			mode,
-			margin,
-			channels: spec ? { x: spec.x, y: spec.y, color: spec.color ?? spec.fill } : {},
-			labels: spec?.labels ?? {},
-			helpers,
-			xDomain: spec?.xDomain ?? xDomain,
-			yDomain: spec?.yDomain ?? yDomain,
-			colorDomain: spec?.colorDomain,
-			colorScale: spec?.colorScale,
-			colorScheme: spec?.colorScheme,
-			colorMidpoint: spec?.colorMidpoint,
-			orientation: orientation ?? spec?.orientation,
-			axisOrigin: spec?.axisOrigin ?? axisOrigin,
-			axisOffset: spec?.axisOffset ?? axisOffset,
-			sort: spec?.sort,
-			continuousCategory: spec?.continuousCategory,
-			chartPreset,
-			onselect,
-			selectable
-		}
-	}
-
-	// Geoms from spec (spec-driven API)
-	const specGeoms = $derived(spec?.geoms ?? [])
-
-	const overlayX = $derived(spec?.x ?? x)
-	const overlayY = $derived(spec?.y ?? y)
-
-	// Geom component resolver for spec-driven mode. Typed as a lookup table, not the union of
-	// its members: a spec names geoms by string at runtime, exactly like `helpers.geoms`, and the
-	// union of every geom's Props has no single shape a generic call site can satisfy.
-	// `any` is the honest type for a heterogeneous table resolved by name — the same one the
-	// public `PlotHelpers.geoms` already declares in lib/plot/types.js.
-	// eslint-disable-next-line @typescript-eslint/no-explicit-any
-	const GEOM_COMPONENTS: Record<string, Component<any>> = {
-		bar: Bar,
-		line: Line,
-		area: Area,
-		point: Point,
-		arc: Arc,
-		box: Box,
-		violin: Violin,
-		heatmap: Heatmap,
-		candlestick: Candlestick,
-		waterfall: Waterfall,
-		hexbin: Hexbin,
-		ribbon: Ribbon,
-		// Radar reads the generic x/y/color this path passes via its own aliases, and takes
-		// its axis order from `options.axes` — see Radar.svelte's Props.
-		radar: Radar,
-		hull: Hull,
-		contour: Contour
-	}
-
-	// Plane annotations read no data, so they take ONLY their own `props` — never the spec's
-	// field channels: a Region's `x`/`y` are ranges, and handing it the field name 'instability'
-	// would be a range of one string.
-	const ANNOTATIONS = { rule: Rule, region: Region }
-
-	function resolveGeomComponent(type: string) {
-		return helpers?.geoms?.[type] ?? GEOM_COMPONENTS[type]
+		return resolvePlotConfig(
+			spec,
+			{
+				data,
+				width,
+				height,
+				mode,
+				margin,
+				helpers,
+				xDomain,
+				yDomain,
+				orientation,
+				axisOrigin,
+				axisOffset,
+				onselect,
+				selectable
+			},
+			chartPreset
+		)
 	}
 </script>
 
 <div class="plot-root">
-	{#if chartTitle}
-		<div class="plot-title" data-plot-title>{chartTitle}</div>
+	{#if chrome.title}
+		<div class="plot-title" data-plot-title>{chrome.title}</div>
 	{/if}
 
 	<!-- The shared root shell (PlotState, responsive width, context, animation, patterns, zoom).
@@ -226,57 +153,33 @@
 		config={buildPlotConfig()}
 		{animate}
 		{zoom}
-		ariaLabel={chartTitle || 'Chart visualization'}
-		summary={chartSummary}
+		ariaLabel={chrome.title || 'Chart visualization'}
+		summary={chrome.summary}
 		bind:selected
 	>
 		<!-- Grid (behind everything) -->
-		{#if showGrid}
-			<Grid lines={gridLines} {xTicks} {yTicks} />
+		{#if chrome.showGrid}
+			<Grid lines={chrome.gridLines} {xTicks} {yTicks} />
 		{/if}
 
 		<!-- Declarative children (geom components) -->
 		{@render children?.()}
 
-		<!-- Spec-driven geoms. Keyed by position, not type: two regions in one spec are normal, and
-		     a type key would be a duplicate that aborts the whole render. -->
-		{#each specGeoms as geomSpec, i (`${geomSpec.type}-${i}`)}
-			{@const Annotation = ANNOTATIONS[geomSpec.type as keyof typeof ANNOTATIONS]}
-			{@const GeomComponent = resolveGeomComponent(geomSpec.type)}
-			{#if Annotation && !helpers?.geoms?.[geomSpec.type]}
-				<Annotation {...geomSpec.props ?? {}} />
-			{:else if GeomComponent}
-				<GeomComponent
-					x={geomSpec.x ?? spec?.x}
-					y={geomSpec.y ?? spec?.y}
-					color={geomSpec.color ?? spec?.color}
-					fill={geomSpec.fill ?? spec?.fill}
-					pattern={geomSpec.pattern}
-					symbol={geomSpec.symbol}
-					stat={geomSpec.stat}
-					label={geomSpec.label}
-					options={{
-						...(spec?.stack !== undefined ? { stack: spec.stack } : {}),
-						...(spec?.orientation !== undefined ? { orientation: spec.orientation } : {}),
-						...(geomSpec.options ?? {})
-					}}
-					{...geomSpec.props ?? {}}
-				/>
-			{/if}
-		{/each}
+		<!-- Spec-driven geoms -->
+		<SpecGeoms {spec} {helpers} />
 
 		<!-- Axes -->
 		{#if axes}
 			<Axis
 				type="x"
-				label={spec?.labels?.[spec?.x ?? ''] ?? ''}
+				label={chrome.xLabel}
 				format={xFormat}
 				ticks={xTicks}
 				{minorTicks}
 			/>
 			<Axis
 				type="y"
-				label={spec?.labels?.[spec?.y ?? ''] ?? ''}
+				label={chrome.yLabel}
 				format={yFormat}
 				ticks={yTicks}
 				{minorTicks}
@@ -284,16 +187,16 @@
 		{/if}
 
 		{#if trend !== null && trend !== undefined}
-			<Trend x={overlayX} y={overlayY} {trend} />
+			<Trend x={chrome.overlayX} y={chrome.overlayY} {trend} />
 		{/if}
 
 		{#if (highlight !== null && highlight !== undefined) || selectable || selected.length}
-			<Highlight x={overlayX} y={overlayY} {highlight} {label} />
+			<Highlight x={chrome.overlayX} y={chrome.overlayY} {highlight} {label} />
 		{/if}
 
 		<!-- HTML overlays — outside the svg but INSIDE the plot-state context. -->
 		{#snippet overlay()}
-			{#if showLegend}
+			{#if chrome.showLegend}
 				<Legend labels={spec?.labels ?? {}} />
 			{/if}
 
@@ -301,29 +204,7 @@
 				<Tooltip {tooltip} />
 			{/if}
 
-			{#if tableData.length > 0 && tableColumns.length > 0}
-				<table class="plot-sr-table" aria-label={chartTitle || 'Chart data'}>
-					{#if chartTitle}
-						<caption>{chartTitle}</caption>
-					{/if}
-					<thead>
-						<tr>
-							{#each tableColumns as col (col)}
-								<th scope="col">{col}</th>
-							{/each}
-						</tr>
-					</thead>
-					<tbody>
-						{#each tableData as row, i (i)}
-							<tr>
-								{#each tableColumns as col (col)}
-									<td>{row[col] ?? ''}</td>
-								{/each}
-							</tr>
-						{/each}
-					</tbody>
-				</table>
-			{/if}
+			<DataTable rows={tableData} {columns} title={chrome.title} />
 		{/snippet}
 	</PlotSurface>
 </div>
@@ -341,17 +222,4 @@
 		text-align: center;
 		margin-bottom: 4px;
 	}
-
-	/* Visually hidden — in DOM for screen readers, not visible */
-	.plot-sr-table {
-		position: absolute;
-		width: 1px;
-		height: 1px;
-		padding: 0;
-		margin: -1px;
-		overflow: hidden;
-		clip: rect(0, 0, 0, 0);
-		white-space: nowrap;
-		border: 0;
-	}
 </style>

package/dist/Plot.svelte.d.ts

@@ -1,4 +1,4 @@
-import type { Component, Snippet } from 'svelte';
+import type { Snippet } from 'svelte';
 import type { PlotSpec, PlotHelpers } from './lib/plot/types.js';
 type Row = Record<string, unknown>;
 type Method = string | number | {
@@ -59,6 +59,6 @@ type Props = {
     animate?: boolean;
     children?: Snippet;
 };
-declare const Plot: Component<Props, {}, "selected">;
+declare const Plot: import("svelte").Component<Props, {}, "selected">;
 type Plot = ReturnType<typeof Plot>;
 export default Plot;

package/dist/geoms/Arc.svelte

@@ -55,7 +55,7 @@
 {#if arcs.length > 0}
 	<g data-plot-geom="arc" transform="translate({w / 2}, {h / 2})">
 		<!-- svelte-ignore a11y_no_noninteractive_tabindex -->
-		{#each arcs as arc (arc.key)}
+		{#each arcs as arc (arc.id)}
 			<path
 				d={arc.d}
 				fill={arc.fill}

package/dist/geoms/Bar.svelte

@@ -91,26 +91,22 @@
 	const effectiveOrientation = $derived(options.orientation ?? plotState.orientation)
 	const seriesField = $derived(fill ?? color)
 
-	let dimmedByKey = $state<Record<string, boolean>>({})
-
-	$effect(() => {
-		if (!cf) {
-			dimmedByKey = {}
-			return
-		}
-		// cf.version is a $state counter that increments on every filter mutation.
-		// Reading it here establishes a reactive dependency so the effect re-runs
-		// whenever any filter changes — including changes from sibling FilterBars.
+	/** Bars the crossfilter dims, by key. A derivation, so it needs no effect writing state. */
+	const dimmedByKey = $derived.by((): Record<string, boolean> => {
+		if (!cf) return {}
+		// cf.version is a $state counter that increments on every filter mutation. Reading it
+		// makes this re-derive whenever any filter changes — including a sibling FilterBar's.
 		void cf.version
-		const next: Record<string, boolean> = {}
+		const dimmed: Record<string, boolean> = {}
 		for (const bar of bars) {
-			const dimmedByX = x ? cf.isDimmed(x, bar.data[x]) : false
-			const dimmedByY = y ? cf.isDimmed(y, bar.data[y]) : false
-			next[bar.key] = dimmedByX || dimmedByY
+			dimmed[bar.key] = (x ? cf.isDimmed(x, bar.data[x]) : false) || (y ? cf.isDimmed(y, bar.data[y]) : false)
 		}
-		dimmedByKey = next
+		return dimmed
 	})
 
+	/** Whether a bar takes clicks and keys at all. */
+	const activatable = $derived(filterable || Boolean(onselect) || keyboard || plotState.interactive)
+
 	function handleBarClick(barX: unknown) {
 		if (!filterable || !x || !cf) return
 		cf.toggleCategorical(x, barX)
@@ -130,20 +126,19 @@
 			)
 	}
 
-	function handleBarActivate(bar: { data: Row }, event: MouseEvent) {
+	/**
+	 * A bar activated by click, Enter or Space. A filterable bar FILTERS — it does not also emit
+	 * `onselect`, the rule the keyboard path always had and a click did not; otherwise it
+	 * selects. The plot-level selection (`selectBar`) runs either way.
+	 */
+	function activate(bar: { data: Row }, event: MouseEvent | KeyboardEvent) {
 		if (filterable && x) handleBarClick(bar.data[x])
-		onselect?.(bar.data)
+		else onselect?.(bar.data)
 		selectBar(bar, event)
 	}
 
 	function handleBarKeyActivate(bar: { data: Row }, event: KeyboardEvent) {
-		if (event.key !== 'Enter' && event.key !== ' ') return
-		if (filterable && x) {
-			handleBarClick(bar.data[x])
-		} else {
-			onselect?.(bar.data)
-		}
-		selectBar(bar, event)
+		if (event.key === 'Enter' || event.key === ' ') activate(bar, event)
 	}
 </script>
 
@@ -165,14 +160,10 @@
 				data-plot-category={bar.data[x ?? '']}
 				data-dimmed={dimmedByKey[bar.key] ? true : undefined}
 				style:cursor={filterable || onselect || plotState.interactive ? 'pointer' : undefined}
-				onclick={filterable || onselect || keyboard || plotState.interactive
-					? (e) => handleBarActivate(bar, e)
-					: undefined}
-				onkeydown={filterable || onselect || keyboard || plotState.interactive
-					? (e) => handleBarKeyActivate(bar, e)
-					: undefined}
-				role={filterable || onselect || keyboard || plotState.interactive ? 'button' : 'graphics-symbol'}
-				tabindex={filterable || onselect || keyboard || plotState.interactive ? 0 : undefined}
+				onclick={activatable ? (e) => activate(bar, e) : undefined}
+				onkeydown={activatable ? (e) => handleBarKeyActivate(bar, e) : undefined}
+				role={activatable ? 'button' : 'graphics-symbol'}
+				tabindex={activatable ? 0 : undefined}
 				use:keyboardNav={keyboard}
 				aria-label="{bar.data[x ?? '']}: {bar.data[y ?? '']}"
 				onmouseenter={() => plotState.setHovered(bar.data)}

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

@@ -13,6 +13,7 @@ export function buildArcMarks({ data, plot, channels, options, alpha, type }: {
     type?: string;
 }): {
     alpha: number;
+    id: string;
     d: string | null;
     fill: string;
     stroke: string;

package/dist/lib/brewing/marks/arcs.d.ts

@@ -7,7 +7,11 @@
  * @param {number} height
  * @param {{ innerRadius?: number }} opts
  * @param {Map<unknown, string>} [patterns]
- * @returns {{ d: string | null, fill: string, stroke: string, key: unknown, patternId: string | null, pct: number, centroid: [number, number], data: Record<string, unknown> }[]}
+ * `key` is the slice's category — what picks its colour and pattern — so it repeats when rows
+ * share a category, and is undefined without a colour field. `id` is unique per slice (the key
+ * plus its occurrence), for keyed rendering; stable across updates while categories are unique.
+ *
+ * @returns {{ id: string, d: string | null, fill: string, stroke: string, key: unknown, patternId: string | null, pct: number, centroid: [number, number], data: Record<string, unknown> }[]}
  */
 export function buildArcs(data: Record<string, unknown>[], channels: {
     color?: string;
@@ -16,6 +20,7 @@ export function buildArcs(data: Record<string, unknown>[], channels: {
 }, colors: Map<any, any>, width: number, height: number, opts?: {
     innerRadius?: number;
 }, patterns?: Map<unknown, string>): {
+    id: string;
     d: string | null;
     fill: string;
     stroke: string;

package/dist/lib/brewing/marks/arcs.js

@@ -11,7 +11,11 @@ import { literalColor, markEntry } from '../colors.js'
  * @param {number} height
  * @param {{ innerRadius?: number }} opts
  * @param {Map<unknown, string>} [patterns]
- * @returns {{ d: string | null, fill: string, stroke: string, key: unknown, patternId: string | null, pct: number, centroid: [number, number], data: Record<string, unknown> }[]}
+ * `key` is the slice's category — what picks its colour and pattern — so it repeats when rows
+ * share a category, and is undefined without a colour field. `id` is unique per slice (the key
+ * plus its occurrence), for keyed rendering; stable across updates while categories are unique.
+ *
+ * @returns {{ id: string, d: string | null, fill: string, stroke: string, key: unknown, patternId: string | null, pct: number, centroid: [number, number], data: Record<string, unknown> }[]}
  */
 export function buildArcs(data, channels, colors, width, height, opts = {}, patterns) {
 	const { color: lf, y: yf } = channels
@@ -32,6 +36,7 @@ export function buildArcs(data, channels, colors, width, height, opts = {}, patt
 	// Label radius: midpoint between inner and outer (or 70% out for solid pie)
 	const labelRadius = innerRadius > 0 ? (innerRadius + radius) / 2 : radius * 0.65
 	const labelArc = arc().innerRadius(labelRadius).outerRadius(labelRadius)
+	const seen = new Map()
 	return slices.map((slice, i) => {
 		// With a literal color there's no category field, so key each slice by index to keep
 		// them distinct (patterns, which are field-keyed, don't apply to a single literal fill).
@@ -41,7 +46,10 @@ export function buildArcs(data, channels, colors, width, height, opts = {}, patt
 			!lit && key !== null && key !== undefined && patterns?.has(key) ? toPatternId(String(key)) : null
 		const pct = Math.round(((slice.endAngle - slice.startAngle) / total) * 100)
 		const [cx, cy] = labelArc.centroid(slice)
+		const occurrence = seen.get(key) ?? 0
+		seen.set(key, occurrence + 1)
 		return {
+			id: `${String(key)}#${occurrence}`,
 			d: arcGen(slice),
 			fill: colorEntry.fill,
 			stroke: colorEntry.stroke,

package/dist/lib/brewing/polar.js

@@ -43,11 +43,15 @@
  * Fills in the derived fields shared by every axis, regardless of which of the two
  * accepted shorthand forms it started from.
  *
- * @param {string|AxisSpec} entry
+ * Only an object is an AxisSpec; any other value — a string, or a number / boolean category
+ * read from the data — is the axis key itself. (Treating every non-string as a spec spread a
+ * numeric category into `{}`, keying every numeric axis `undefined`.)
+ *
+ * @param {string|number|AxisSpec} entry
  * @returns {ResolvedAxis}
  */
 function normaliseAxis(entry) {
-	const spec = typeof entry === 'string' ? { key: entry } : entry
+	const spec = typeof entry === 'object' ? entry : { key: entry }
 	const label = spec.label ?? spec.key
 	return {
 		...spec,
@@ -101,7 +105,8 @@ function axisKeysInData(data, axisField) {
 	const seen = new Set()
 	for (const row of data) {
 		const key = row?.[axisField]
-		if (key !== undefined) seen.add(key)
+		// A missing category — undefined or null — names no axis.
+		if (key !== undefined && key !== null) seen.add(key)
 	}
 	return [...seen]
 }

package/dist/lib/plot/spec.d.ts

@@ -0,0 +1,59 @@
+/**
+ * The config `PlotSurface` builds its `PlotState` from.
+ *
+ * @param {Record<string, any> | undefined} spec
+ * @param {Record<string, any>} props - the component's props
+ * @param {unknown} chartPreset - the resolved preset (context, else the default)
+ */
+export function resolvePlotConfig(spec: Record<string, any> | undefined, props: Record<string, any>, chartPreset: unknown): {
+    [k: string]: any;
+};
+/**
+ * The chrome around the marks: grid, legend, title, summary, axis labels, and the fields the
+ * trend / highlight overlays draw on.
+ *
+ * `grid`: `false` hides it; `true` is 'auto'; `'x' | 'y' | 'both'` names the lines.
+ *
+ * @param {Record<string, any> | undefined} spec
+ * @param {Record<string, any>} props
+ */
+export function resolveChrome(spec: Record<string, any> | undefined, props: Record<string, any>): {
+    showGrid: boolean;
+    gridLines: any;
+    showLegend: any;
+    title: any;
+    summary: any;
+    overlayX: any;
+    overlayY: any;
+    xLabel: any;
+    yLabel: any;
+};
+/**
+ * The accessible table's columns: the spec's channels (deduped — a table's keyed each needs
+ * unique names, and `x === color` is normal), else the first row's keys.
+ *
+ * @param {Record<string, any> | undefined} spec
+ * @param {Record<string, unknown>[]} rows
+ * @returns {string[]}
+ */
+export function tableColumns(spec: Record<string, any> | undefined, rows: Record<string, unknown>[]): string[];
+/**
+ * The props for one `spec.geoms` entry: the spec's channels unless the geom names its own,
+ * the spec's stack / orientation under the geom's options, and the geom's `props` over all.
+ *
+ * @param {Record<string, any>} geomSpec
+ * @param {Record<string, any> | undefined} spec
+ */
+export function specGeomProps(geomSpec: Record<string, any>, spec: Record<string, any> | undefined): any;
+/**
+ * The PlotState config fields read straight from spec and/or props, in config order.
+ * @type {Array<[string, keyof typeof SOURCES]>}
+ */
+export const PLOT_CONFIG_FIELDS: Array<[string, keyof typeof SOURCES]>;
+declare namespace SOURCES {
+    function spec(key: any, spec: any): any;
+    function prop(key: any, _spec: any, props: any): any;
+    function specFirst(key: any, spec: any, props: any): any;
+    function propFirst(key: any, spec: any, props: any): any;
+}
+export {};

package/dist/lib/plot/spec.js

@@ -0,0 +1,131 @@
+/**
+ * How `PlotChart` reads its inputs: a `spec` object and component props, which overlap.
+ *
+ * The rule is "a spec value overrides its prop", with one declared exception — `orientation`,
+ * where the prop wins so a wrapper can force direction over a shared spec. Written as a table
+ * so the exception is visible rather than one `??` in twenty turned the other way. Pure: the
+ * component derives from these, and they are tested without rendering.
+ */
+
+/** Where a config field comes from. A null/undefined value falls through to the other source. */
+const SOURCES = {
+	spec: (key, spec) => spec?.[key],
+	prop: (key, _spec, props) => props[key],
+	specFirst: (key, spec, props) => spec?.[key] ?? props[key],
+	propFirst: (key, spec, props) => props[key] ?? spec?.[key]
+}
+
+/**
+ * The PlotState config fields read straight from spec and/or props, in config order.
+ * @type {Array<[string, keyof typeof SOURCES]>}
+ */
+export const PLOT_CONFIG_FIELDS = [
+	['data', 'specFirst'],
+	['width', 'specFirst'],
+	['height', 'specFirst'],
+	['mode', 'prop'],
+	['margin', 'prop'],
+	['helpers', 'prop'],
+	['xDomain', 'specFirst'],
+	['yDomain', 'specFirst'],
+	['colorDomain', 'spec'],
+	['colorScale', 'spec'],
+	['colorScheme', 'spec'],
+	['colorMidpoint', 'spec'],
+	['orientation', 'propFirst'],
+	['axisOrigin', 'specFirst'],
+	['axisOffset', 'specFirst'],
+	['sort', 'spec'],
+	['continuousCategory', 'spec'],
+	['onselect', 'prop'],
+	['selectable', 'prop']
+]
+
+/**
+ * The config `PlotSurface` builds its `PlotState` from.
+ *
+ * @param {Record<string, any> | undefined} spec
+ * @param {Record<string, any>} props - the component's props
+ * @param {unknown} chartPreset - the resolved preset (context, else the default)
+ */
+export function resolvePlotConfig(spec, props, chartPreset) {
+	const config = Object.fromEntries(
+		PLOT_CONFIG_FIELDS.map(([key, source]) => [key, SOURCES[source](key, spec, props)])
+	)
+	// A spec names its channels; the prop-driven form has none here (children declare them).
+	config.channels = spec ? { x: spec.x, y: spec.y, color: spec.color ?? spec.fill } : {}
+	config.labels = spec?.labels ?? {}
+	config.chartPreset = chartPreset
+	return config
+}
+
+/** An axis label: the spec's label for the field on that axis, else blank. */
+const axisLabel = (spec, field) => spec?.labels?.[field ?? ''] ?? ''
+
+/**
+ * The chrome around the marks: grid, legend, title, summary, axis labels, and the fields the
+ * trend / highlight overlays draw on.
+ *
+ * `grid`: `false` hides it; `true` is 'auto'; `'x' | 'y' | 'both'` names the lines.
+ *
+ * @param {Record<string, any> | undefined} spec
+ * @param {Record<string, any>} props
+ */
+export function resolveChrome(spec, props) {
+	const grid = spec?.grid ?? props.grid
+	return {
+		showGrid: grid !== false,
+		gridLines: typeof grid === 'boolean' ? 'auto' : grid,
+		showLegend: spec?.legend ?? props.legend,
+		title: spec?.title ?? props.title,
+		summary: spec?.summary ?? props.summary,
+		overlayX: spec?.x ?? props.x,
+		overlayY: spec?.y ?? props.y,
+		xLabel: axisLabel(spec, spec?.x),
+		yLabel: axisLabel(spec, spec?.y)
+	}
+}
+
+/**
+ * The accessible table's columns: the spec's channels (deduped — a table's keyed each needs
+ * unique names, and `x === color` is normal), else the first row's keys.
+ *
+ * @param {Record<string, any> | undefined} spec
+ * @param {Record<string, unknown>[]} rows
+ * @returns {string[]}
+ */
+export function tableColumns(spec, rows) {
+	const channels = [spec?.x, spec?.y, spec?.color ?? spec?.fill].filter(Boolean)
+	if (channels.length > 0) return [...new Set(channels)]
+	return rows[0] ? Object.keys(rows[0]) : []
+}
+
+/** Spec-level options every geom inherits — only when the spec sets them. */
+function inheritedOptions(spec) {
+	const options = {}
+	if (spec?.stack !== undefined) options.stack = spec.stack
+	if (spec?.orientation !== undefined) options.orientation = spec.orientation
+	return options
+}
+
+/**
+ * The props for one `spec.geoms` entry: the spec's channels unless the geom names its own,
+ * the spec's stack / orientation under the geom's options, and the geom's `props` over all.
+ *
+ * @param {Record<string, any>} geomSpec
+ * @param {Record<string, any> | undefined} spec
+ */
+export function specGeomProps(geomSpec, spec) {
+	return {
+		x: geomSpec.x ?? spec?.x,
+		y: geomSpec.y ?? spec?.y,
+		color: geomSpec.color ?? spec?.color,
+		fill: geomSpec.fill ?? spec?.fill,
+		pattern: geomSpec.pattern,
+		symbol: geomSpec.symbol,
+		stat: geomSpec.stat,
+		label: geomSpec.label,
+		options: { ...inheritedOptions(spec), ...(geomSpec.options ?? {}) },
+		...(geomSpec.props ?? {})
+	}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rokkit/chart",
-  "version": "1.8.0",
+  "version": "1.8.2",
   "type": "module",
   "description": "Data-driven chart components",
   "repository": {