@galaxy-io/dls 1.2.7 → 1.3.1

package/dist/charts/barChartGeometry.js

@@ -0,0 +1,210 @@
+import { BarChartNormalization, BarCorners } from "./types.js";
+import { BAR_WIDTH_RATIO, MAX_GAP_SHARE } from "./constants.js";
+import { 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, domain, resolveColor }) {
+	const valueScale = buildValueScale(domain, [plotHeight, 0]);
+	const baselineY = valueScale(0);
+	const rects = [];
+	const bands = [];
+	if (groups.length === 0 || plotWidth <= 0 || plotHeight <= 0) return {
+		rects,
+		bands,
+		valueScale
+	};
+	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;
+		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;
+				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,
+					metric: bar.metric,
+					componentKey: component.key,
+					label: component.label,
+					value,
+					x: barX,
+					y,
+					width: barWidth,
+					height,
+					color: resolveColor({
+						metric: bar.metric,
+						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
+		});
+	});
+	return {
+		rects,
+		bands,
+		valueScale
+	};
+}
+//#endregion
+export { buildBarChartGeometry, getBarValueDomain, roundedRectPath };

package/dist/charts/barChartLegend.d.ts

@@ -0,0 +1,25 @@
+import type { BarChartGroupDatum, ChartLegendItem, ChartSeriesStyles } from "./types";
+import type { SeriesColorResolver } from "./useSeriesColorResolver";
+/**
+ * Legend entries for a bar chart.
+ *
+ * A pure walk over the data, kept out of the component because it is the one
+ * legend in the DLS that cannot be a `.map()` over the `series` record: a bar's
+ * *components* are a second dimension with no record of their own, so a stacked
+ * chart's legend has to be recovered from the data itself.
+ */
+interface GetBarLegendItemsArgs<TMetric extends string, TComponentKey extends string> {
+    /**
+     * Whether the chart as a whole is stacked.
+     *
+     * Decides which dimension the legend names, and must match the flag the
+     * geometry coloured with — a legend naming metrics beside bars coloured by
+     * component describes a chart that is not on screen.
+     */
+    isStacked: boolean;
+    series: ChartSeriesStyles<TMetric>;
+    groups: BarChartGroupDatum<TMetric, TComponentKey>[];
+    colors: SeriesColorResolver<TMetric>;
+}
+export declare function getBarLegendItems<TMetric extends string, TComponentKey extends string>({ isStacked, series, groups, colors, }: GetBarLegendItemsArgs<TMetric, TComponentKey>): ChartLegendItem[];
+export {};

package/dist/charts/barChartLegend.js

@@ -0,0 +1,23 @@
+//#region src/charts/barChartLegend.ts
+function getBarLegendItems({ isStacked, series, groups, colors }) {
+	if (!isStacked) return colors.keys.map((metric) => ({
+		key: metric,
+		label: series[metric].label,
+		color: colors.resolve(metric)
+	}));
+	const seen = /* @__PURE__ */ new Map();
+	for (const group of groups) for (const bar of group.bars) bar.components.forEach((component, componentIndex) => {
+		if (!seen.has(component.key)) seen.set(component.key, {
+			label: component.label,
+			index: componentIndex,
+			explicit: component.color
+		});
+	});
+	return [...seen.entries()].map(([key, { label, index, explicit }]) => ({
+		key,
+		label,
+		color: colors.resolveByIndex(index, explicit)
+	}));
+}
+//#endregion
+export { getBarLegendItems };

package/dist/charts/chartFormat.d.ts

@@ -0,0 +1,27 @@
+import { ChartValueUnit } from "./types";
+import type { ChartLabelFormatter, ChartPlotTooltipModel, 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;
+/**
+ * Flatten a tooltip model into one sentence, for a screen reader.
+ *
+ * Derived from the tooltip rather than written separately so the two cannot
+ * drift: whatever a sighted reader sees on hover is what a keyboard reader
+ * hears on focus, by construction.
+ */
+export declare function describeTooltipModel(model: ChartPlotTooltipModel): string;

package/dist/charts/chartFormat.js

@@ -0,0 +1,71 @@
+import { ChartValueUnit } from "./types.js";
+import { match } from "ts-pattern";
+//#region src/charts/chartFormat.ts
+/**
+* Value and label formatting for the chart components.
+*
+* Resolving the formatter once, centrally, is what keeps axis ticks, value
+* labels and tooltip rows from drifting apart — a recurring problem when every
+* call site writes its own one-liner.
+*/
+/**
+* `Intl` formatters are comparatively expensive to construct, and the charts
+* format every tick and tooltip row on each render, so instances are cached per
+* unit.
+*/
+var FORMATTER_CACHE = /* @__PURE__ */ new Map();
+function getIntlFormatter(unit) {
+	const cached = FORMATTER_CACHE.get(unit);
+	if (cached) return cached;
+	const formatter = match(unit).with(ChartValueUnit.PLAIN, () => new Intl.NumberFormat(void 0, { maximumFractionDigits: 2 })).with(ChartValueUnit.CURRENCY, () => new Intl.NumberFormat(void 0, {
+		style: "currency",
+		currency: "USD",
+		maximumFractionDigits: 0
+	})).with(ChartValueUnit.PERCENT, () => new Intl.NumberFormat(void 0, { maximumFractionDigits: 1 })).with(ChartValueUnit.COMPACT, () => new Intl.NumberFormat(void 0, {
+		notation: "compact",
+		maximumFractionDigits: 1
+	})).exhaustive();
+	FORMATTER_CACHE.set(unit, formatter);
+	return formatter;
+}
+/**
+* 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).
+*/
+function formatChartValue(value, unit) {
+	if (!Number.isFinite(value)) return "—";
+	const formatted = getIntlFormatter(unit).format(value);
+	return unit === ChartValueUnit.PERCENT ? `${formatted}%` : formatted;
+}
+/**
+* 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.
+*/
+function resolveValueFormatter(valueFormatter, unit) {
+	if (valueFormatter) return valueFormatter;
+	const resolvedUnit = unit ?? ChartValueUnit.PLAIN;
+	return (value) => formatChartValue(value, resolvedUnit);
+}
+/** Pick the effective label formatter, defaulting to identity. */
+function resolveLabelFormatter(labelFormatter) {
+	return labelFormatter ?? ((label) => label);
+}
+/**
+* Flatten a tooltip model into one sentence, for a screen reader.
+*
+* Derived from the tooltip rather than written separately so the two cannot
+* drift: whatever a sighted reader sees on hover is what a keyboard reader
+* hears on focus, by construction.
+*/
+function describeTooltipModel(model) {
+	if (model.rows.length === 0) return model.label;
+	const rows = model.rows.map((row) => `${row.label} ${row.formattedValue}`).join(", ");
+	return `${model.label}: ${rows}`;
+}
+//#endregion
+export { describeTooltipModel, formatChartValue, resolveLabelFormatter, resolveValueFormatter };

package/dist/charts/chartScales.d.ts

@@ -0,0 +1,120 @@
+import type { ChartMargin, ChartValueDomain, ChartValueFormatter } from "./types";
+/**
+ * Scale construction and axis sizing for the chart components.
+ *
+ * Pure arithmetic with no React and no theme access, so it can be unit-reasoned
+ * about and stays safe for Linaria's build-time evaluation.
+ */
+export declare function clamp(value: number, min: number, max: number): number;
+/**
+ * Coerce a datum value into something safe to feed a scale.
+ *
+ * A single `NaN` or `Infinity` in consumer data otherwise propagates into every
+ * path's `d` attribute and blanks the entire chart rather than one mark.
+ */
+export declare function sanitizeValue(value: number | undefined | null): number;
+/**
+ * Merge a partial margin over the defaults.
+ *
+ * Written per-field rather than as a spread: spreading an object that carries
+ * an explicit `undefined` overwrites the default with `undefined` rather than
+ * falling back to it, which is easy to trip over when the partial is assembled
+ * from separate optional values.
+ *
+ * `defaults` exists because the cartesian default reserves axis gutters a
+ * radial chart has no use for. Taking it as a parameter keeps the merge
+ * per-field: a chart that substituted its own defaults with `margin ?? OWN`
+ * would silently fall back to the *cartesian* defaults the moment a caller
+ * passed a partial, handing an axis-less chart a 52px left gutter.
+ */
+export declare function resolveMargin(partial?: Partial<ChartMargin>, defaults?: ChartMargin): ChartMargin;
+/** Inner plot dimensions, never negative. */
+export declare function getPlotDimensions(width: number, height: number, margin: ChartMargin): {
+    plotWidth: number;
+    plotHeight: number;
+};
+/**
+ * Widen a margin to leave room for axis titles.
+ *
+ * The reservation has to happen here rather than inside the axis, because the
+ * margin is resolved before any axis renders — and with the root SVG set to
+ * `overflow: visible`, an unreserved title would paint outside the container and
+ * be clipped by whatever the consumer wraps the chart in.
+ *
+ * Applied to the caller's *partial* before {@link resolveMargin} fills in the
+ * defaults, so an explicit `margin.left` still governs the tick gutter and the
+ * title band is added on top of it rather than eating into it. Returns the input
+ * untouched when there are no titles, so the common case allocates nothing.
+ */
+export declare function addAxisTitleSpace(partial: Partial<ChartMargin> | undefined, { hasValueTitle, hasCategoryTitle }: {
+    hasValueTitle: boolean;
+    hasCategoryTitle: boolean;
+}): Partial<ChartMargin> | undefined;
+/**
+ * Turn a raw data extent into the domain the axis and the marks both use.
+ *
+ * Applies the caller's override, then three behaviours worth knowing:
+ *
+ * - **Zero is always in the domain.** Bars need a baseline to grow from, and
+ *   without this a negative value maps outside the range and renders as a
+ *   rectangle with negative height, which paints nothing at all.
+ * - **A zero-width domain is widened to 0–1.** d3's `normalize()` returns a
+ *   constant `0.5` when the domain has no extent, so empty or all-zero data
+ *   would otherwise map every value to the middle of the plot and strand the
+ *   baseline halfway up.
+ * - **`nice()` rounds the ends outward** to values a reader would choose.
+ *
+ * Split out of {@link buildValueScale} so the domain is computed exactly once
+ * per chart and then handed to both the tick list and the geometry. Building it
+ * twice — once at a throwaway range to get ticks, once at the real range to
+ * place marks — leaves two `nice()` calls that must agree forever.
+ *
+ * `nice()` deliberately takes **no argument**. The default count is 10, not the
+ * five ticks {@link DEFAULT_VALUE_TICK_COUNT} asks for, and nicing to the tick
+ * count instead would change the axis extent on every existing chart.
+ */
+export declare function resolveValueDomain(raw: [number, number], override?: Partial<ChartValueDomain>): [number, number];
+/**
+ * Linear scale over an already-resolved domain.
+ *
+ * Does no nicing and no zero-forcing — {@link resolveValueDomain} has done
+ * both. Takes the domain rather than raw data so the same numbers drive the
+ * axis, the ticks and every mark.
+ */
+export declare function buildValueScale(domain: [number, number], range: [number, number]): import("d3-scale").ScaleLinear<number, number, never>;
+/** Point scale for categories, used by the line chart. */
+export declare function buildCategoryPointScale(labels: string[], range: [number, number], padding?: number): import("d3-scale").ScalePoint<string>;
+/**
+ * Left margin needed to fit the widest formatted tick label.
+ *
+ * Estimated from character count rather than measured from the DOM, mirroring
+ * `estimateColumnWidth` in `table/utils.ts`, so it works during server rendering
+ * and build-time evaluation. The estimate only has to be close: tick labels
+ * right-align against the plot and ellipsize, so an underestimate truncates one
+ * label rather than breaking the layout, and {@link MAX_AUTO_MARGIN_LEFT} caps
+ * what a pathological formatter can take from the plot.
+ *
+ * Rounded up to {@link AUTO_MARGIN_LEFT_STEP} rather than used raw — see that
+ * constant for why an exact fit is the wrong target.
+ *
+ * Safe to call before the chart has been measured: `nice()` and `ticks()` depend
+ * on the domain and the requested count, never on the scale's range, so the tick
+ * values here are the same ones the axis renders later.
+ */
+export declare function estimateValueAxisMargin(ticks: number[], formatter: ChartValueFormatter): number;
+/**
+ * How many categories to skip between rendered axis labels.
+ *
+ * Returns 1 when every label fits, so a chart that is not crowded renders
+ * exactly as it would with no skipping at all.
+ */
+export declare function getCategoryLabelStride(labels: string[], step: number): number;
+/**
+ * Tick values for a resolved domain, honoring an explicit tick count.
+ *
+ * Needs no dimensions, which is what breaks the apparent circularity in the
+ * layout: the left margin must fit the tick labels, the margin decides the plot
+ * size, and the plot size builds the scale. Tick *values* fall out of the domain
+ * alone, so they can be known before anything is measured.
+ */
+export declare function getValueTicks(domain: [number, number], override?: Partial<ChartValueDomain>): number[];

package/dist/charts/chartScales.js

@@ -0,0 +1,165 @@
+import { CAPTION_CHAR_WIDTH_PX, DEFAULT_CHART_MARGIN } from "./constants.js";
+import { scaleLinear, scalePoint } from "d3-scale";
+//#region src/charts/chartScales.ts
+/**
+* Scale construction and axis sizing for the chart components.
+*
+* Pure arithmetic with no React and no theme access, so it can be unit-reasoned
+* about and stays safe for Linaria's build-time evaluation.
+*/
+function clamp(value, min, max) {
+	return Math.min(Math.max(value, min), max);
+}
+/**
+* Coerce a datum value into something safe to feed a scale.
+*
+* A single `NaN` or `Infinity` in consumer data otherwise propagates into every
+* path's `d` attribute and blanks the entire chart rather than one mark.
+*/
+function sanitizeValue(value) {
+	return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+/**
+* Merge a partial margin over the defaults.
+*
+* Written per-field rather than as a spread: spreading an object that carries
+* an explicit `undefined` overwrites the default with `undefined` rather than
+* falling back to it, which is easy to trip over when the partial is assembled
+* from separate optional values.
+*
+* `defaults` exists because the cartesian default reserves axis gutters a
+* radial chart has no use for. Taking it as a parameter keeps the merge
+* per-field: a chart that substituted its own defaults with `margin ?? OWN`
+* would silently fall back to the *cartesian* defaults the moment a caller
+* passed a partial, handing an axis-less chart a 52px left gutter.
+*/
+function resolveMargin(partial, defaults = DEFAULT_CHART_MARGIN) {
+	return {
+		top: partial?.top ?? defaults.top,
+		right: partial?.right ?? defaults.right,
+		bottom: partial?.bottom ?? defaults.bottom,
+		left: partial?.left ?? defaults.left
+	};
+}
+/** Inner plot dimensions, never negative. */
+function getPlotDimensions(width, height, margin) {
+	return {
+		plotWidth: Math.max(0, width - margin.left - margin.right),
+		plotHeight: Math.max(0, height - margin.top - margin.bottom)
+	};
+}
+/**
+* Widen a margin to leave room for axis titles.
+*
+* The reservation has to happen here rather than inside the axis, because the
+* margin is resolved before any axis renders — and with the root SVG set to
+* `overflow: visible`, an unreserved title would paint outside the container and
+* be clipped by whatever the consumer wraps the chart in.
+*
+* Applied to the caller's *partial* before {@link resolveMargin} fills in the
+* defaults, so an explicit `margin.left` still governs the tick gutter and the
+* title band is added on top of it rather than eating into it. Returns the input
+* untouched when there are no titles, so the common case allocates nothing.
+*/
+function addAxisTitleSpace(partial, { hasValueTitle, hasCategoryTitle }) {
+	if (!hasValueTitle && !hasCategoryTitle) return partial;
+	return {
+		...partial,
+		left: (partial?.left ?? DEFAULT_CHART_MARGIN.left) + (hasValueTitle ? 26 : 0),
+		bottom: (partial?.bottom ?? DEFAULT_CHART_MARGIN.bottom) + (hasCategoryTitle ? 18 : 0)
+	};
+}
+/**
+* Turn a raw data extent into the domain the axis and the marks both use.
+*
+* Applies the caller's override, then three behaviours worth knowing:
+*
+* - **Zero is always in the domain.** Bars need a baseline to grow from, and
+*   without this a negative value maps outside the range and renders as a
+*   rectangle with negative height, which paints nothing at all.
+* - **A zero-width domain is widened to 0–1.** d3's `normalize()` returns a
+*   constant `0.5` when the domain has no extent, so empty or all-zero data
+*   would otherwise map every value to the middle of the plot and strand the
+*   baseline halfway up.
+* - **`nice()` rounds the ends outward** to values a reader would choose.
+*
+* Split out of {@link buildValueScale} so the domain is computed exactly once
+* per chart and then handed to both the tick list and the geometry. Building it
+* twice — once at a throwaway range to get ticks, once at the real range to
+* place marks — leaves two `nice()` calls that must agree forever.
+*
+* `nice()` deliberately takes **no argument**. The default count is 10, not the
+* five ticks {@link DEFAULT_VALUE_TICK_COUNT} asks for, and nicing to the tick
+* count instead would change the axis extent on every existing chart.
+*/
+function resolveValueDomain(raw, override) {
+	const min = override?.min ?? raw[0];
+	const max = override?.max ?? raw[1];
+	const lo = Math.min(0, min);
+	const hi = Math.max(0, max);
+	const [niceLo, niceHi] = scaleLinear().domain([lo, lo === hi ? hi + 1 : hi]).nice().domain();
+	return [niceLo, niceHi];
+}
+/**
+* Linear scale over an already-resolved domain.
+*
+* Does no nicing and no zero-forcing — {@link resolveValueDomain} has done
+* both. Takes the domain rather than raw data so the same numbers drive the
+* axis, the ticks and every mark.
+*/
+function buildValueScale(domain, range) {
+	return scaleLinear().domain(domain).range(range);
+}
+/** Point scale for categories, used by the line chart. */
+function buildCategoryPointScale(labels, range, padding = 0) {
+	return scalePoint().domain(labels).range(range).padding(padding);
+}
+/**
+* Left margin needed to fit the widest formatted tick label.
+*
+* Estimated from character count rather than measured from the DOM, mirroring
+* `estimateColumnWidth` in `table/utils.ts`, so it works during server rendering
+* and build-time evaluation. The estimate only has to be close: tick labels
+* right-align against the plot and ellipsize, so an underestimate truncates one
+* label rather than breaking the layout, and {@link MAX_AUTO_MARGIN_LEFT} caps
+* what a pathological formatter can take from the plot.
+*
+* Rounded up to {@link AUTO_MARGIN_LEFT_STEP} rather than used raw — see that
+* constant for why an exact fit is the wrong target.
+*
+* Safe to call before the chart has been measured: `nice()` and `ticks()` depend
+* on the domain and the requested count, never on the scale's range, so the tick
+* values here are the same ones the axis renders later.
+*/
+function estimateValueAxisMargin(ticks, formatter) {
+	let widest = 0;
+	for (const tick of ticks) widest = Math.max(widest, formatter(tick).length * CAPTION_CHAR_WIDTH_PX);
+	const needed = Math.ceil(widest) + 12;
+	return clamp(Math.ceil(needed / 8) * 8, 32, 96);
+}
+/**
+* How many categories to skip between rendered axis labels.
+*
+* Returns 1 when every label fits, so a chart that is not crowded renders
+* exactly as it would with no skipping at all.
+*/
+function getCategoryLabelStride(labels, step) {
+	if (labels.length === 0 || step <= 0) return 1;
+	let widest = 0;
+	for (const label of labels) widest = Math.max(widest, label.length * CAPTION_CHAR_WIDTH_PX);
+	const required = widest + 8;
+	return required <= step ? 1 : Math.ceil(required / step);
+}
+/**
+* Tick values for a resolved domain, honoring an explicit tick count.
+*
+* Needs no dimensions, which is what breaks the apparent circularity in the
+* layout: the left margin must fit the tick labels, the margin decides the plot
+* size, and the plot size builds the scale. Tick *values* fall out of the domain
+* alone, so they can be known before anything is measured.
+*/
+function getValueTicks(domain, override) {
+	return scaleLinear().domain(domain).ticks(override?.tickCount ?? 5);
+}
+//#endregion
+export { addAxisTitleSpace, buildCategoryPointScale, buildValueScale, clamp, estimateValueAxisMargin, getCategoryLabelStride, getPlotDimensions, getValueTicks, resolveMargin, resolveValueDomain, sanitizeValue };

package/dist/charts/chartTheme.d.ts

@@ -0,0 +1,18 @@
+import type { Theme } from "../theme/types";
+import { ChartPalette } from "./types";
+/**
+ * Palette resolution for the chart components.
+ *
+ * Consumer data names a {@link ChartPalette} slot; the concrete color is looked
+ * up here against the active theme. That keeps raw hex out of application data
+ * and guarantees both themes render correctly.
+ *
+ * Linaria evaluates this module at build time, so it must not import components.
+ */
+/** Resolve a palette slot to a concrete color for the active theme. */
+export declare function resolveChartPaletteColor(theme: Theme, palette: ChartPalette): string;
+/**
+ * Resolve the color for a series, honoring an explicit slot and otherwise
+ * falling back to the series' position in the default palette order.
+ */
+export declare function resolveSeriesColor(theme: Theme, index: number, palette?: ChartPalette): string;