@galaxy-io/dls 1.2.6 → 1.3.0

package/dist/charts/PieChart.js

@@ -1,183 +1,171 @@
-import { useGalaxyTheme, withTheme } from "../theme/GalaxyTheme.js";
-import Text, { TextSize, TextWeight } from "../text/Text.js";
+import { useGalaxyTheme } from "../theme/GalaxyTheme.js";
 import FlexWrapper, { AlignItems, FlexDirection, JustifyContent } from "../containers/FlexWrapper.js";
-import { useElementWidth } from "../hooks/useElementWidth.js";
-import Wrapper from "../containers/Wrapper.js";
-import { getChartPalette } from "./constants.js";
-import { defaultLabelFormatter, defaultValueFormatter } from "./utils.js";
-import ChartLegend from "./ChartLegend.js";
-import ChartTooltip from "./ChartTooltip.js";
-/* empty css                   */
-import { styled } from "@linaria/react";
-import { useCallback, useMemo, useRef, useState } from "react";
-import { jsx, jsxs } from "react/jsx-runtime";
-import { arc, pie } from "d3-shape";
+import { ChartMarkState } from "./types.js";
+import { PIE_CHART_MARGIN, PIE_MIN_SLICE_SHARE } from "./constants.js";
+import { ChartTooltipVerticalAlign } from "./useChartTooltipPosition.js";
+import { useChartInteraction } from "./useChartInteraction.js";
+import { useChartFormatters } from "./useChartFormatters.js";
+import { useChartDimensions } from "./useChartDimensions.js";
+import { buildPieChartGeometry } from "./pieChartGeometry.js";
+import { resolveChartPaletteColor, resolveSeriesColor } from "./chartTheme.js";
+import { ChartArcPath, ChartCenterBox } from "./ChartPrimitives.js";
+import ChartFrame from "./ChartFrame.js";
+import { useCallback, useMemo, useRef } from "react";
+import { jsx } from "react/jsx-runtime";
 //#region src/charts/PieChart.tsx
-var DEFAULT_PAD_ANGLE = .02;
-var DEFAULT_CORNER_RADIUS = 2;
-var PIE_MARGIN = 8;
-var _exp = () => ({ $fillWidth }) => $fillWidth ? "flex" : "inline-flex";
-var _exp2 = () => ({ $fillWidth }) => $fillWidth ? "100%" : "auto";
-var ChartWrapper = withTheme(/*#__PURE__*/ styled("div")({
-	name: "ChartWrapper",
-	class: "c1ez9f1",
-	propsAsIs: false,
-	vars: {
-		"c1ez9f1-0": [_exp()],
-		"c1ez9f1-1": [_exp2()]
-	}
-}));
-var resolveSliceColor = (slice, index, palette) => slice.color ?? palette[index % palette.length];
-var PieChart = ({ slices, width, height, fillWidth = false, aspectRatio, innerRadius = 0, padAngle = DEFAULT_PAD_ANGLE, cornerRadius = DEFAULT_CORNER_RADIUS, valueFormatter = defaultValueFormatter, labelFormatter = defaultLabelFormatter, tooltipRenderer, noTooltip = false, showLegend = true, showLabels = false, ariaLabel }) => {
+/**
+* Pie and donut chart.
+*
+* Unlike the cartesian charts there is no category axis to hit-test against, so
+* each arc is its own target. Small slices are folded into an "Other" bucket by
+* default, which keeps every remaining arc large enough to actually hit.
+*/
+var PieChart = ({ series, slices, width, height, fillWidth, fillHeight, aspectRatio, margin, innerRadiusRatio, padAngle, cornerRadius, minSliceShare = PIE_MIN_SLICE_SHARE, aggregatedLabel, centerContent, valueUnit, valueFormatter, labelFormatter, showLegend = true, noTooltip = false, tooltipRenderer, isLoading = false, contentWhenEmpty, ariaLabel, ariaDescription, onPinnedChange }) => {
 	const { theme } = useGalaxyTheme();
 	const containerRef = useRef(null);
-	const svgRef = useRef(null);
-	const [tooltip, setTooltip] = useState(null);
-	const [hoveredSliceIndex, setHoveredSliceIndex] = useState(null);
-	const measuredWidth = useElementWidth(containerRef);
-	const resolvedWidth = fillWidth ? measuredWidth ?? 0 : width ?? 0;
-	const resolvedHeight = aspectRatio ? resolvedWidth / aspectRatio : height ?? 0;
-	const palette = useMemo(() => getChartPalette(theme), [theme]);
-	const outerRadius = useMemo(() => Math.min(resolvedWidth, resolvedHeight) / 2 - PIE_MARGIN, [resolvedWidth, resolvedHeight]);
-	const effectivePadAngle = innerRadius > 0 ? padAngle : 0;
-	const pieGen = useMemo(() => pie().value((d) => d.value).sort(null).padAngle(effectivePadAngle), [effectivePadAngle]);
-	const arcs = useMemo(() => pieGen(slices), [pieGen, slices]);
-	const arcGen = useMemo(() => arc().innerRadius(innerRadius).outerRadius(outerRadius).cornerRadius(cornerRadius), [
-		innerRadius,
-		outerRadius,
-		cornerRadius
-	]);
-	const labelArc = useMemo(() => {
-		const mid = innerRadius > 0 ? (innerRadius + outerRadius) / 2 : outerRadius * .65;
-		return arc().innerRadius(mid).outerRadius(mid);
-	}, [innerRadius, outerRadius]);
-	const total = useMemo(() => slices.reduce((sum, s) => sum + s.value, 0), [slices]);
-	const handleSliceMouseEnter = useCallback((sliceIndex, event) => {
-		const slice = slices[sliceIndex];
-		if (!slice) return;
-		const svgRect = svgRef.current?.getBoundingClientRect();
-		if (!svgRect) return;
-		setHoveredSliceIndex(sliceIndex);
-		setTooltip({
-			label: labelFormatter(slice.label),
-			items: [{
-				seriesKey: slice.label,
-				seriesName: labelFormatter(slice.label),
-				value: slice.value,
-				color: resolveSliceColor(slice, sliceIndex, palette)
-			}],
-			x: event.clientX - svgRect.left,
-			y: event.clientY - svgRect.top
-		});
-	}, [
-		slices,
-		palette,
+	const dimensions = useChartDimensions({
+		containerRef,
+		width,
+		height,
+		fillWidth,
+		fillHeight,
+		aspectRatio,
+		margin: margin ?? PIE_CHART_MARGIN
+	});
+	const { plotWidth, plotHeight } = dimensions;
+	const { formatValue, formatLabel } = useChartFormatters({
+		valueFormatter,
+		valueUnit,
 		labelFormatter
-	]);
-	const handleSliceMouseMove = useCallback((event) => {
-		if (hoveredSliceIndex === null) return;
-		const svgRect = svgRef.current?.getBoundingClientRect();
-		if (!svgRect) return;
-		setTooltip((prev) => prev ? {
-			...prev,
-			x: event.clientX - svgRect.left,
-			y: event.clientY - svgRect.top
-		} : null);
-	}, [hoveredSliceIndex]);
-	const handleSliceMouseLeave = useCallback(() => {
-		setHoveredSliceIndex(null);
-		setTooltip(null);
-	}, []);
-	const legendSeries = useMemo(() => slices.map((s, i) => ({
-		key: s.label,
-		name: labelFormatter(s.label),
-		color: resolveSliceColor(s, i, palette)
-	})), [
+	});
+	const sliceKeys = useMemo(() => Object.keys(series), [series]);
+	const getSliceLabel = useCallback((sliceKey) => series[sliceKey]?.label ?? sliceKey, [series]);
+	const getSliceColor = useCallback((sliceKey) => series[sliceKey]?.color, [series]);
+	const resolveColor = useCallback(({ sliceKey, index, explicit }) => {
+		if (explicit) return resolveChartPaletteColor(theme, explicit);
+		if (sliceKey === null) return theme.color.text.tertiary;
+		const slotIndex = sliceKeys.indexOf(sliceKey);
+		return resolveSeriesColor(theme, slotIndex >= 0 ? slotIndex : index);
+	}, [theme, sliceKeys]);
+	const geometry = useMemo(() => buildPieChartGeometry({
 		slices,
-		palette,
-		labelFormatter
+		plotWidth,
+		plotHeight,
+		innerRadiusRatio,
+		padAngle,
+		cornerRadius,
+		minSliceShare,
+		aggregatedLabel,
+		resolveColor,
+		getSliceColor,
+		getSliceLabel
+	}), [
+		slices,
+		plotWidth,
+		plotHeight,
+		innerRadiusRatio,
+		padAngle,
+		cornerRadius,
+		minSliceShare,
+		aggregatedLabel,
+		resolveColor,
+		getSliceColor,
+		getSliceLabel
 	]);
-	if (resolvedWidth === 0 || resolvedHeight === 0) return /* @__PURE__ */ jsx(ChartWrapper, {
-		ref: containerRef,
-		$fillWidth: fillWidth
+	const isEmpty = geometry.arcs.length === 0;
+	const legendItems = useMemo(() => geometry.arcs.map((chartArc) => ({
+		key: chartArc.id,
+		label: formatLabel(chartArc.label),
+		color: chartArc.color
+	})), [geometry.arcs, formatLabel]);
+	const legendKeys = useMemo(() => legendItems.map((item) => item.key), [legendItems]);
+	const interaction = useChartInteraction({
+		categoryCount: geometry.arcs.length,
+		seriesKeys: legendKeys,
+		disabled: noTooltip || isLoading || isEmpty,
+		onPinnedChange
 	});
-	const cx = resolvedWidth / 2;
-	const cy = resolvedHeight / 2;
-	const defaultAriaLabel = `Pie chart with ${slices.length} slices`;
-	return /* @__PURE__ */ jsxs(ChartWrapper, {
-		ref: containerRef,
-		$fillWidth: fillWidth,
-		children: [/* @__PURE__ */ jsxs(Wrapper, {
-			position: "relative",
-			children: [/* @__PURE__ */ jsx("svg", {
-				ref: svgRef,
-				width: resolvedWidth,
-				height: resolvedHeight,
-				role: "img",
-				"aria-label": ariaLabel ?? defaultAriaLabel,
-				children: /* @__PURE__ */ jsx("g", {
-					transform: `translate(${cx}, ${cy})`,
-					children: arcs.map((d, i) => {
-						const color = resolveSliceColor(d.data, i, palette);
-						const isDimmed = hoveredSliceIndex !== null && hoveredSliceIndex !== i;
-						const path = arcGen(d) ?? "";
-						const pct = total > 0 ? Math.round(d.data.value / total * 100) : 0;
-						return /* @__PURE__ */ jsxs("g", { children: [/* @__PURE__ */ jsx("path", {
-							d: path,
-							fill: color,
-							opacity: isDimmed ? .3 : 1,
-							style: {
-								transition: `opacity 150ms ease-in-out`,
-								cursor: "pointer"
-							},
-							onMouseEnter: (e) => handleSliceMouseEnter(i, e),
-							onMouseMove: handleSliceMouseMove,
-							onMouseLeave: handleSliceMouseLeave,
-							onFocus: (e) => handleSliceMouseEnter(i, e),
-							onBlur: handleSliceMouseLeave,
-							tabIndex: 0,
-							role: "graphics-symbol",
-							"aria-roledescription": "slice",
-							"aria-label": `${labelFormatter(d.data.label)}: ${valueFormatter(d.data.value)} (${pct}%)`
-						}), showLabels && pct > 5 && (() => {
-							const [lx, ly] = labelArc.centroid(d);
-							const labelW = 48;
-							const labelH = 20;
-							return /* @__PURE__ */ jsx("foreignObject", {
-								x: lx - labelW / 2,
-								y: ly - labelH / 2,
-								width: labelW,
-								height: labelH,
-								style: { pointerEvents: "none" },
-								children: /* @__PURE__ */ jsx(FlexWrapper, {
-									justifyContent: JustifyContent.CENTER,
-									alignItems: AlignItems.CENTER,
-									fillWidth: true,
-									fillHeight: true,
-									children: /* @__PURE__ */ jsx(Text, {
-										size: TextSize.CAPTION,
-										weight: TextWeight.MEDIUM,
-										hex: theme.color.text.primaryAlt,
-										children: `${pct}%`
-									})
-								})
-							});
-						})()] }, d.data.label);
-					})
-				})
-			}), !noTooltip && (tooltipRenderer ? tooltip && tooltipRenderer(tooltip) : /* @__PURE__ */ jsx(ChartTooltip, {
-				data: tooltip,
-				valueFormatter
-			}))]
-		}), showLegend && /* @__PURE__ */ jsx(FlexWrapper, {
-			direction: FlexDirection.ROW,
-			gap: 0,
-			children: /* @__PURE__ */ jsx(ChartLegend, {
-				series: legendSeries,
-				palette
-			})
-		})]
+	const tooltipModel = useMemo(() => {
+		if (noTooltip || interaction.activeIndex === null) return null;
+		const chartArc = geometry.arcs[interaction.activeIndex];
+		if (!chartArc) return null;
+		return {
+			label: formatLabel(chartArc.label),
+			rows: [{
+				key: chartArc.id,
+				label: `${Math.round(chartArc.share * 1e3) / 10}% of total`,
+				value: chartArc.value,
+				formattedValue: formatValue(chartArc.value),
+				color: chartArc.color
+			}],
+			anchorX: chartArc.anchorX,
+			anchorY: chartArc.anchorY
+		};
+	}, [
+		noTooltip,
+		interaction.activeIndex,
+		geometry.arcs,
+		formatValue,
+		formatLabel
+	]);
+	const showCenter = centerContent && (innerRadiusRatio ?? .62) > 0;
+	return /* @__PURE__ */ jsx(ChartFrame, {
+		containerRef,
+		dimensions,
+		fillWidth,
+		fillHeight,
+		interaction,
+		ariaLabel: ariaLabel ?? `Pie chart with ${geometry.arcs.length} slices`,
+		ariaDescription,
+		noTooltip,
+		tooltipModel,
+		tooltipRenderer,
+		placeAwayFromX: geometry.centerX,
+		verticalAlign: ChartTooltipVerticalAlign.CENTERED,
+		isEmpty,
+		isLoading,
+		contentWhenEmpty,
+		showLegend,
+		legendItems,
+		legendInset: 0,
+		plotOverlay: showCenter && !isEmpty ? /* @__PURE__ */ jsx(ChartDonutCenter, {
+			centerX: dimensions.margin.left + geometry.centerX,
+			centerY: dimensions.margin.top + geometry.centerY,
+			diameter: geometry.innerRadius * 2,
+			children: centerContent
+		}) : null,
+		children: /* @__PURE__ */ jsx("g", {
+			transform: `translate(${geometry.centerX}, ${geometry.centerY})`,
+			children: geometry.arcs.map((chartArc, index) => /* @__PURE__ */ jsx(ChartArcPath, {
+				d: chartArc.path,
+				fill: chartArc.color,
+				"data-state": isLoading ? ChartMarkState.MUTED : interaction.getMarkState({
+					categoryIndex: index,
+					seriesKey: chartArc.id
+				}),
+				"data-interactive": noTooltip || isLoading ? "false" : "true",
+				onMouseEnter: () => interaction.onCategoryEnter(index),
+				onMouseLeave: interaction.onCategoryLeave,
+				onClick: () => interaction.onCategoryClick(index),
+				"aria-label": `${chartArc.label}: ${formatValue(chartArc.value)}`
+			}, chartArc.id))
+		})
 	});
 };
+/** Positions arbitrary content inside the donut hole. */
+var ChartDonutCenter = ({ centerX, centerY, diameter, children }) => /* @__PURE__ */ jsx(ChartCenterBox, {
+	$centerX: centerX,
+	$centerY: centerY,
+	$diameter: diameter,
+	children: /* @__PURE__ */ jsx(FlexWrapper, {
+		direction: FlexDirection.COLUMN,
+		justifyContent: JustifyContent.CENTER,
+		alignItems: AlignItems.CENTER,
+		gap: 2,
+		fillWidth: true,
+		fillHeight: true,
+		children
+	})
+});
 //#endregion
 export { PieChart as default };

package/dist/charts/barChartGeometry.d.ts

@@ -0,0 +1,87 @@
+import { buildValueScale } from "./chartScales";
+import { BarChartNormalization, BarCorners } from "./types";
+import type { BarChartGroupBand, BarChartGroupDatum, BarChartRect, ChartPalette, ChartValueDomain } from "./types";
+/**
+ * Bar chart geometry.
+ *
+ * Flattens the group → bar → component hierarchy into a flat array of
+ * rectangles plus one hit band per group, so the component body is a `.map()`
+ * with no nested loops or running accumulators.
+ *
+ * Pure: no React, no theme access. Colors arrive through a resolver callback so
+ * this module never has to know how the palette maps to the theme.
+ */
+interface BarSpacing {
+    /** Px between neighbouring groups. */
+    groupGap: number;
+    /** Px between bars inside a group. */
+    barGap: number;
+}
+/**
+ * Pick gap sizes from how crowded the chart is.
+ *
+ * Sparse charts stay roomy regardless of width; once there are enough bars to
+ * matter, the gaps tighten as the plot narrows.
+ */
+export declare function getBarSpacing(plotWidth: number, totalBars: number): BarSpacing;
+/**
+ * Rectangle with one pair of corners rounded.
+ *
+ * The radius is clamped to half the height as well as half the width, so a very
+ * short bar renders as a symmetric cap instead of a lopsided half-pill.
+ */
+export declare function roundedRectPath(x: number, y: number, width: number, height: number, radius: number, corners: BarCorners): string;
+/**
+ * Signed value domain across every group.
+ *
+ * Percent-normalized charts always span 0–1, so the axis is stable no matter
+ * what the underlying totals are.
+ */
+export declare function getBarValueDomain<TMetric extends string, TPivot extends string, TComponentKey extends string>(groups: BarChartGroupDatum<TMetric, TPivot, TComponentKey>[], normalization: BarChartNormalization): [number, number];
+export interface BarChartGeometry<TMetric extends string, TComponentKey extends string = string> {
+    /** Every rendered rectangle, in draw order. */
+    rects: BarChartRect<TMetric, TComponentKey>[];
+    /** One hit target per group, tiling the plot with no gaps. */
+    bands: BarChartGroupBand[];
+    /** The resolved value scale, shared with the axis. */
+    valueScale: ReturnType<typeof buildValueScale>;
+    /** Pixel y of value zero — where bars meet the baseline. */
+    baselineY: number;
+}
+interface BuildBarChartGeometryArgs<TMetric extends string, TPivot extends string, TComponentKey extends string> {
+    groups: BarChartGroupDatum<TMetric, TPivot, TComponentKey>[];
+    plotWidth: number;
+    plotHeight: number;
+    normalization: BarChartNormalization;
+    /**
+     * Whether the chart as a whole is stacked.
+     *
+     * Chart-wide, not per bar, because it decides the *colour rule* and the legend
+     * lists one domain for the whole chart. Deriving it per bar would colour a
+     * single-component bar by metric while the legend named components.
+     */
+    isStacked: boolean;
+    valueDomain?: Partial<ChartValueDomain>;
+    /**
+     * Maps one segment to a concrete color.
+     *
+     * The geometry deliberately does not decide the rule — it only reports what
+     * it knows about the segment. Whether a stack is coloured by component or a
+     * group by metric is a presentation question, and it needs the `series`
+     * record to answer, which this module has no business importing.
+     */
+    resolveColor: (args: ResolveBarColorArgs<TMetric>) => string;
+}
+export interface ResolveBarColorArgs<TMetric extends string> {
+    metric: TMetric;
+    /** Index of the bar within its group. */
+    barIndex: number;
+    /** Index of the component within its bar. */
+    componentIndex: number;
+    /** True when the *chart* is stacked — see the option of the same name. */
+    isStacked: boolean;
+    /** The component's own palette override, if it declared one. */
+    explicit?: ChartPalette;
+}
+export declare function buildBarChartGeometry<TMetric extends string, TPivot extends string = string, TComponentKey extends string = string>({ groups, plotWidth, plotHeight, normalization, isStacked, valueDomain, resolveColor, }: BuildBarChartGeometryArgs<TMetric, TPivot, TComponentKey>): BarChartGeometry<TMetric, TComponentKey>;
+export {};

package/dist/charts/barChartGeometry.js

@@ -0,0 +1,218 @@
+import { BarChartNormalization, BarCorners } from "./types.js";
+import { BAR_WIDTH_RATIO, MAX_GAP_SHARE } from "./constants.js";
+import { applyDomainOverride, buildValueScale, sanitizeValue } from "./chartScales.js";
+//#region src/charts/barChartGeometry.ts
+/**
+* Pick gap sizes from how crowded the chart is.
+*
+* Sparse charts stay roomy regardless of width; once there are enough bars to
+* matter, the gaps tighten as the plot narrows.
+*/
+function getBarSpacing(plotWidth, totalBars) {
+	if (totalBars < 13 || plotWidth > 650) return {
+		groupGap: 24,
+		barGap: 6
+	};
+	if (plotWidth > 500) return {
+		groupGap: 16,
+		barGap: 4
+	};
+	return {
+		groupGap: 12,
+		barGap: 3
+	};
+}
+/**
+* Rectangle with one pair of corners rounded.
+*
+* The radius is clamped to half the height as well as half the width, so a very
+* short bar renders as a symmetric cap instead of a lopsided half-pill.
+*/
+function roundedRectPath(x, y, width, height, radius, corners) {
+	const r = corners === BarCorners.NONE ? 0 : Math.max(0, Math.min(radius, width / 2, height / 2));
+	if (r === 0) return `M${x},${y} h${width} v${height} h${-width} z`;
+	if (corners === BarCorners.TOP) return [
+		`M${x},${y + r}`,
+		`a${r},${r} 0 0 1 ${r},${-r}`,
+		`h${width - 2 * r}`,
+		`a${r},${r} 0 0 1 ${r},${r}`,
+		`v${height - r}`,
+		`h${-width}`,
+		`z`
+	].join(" ");
+	return [
+		`M${x},${y}`,
+		`h${width}`,
+		`v${height - r}`,
+		`a${r},${r} 0 0 1 ${-r},${r}`,
+		`h${-(width - 2 * r)}`,
+		`a${r},${r} 0 0 1 ${-r},${-r}`,
+		`z`
+	].join(" ");
+}
+/**
+* Turn one bar's components into stacked `[from, to]` intervals.
+*
+* Positive and negative values accumulate on separate cursors, which is what
+* lets a bar mixing both stack upward and downward from the baseline without
+* any special-casing downstream — and is also why percent normalization is a
+* one-line division rather than a second code path.
+*/
+function stackComponents(values, normalization) {
+	let positiveCursor = 0;
+	let negativeCursor = 0;
+	const intervals = values.map((value) => {
+		if (value >= 0) {
+			const from = positiveCursor;
+			positiveCursor += value;
+			return {
+				value,
+				from,
+				to: positiveCursor
+			};
+		}
+		const to = negativeCursor;
+		negativeCursor += value;
+		return {
+			value,
+			from: negativeCursor,
+			to
+		};
+	});
+	if (normalization !== BarChartNormalization.PERCENT) return intervals;
+	const magnitude = positiveCursor - negativeCursor;
+	if (magnitude === 0) return intervals;
+	return intervals.map((interval) => ({
+		value: interval.value,
+		from: interval.from / magnitude,
+		to: interval.to / magnitude
+	}));
+}
+/**
+* Signed value domain across every group.
+*
+* Percent-normalized charts always span 0–1, so the axis is stable no matter
+* what the underlying totals are.
+*/
+function getBarValueDomain(groups, normalization) {
+	if (normalization === BarChartNormalization.PERCENT) return [0, 1];
+	let min = 0;
+	let max = 0;
+	for (const group of groups) for (const bar of group.bars) {
+		let positive = 0;
+		let negative = 0;
+		for (const component of bar.components) {
+			const value = sanitizeValue(component.value);
+			if (value >= 0) positive += value;
+			else negative += value;
+		}
+		if (positive > max) max = positive;
+		if (negative < min) min = negative;
+	}
+	return [min, max];
+}
+function buildBarChartGeometry({ groups, plotWidth, plotHeight, normalization, isStacked, valueDomain, resolveColor }) {
+	const valueScale = buildValueScale(applyDomainOverride(getBarValueDomain(groups, normalization), valueDomain), [plotHeight, 0]);
+	const baselineY = valueScale(0);
+	const rects = [];
+	const bands = [];
+	if (groups.length === 0 || plotWidth <= 0 || plotHeight <= 0) return {
+		rects,
+		bands,
+		valueScale,
+		baselineY
+	};
+	const { groupGap, barGap } = getBarSpacing(plotWidth, groups.reduce((sum, group) => sum + group.bars.length, 0));
+	const step = plotWidth / groups.length;
+	const effectiveGroupGap = Math.min(groupGap, step * MAX_GAP_SHARE);
+	const groupWidth = Math.max(1, step - effectiveGroupGap);
+	groups.forEach((group, groupIndex) => {
+		const bandX = groupIndex * step;
+		const groupX = bandX + (step - groupWidth) / 2;
+		const barCount = Math.max(1, group.bars.length);
+		const effectiveBarGap = Math.min(barGap, groupWidth / barCount * MAX_GAP_SHARE);
+		const slotWidth = (groupWidth - (barCount - 1) * effectiveBarGap) / barCount;
+		const barWidth = Math.max(1, Math.min(slotWidth * BAR_WIDTH_RATIO, 44));
+		const radius = barWidth < 40 ? 2 : 4;
+		const barsStartX = groupX + (groupWidth - (barCount * barWidth + (barCount - 1) * effectiveBarGap)) / 2;
+		let groupTopY = baselineY;
+		let hasValue = false;
+		group.bars.forEach((bar, barIndex) => {
+			const barX = barsStartX + barIndex * (barWidth + effectiveBarGap);
+			const values = bar.components.map((component) => sanitizeValue(component.value));
+			const intervals = stackComponents(values, normalization);
+			let firstPositive = -1;
+			let lastPositive = -1;
+			let firstNegative = -1;
+			let lastNegative = -1;
+			values.forEach((value, index) => {
+				if (value > 0) {
+					if (firstPositive === -1) firstPositive = index;
+					lastPositive = index;
+				}
+				if (value < 0) {
+					if (firstNegative === -1) firstNegative = index;
+					lastNegative = index;
+				}
+			});
+			bar.components.forEach((component, componentIndex) => {
+				const { value, from, to } = intervals[componentIndex];
+				if (value === 0) return;
+				hasValue = true;
+				const isNegative = value < 0;
+				const isCap = componentIndex === (isNegative ? lastNegative : lastPositive);
+				const fromY = Math.round(valueScale(from));
+				const toY = Math.round(valueScale(to));
+				const topY = Math.min(fromY, toY);
+				const rawHeight = Math.abs(fromY - toY);
+				const isStackedBar = bar.components.length > 1;
+				const shave = componentIndex === (isNegative ? firstNegative : firstPositive) ? 0 : 2;
+				const height = Math.max(isStackedBar ? 0 : 2, rawHeight - shave);
+				const y = isNegative ? topY + shave : topY;
+				if (!isNegative && y < groupTopY) groupTopY = y;
+				rects.push({
+					id: `${groupIndex}:${barIndex}:${component.key}`,
+					groupIndex,
+					barIndex,
+					metric: bar.metric,
+					componentKey: component.key,
+					label: component.label,
+					value,
+					valueRange: [from, to],
+					x: barX,
+					y,
+					width: barWidth,
+					height,
+					color: resolveColor({
+						metric: bar.metric,
+						barIndex,
+						componentIndex,
+						isStacked,
+						explicit: component.color
+					}),
+					corners: isCap ? isNegative ? BarCorners.BOTTOM : BarCorners.TOP : BarCorners.NONE,
+					radius
+				});
+			});
+		});
+		bands.push({
+			groupIndex,
+			label: group.label,
+			x: bandX,
+			y: 0,
+			width: step,
+			height: plotHeight,
+			anchorX: bandX + step / 2,
+			anchorY: groupTopY,
+			isEmpty: !hasValue
+		});
+	});
+	return {
+		rects,
+		bands,
+		valueScale,
+		baselineY
+	};
+}
+//#endregion
+export { buildBarChartGeometry, getBarSpacing, getBarValueDomain, roundedRectPath };

package/dist/charts/chartFormat.d.ts

@@ -0,0 +1,19 @@
+import { ChartValueUnit } from "./types";
+import type { ChartLabelFormatter, ChartValueFormatter } from "./types";
+/**
+ * Format a value with a built-in unit.
+ *
+ * `PERCENT` takes a 0–100 value rather than a 0–1 fraction, matching how
+ * percentage data usually arrives, and appends the sign itself instead of using
+ * `style: "percent"` (which would divide by 100).
+ */
+export declare function formatChartValue(value: number, unit: ChartValueUnit): string;
+/**
+ * Pick the effective value formatter.
+ *
+ * An explicit `valueFormatter` always wins; otherwise the unit supplies a
+ * default, and `PLAIN` is the fallback when neither is given.
+ */
+export declare function resolveValueFormatter(valueFormatter?: ChartValueFormatter, unit?: ChartValueUnit): ChartValueFormatter;
+/** Pick the effective label formatter, defaulting to identity. */
+export declare function resolveLabelFormatter(labelFormatter?: ChartLabelFormatter): ChartLabelFormatter;