@fundar/data-chart-telling 0.0.64 → 1.1.0

package/dist/plots/bar/Plot.svelte

@@ -1,446 +1,41 @@
 <script lang="ts" generics="TData extends Record<string, unknown>">
-	import { paletteColor } from '../../utils/color';
-	import { buildSeries } from '../../utils/grouping';
-	import { getLegendInteraction } from '../../layout/legend/interaction.svelte';
-	import {
-		disabledFillOverride,
-		resolveEffectiveDisabledStyle,
-		omitDisabledSeries,
-		buildSeriesColorIndex
-	} from '../utils/legendDisabled';
-	import { SvelteMap } from 'svelte/reactivity';
-	import { resolveAccessor } from '../utils/accessors';
-	import { getConfiguration } from '../../configuration/config.svelte';
-	import {
-		buildGroupedSeries,
-		validateSegments,
-		buildScopedMarkerGroups
-	} from '../utils/segments';
-	import { isGapValue } from '../utils/gaps';
-	import { niceDomain, naturalTickCount } from '../../layout/scales/niceDomain';
-	import { AUTO_MARGIN_ESTIMATE } from '../../layout/plot/margins';
-	import { createBarLayout } from './layout.svelte';
-	import {
-		createLabelMarginTracker,
-		halfDimensionOverflowCap
-	} from '../utils/labelOverflow.svelte';
-	import { estimateValueLabelMargin } from '../utils/valueLabelMargin';
-	import { buildHoverPoints } from './hoverPoints';
-	import { buildBarMarkers } from './buildBarMarkers';
-	import { resolveGapsForSeries, resolveDiscreteGapFills } from '../utils/gaps';
-	import ValueLabels from './ValueLabels.svelte';
-	import BasePlotLayout from '../../layout/plot/BasePlotLayout.svelte';
-	import {
-		hasHoverMarker,
-		resolveHoverStrategy,
-		resolveHoverSync
-	} from '../../layout/tooltip/utils';
-	import type { AxisBasedMarkersConfig } from '../../types/markers/common';
-	import type { BasePlotProps } from '../../types/plots/props';
-	import type { AxisValue, AxisScale, AxisBasedScalesConfig } from '../../types/layout/scales';
-	import type { Series, SeriesProps, DataProps } from '../../types/plots/data/common';
-	import type { GapsAwarePlotStylesConfig } from '../../types/layout/styles';
-	import type { ValueAnchor } from '../../types/plots/constants';
-	import type { BarSegmentStyle } from '../../types/plots/segments/common';
-	import type { LegendDisabledStyle } from '../../types/layout/legend';
-	import type { MarginOverflow } from '../utils/labelOverflow.svelte';
+	import Plot from '../../layout/plot/Plot.svelte';
+	import { buildBarDefaults } from './defaults';
+	import type { BarPlotProps, BarPlotCoreProps } from '../../types/plots/bar/props';
 
 	/**
-	 * A bar chart, vertical by default. Accepts either a pre-built `series`
-	 * array or flat `data/x/y/z` props — mirrors the line/heatmap plot contract
-	 * so the chart-level container/timeline/facet/legend wrap it unchanged.
+	 * A bar plot: vertical when its categories run along `x`, horizontal when they run along `y` (the value then on `x`, as in svelteplot's `BarX`). Draws from pre-built `series` or flat `data` rows.
+	 * Optional chrome (`title`, `subtitle`, `caption`, `header`, `footer`,
+	 * `legend`) frames it; `timeline` and `facet` slice its `data` rows.
 	 */
-	type Props = BasePlotProps<
-		SeriesProps<TData> | DataProps<TData>,
-		TData,
-		GapsAwarePlotStylesConfig<BarSegmentStyle>,
-		BarSegmentStyle,
-		AxisBasedMarkersConfig,
-		AxisBasedScalesConfig<TData>
-	>;
-
 	let {
-		width,
-		height,
-		series,
-		data,
-		x,
-		y,
-		z,
-		styles = {},
-		segments = {},
-		markers = [],
-		scales = {},
-		margins,
-		tooltip = undefined
-	}: Props = $props();
-
-	$effect(() => {
-		validateSegments(segments);
-	});
-
-	const cfg = $derived(getConfiguration());
-	const legendInteraction = $derived(getLegendInteraction());
-	// Unfiltered series list, for stable per-name color indexing.
-	const fullSeries = $derived(series ?? buildSeries(data!, x!, y!, z));
-	const colorIndex = $derived(buildSeriesColorIndex(fullSeries));
-	function colorForSeries(name: string): string {
-		return paletteColor(colorIndex.get(name) ?? 0, cfg.palette);
-	}
-	// Drops series toggled off with `disabled: { mode: 'omit' }`.
-	const resolvedSeries = $derived(omitDisabledSeries(fullSeries, legendInteraction));
-	const groupedSeries = $derived(
-		// connect: false — bars are discrete; there's no visual gap between
-		// adjacent categories to bridge (see buildGroupedSeries's own doc).
-		buildGroupedSeries<Series<TData>, BarSegmentStyle>(resolvedSeries, segments, false)
-	);
-	const showVals = $derived(styles.values?.show ?? false);
-	const formatValue = $derived(styles.values?.format ?? ((v: number) => `${v}`));
-	const valAnchor = $derived<ValueAnchor>(styles.values?.anchor ?? 'outside');
-
-	// Fills leading/internal/trailing missing-data holes with an
-	// interpolated, distinctly-styled bar, resolved per series like
-	// `segments` — see `GapsAwarePlotStylesConfig` (`types/layout/styles.ts`).
-	const gaps = $derived(styles.gaps ?? {});
-	const gapFillMaps = $derived(
-		new Map(
-			resolvedSeries.map((s) => [
-				s.name,
-				resolveDiscreteGapFills(s, resolveGapsForSeries(gaps, s.name))
-			])
-		)
-	);
-
-	// `xAcc`/`yAcc` are always data-semantic (category/value) — independent of
-	// which *visual* axis ends up drawing them, decided by `categoricalAxis`.
-	const xAcc = $derived(resolveAccessor(resolvedSeries[0]?.x ?? ((d: TData) => d)));
-	const yAcc = $derived(resolveAccessor(resolvedSeries[0]?.y ?? ((d: TData) => d)));
-	const flat = $derived(resolvedSeries.flatMap((s) => s.data));
-
-	const scopedGroups = $derived(
-		buildScopedMarkerGroups<TData, Series<TData>, BarSegmentStyle>({
-			groupedSeries,
-			segments,
-			colorFor: (series) => colorForSeries(series.name),
-			segmentColorFor: (style, defaultColor) => style?.fill ?? defaultColor
-		})
-	);
-
-	/**
-	 * Which visual axis draws the category, and therefore whether this renders
-	 * as vertical bars (`BarY`, category on X) or horizontal bars (`BarX`,
-	 * category on Y). Mirrors how pyramid/heatmap default an `AxisScale.type`
-	 * themselves: `scales.x`/`scales.y` always describe *that visual axis*
-	 * regardless of which data field lands there, so marking `scales.y.type:
-	 * 'categorical'` simply says "the category is drawn on Y this time" — x
-	 * defaults to categorical when neither is marked.
-	 */
-	const categoricalAxis = $derived.by((): 'x' | 'y' => {
-		const xCategorical = scales.x?.type === 'categorical';
-		const yCategorical = scales.y?.type === 'categorical';
-		if (xCategorical && yCategorical) {
-			console.warn(
-				"BarPlot: scales.x.type and scales.y.type can't both be 'categorical' — " +
-					'mark only one axis as the category axis. Defaulting to x.'
-			);
-			return 'x';
-		}
-		return yCategorical ? 'y' : 'x';
-	});
-	const isHorizontal = $derived(categoricalAxis === 'y');
-
-	/**
-	 * `'categorical'` is our own sentinel (BarPlot-only), not a real svelteplot
-	 * scale type — svelteplot's x/y scales don't recognise it (it's valid only
-	 * for `color`/`symbol`). Strip it before the scale reaches svelteplot so it
-	 * auto-infers the real type (typically `point`/`band`) the same way it
-	 * already does when `type` is left unset entirely.
-	 */
-	function stripCategoricalType(scale?: AxisScale<TData>): AxisScale<TData> | undefined {
-		if (scale?.type !== 'categorical') return scale;
-		const rest = { ...scale };
-		delete rest.type;
-		return rest;
-	}
-	// Backs the category axis's `paddingInner`/`paddingOuter` — the gap
-	// *between* category groups — with the theme's `bar.paddingInner`/
-	// `paddingOuter` default, when the plot doesn't set its own (or the
-	// `padding` shorthand). BarPlot-only, unlike svelteplot's own hardcoded
-	// 0.15 fallback for every band scale.
-	function withDefaultPadding(scale?: AxisScale<TData>): AxisScale<TData> {
-		return {
-			...scale,
-			paddingInner: scale?.paddingInner ?? scale?.padding ?? cfg.bar.paddingInner,
-			paddingOuter: scale?.paddingOuter ?? scale?.padding ?? cfg.bar.paddingOuter
-		};
-	}
-
-	// Mirrors `createBarLayout`'s own `layout` derivation, read off the raw
-	// `scales` prop rather than `resolvedScales` — `valueExtent`/
-	// `withValueDomain` below feed `resolvedScales`, so reading it back off
-	// `resolvedScales` (or `barLayout.layout`, built from it) would be circular.
-	const seriesLayout = $derived(scales.z?.seriesLayout ?? 'overlap');
-
-	/**
-	 * The value axis's real rendered range — `[0, ...]` for 'grouped'/'overlap'
-	 * (each row's own value, same range `svelteplot`'s own auto-domain would
-	 * find), but for 'stacked' the *per-category total* (every series summed),
-	 * which a plain per-row scan can't see. Needed so `withValueDomain` can
-	 * nice-widen the axis itself instead of deferring to `buildScale`'s
-	 * `nice: true` default, which only ever sees raw per-row values and would
-	 * under-widen a stacked total's real top.
-	 */
-	const valueExtent = $derived.by((): [number, number] | undefined => {
-		let lo = 0;
-		let hi = 0;
-		if (seriesLayout === 'stacked') {
-			const totals = new SvelteMap<AxisValue, number>();
-			for (const s of resolvedSeries) {
-				const sx = resolveAccessor(s.x);
-				const sy = resolveAccessor(s.y);
-				for (const row of s.data) {
-					const raw = sy(row);
-					if (isGapValue(raw)) continue;
-					const cat = sx(row);
-					totals.set(cat, (totals.get(cat) ?? 0) + Number(raw));
-				}
-			}
-			for (const total of totals.values()) {
-				lo = Math.min(lo, total);
-				hi = Math.max(hi, total);
-			}
-		} else {
-			for (const s of resolvedSeries) {
-				const sy = resolveAccessor(s.y);
-				for (const row of s.data) {
-					const raw = sy(row);
-					if (isGapValue(raw)) continue;
-					const v = Number(raw);
-					lo = Math.min(lo, v);
-					hi = Math.max(hi, v);
-				}
-			}
-		}
-		return hi > lo ? [lo, hi] : undefined;
-	});
-
-	/**
-	 * Nice-widens the value axis using `valueExtent` (baseline/stack-aware,
-	 * unlike `buildScale`'s own `nice: true` default) with an epsilon
-	 * tolerance — see `niceDomain` — so a stacked total that's supposed to
-	 * land exactly on a round number (a "parts of a whole" dataset, e.g.
-	 * percentages summing to 100) doesn't get bumped a full step further by
-	 * float noise from summing already-rounded parts. Skipped once the
-	 * caller sets their own `domain`/`ticks`/`nice`.
-	 */
-	function withValueDomain(scale?: AxisScale<TData>): AxisScale<TData> | undefined {
-		if (scale?.domain != null || scale?.ticks != null || scale?.nice != null) return scale;
-		if (!valueExtent) return scale;
-		const [lo, hi] = valueExtent;
-		const spacing = isHorizontal ? 80 : 50;
-		const marginEstimate = isHorizontal
-			? AUTO_MARGIN_ESTIMATE.left + AUTO_MARGIN_ESTIMATE.right
-			: AUTO_MARGIN_ESTIMATE.top + AUTO_MARGIN_ESTIMATE.bottom;
-		const span = Math.max(0, (isHorizontal ? width : height) - marginEstimate);
-		const count = naturalTickCount(span, spacing, 2);
-		return { ...scale, domain: niceDomain(lo, hi, count) };
-	}
-
-	// The single, fully-resolved scales object both BasePlotLayout (ticks,
-	// grid, sort, the real svelteplot scale) and `createBarLayout` (the
-	// grouped-bar-width estimate) read for everything — avoids keeping a
-	// second, separately-patched copy of `scales.x`/`scales.y` in sync with
-	// the one actually forwarded.
-	const resolvedScales = $derived({
-		...scales,
-		x: stripCategoricalType(
-			categoricalAxis === 'x' ? withDefaultPadding(scales.x) : withValueDomain(scales.x)
-		),
-		y: stripCategoricalType(
-			categoricalAxis === 'y' ? withDefaultPadding(scales.y) : withValueDomain(scales.y)
-		)
-	});
-
-	// The accessor feeding each *visual* channel — swapped from the
-	// data-semantic xAcc/yAcc when the category is drawn on Y.
-	const plotGetX = $derived(isHorizontal ? (d: TData) => Number(yAcc(d)) : xAcc);
-	const plotGetY = $derived(isHorizontal ? xAcc : (d: TData) => Number(yAcc(d)));
-
-	/**
-	 * Series-layout geometry (grouped/stacked offsets, band-width estimate,
-	 * value baseline) — the single source of truth shared by bar-segment
-	 * rendering, value labels, and hover markers below. See `layout.svelte.ts`.
-	 */
-	const barLayout = createBarLayout<TData>({
-		scales: () => resolvedScales,
-		isHorizontal: () => isHorizontal,
-		width: () => width,
-		height: () => height,
-		margins: () => margins,
-		flat: () => flat,
-		xAcc: () => xAcc,
-		groupedSeries: () => groupedSeries,
-		gapFillMaps: () => gapFillMaps
-	});
-
-	// `x`/`y` here are visual (matched against BasePlotLayout's own getX/getY,
-	// which drive tick/domain computation and the Pointer's hit-testing) —
-	// `row` (see BasePlotLayout/HoverPoint) is what lets the template recover the
-	// semantic category regardless of which axis it landed on.
-	const hoverIsolate = $derived(styles.values?.hoverIsolate ?? false);
-
-	// A value label hovered while `styles.values.hoverIsolate` is on dims
-	// every other series exactly like a legend toggle would — local to this
-	// one `<Plot>` instance (not the shared HoverStore) so the gesture can't
-	// leak into unrelated tooltip/crosshair behavior.
-	let hoverIsolatedSeries = $state<string | null>(null);
-
-	function effectiveDisabledFor(name: string): LegendDisabledStyle | undefined {
-		return resolveEffectiveDisabledStyle(
-			name,
-			legendInteraction,
-			cfg.legend.disabledOpacity,
-			hoverIsolate,
-			hoverIsolatedSeries
-		);
-	}
-
-	// A legend-disabled series is dimmed on the bar itself, but never surfaces
-	// in hover/tooltip — its points are simply absent from the candidate list.
-	const hoverPoints = $derived(
-		buildHoverPoints(resolvedSeries, isHorizontal, barLayout, colorForSeries).filter(
-			(p) => !legendInteraction?.disabledSeries.has(p.series!)
-		)
-	);
-
-	const hover = $derived({
-		active: tooltip != null || hasHoverMarker(markers),
-		points: hoverPoints,
-		label: (r: TData) => String(yAcc(r)),
-		strategy: resolveHoverStrategy(tooltip?.strategy, markers, categoricalAxis),
-		sync: resolveHoverSync(tooltip?.sync, markers),
+		title,
+		subtitle,
+		caption,
+		header,
+		footer,
+		legend,
+		order,
+		timeline,
+		facet,
 		tooltip,
-		// The category axis is a band scale — `<Pointer>`'s nearest-point-by-
-		// distance match (svelteplot's own projection of each candidate's band
-		// centre) can disagree by a couple of pixels with where `<BarX>`/`<BarY>`
-		// (via svelteplot's `RectPath`) actually render that band, which is
-		// enough to mismatch the neighbouring category once bands get thin
-		// (many categories). The `role: 'hitArea'` bar markers `buildBarMarkers`
-		// emits hit-test each series' own segment directly instead — see its
-		// own doc comment.
-		pointMatching: 'contains' as const
-	});
-
-	// Estimated overflow for an `'outside'`-anchored value label at the most
-	// extreme value in the whole dataset — not just the current frame, so it
-	// stays stable across a timeline scrubber instead of resetting to zero
-	// and regrowing on every tick. Stacked labels sit at their own segment's
-	// midpoint (see `valueTextFn` above), well inside the bar, so they carry
-	// no such risk; `start`/`end` anchors sit inside the bar too.
-	const valueLabelFloor = $derived.by((): MarginOverflow | undefined => {
-		if (!showVals || valAnchor !== 'outside' || barLayout.layout === 'stacked') return undefined;
-		const font = styles.values?.fontStyle;
-		const fontSize = typeof font?.fontSize === 'number' ? font.fontSize : 12;
-		const canvasFont = `${fontSize}px ${cfg.font === 'inherit' ? 'sans-serif' : cfg.font}`;
-		if (isHorizontal) {
-			const offset = Math.abs(typeof font?.dx === 'number' ? font.dx : 6);
-			const texts: string[] = [];
-			for (const s of resolvedSeries) {
-				const sy = resolveAccessor(s.y);
-				let extremeValue = 0;
-				let extremeRow: TData | undefined;
-				for (const d of s.data) {
-					const v = Number(sy(d));
-					if (Number.isNaN(v)) continue;
-					if (extremeRow === undefined || Math.abs(v) > Math.abs(extremeValue)) {
-						extremeValue = v;
-						extremeRow = d;
-					}
-				}
-				if (extremeRow === undefined) continue;
-				texts.push(formatValue(extremeValue, s.name));
-			}
-			const right = estimateValueLabelMargin(texts, { canvasFont, reach: offset });
-			return { left: 0, right, top: 0, bottom: 0 };
-		}
-		const offset = Math.abs(typeof font?.dy === 'number' ? font.dy : 6);
-		return { left: 0, right: 0, top: Math.ceil(offset + fontSize * 1.2), bottom: 0 };
-	});
-
-	// See `halfDimensionOverflowCap`'s own doc comment.
-	const maxLabelOverflow = $derived(halfDimensionOverflowCap(width, height));
-
-	// A bar's value label can grow past the plot's own content box (e.g. a
-	// tall bar's `anchor: 'outside'` label pushing past the top margin) —
-	// `valueLabelFloor` covers the common case up front; each label's own
-	// rendered overflow still feeds `labelMargin.report` for whatever that
-	// estimate doesn't cover. See `labelOverflow.svelte.ts`.
-	const labelMargin = createLabelMarginTracker(
-		() => margins,
-		() => resolvedSeries,
-		() => valueLabelFloor ?? { left: 0, right: 0, top: 0, bottom: 0 },
-		() => maxLabelOverflow
-	);
+		margins = $bindable(),
+		...core
+	}: BarPlotProps<TData> = $props();
 </script>
 
-<BasePlotLayout
-	{width}
-	{height}
-	{styles}
-	data={flat}
-	getX={plotGetX}
-	getY={plotGetY}
-	{hover}
-	scales={resolvedScales}
-	{...labelMargin.plotProps}
-	xTickRotate={resolvedScales?.x?.tickRotate}
-	markers={({ setHoverMatch, clearHoverMatch }) => [
-		...buildBarMarkers({
-			groupedSeries,
-			barLayout,
-			isHorizontal,
-			hoverPoints,
-			colorFor: colorForSeries,
-			disabledFillFor: (name) => disabledFillOverride(effectiveDisabledFor(name)),
-			active: hover.active,
-			setHoverMatch,
-			clearHoverMatch,
-			gapFillMaps
-		}),
-		...markers
-	]}
-	seriesData={resolvedSeries}
-	{scopedGroups}
->
-	{#snippet children({ numericMargins })}
-		{#if showVals}
-			{#each groupedSeries as group, seriesIndex (group.series.name)}
-				<ValueLabels
-					{group}
-					{seriesIndex}
-					{barLayout}
-					{isHorizontal}
-					{valAnchor}
-					{formatValue}
-					values={styles.values}
-					axisColor={cfg.axis.color}
-					disabled={effectiveDisabledFor(group.series.name)}
-					{width}
-					{height}
-					{numericMargins}
-					onHoverSeries={hoverIsolate
-						? () => {
-								hoverIsolatedSeries = group.series.name;
-							}
-						: undefined}
-					onHoverEnd={hoverIsolate
-						? () => {
-								hoverIsolatedSeries = null;
-							}
-						: undefined}
-					onOverflow={labelMargin.report}
-				/>
-			{/each}
-		{/if}
-	{/snippet}
-</BasePlotLayout>
+<Plot
+	core={core as BarPlotCoreProps<TData>}
+	defaults={buildBarDefaults}
+	bind:margins
+	{title}
+	{subtitle}
+	{caption}
+	{header}
+	{footer}
+	{legend}
+	{order}
+	{timeline}
+	{facet}
+	{tooltip}
+/>

package/dist/plots/bar/Plot.svelte.d.ts

@@ -1,12 +1,9 @@
-import type { AxisBasedMarkersConfig } from '../../types/markers/common';
-import type { BasePlotProps } from '../../types/plots/props';
-import type { AxisBasedScalesConfig } from '../../types/layout/scales';
-import type { SeriesProps, DataProps } from '../../types/plots/data/common';
-import type { GapsAwarePlotStylesConfig } from '../../types/layout/styles';
+import Plot from '../../layout/plot/Plot.svelte';
+import type { BarPlotProps } from '../../types/plots/bar/props';
 declare function $$render<TData extends Record<string, unknown>>(): {
-    props: BasePlotProps<SeriesProps<TData> | DataProps<TData>, TData, GapsAwarePlotStylesConfig<import("../..").AreaStyle>, import("../..").AreaStyle, AxisBasedMarkersConfig, AxisBasedScalesConfig<TData>>;
+    props: BarPlotProps<TData>;
     exports: {};
-    bindings: "";
+    bindings: "margins";
     slots: {};
     events: {};
 };
@@ -14,7 +11,7 @@ declare class __sveltets_Render<TData extends Record<string, unknown>> {
     props(): ReturnType<typeof $$render<TData>>['props'];
     events(): ReturnType<typeof $$render<TData>>['events'];
     slots(): ReturnType<typeof $$render<TData>>['slots'];
-    bindings(): "";
+    bindings(): "margins";
     exports(): {};
 }
 interface $$IsomorphicComponent {

package/dist/plots/bar/defaults.d.ts

@@ -0,0 +1,9 @@
+import type { AxisPlotDefaults } from '../../types/phases';
+import type { BarPlotState, BarPlotCtx } from '../../types/plots/bar/state';
+/**
+ * BarPlot on the shared pipeline: discrete bars with gap fills along one
+ * category axis - `x`, or `y` for horizontal bars, as the "data" phase reads
+ * it off the values - its own scales (padding, bar layout) and markers.
+ * Its plot defaults to: hover along the category axis, timeline tweens matched per category and group.
+ */
+export declare function buildBarDefaults<TData extends Record<string, unknown>>(): AxisPlotDefaults<BarPlotState<TData>, BarPlotCtx>;

package/dist/plots/bar/defaults.js

@@ -0,0 +1,88 @@
+import { ProcessedPositions } from '../../phases/transforms/ProcessedPositions';
+import { buildMarks, buildValueLabels, buildHitAreas, buildBarGeometry } from './markers';
+import { NiceTicks } from '../../layout/scales/NiceTicks';
+import { SERIES_KEY } from '../../phases/transforms/TransformsPhase';
+import { PlotAxes } from '../../phases/data/PlotAxes';
+/**
+ * The domain a bar plot fits to its own bars on its value axis: from zero to
+ * the tallest span, niced to as many ticks as fit the plot. Left out when the
+ * author pins the axis, and when there is no span to fit.
+ */
+function fitValueDomain(state) {
+    const axis = PlotAxes.valueOf(state);
+    const scale = state.scales[axis];
+    if (scale?.domain != null || scale?.ticks != null || scale?.nice != null)
+        return {};
+    // Every bar's span, as the "transforms" phase left it - its baseline is
+    // unknown until the domain is, so a plain bar reads as reaching from zero.
+    const { of: spanOf } = ProcessedPositions.span(state.processedData, axis);
+    let lo = 0;
+    let hi = 0;
+    for (const row of state.processedData?.data ?? []) {
+        const span = spanOf(row);
+        if (!span)
+            continue;
+        lo = Math.min(lo, ...span);
+        hi = Math.max(hi, ...span);
+    }
+    if (hi <= lo)
+        return {};
+    return { [axis]: { domain: NiceTicks.fit(state, axis, lo, hi, scale?.niceTolerance) } };
+}
+/**
+ * BarPlot on the shared pipeline: discrete bars with gap fills along one
+ * category axis - `x`, or `y` for horizontal bars, as the "data" phase reads
+ * it off the values - its own scales (padding, bar layout) and markers.
+ * Its plot defaults to: hover along the category axis, timeline tweens matched per category and group.
+ */
+export function buildBarDefaults() {
+    return {
+        data: {
+            discreteAxes: 1,
+            segments: { color: (style) => style?.fill, connect: false }
+        },
+        scales: {
+            zero: ['value'],
+            defaults: (_state, ctx) => ({
+                category: { paddingInner: ctx.cfg.bar.paddingInner, paddingOuter: ctx.cfg.bar.paddingOuter }
+            }),
+            fit: fitValueDomain
+        },
+        styles: {
+            values: {
+                // An `'outside'` label sits past its bar's end, which the tallest bar takes to the edge.
+                reach: (labels, state) => {
+                    if (labels.anchor !== 'outside')
+                        return [];
+                    const axis = PlotAxes.valueOf(state);
+                    if (ProcessedPositions.span(state.processedData, axis).stacked)
+                        return [];
+                    if (!state.axes?.isHorizontal) {
+                        const at = { y: -labels.offset('y') };
+                        return [labels.edgeBox('0', { x: 'middle', y: 'before' }, at, ['top'])];
+                    }
+                    const at = { x: labels.offset('x') };
+                    return labels
+                        .extremes(state.resolvedSeries ?? [], PlotAxes.valueOf(state))
+                        .map(({ series, value }) => labels.edgeBox(labels.format(value, series.name), { x: 'after', y: 'middle' }, at, [
+                        'right'
+                    ]));
+                }
+            }
+        },
+        markers: { marks: buildMarks, valueLabels: buildValueLabels },
+        hover: {
+            // Each bar matched by its own band (see `buildHitAreas`); a grouped bar's dot is
+            // drawn in its series' slice of the band.
+            pointMatching: 'contains',
+            decorate: (state, ctx) => {
+                const { sliceOf } = buildBarGeometry(state, ctx.cfg.bar.seriesPadding);
+                return (row) => ({
+                    areaInset: sliceOf(String(row[SERIES_KEY]))
+                });
+            },
+            hitAreas: buildHitAreas
+        },
+        timeline: { interpolation: { value: 'value', key: ['category', 'grouping'] } }
+    };
+}

package/dist/plots/bar/markers.d.ts

@@ -0,0 +1,45 @@
+import type { BarMarkerConfig, TextMarkerConfig } from '../../types/markers/common';
+import type { BarPlotState, BarPlotCtx } from '../../types/plots/bar/state';
+import type { ProcessedRow } from '../../types/phases';
+import type { AxisValue } from '../../types/layout/mapping';
+import type { BandSlice } from '../../types/layout/hover';
+import type { HoverConfig } from '../../types/plots/props';
+import { ValueLabels } from '../../layout/styles/ValueLabels';
+import type { AxisBasedMarkersConfig } from '../../types/markers/common';
+/**
+ * Where a bar plot's bars sit, read off the state its phases leave: each
+ * processed row's category and span along the value axis, whether the series
+ * stack, and the slice of its category band each series takes when they sit
+ * side by side. Slices are fractions of the band, so they hold at any width.
+ */
+export declare function buildBarGeometry<TData extends Record<string, unknown>>(state: BarPlotState<TData>, seriesPadding: number): {
+    stacked: boolean;
+    baseline: number;
+    spanOf: (row: ProcessedRow) => [number, number] | undefined;
+    categoryOf: (row: ProcessedRow) => AxisValue;
+    sliceOf: (name: string) => BandSlice | undefined;
+};
+/**
+ * BarPlot's invisible `role: 'hitArea'` markers - one per hover candidate: a
+ * band across the whole plot along the value axis (full height for vertical
+ * bars, full width for horizontal ones), over its category, or its series'
+ * slice of it. The pointer needn't be over the visible bar. They drive the
+ * plot's hover when it is active.
+ */
+export declare function buildHitAreas<TData extends Record<string, unknown>>(state: BarPlotState<TData>, hover: HoverConfig<any>, ctx: BarPlotCtx): BarMarkerConfig[];
+/**
+ * BarPlot's `styles.values` as one `'text'` marker per series, over the same
+ * processed rows its bars draw (gap rows never get a label). `anchor` places
+ * each label along its bar: past its top (`'outside'`), just inside it
+ * (`'start'`), at its base (`'end'`), or centred (`'middle'`); a stacked bar's
+ * label always sits at the middle of its own span. A grouped bar's label
+ * shifts with its series' slice of the band.
+ */
+export declare function buildValueLabels<TData extends Record<string, unknown>>(labels: ValueLabels, state: BarPlotState<TData>, ctx: BarPlotCtx): TextMarkerConfig[];
+/**
+ * BarPlot's "markers" phase: visible `role: 'segment'` bars - real data plus
+ * gap fills - drawing the rows the "transforms" phase left, prepended onto
+ * whatever the "statistics" phase already put in `state.markers`, and its
+ * value labels on top of everything.
+ */
+export declare function buildMarks<TData extends Record<string, unknown>>(state: BarPlotState<TData>, ctx: BarPlotCtx): AxisBasedMarkersConfig[];