@rokkit/chart 1.7.0 → 1.8.1

package/README.md

@@ -100,6 +100,19 @@ const dimensions = brewer.getDimensions()
 | `Plot.Grid`   | Background grid lines derived from axis scales.           |
 | `Plot.Legend` | Color legend; clicking items filters the visible series.  |
 
+Every geom is on the namespace too — `Line`, `Area`, `Point`, `Arc`, `Box`, `Violin`, `Jitter`,
+`Heatmap`, `Hexbin`, `Candlestick`, `Waterfall`, `Ribbon`, `Radar`, `Highlight`, `Trend` — plus four
+that annotate the metric plane rather than draw rows:
+
+| Component      | Description                                                                                   |
+| -------------- | --------------------------------------------------------------------------------------------- |
+| `Plot.Rule`    | Reference lines at `x` / `y` values, or `slope` + `intercept`, clipped to the plot.           |
+| `Plot.Region`  | Shaded band (`[lo, hi]`, `null` = open end) or polygon (`points`) in data coordinates.        |
+| `Plot.Hull`    | Padded convex hull around each group of the `fill` / `color` field.                           |
+| `Plot.Contour` | Kernel-density contours per group — rings, or `filled` bands.                                 |
+
+Together they draw architecture charts such as Robert Martin's main sequence — see the Charts guide.
+
 ### `Plot.Root` props
 
 | Prop                | Type               | Default                               | Description                                                           |

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

@@ -3,24 +3,14 @@
 	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 SpecGeoms from './Plot/SpecGeoms.svelte'
+	import DataTable from './Plot/DataTable.svelte'
 	import Highlight from './geoms/Highlight.svelte'
 	import Trend from './geoms/Trend.svelte'
 
@@ -66,6 +56,11 @@
 		axisOrigin?: [number | undefined, number | undefined]
 		/** Nudge an edge-pinned axis outward by N px (Q1 only). Also via `spec.axisOffset`. */
 		axisOffset?: number
+		/** Fix the x domain instead of inferring it from the data — e.g. `[0, 1]` for a metric
+		 *  plane defined by theory, not by where the rows fall. Also via `spec.xDomain`. */
+		xDomain?: unknown[]
+		/** Fix the y domain. Also via `spec.yDomain`. */
+		yDomain?: unknown[]
 		/** Animate marks on data/flip changes (opt-out for e.g. AnimatedPlot, which
 		 *  tweens its own frames). Enabled one frame after the width settles so the
 		 *  initial layout paints un-animated. Default `true`. */
@@ -104,6 +99,8 @@
 		selected = $bindable([]),
 		axisOrigin = undefined,
 		axisOffset = undefined,
+		xDomain = undefined,
+		yDomain = undefined,
 		animate = true,
 		children
 	}: Props = $props()
@@ -111,90 +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,
-			yDomain: spec?.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
-	const GEOM_COMPONENTS = {
-		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
-	}
-
-	function resolveGeomComponent(type: string) {
-		return helpers?.geoms?.[type] ?? GEOM_COMPONENTS[type as keyof typeof GEOM_COMPONENTS]
+		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).
@@ -203,52 +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 -->
-		{#each specGeoms as geomSpec (geomSpec.type)}
-			{@const GeomComponent = resolveGeomComponent(geomSpec.type)}
-			{#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 ?? {})
-					}}
-				/>
-			{/if}
-		{/each}
+		<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}
@@ -256,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}
 
@@ -273,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>
@@ -313,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

@@ -48,6 +48,11 @@ type Props = {
     axisOrigin?: [number | undefined, number | undefined];
     /** Nudge an edge-pinned axis outward by N px (Q1 only). Also via `spec.axisOffset`. */
     axisOffset?: number;
+    /** Fix the x domain instead of inferring it from the data — e.g. `[0, 1]` for a metric
+     *  plane defined by theory, not by where the rows fall. Also via `spec.xDomain`. */
+    xDomain?: unknown[];
+    /** Fix the y domain. Also via `spec.yDomain`. */
+    yDomain?: unknown[];
     /** Animate marks on data/flip changes (opt-out for e.g. AnimatedPlot, which
      *  tweens its own frames). Enabled one frame after the width settles so the
      *  initial layout paints un-animated. Default `true`. */