@rokkit/chart 1.3.7 → 1.3.8

package/dist/Plot.svelte

@@ -1,14 +1,13 @@
 <script lang="ts">
-	import { setContext, getContext, untrack } from 'svelte'
+	import { getContext } from 'svelte'
 	import type { Snippet } from 'svelte'
-	import { PlotState } from './PlotState.svelte.js'
 	import { defaultPreset } from './lib/preset.js'
 	import type { PlotSpec, PlotHelpers } from './lib/plot/types.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 DefinePatterns from './patterns/DefinePatterns.svelte'
 	import Bar from './geoms/Bar.svelte'
 	import Line from './geoms/Line.svelte'
 	import Area from './geoms/Area.svelte'
@@ -57,6 +56,10 @@
 		onselect?: (detail: unknown) => void
 		selectable?: boolean
 		selected?: Row[]
+		/** 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`. */
+		animate?: boolean
 		children?: Snippet
 	}
 
@@ -66,7 +69,7 @@
 		helpers = {},
 		width = 600,
 		height = 400,
-		mode = 'light',
+		mode = undefined,
 		grid = true,
 		axes = true,
 		margin = undefined,
@@ -88,29 +91,13 @@
 		onselect = undefined,
 		selectable = false,
 		selected = $bindable([]),
+		animate = true,
 		children
 	}: Props = $props()
 
 	const chartPresetCtx = getContext<ChartPresetCtx | undefined>('chart-preset')
 	const chartPreset = $derived(chartPresetCtx?.current ?? defaultPreset)
 
-	// Responsive width: observe container and use actual pixel width for scale calculations
-	let svgEl = $state<SVGSVGElement | null>(null)
-	let containerEl = $state<HTMLDivElement | null>(null)
-	let observedWidth = $state(0)
-
-	$effect(() => {
-		if (!containerEl) return
-		const ro = new ResizeObserver((entries) => {
-			const w = Math.floor(entries[0].contentRect.width)
-			if (w > 0) observedWidth = w
-		})
-		ro.observe(containerEl)
-		return () => ro.disconnect()
-	})
-
-	const effectiveWidth = $derived(observedWidth > 0 ? observedWidth : (spec?.width ?? width))
-	const svgHeight = $derived(spec?.height ?? height)
 	const gridValue = $derived(spec?.grid ?? grid)
 	const showGrid = $derived(gridValue !== false)
 	const gridLines = $derived(
@@ -123,18 +110,22 @@
 	// Accessible data table — screen reader fallback
 	const tableData = $derived(spec?.data ?? data)
 	const tableColumns = $derived.by(() => {
-		const cols = [spec?.x, spec?.y, spec?.color ?? spec?.fill].filter(
-			(c): c is string => Boolean(c)
-		)
+		// 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) : []
 	})
 
+	// 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: effectiveWidth,
+			width: spec?.width ?? width,
 			height: spec?.height ?? height,
 			mode,
 			margin,
@@ -148,60 +139,14 @@
 			colorScheme: spec?.colorScheme,
 			colorMidpoint: spec?.colorMidpoint,
 			orientation: spec?.orientation,
+			sort: spec?.sort,
+			continuousCategory: spec?.continuousCategory,
 			chartPreset,
 			onselect,
 			selectable
 		}
 	}
 
-	// Create PlotState with initial values and provide as context.
-	// untrack() suppresses "captures initial value" warnings — intentional:
-	// the $effect below handles all subsequent reactive updates.
-	const plotState = untrack(() => new PlotState(buildPlotConfig()))
-	setContext('plot-state', plotState)
-
-	// Keep state in sync when reactive config changes
-	$effect(() => {
-		plotState.update(buildPlotConfig())
-	})
-
-	// external control → state
-	$effect(() => {
-		plotState.setSelected(selected)
-	})
-	// clicks (state) → prop, guarded to avoid an update loop
-	$effect(() => {
-		const rows = plotState.selectedRows
-		const same = rows.length === selected.length && rows.every((r, i) => r === selected[i])
-		if (!same) selected = rows
-	})
-
-	$effect(() => {
-		if (!zoom || !svgEl) return
-		// d3-zoom/d3-selection are client-only; load them dynamically so they are
-		// not bundled into (and tree-shaken-as-unused from) the SSR/main bundle.
-		let cancelled = false
-		let detach: (() => void) | undefined
-		Promise.all([import('d3-zoom'), import('d3-selection')]).then(
-			([{ zoom: d3Zoom }, { select }]) => {
-				if (cancelled || !svgEl) return
-				const zoomBehavior = d3Zoom<SVGSVGElement, unknown>()
-					.scaleExtent([1, 8])
-					.on('zoom', (event) => {
-						plotState.applyZoom(event.transform)
-					})
-				const sel = select(svgEl)
-				sel.call(zoomBehavior)
-				detach = () => sel.on('.zoom', null)
-			}
-		)
-		return () => {
-			cancelled = true
-			detach?.()
-			plotState.resetZoom()
-		}
-	})
-
 	// Geoms from spec (spec-driven API)
 	const specGeoms = $derived(spec?.geoms ?? [])
 
@@ -229,111 +174,100 @@
 	}
 </script>
 
-<div class="plot-root" data-plot-root data-mode={mode} bind:this={containerEl}>
+<div class="plot-root">
 	{#if chartTitle}
 		<div class="plot-title" data-plot-title>{chartTitle}</div>
 	{/if}
 
-	<svg
-		bind:this={svgEl}
-		width={effectiveWidth}
-		height={svgHeight}
-		viewBox="0 0 {effectiveWidth} {svgHeight}"
-		role="img"
-		aria-label={chartTitle || 'Chart visualization'}
-		style:cursor={zoom ? 'grab' : undefined}
+	<!-- The shared root shell (PlotState, responsive width, context, animation, patterns, zoom).
+	     The batteries below (grid/axes/geoms/overlays) render inside its canvas via context. -->
+	<PlotSurface
+		config={buildPlotConfig()}
+		{animate}
+		{zoom}
+		ariaLabel={chartTitle || 'Chart visualization'}
+		summary={chartSummary}
+		bind:selected
 	>
-		{#if chartSummary}
-			<desc>{chartSummary}</desc>
+		<!-- Grid (behind everything) -->
+		{#if showGrid}
+			<Grid lines={gridLines} {xTicks} {yTicks} />
 		{/if}
-		<!-- SVG pattern defs -->
-		<DefinePatterns />
 
-		<g
-			class="plot-canvas"
-			transform="translate({plotState.margin.left}, {plotState.margin.top})"
-			data-plot-canvas
-		>
-			<!-- Grid (behind everything) -->
-			{#if showGrid}
-				<Grid lines={gridLines} {xTicks} {yTicks} />
+		<!-- 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}
 
-			<!-- Declarative children (geom components) -->
-			{@render children?.()}
+		<!-- Axes -->
+		{#if axes}
+			<Axis type="x" label={spec?.labels?.[spec?.x ?? ''] ?? ''} format={xFormat} ticks={xTicks} {minorTicks} />
+			<Axis type="y" label={spec?.labels?.[spec?.y ?? ''] ?? ''} format={yFormat} ticks={yTicks} {minorTicks} />
+		{/if}
 
-			<!-- 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}
+		{#if trend !== null && trend !== undefined}
+			<Trend x={overlayX} y={overlayY} {trend} />
+		{/if}
 
-			<!-- Axes -->
-			{#if axes}
-				<Axis type="x" label={spec?.labels?.[spec?.x ?? ''] ?? ''} format={xFormat} ticks={xTicks} {minorTicks} />
-				<Axis type="y" label={spec?.labels?.[spec?.y ?? ''] ?? ''} format={yFormat} ticks={yTicks} {minorTicks} />
-			{/if}
+		{#if (highlight !== null && highlight !== undefined) || selectable || selected.length}
+			<Highlight x={overlayX} y={overlayY} {highlight} {label} />
+		{/if}
 
-			{#if trend !== null && trend !== undefined}
-				<Trend x={overlayX} y={overlayY} {trend} />
+		<!-- HTML overlays — outside the svg but INSIDE the plot-state context. -->
+		{#snippet overlay()}
+			{#if showLegend}
+				<Legend labels={spec?.labels ?? {}} />
 			{/if}
 
-			{#if (highlight !== null && highlight !== undefined) || selectable || selected.length}
-				<Highlight x={overlayX} y={overlayY} {highlight} {label} />
+			{#if tooltip}
+				<Tooltip {tooltip} />
 			{/if}
-		</g>
-	</svg>
 
-	<!-- Legend (HTML, outside SVG) -->
-	{#if showLegend}
-		<Legend labels={spec?.labels ?? {}} />
-	{/if}
-
-	<!-- Tooltip (HTML, fixed-position overlay) -->
-	{#if tooltip}
-		<Tooltip {tooltip} />
-	{/if}
-
-	<!-- Accessible data table — visually hidden, announces data to screen readers -->
-	{#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>
+			{#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}
-					</tr>
-				{/each}
-			</tbody>
-		</table>
-	{/if}
+					</tbody>
+				</table>
+			{/if}
+		{/snippet}
+	</PlotSurface>
 </div>
 
 <style>
@@ -343,23 +277,6 @@
 		height: auto;
 	}
 
-	[data-plot-root][data-mode='light'] {
-		color: rgba(var(--color-surface-700, 59, 65, 77), 1);
-	}
-
-	[data-plot-root][data-mode='dark'] {
-		color: rgba(var(--color-surface-200, 224, 224, 224), 1);
-	}
-
-	svg {
-		display: block;
-		overflow: visible;
-	}
-
-	.plot-canvas {
-		pointer-events: all;
-	}
-
 	.plot-title {
 		font-size: 14px;
 		font-weight: 600;

package/dist/Plot.svelte.d.ts

@@ -39,6 +39,10 @@ type Props = {
     onselect?: (detail: unknown) => void;
     selectable?: boolean;
     selected?: Row[];
+    /** 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`. */
+    animate?: boolean;
     children?: Snippet;
 };
 declare const Plot: import("svelte").Component<Props, {}, "selected">;

package/dist/PlotState.svelte.d.ts

@@ -41,6 +41,22 @@ export class PlotState {
         symbols: any;
     };
     get data(): any[];
+    /** @returns {{ x?: string, y?: string, color?: string, pattern?: string, symbol?: string }} */
+    get channels(): {
+        x?: string;
+        y?: string;
+        color?: string;
+        pattern?: string;
+        symbol?: string;
+    };
+    get isFlipped(): boolean;
+    get continuousCategory(): boolean;
+    place(u: any, v: any): {
+        x: any;
+        y: any;
+    };
+    get bandScale(): any;
+    get valueScale(): any;
     get margin(): {
         top: number;
         right: number;

package/dist/PlotState.svelte.js

@@ -17,6 +17,9 @@ import { assignSymbols } from './lib/brewing/marks/points.js'
 
 let nextId = 0
 
+// Geoms that treat the x channel as categorical (band scale), even for numeric x.
+const CATEGORICAL_X = new Set(['bar', 'box', 'violin', 'jitter'])
+
 export class PlotState {
 	#data = $state([])
 	#rawData = $state([])
@@ -43,6 +46,13 @@ export class PlotState {
 	#onselect = $state(undefined)
 	#selectable = $state(false)
 	#orientationOverride = $state(undefined)
+	// When true, the category (x) axis is a CONTINUOUS position scale (kept linear, not
+	// band-forced) — e.g. AnimatedPlot's bar-chart race, whose tweened `_rank` must position
+	// smoothly. It still flips like any category-x chart; buildBars uses continuous positioning.
+	#continuousCategory = $state(false)
+	// Order the category (band) axis by aggregated value instead of by label: 'desc' | 'asc'.
+	// Sorts bars by size (histogram-style); undefined keeps data/label order.
+	#sort = $state(undefined)
 
 	axisOrigin = $state([undefined, undefined])
 	#axisOffset = $state(0)
@@ -53,8 +63,11 @@ export class PlotState {
 	#innerWidth = $derived(this.#width - this.#effectiveMargin.left - this.#effectiveMargin.right)
 	#innerHeight = $derived(this.#height - this.#effectiveMargin.top - this.#effectiveMargin.bottom)
 
-	// Effective channels: prefer top-level channels; fall back to first geom's channels
-	// for the declarative API where no spec is provided.
+	// Effective channels: prefer top-level channels PER FIELD, falling back to the
+	// first geom's channels. Merged per-field (not all-or-nothing) so a composable
+	// <Plot.Root x y> that omits `color` still picks up a geom's color channel
+	// (e.g. <Plot.Box color=x>) — otherwise `colors` has no per-category entries and
+	// every mark falls back to gray.
 	#mergeGeomChannels(tc, geom) {
 		return {
 			x: tc.x ?? geom.channels?.x,
@@ -67,15 +80,32 @@ export class PlotState {
 
 	#effectiveChannels = $derived.by(() => {
 		const tc = this.#channels
-		if (tc.x && tc.y) return tc
 		const firstGeom = this.#geoms[0]
 		if (!firstGeom) return tc
 		return this.#mergeGeomChannels(tc, firstGeom)
 	})
 
 	#resolveXType(rawXType, yType) {
-		const hasBarGeom = this.#geoms.some((g) => g.type === 'bar')
-		return hasBarGeom && rawXType === 'continuous' && yType === 'continuous' ? 'band' : rawXType
+		const hasBandGeom = this.#geoms.some((g) => CATEGORICAL_X.has(g.type))
+		return hasBandGeom && rawXType === 'continuous' && yType === 'continuous' ? 'band' : rawXType
+	}
+
+	// Category order sorted by aggregated value (sum of the value channel per category).
+	// Drives "sort bars by size" for the band axis + its ticks. Returns null when not sorting.
+	#sortedBandDomain(datasets) {
+		if (!this.#sort) return null
+		const xf = this.#effectiveChannels.x
+		const yf = this.#effectiveChannels.y
+		if (!xf || !yf) return null
+		const totals = new Map()
+		for (const ds of datasets) {
+			for (const d of ds) {
+				const key = d[xf]
+				totals.set(key, (totals.get(key) ?? 0) + (Number(d[yf]) || 0))
+			}
+		}
+		const dir = this.#sort === 'asc' ? 1 : -1
+		return [...totals.keys()].sort((a, b) => dir * ((totals.get(a) ?? 0) - (totals.get(b) ?? 0)))
 	}
 
 	orientation = $derived.by(() => {
@@ -89,6 +119,24 @@ export class PlotState {
 		return inferOrientation(this.#resolveXType(rawXType, yType), yType)
 	})
 
+	// True when the x-channel is the categorical (band) axis — a string category, or a numeric
+	// category a bar/box/violin/jitter geom bands (incl. a race's rank via continuousCategory).
+	// Only such charts flip; a plain scatter (both continuous, no banding geom) is false → the
+	// orientation is a no-op for the scales.
+	#bandIsX = $derived.by(() => {
+		const x = this.#effectiveChannels.x
+		const y = this.#effectiveChannels.y
+		if (!x || !y) return false
+		// Resolved type: a bar/box/violin/jitter geom bands a numeric x (e.g. year, week),
+		// so those NUMERIC categories are flippable too — not just string categories.
+		return this.#resolveXType(inferFieldType(this.#data, x), inferFieldType(this.#data, y)) === 'band'
+	})
+
+	// Flip = render a category-on-x chart horizontally: the category (x) axis stands up on the
+	// vertical screen and the value (y) axis runs along the horizontal screen. x/y channels are
+	// unchanged — only the screen mapping rotates.
+	#flipped = $derived(this.orientation === 'horizontal' && this.#bandIsX)
+
 	colorScaleType = $derived.by(() => {
 		const field = this.#effectiveChannels.color
 		if (!field) return 'categorical'
@@ -118,15 +166,30 @@ export class PlotState {
 		if (!field) return null
 		const datasets =
 			this.#geoms.length > 0 ? this.#geoms.map((g) => this.geomData(g.id)) : [this.#rawData]
-		const includeZero = this.orientation === 'horizontal'
-		// For vertical bar charts, force scaleBand even when X values are numeric (e.g. year).
-		// Horizontal bar charts keep X as a continuous value axis.
-		const hasBarGeom = this.#geoms.some((g) => g.type === 'bar')
-		const bandX = hasBarGeom && this.orientation !== 'horizontal'
+		// includeZero applies to the VALUE axis. When flipped, x is the category axis, not
+		// the value axis, so it must NOT include zero.
+		const includeZero = this.orientation === 'horizontal' && !this.#flipped
+		// Force scaleBand when x is the categorical axis (incl. flipped, where numeric categories
+		// must stay a band). Exception: a CONTINUOUS category axis (a bar race's tweened rank) is
+		// kept LINEAR so fractional positions tween smoothly — buildBars positions it directly.
+		const hasBandGeom = this.#geoms.some((g) => CATEGORICAL_X.has(g.type))
+		const bandX =
+			hasBandGeom &&
+			!this.#continuousCategory &&
+			(this.orientation !== 'horizontal' || this.#flipped)
+		// Flip: the category (x) axis stands up on the vertical screen → range over height.
+		const range = this.#flipped ? [this.#innerHeight, 0] : undefined
+		// Sort the band domain by aggregated value when requested (bars by size); an explicit
+		// xDomain override wins.
+		const domain = this.#xDomain ?? (bandX ? this.#sortedBandDomain(datasets) : null) ?? undefined
 		const base = buildUnifiedXScale(datasets, field, this.#innerWidth, {
-			domain: this.#xDomain,
+			domain,
 			includeZero,
-			band: bandX
+			band: bandX,
+			range,
+			// A continuous category axis (bar-race rank) uses a deliberately padded domain —
+			// don't nice() it back to whole numbers.
+			nice: !this.#continuousCategory
 		})
 		return this.#zoomTransform && typeof base?.bandwidth !== 'function'
 			? this.#zoomTransform.rescaleX(base)
@@ -139,8 +202,9 @@ export class PlotState {
 		if (!boxGeom) return null
 		const boxData = this.geomData(boxGeom.id)
 		const isValid = (v) => v !== null && v !== undefined && !isNaN(v)
-		const mins = boxData.map((d) => d.iqr_min).filter(isValid)
-		const maxs = boxData.map((d) => d.iqr_max).filter(isValid)
+		const flatOutliers = boxData.flatMap((d) => d.outliers ?? []).filter(isValid)
+		const mins = [...boxData.map((d) => d.iqr_min).filter(isValid), ...flatOutliers]
+		const maxs = [...boxData.map((d) => d.iqr_max).filter(isValid), ...flatOutliers]
 		return mins.length > 0 && maxs.length > 0 ? [Math.min(...mins), Math.max(...maxs)] : null
 	}
 
@@ -181,9 +245,13 @@ export class PlotState {
 		if (!field) return null
 		const datasets =
 			this.#geoms.length > 0 ? this.#geoms.map((g) => this.geomData(g.id)) : [this.#rawData]
-		const includeZero = this.orientation === 'vertical'
+		// includeZero applies to the VALUE axis: vertical charts (value on y) and flipped
+		// charts (value still y, but now the horizontal screen axis) both want a 0 baseline.
+		const includeZero = this.orientation === 'vertical' || this.#flipped
 		const yDomain = this.#yDomain ?? this.#resolveBoxDomain() ?? this.#resolveStackDomain(field)
-		const base = buildUnifiedYScale(datasets, field, this.#innerHeight, { domain: yDomain, includeZero })
+		// Flip: the value (y) axis runs along the horizontal screen → range over width.
+		const range = this.#flipped ? [0, this.#innerWidth] : undefined
+		const base = buildUnifiedYScale(datasets, field, this.#innerHeight, { domain: yDomain, includeZero, range })
 		return this.#zoomTransform ? this.#zoomTransform.rescaleY(base) : base
 	})
 
@@ -283,6 +351,8 @@ export class PlotState {
 		this.#axisOffset = config.axisOffset ?? 0
 		this.#marginOverride = config.margin ?? undefined
 		this.#orientationOverride = config.orientation ?? undefined
+		this.#continuousCategory = config.continuousCategory ?? false
+		this.#sort = config.sort ?? undefined
 	}
 
 	update(config) {
@@ -309,6 +379,8 @@ export class PlotState {
 		if (config.axisOffset !== undefined) this.#axisOffset = config.axisOffset
 		this.#marginOverride = config.margin ?? undefined
 		this.#orientationOverride = config.orientation ?? undefined
+		this.#continuousCategory = config.continuousCategory ?? false
+		this.#sort = config.sort ?? undefined
 	}
 
 	registerGeom(config) {
@@ -360,6 +432,36 @@ export class PlotState {
 		// array separately, so their elements are not ===. Same content, aligned identity.
 		return this.#rawData
 	}
+	/** @returns {{ x?: string, y?: string, color?: string, pattern?: string, symbol?: string }} */
+	get channels() {
+		return this.#channels
+	}
+
+	// ─── Orientation helpers (horizontal / axis-flip) ──────────────────────────
+	// True when the chart is rendered horizontally (category axis stood up on the
+	// vertical screen, value axis along the horizontal screen). x/y channels unchanged.
+	get isFlipped() {
+		return this.#flipped
+	}
+	// True when the category (x) axis is a continuous position scale (kept linear) rather than a
+	// band — a bar-chart race's tweened rank. buildBars uses continuous positioning for it.
+	get continuousCategory() {
+		return this.#continuousCategory
+	}
+	// Map abstract (x-channel, y-channel) scale outputs to screen coords. When flipped,
+	// the two screen axes swap. Geoms compute u = xScale(d[x]), v = yScale(d[y]) then
+	// `const { x, y } = plotState.place(u, v)`.
+	place(u, v) {
+		return this.#flipped ? { x: v, y: u } : { x: u, y: v }
+	}
+	// The categorical (band) scale and the continuous (value) scale, regardless of
+	// orientation — their ranges are already oriented to the correct screen axis.
+	get bandScale() {
+		return this.#bandIsX ? this.xScale : this.yScale
+	}
+	get valueScale() {
+		return this.#bandIsX ? this.yScale : this.xScale
+	}
 	get margin() {
 		return this.#effectiveMargin
 	}