@galaxy-io/dls 1.2.6 → 1.3.0

package/dist/charts/constants.js

@@ -1,38 +1,246 @@
+import { ChartPalette } from "./types.js";
 //#region src/charts/constants.ts
 /**
-* Theme-derived chart series color palette.
-* Purple first to match Galaxy brand aesthetic.
-*/
-var getChartPalette = (theme) => [
-	theme.color.text.purple,
-	theme.color.text.pink,
-	theme.color.text.blue,
-	theme.color.text.teal,
-	theme.color.text.lime,
-	theme.color.text.orange,
-	theme.color.text.yellow,
-	theme.color.text.success,
-	theme.color.text.error
-];
+* Layout and motion tokens for the chart components.
+*
+* This module is evaluated by Linaria at build time — its constants are
+* interpolated statically into styled templates — so it must stay free of
+* component imports. Pulling React, framer-motion or Phosphor in here would
+* drag them into build-time evaluation.
+*/
 var DEFAULT_CHART_MARGIN = {
-	top: 16,
+	top: 12,
 	right: 16,
-	bottom: 32,
-	left: 48
+	bottom: 36,
+	left: 52
+};
+/**
+* Gap between a value-axis tick label and the plot edge.
+*
+* The label box is `margin.left - VALUE_AXIS_TICK_GAP` wide, so the axis
+* geometry follows the margin instead of hardcoding an offset.
+*/
+var VALUE_AXIS_TICK_GAP = 12;
+/** Height of a value-axis tick label box in px. */
+var VALUE_AXIS_LABEL_HEIGHT = 20;
+/** Height of the category-axis label box in px. */
+var CATEGORY_AXIS_LABEL_HEIGHT = 24;
+/** Gap between the plot's bottom edge and the category labels, in px. */
+var CATEGORY_AXIS_LABEL_GAP = 8;
+/** Band reserved for an axis title, in px. Sized for one CAPTION line. */
+var AXIS_TITLE_BAND = 18;
+/**
+* Clear space between an axis title and its tick labels, in px.
+*
+* The category axis gets this for free: its labels sit in a 24px box and its
+* title in an 18px band, and centring a CAPTION line in each leaves roughly this
+* much air between the two. The value axis has no such slack — its title band
+* abuts the label box exactly — so without reserving it here a wide tick number
+* runs straight into the rotated title, and the two axes visibly disagree.
+*/
+var AXIS_TITLE_GAP = 8;
+/** Default approximate tick count on the value axis. */
+var DEFAULT_VALUE_TICK_COUNT = 5;
+/** Corner radius applied to the outer end of a wide bar, in px. */
+var BAR_RADIUS = 4;
+/** Corner radius for bars narrower than {@link NARROW_BAR_WIDTH}, in px. */
+var BAR_RADIUS_NARROW = 2;
+/** Bars below this width use the smaller radius so the curve doesn't dominate. */
+var NARROW_BAR_WIDTH = 40;
+/**
+* Px shaved off a stacked segment's covered edge to separate it from its
+* neighbour.
+*
+* Keep this a whole number. The geometry snaps every stack boundary to a whole
+* pixel first, so an integer gap renders at exactly the same size at every seam;
+* a fractional one would land differently against the device pixel grid from one
+* boundary to the next and read as uneven.
+*
+* Applied to every segment except the one sitting on the baseline, so each seam
+* gets a gap and the bar still meets the axis flush.
+*/
+var STACK_SEGMENT_GAP = 2;
+/** Minimum rendered height for a non-zero bar, in px. */
+var MIN_BAR_LENGTH = 2;
+/**
+* Target gaps in px between groups, and between bars within a group.
+*
+* The within-group gap must stay clearly smaller than the between-group gap —
+* that ratio is the only thing making a group read as a group. When the two are
+* close, the eye has nothing to bind a group's bars together and the chart reads
+* as one long row of unrelated bars.
+*/
+var GROUP_GAP_COMFORTABLE = 24;
+var BAR_GAP_COMFORTABLE = 6;
+var GROUP_GAP_MEDIUM = 16;
+var BAR_GAP_MEDIUM = 4;
+var GROUP_GAP_TIGHT = 12;
+var BAR_GAP_TIGHT = 3;
+/**
+* Fraction of its available slot a bar actually fills.
+*
+* Bars sized to consume every last pixel of their group read as heavy, and the
+* chart becomes a wall of colour rather than a set of measurements. Holding them
+* back leaves air on both sides of each group without touching the gap between
+* neighbouring bars.
+*/
+var BAR_WIDTH_RATIO = .8;
+/**
+* Ceiling on a single bar's thickness, in px.
+*
+* Without it a two- or three-category chart divides the whole plot between a
+* handful of bars and produces slabs — the width stops carrying information the
+* moment it exceeds what the eye needs to compare heights.
+*/
+var MAX_BAR_WIDTH = 44;
+/** Below this many bars the chart always uses comfortable spacing. */
+var MIN_BARS_FOR_TIGHT_SPACING = 13;
+/**
+* Ceiling on a gap, as a share of the space it divides.
+*
+* The gaps above are absolute pixel values chosen from chart-wide density, which
+* says nothing about how much room a *single* category actually got. Forty
+* categories in a 650px plot leave a 16px step, and a 24px gap subtracted from
+* that goes negative — the width lands on its 1px floor and every bar renders as
+* a hairline. Capping the gap proportionally keeps it honest at any density: it
+* stays exactly as specified whenever there is room, and degrades smoothly when
+* there is not.
+*/
+var MAX_GAP_SHARE = .3;
+/** Plot widths above this stay comfortable; below the tight threshold go tight. */
+var WIDTH_FOR_MEDIUM_SPACING = 650;
+var WIDTH_FOR_TIGHT_SPACING = 500;
+/** Grid lines extend this far past both plot edges, in px. */
+var GRID_LINE_BLEED = 12;
+var DEFAULT_LINE_STROKE_WIDTH = 1.5;
+/** Radius of the dot marking a point on a hovered category, in px. */
+var LINE_POINT_RADIUS = 3.5;
+/** Opacity of the area fill under a line. */
+var LINE_AREA_OPACITY = .12;
+/** Gap between slices, in radians. */
+var PIE_PAD_ANGLE = .012;
+/** Slice corner radius in px. */
+var PIE_CORNER_RADIUS = 2;
+/** Inner radius as a fraction of the outer radius, for donut mode. */
+var PIE_DONUT_INNER_RATIO = .62;
+/**
+* Share of the narrowest slice that its two inner pad insets may consume.
+*
+* d3 turns {@link PIE_PAD_ANGLE} into a *constant linear* gap, and holding that
+* width at radius `r` costs an angular inset of `asin(gap / 2r)` — unbounded as
+* `r` approaches zero. When the two insets no longer fit inside a slice's own
+* span, d3 collapses that slice's inner edge rather than sweeping backwards. The
+* collapse is what makes a hole-less pie look wrong: the gap edge stops being
+* radial, so gaps sit at visibly different widths and lean at slight angles, and
+* it bites hardest between the *narrowest* slices, where the span runs out
+* first.
+*
+* So the inner radius is solved for rather than guessed: pick the radius that
+* keeps both insets inside the narrowest slice, with this much of it spent. At
+* 0.7 the measured gap spread is 1.01× (against 1.46× when the inner edge is
+* left to collapse), and the remaining 30% is what absorbs the corner radius.
+*/
+var PIE_MAX_INSET_SHARE = .7;
+/**
+* Ceiling on the auto-derived inner radius, as a share of the outer radius.
+*
+* The radius needed grows without bound as the narrowest slice shrinks, so a
+* single sliver would otherwise turn a pie into a donut. Past this point the
+* hole is doing more visual damage than the uneven gap it fixes, so the gap is
+* allowed to degrade instead — never worse than it renders today.
+*/
+var PIE_MAX_AUTO_INNER_RATIO = .06;
+/** How far outside the arc the tooltip anchors, in px. */
+var PIE_TOOLTIP_ANCHOR_INSET = 8;
+/**
+* Default share below which a slice is folded into an "Other" bucket.
+*
+* Slivers this thin are unreadable and effectively unhoverable, so grouping
+* them communicates more than rendering each faithfully.
+*/
+var PIE_MIN_SLICE_SHARE = .02;
+/** Margin around a pie, which needs no axis gutters. */
+var PIE_CHART_MARGIN = {
+	top: 8,
+	right: 8,
+	bottom: 8,
+	left: 8
 };
-/** Spacing between bars within a group (fraction of bandwidth, 0-1) */
-var DEFAULT_BAR_PADDING_INNER = .2;
-/** Spacing around bar groups (fraction of step, 0-1) */
-var DEFAULT_BAR_PADDING_OUTER = .1;
-/** Default bar top-corner radius in px */
-var DEFAULT_BAR_RADIUS = 4;
-/** Default line stroke width in px */
-var DEFAULT_LINE_STROKE_WIDTH = 2;
-/** Default data-point dot radius in px */
-var DEFAULT_LINE_DOT_RADIUS = 4;
-/** Transition duration in ms for hover effects */
-var CHART_TRANSITION_MS = 150;
-/** Default number of y-axis ticks */
-var DEFAULT_Y_TICK_COUNT = 5;
+/**
+* Duration in ms for hover, dim and tooltip transitions.
+*
+* Sits inside the 75–150ms band the DLS uses everywhere else. Hover feedback is
+* a response, not an animation — anything long enough to *watch* reads as the
+* chart being slow rather than the chart being smooth.
+*/
+var CHART_TRANSITION_MS = 100;
+/**
+* Delay in ms before marks return to full strength after the pointer leaves.
+*
+* Restoring immediately makes the whole chart flash while the pointer sweeps
+* across categories. Highlighting stays instant (no delay) — only the
+* *un*-highlight waits, so a sweep reads as one continuous gesture.
+*
+* Kept short because it does less work than it looks: while the pointer is
+* anywhere in the plot the chart is still engaged, so `ChartPlotGroup` and
+* `ChartLegendRow` zero this out and category-to-category sweeping is already
+* instant. All this actually covers is the moment the pointer leaves entirely,
+* where a long delay just feels like lag.
+*/
+var CHART_RESTORE_DELAY_MS = 200;
+/**
+* Opacity ramp for the mark states.
+*
+* The grammar is inherited from the reference charts and is the opposite of the
+* obvious one: hovering does not brighten the hovered mark, it *softens*
+* everything else. `MUTED` applies to marks outside the hovered category;
+* `FADED` to marks outside a *pinned* one.
+*
+* The step down from ACTIVE is deliberately steep. These are large filled areas
+* — bars and arcs — and a filled shape still reads as present at an opacity
+* where a hairline would have vanished, so a timid step barely registers as a
+* highlight at all.
+*
+* Keep `FADED` below `MUTED`, or pinning becomes visually indistinguishable
+* from hovering — the pin exists to say "I am holding this one", which only
+* reads if the rest recede further than they do on hover.
+*/
+var CHART_MARK_OPACITY_ACTIVE = 1;
+var CHART_MARK_OPACITY_MUTED = .1;
+var CHART_MARK_OPACITY_FADED = .04;
+/** Distance in px between the tooltip and its anchor. */
+var CHART_TOOLTIP_OFFSET = 10;
+/** Minimum width of the tooltip, in px. */
+var CHART_TOOLTIP_MIN_WIDTH = 168;
+/** Maximum width of the tooltip, in px. */
+var CHART_TOOLTIP_MAX_WIDTH = 320;
+/**
+* Approximate width of one CAPTION-size character.
+*
+* Axis sizing estimates label widths arithmetically rather than measuring the
+* DOM, so it stays correct during build-time evaluation and server rendering.
+*/
+var CAPTION_CHAR_WIDTH_PX = 6.2;
+/** Ceiling for an auto-sized left margin, so a wide formatter can't eat the plot. */
+var MAX_AUTO_MARGIN_LEFT = 96;
+/** Minimum px between category labels before AUTO mode starts skipping them. */
+var MIN_CATEGORY_LABEL_GAP = 8;
+/**
+* Default assignment order for series colors.
+*
+* Purple leads to match the Galaxy brand. Galaxy blue is deliberately absent —
+* it is structural only, reserved for primary actions and selection.
+*/
+var CHART_PALETTE_ORDER = [
+	ChartPalette.PURPLE,
+	ChartPalette.PINK,
+	ChartPalette.BLUE,
+	ChartPalette.TEAL,
+	ChartPalette.LIME,
+	ChartPalette.ORANGE,
+	ChartPalette.YELLOW,
+	ChartPalette.GREEN,
+	ChartPalette.RED
+];
 //#endregion
-export { CHART_TRANSITION_MS, DEFAULT_BAR_PADDING_INNER, DEFAULT_BAR_PADDING_OUTER, DEFAULT_BAR_RADIUS, DEFAULT_CHART_MARGIN, DEFAULT_LINE_DOT_RADIUS, DEFAULT_LINE_STROKE_WIDTH, DEFAULT_Y_TICK_COUNT, getChartPalette };
+export { AXIS_TITLE_BAND, AXIS_TITLE_GAP, BAR_GAP_COMFORTABLE, BAR_GAP_MEDIUM, BAR_GAP_TIGHT, BAR_RADIUS, BAR_RADIUS_NARROW, BAR_WIDTH_RATIO, CAPTION_CHAR_WIDTH_PX, CATEGORY_AXIS_LABEL_GAP, CATEGORY_AXIS_LABEL_HEIGHT, CHART_MARK_OPACITY_ACTIVE, CHART_MARK_OPACITY_FADED, CHART_MARK_OPACITY_MUTED, CHART_PALETTE_ORDER, CHART_RESTORE_DELAY_MS, CHART_TOOLTIP_MAX_WIDTH, CHART_TOOLTIP_MIN_WIDTH, CHART_TOOLTIP_OFFSET, CHART_TRANSITION_MS, DEFAULT_CHART_MARGIN, DEFAULT_LINE_STROKE_WIDTH, DEFAULT_VALUE_TICK_COUNT, GRID_LINE_BLEED, GROUP_GAP_COMFORTABLE, GROUP_GAP_MEDIUM, GROUP_GAP_TIGHT, LINE_AREA_OPACITY, LINE_POINT_RADIUS, MAX_AUTO_MARGIN_LEFT, MAX_BAR_WIDTH, MAX_GAP_SHARE, MIN_BARS_FOR_TIGHT_SPACING, MIN_BAR_LENGTH, MIN_CATEGORY_LABEL_GAP, NARROW_BAR_WIDTH, PIE_CHART_MARGIN, PIE_CORNER_RADIUS, PIE_DONUT_INNER_RATIO, PIE_MAX_AUTO_INNER_RATIO, PIE_MAX_INSET_SHARE, PIE_MIN_SLICE_SHARE, PIE_PAD_ANGLE, PIE_TOOLTIP_ANCHOR_INSET, STACK_SEGMENT_GAP, VALUE_AXIS_LABEL_HEIGHT, VALUE_AXIS_TICK_GAP, WIDTH_FOR_MEDIUM_SPACING, WIDTH_FOR_TIGHT_SPACING };

package/dist/charts/lineChartGeometry.d.ts

@@ -0,0 +1,54 @@
+import { buildCategoryPointScale, buildValueScale } from "./chartScales";
+import { LineChartCurve } from "./types";
+import type { ChartValueDomain, LineChartColumn, LineChartLineDatum, LineChartPath, LineChartPoint } from "./types";
+/**
+ * The union of every line's categories, in first-seen order.
+ *
+ * Lines are allowed to be sparse, so the axis cannot come from any single one
+ * of them. An explicit `categories` list wins, and is worth supplying whenever
+ * the data is gappy — inferring order from a union of incomplete series is
+ * guesswork, and guessing wrong reorders time.
+ */
+export declare function getLineCategories<TMetric extends string>(lines: LineChartLineDatum<TMetric>[], explicit?: string[]): string[];
+/** Signed value domain across every line, ignoring gaps. */
+export declare function getLineValueDomain<TMetric extends string>(lines: LineChartLineDatum<TMetric>[]): [number, number];
+export interface LineChartGeometry<TMetric extends string> {
+    paths: LineChartPath<TMetric>[];
+    columns: LineChartColumn<TMetric>[];
+    /**
+     * Points with no defined neighbour on either side.
+     *
+     * A lone reading has nothing to connect to, so it produces a zero-length path
+     * segment and renders as nothing at all — a silent hole in sparse data. These
+     * are drawn as explicit dots so the value is visible without hovering.
+     */
+    isolatedPoints: LineChartPoint<TMetric>[];
+    categories: string[];
+    valueScale: ReturnType<typeof buildValueScale>;
+    categoryScale: ReturnType<typeof buildCategoryPointScale>;
+    baselineY: number;
+    /**
+     * Distance between category ticks.
+     *
+     * Exposed because axis labels must be centred on their tick, which is not the
+     * same as being centred on the hit band: the first and last bands are clipped
+     * to the plot edge, and centring a label inside a half-width band pushes it
+     * off its tick.
+     */
+    step: number;
+}
+interface BuildLineChartGeometryArgs<TMetric extends string> {
+    lines: LineChartLineDatum<TMetric>[];
+    categories?: string[];
+    plotWidth: number;
+    plotHeight: number;
+    curve: LineChartCurve;
+    valueDomain?: Partial<ChartValueDomain>;
+    strokeWidth?: number;
+    resolveColor: (args: {
+        metric: TMetric;
+        lineIndex: number;
+    }) => string;
+}
+export declare function buildLineChartGeometry<TMetric extends string>({ lines, categories: explicitCategories, plotWidth, plotHeight, curve, valueDomain, strokeWidth: defaultStrokeWidth, resolveColor, }: BuildLineChartGeometryArgs<TMetric>): LineChartGeometry<TMetric>;
+export {};

package/dist/charts/lineChartGeometry.js

@@ -0,0 +1,143 @@
+import { LineChartCurve } from "./types.js";
+import { DEFAULT_LINE_STROKE_WIDTH } from "./constants.js";
+import { applyDomainOverride, buildCategoryPointScale, buildValueScale, sanitizeValue } from "./chartScales.js";
+import { match } from "ts-pattern";
+import { area, curveLinear, curveMonotoneX, curveStepAfter, line } from "d3-shape";
+//#region src/charts/lineChartGeometry.ts
+function resolveCurve(curve) {
+	return match(curve).with(LineChartCurve.LINEAR, () => curveLinear).with(LineChartCurve.SMOOTH, () => curveMonotoneX).with(LineChartCurve.STEP, () => curveStepAfter).exhaustive();
+}
+/**
+* The union of every line's categories, in first-seen order.
+*
+* Lines are allowed to be sparse, so the axis cannot come from any single one
+* of them. An explicit `categories` list wins, and is worth supplying whenever
+* the data is gappy — inferring order from a union of incomplete series is
+* guesswork, and guessing wrong reorders time.
+*/
+function getLineCategories(lines, explicit) {
+	if (explicit) return explicit;
+	const seen = [];
+	const index = /* @__PURE__ */ new Set();
+	for (const lineDatum of lines) for (const point of lineDatum.points) if (!index.has(point.x)) {
+		index.add(point.x);
+		seen.push(point.x);
+	}
+	return seen;
+}
+/** Signed value domain across every line, ignoring gaps. */
+function getLineValueDomain(lines) {
+	let min = 0;
+	let max = 0;
+	let hasValue = false;
+	for (const lineDatum of lines) for (const point of lineDatum.points) {
+		if (point.y === null || point.y === void 0) continue;
+		const value = sanitizeValue(point.y);
+		if (!hasValue) {
+			min = value;
+			max = value;
+			hasValue = true;
+			continue;
+		}
+		if (value < min) min = value;
+		if (value > max) max = value;
+	}
+	return [Math.min(0, min), Math.max(0, max)];
+}
+function buildLineChartGeometry({ lines, categories: explicitCategories, plotWidth, plotHeight, curve, valueDomain, strokeWidth: defaultStrokeWidth = DEFAULT_LINE_STROKE_WIDTH, resolveColor }) {
+	const categories = getLineCategories(lines, explicitCategories);
+	const valueScale = buildValueScale(applyDomainOverride(getLineValueDomain(lines), valueDomain), [plotHeight, 0]);
+	const categoryScale = buildCategoryPointScale(categories, [0, plotWidth]);
+	const baselineY = valueScale(0);
+	const paths = [];
+	const columns = [];
+	const isolatedPoints = [];
+	if (categories.length === 0 || plotWidth <= 0 || plotHeight <= 0) return {
+		paths,
+		columns,
+		isolatedPoints,
+		categories,
+		valueScale,
+		categoryScale,
+		baselineY,
+		step: 0
+	};
+	const curveFactory = resolveCurve(curve);
+	const categoryIndex = new Map(categories.map((label, index) => [label, index]));
+	const xAt = (index) => categoryScale(categories[index]) ?? 0;
+	const pointsByCategory = categories.map(() => []);
+	lines.forEach((lineDatum, lineIndex) => {
+		const color = resolveColor({
+			metric: lineDatum.metric,
+			lineIndex
+		});
+		const stroke = lineDatum.strokeWidth ?? defaultStrokeWidth;
+		const plotted = categories.map((_, index) => ({
+			categoryIndex: index,
+			value: null
+		}));
+		for (const point of lineDatum.points) {
+			const index = categoryIndex.get(point.x);
+			if (index === void 0) continue;
+			plotted[index].value = point.y === null || point.y === void 0 ? null : sanitizeValue(point.y);
+		}
+		const isDefined = (p) => p.value !== null;
+		const strokePath = line().defined(isDefined).x((p) => xAt(p.categoryIndex)).y((p) => valueScale(p.value)).curve(curveFactory)(plotted) ?? "";
+		const areaPath = lineDatum.showArea ? area().defined(isDefined).x((p) => xAt(p.categoryIndex)).y0(baselineY).y1((p) => valueScale(p.value)).curve(curveFactory)(plotted) ?? void 0 : void 0;
+		paths.push({
+			id: lineDatum.metric,
+			metric: lineDatum.metric,
+			lineIndex,
+			path: strokePath,
+			areaPath,
+			dashArray: lineDatum.dashSize ? `${lineDatum.dashSize} ${lineDatum.dashSize}` : void 0,
+			strokeWidth: stroke,
+			color
+		});
+		plotted.forEach((p, index) => {
+			if (p.value === null) return;
+			const point = {
+				id: `${lineDatum.metric}:${p.categoryIndex}`,
+				metric: lineDatum.metric,
+				categoryIndex: p.categoryIndex,
+				value: p.value,
+				x: xAt(p.categoryIndex),
+				y: valueScale(p.value),
+				color
+			};
+			pointsByCategory[p.categoryIndex].push(point);
+			const hasPrev = index > 0 && plotted[index - 1].value !== null;
+			const hasNext = index < plotted.length - 1 && plotted[index + 1].value !== null;
+			if (!hasPrev && !hasNext) isolatedPoints.push(point);
+		});
+	});
+	const step = categories.length > 1 ? categoryScale.step() : plotWidth;
+	categories.forEach((label, index) => {
+		const x = xAt(index);
+		const points = pointsByCategory[index];
+		const rawBandX = x - step / 2;
+		const bandX = Math.max(0, rawBandX);
+		const bandWidth = Math.min(plotWidth, rawBandX + step) - bandX;
+		columns.push({
+			categoryIndex: index,
+			label,
+			x,
+			bandX,
+			bandWidth,
+			points,
+			anchorY: points.length > 0 ? Math.min(...points.map((p) => p.y)) : baselineY
+		});
+	});
+	return {
+		paths,
+		columns,
+		isolatedPoints,
+		categories,
+		valueScale,
+		categoryScale,
+		baselineY,
+		step
+	};
+}
+//#endregion
+export { buildLineChartGeometry, getLineCategories, getLineValueDomain };

package/dist/charts/pieChartGeometry.d.ts

@@ -0,0 +1,48 @@
+import type { ChartPalette, PieChartArc, PieChartSliceDatum } from "./types";
+/**
+ * Pie and donut geometry.
+ *
+ * Produces a flat array of finished arcs — path, anchor, colour and share all
+ * resolved — so the component body is a `.map()`.
+ *
+ * Pure: no React, no theme access. Colours arrive through a resolver callback.
+ */
+export interface PieChartGeometry<TSlice extends string> {
+    arcs: PieChartArc<TSlice>[];
+    /** Sum of every sanitised value. Zero means there is nothing to draw. */
+    total: number;
+    /** Centre of the pie, in plot coordinates. */
+    centerX: number;
+    centerY: number;
+    outerRadius: number;
+    innerRadius: number;
+}
+interface BuildPieChartGeometryArgs<TSlice extends string> {
+    slices: PieChartSliceDatum<TSlice>[];
+    plotWidth: number;
+    plotHeight: number;
+    /** Hole size as a fraction of the outer radius. `0` is a solid pie. */
+    innerRadiusRatio?: number;
+    padAngle?: number;
+    cornerRadius?: number;
+    /**
+     * Slices below this share of the total are folded into one bucket.
+     *
+     * `0` disables folding. A donut with forty slivers communicates nothing, and
+     * the slivers are individually unhoverable, so a modest default is kinder
+     * than faithfully rendering every one.
+     */
+    minSliceShare?: number;
+    /** Label for the folded bucket. */
+    aggregatedLabel?: string;
+    resolveColor: (args: {
+        sliceKey: TSlice | null;
+        index: number;
+        explicit?: ChartPalette;
+    }) => string;
+    /** Palette override declared by the caller for a given slice. */
+    getSliceColor?: (sliceKey: TSlice) => ChartPalette | undefined;
+    getSliceLabel: (sliceKey: TSlice) => string;
+}
+export declare function buildPieChartGeometry<TSlice extends string>({ slices, plotWidth, plotHeight, innerRadiusRatio, padAngle, cornerRadius, minSliceShare, aggregatedLabel, resolveColor, getSliceColor, getSliceLabel, }: BuildPieChartGeometryArgs<TSlice>): PieChartGeometry<TSlice>;
+export {};

package/dist/charts/pieChartGeometry.js

@@ -0,0 +1,89 @@
+import { AGGREGATED_SLICE_KEY } from "./types.js";
+import { PIE_DONUT_INNER_RATIO, PIE_MAX_AUTO_INNER_RATIO, PIE_MAX_INSET_SHARE, PIE_PAD_ANGLE } from "./constants.js";
+import { sanitizeValue } from "./chartScales.js";
+import { arc, pie } from "d3-shape";
+//#region src/charts/pieChartGeometry.ts
+function buildPieChartGeometry({ slices, plotWidth, plotHeight, innerRadiusRatio = PIE_DONUT_INNER_RATIO, padAngle = PIE_PAD_ANGLE, cornerRadius = 2, minSliceShare = 0, aggregatedLabel = "Other", resolveColor, getSliceColor, getSliceLabel }) {
+	const outerRadius = Math.max(0, Math.min(plotWidth, plotHeight) / 2);
+	const gapWidth = outerRadius * Math.max(0, padAngle);
+	const requestedInnerRadius = outerRadius * Math.min(Math.max(innerRadiusRatio, 0), .95);
+	const centerX = plotWidth / 2;
+	const centerY = plotHeight / 2;
+	const sanitized = slices.map((slice) => ({
+		sliceKey: slice.key,
+		value: Math.max(0, sanitizeValue(slice.value))
+	}));
+	const total = sanitized.reduce((sum, slice) => sum + slice.value, 0);
+	const empty = {
+		arcs: [],
+		total,
+		centerX,
+		centerY,
+		outerRadius,
+		innerRadius: requestedInnerRadius
+	};
+	if (total <= 0 || outerRadius <= 0) return empty;
+	const kept = [];
+	let foldedValue = 0;
+	for (const slice of sanitized) {
+		const share = slice.value / total;
+		if (minSliceShare > 0 && share < minSliceShare) {
+			foldedValue += slice.value;
+			continue;
+		}
+		kept.push({
+			sliceKey: slice.sliceKey,
+			label: getSliceLabel(slice.sliceKey),
+			value: slice.value,
+			explicit: getSliceColor?.(slice.sliceKey),
+			isAggregated: false
+		});
+	}
+	if (foldedValue > 0) kept.push({
+		sliceKey: null,
+		label: aggregatedLabel,
+		value: foldedValue,
+		isAggregated: true
+	});
+	const maxInset = kept.reduce((min, slice) => Math.min(min, slice.value), Infinity) / total * 2 * Math.PI * PIE_MAX_INSET_SHARE / 2;
+	const solvedInnerRadius = gapWidth > 0 && maxInset > 0 ? gapWidth / 2 / Math.sin(maxInset) : 0;
+	const innerRadius = Math.max(requestedInnerRadius, Math.min(solvedInnerRadius, outerRadius * PIE_MAX_AUTO_INNER_RATIO));
+	const layout = pie().sort(null).value((slice) => slice.value).padAngle(padAngle);
+	const arcGenerator = arc().innerRadius(innerRadius).outerRadius(outerRadius).cornerRadius(cornerRadius);
+	return {
+		arcs: layout(kept).map((slot, index) => {
+			const slice = slot.data;
+			const midAngle = (slot.startAngle + slot.endAngle) / 2;
+			const anchorRadius = outerRadius + 8;
+			return {
+				id: slice.isAggregated ? AGGREGATED_SLICE_KEY : slice.sliceKey,
+				sliceKey: slice.sliceKey,
+				label: slice.label,
+				value: slice.value,
+				share: slice.value / total,
+				path: arcGenerator({
+					startAngle: slot.startAngle,
+					endAngle: slot.endAngle,
+					padAngle: slot.padAngle
+				}) ?? "",
+				startAngle: slot.startAngle,
+				endAngle: slot.endAngle,
+				anchorX: centerX + Math.sin(midAngle) * anchorRadius,
+				anchorY: centerY - Math.cos(midAngle) * anchorRadius,
+				color: resolveColor({
+					sliceKey: slice.sliceKey,
+					index,
+					explicit: slice.explicit
+				}),
+				isAggregated: slice.isAggregated
+			};
+		}),
+		total,
+		centerX,
+		centerY,
+		outerRadius,
+		innerRadius
+	};
+}
+//#endregion
+export { buildPieChartGeometry };