@galaxy-io/dls 1.2.7 → 1.3.1

package/dist/charts/useCartesianChartLayout.d.ts

@@ -0,0 +1,70 @@
+import type { ChartLabelFormatter, ChartMargin, ChartValueDomain, ChartValueFormatter, ChartValueUnit } from "./types";
+import type { ChartDimensions } from "./useChartDimensions";
+/**
+ * Everything a cartesian chart resolves *before* it can be measured.
+ *
+ * There is a hard ordering inside bar and line alike:
+ *
+ * ```
+ * domain → ticks → left margin → dimensions → plot size → geometry
+ * ```
+ *
+ * The gutter has to fit the tick labels, the ticks come from the domain, and
+ * the domain comes from the data — none of which needs the plot. Everything
+ * after `geometry` does need it, which is why this hook stops there rather than
+ * trying to own the whole chart: the geometry builders are generic over the
+ * chart's own key types, and threading those through here would buy nothing.
+ *
+ * Deliberately **not generic**. `getBarValueDomain` and `getLineValueDomain`
+ * have already erased the key types by the time they return an extent, so
+ * nothing in this phase needs them.
+ */
+interface UseCartesianChartLayoutOptions {
+    containerRef: React.RefObject<HTMLDivElement | null>;
+    /**
+     * The data's own extent, before any override or nicing.
+     *
+     * Free to be a fresh array each render — the memo below keys on the two
+     * numbers, not the array's identity.
+     */
+    rawDomain: [number, number];
+    valueDomain?: Partial<ChartValueDomain>;
+    width?: number;
+    height?: number;
+    fillWidth?: boolean;
+    fillHeight?: boolean;
+    aspectRatio?: number;
+    margin?: Partial<ChartMargin>;
+    valueUnit?: ChartValueUnit;
+    valueFormatter?: ChartValueFormatter;
+    labelFormatter?: ChartLabelFormatter;
+    /**
+     * Rewrites the resolved value formatter for the axis alone.
+     *
+     * Takes the resolved formatter rather than replacing it, because the only
+     * caller — a percent-normalized bar chart — falls back to it whenever the
+     * consumer asked for something specific. Applies to the tick labels *and* the
+     * gutter estimate, which is the point: sizing the gutter with a different
+     * formatter than the one that renders into it is how a gutter ends up too
+     * narrow for its own labels.
+     *
+     * Must be stable; memoize it at the call site.
+     */
+    deriveAxisFormatter?: (formatValue: ChartValueFormatter) => ChartValueFormatter;
+    valueAxisTitle?: string;
+    categoryAxisTitle?: string;
+}
+export interface CartesianChartLayout {
+    dimensions: ChartDimensions;
+    /** Override applied, zero included, degenerate widened, `nice()` applied. */
+    domain: [number, number];
+    valueTicks: number[];
+    /** Tooltip rows and value labels. */
+    formatValue: ChartValueFormatter;
+    /** Category names — the axis and the tooltip heading. */
+    formatLabel: ChartLabelFormatter;
+    /** Axis ticks. Identical to `formatValue` unless `deriveAxisFormatter` said otherwise. */
+    formatAxisValue: ChartValueFormatter;
+}
+export declare function useCartesianChartLayout({ containerRef, rawDomain, valueDomain, width, height, fillWidth, fillHeight, aspectRatio, margin, valueUnit, valueFormatter, labelFormatter, deriveAxisFormatter, valueAxisTitle, categoryAxisTitle, }: UseCartesianChartLayoutOptions): CartesianChartLayout;
+export {};

package/dist/charts/useCartesianChartLayout.js

@@ -0,0 +1,56 @@
+import { addAxisTitleSpace, estimateValueAxisMargin, getValueTicks, resolveValueDomain } from "./chartScales.js";
+import { useChartFormatters } from "./useChartFormatters.js";
+import { useChartDimensions } from "./useChartDimensions.js";
+import { useMemo } from "react";
+//#region src/charts/useCartesianChartLayout.ts
+function useCartesianChartLayout({ containerRef, rawDomain, valueDomain, width, height, fillWidth, fillHeight, aspectRatio, margin, valueUnit, valueFormatter, labelFormatter, deriveAxisFormatter, valueAxisTitle, categoryAxisTitle }) {
+	const { formatValue, formatLabel } = useChartFormatters({
+		valueFormatter,
+		valueUnit,
+		labelFormatter
+	});
+	const formatAxisValue = useMemo(() => deriveAxisFormatter?.(formatValue) ?? formatValue, [deriveAxisFormatter, formatValue]);
+	const [rawMin, rawMax] = rawDomain;
+	const domain = useMemo(() => resolveValueDomain([rawMin, rawMax], valueDomain), [
+		rawMin,
+		rawMax,
+		valueDomain
+	]);
+	const valueTicks = useMemo(() => getValueTicks(domain, valueDomain), [domain, valueDomain]);
+	const dimensions = useChartDimensions({
+		containerRef,
+		width,
+		height,
+		fillWidth,
+		fillHeight,
+		aspectRatio,
+		margin: addAxisTitleSpace(useMemo(() => ({
+			...margin,
+			left: margin?.left ?? estimateValueAxisMargin(valueTicks, formatAxisValue)
+		}), [
+			margin,
+			valueTicks,
+			formatAxisValue
+		]), {
+			hasValueTitle: Boolean(valueAxisTitle),
+			hasCategoryTitle: Boolean(categoryAxisTitle)
+		})
+	});
+	return useMemo(() => ({
+		dimensions,
+		domain,
+		valueTicks,
+		formatValue,
+		formatLabel,
+		formatAxisValue
+	}), [
+		dimensions,
+		domain,
+		valueTicks,
+		formatValue,
+		formatLabel,
+		formatAxisValue
+	]);
+}
+//#endregion
+export { useCartesianChartLayout };

package/dist/charts/useChartDimensions.d.ts

@@ -0,0 +1,47 @@
+import type { ChartMargin } from "./types";
+interface UseChartDimensionsOptions {
+    /**
+     * The element to measure.
+     *
+     * Owned by the caller rather than returned from here: a hook that hands back
+     * a ref inside its result object reads as a ref access during render, both to
+     * the `react-hooks/refs` lint rule and to anyone reviewing the call site.
+     */
+    containerRef: React.RefObject<HTMLElement | null>;
+    width?: number;
+    height?: number;
+    fillWidth?: boolean;
+    /**
+     * Take the height from the measured box rather than a prop.
+     *
+     * Requires an ancestor with a definite height — see {@link ChartSize}. The
+     * measured element is the *plot box*, not the chart root, so the legend is
+     * already excluded by flexbox and nothing here has to subtract it.
+     */
+    fillHeight?: boolean;
+    aspectRatio?: number;
+    margin?: Partial<ChartMargin>;
+    /**
+     * Fallback for whichever fields `margin` leaves out.
+     *
+     * Radial charts pass their own, since the cartesian default reserves gutters
+     * for axes they do not draw. Merged per field, so a caller's partial margin
+     * lands on top of *this* rather than reverting the chart to the cartesian
+     * defaults.
+     */
+    defaultMargin?: ChartMargin;
+}
+export interface ChartDimensions {
+    width: number;
+    height: number;
+    plotWidth: number;
+    plotHeight: number;
+    margin: ChartMargin;
+    /** False until the box has usable dimensions; guard mark rendering on it. */
+    isMeasured: boolean;
+    /** Handed to the plot box so it reserves space before measurement lands. */
+    reservedHeight?: number;
+    reservedAspectRatio?: number;
+}
+export declare function useChartDimensions({ containerRef, width, height, fillWidth, fillHeight, aspectRatio, margin: marginOverride, defaultMargin, }: UseChartDimensionsOptions): ChartDimensions;
+export {};

package/dist/charts/useChartDimensions.js

@@ -0,0 +1,63 @@
+import { useElementClientSize } from "../hooks/useElementClientSize.js";
+import { DEFAULT_CHART_MARGIN } from "./constants.js";
+import { getPlotDimensions, resolveMargin } from "./chartScales.js";
+import { useEffect, useMemo } from "react";
+//#region src/charts/useChartDimensions.ts
+function useChartDimensions({ containerRef, width, height, fillWidth = false, fillHeight = false, aspectRatio, margin: marginOverride, defaultMargin }) {
+	const { width: measuredWidth, height: measuredHeight } = useElementClientSize(containerRef);
+	const resolvedWidth = fillWidth ? measuredWidth ?? 0 : width ?? 0;
+	const resolvedHeight = fillHeight ? measuredHeight ?? 0 : aspectRatio ? resolvedWidth / aspectRatio : height ?? 0;
+	const { top: marginTop, right: marginRight, bottom: marginBottom, left: marginLeft } = marginOverride ?? {};
+	const { top: defaultTop, right: defaultRight, bottom: defaultBottom, left: defaultLeft } = defaultMargin ?? DEFAULT_CHART_MARGIN;
+	const margin = useMemo(() => resolveMargin({
+		top: marginTop,
+		right: marginRight,
+		bottom: marginBottom,
+		left: marginLeft
+	}, {
+		top: defaultTop,
+		right: defaultRight,
+		bottom: defaultBottom,
+		left: defaultLeft
+	}), [
+		marginTop,
+		marginRight,
+		marginBottom,
+		marginLeft,
+		defaultTop,
+		defaultRight,
+		defaultBottom,
+		defaultLeft
+	]);
+	const { plotWidth, plotHeight } = useMemo(() => getPlotDimensions(resolvedWidth, resolvedHeight, margin), [
+		resolvedWidth,
+		resolvedHeight,
+		margin
+	]);
+	useEffect(() => {
+		if (typeof process !== "undefined" && process.env.NODE_ENV === "production") return;
+		if (!fillHeight || measuredHeight === void 0 || measuredHeight > 0) return;
+		console.warn("[@galaxy-io/dls] A chart with `fillHeight` measured 0px tall and will not render. `fillHeight` takes its height from the container, so an ancestor needs a definite height — an explicit height, a flex or grid track, or absolute positioning. Use `height` or `aspectRatio` instead if the container is sized by its content.");
+	}, [fillHeight, measuredHeight]);
+	return useMemo(() => ({
+		width: resolvedWidth,
+		height: resolvedHeight,
+		plotWidth,
+		plotHeight,
+		margin,
+		isMeasured: resolvedWidth > 0 && resolvedHeight > 0,
+		reservedHeight: fillHeight || aspectRatio ? void 0 : height,
+		reservedAspectRatio: fillHeight ? void 0 : aspectRatio
+	}), [
+		resolvedWidth,
+		resolvedHeight,
+		plotWidth,
+		plotHeight,
+		margin,
+		aspectRatio,
+		height,
+		fillHeight
+	]);
+}
+//#endregion
+export { useChartDimensions };

package/dist/charts/useChartFormatters.d.ts

@@ -0,0 +1,19 @@
+import type { ChartLabelFormatter, ChartValueFormatter, ChartValueUnit } from "./types";
+interface UseChartFormattersOptions {
+    valueFormatter?: ChartValueFormatter;
+    valueUnit?: ChartValueUnit;
+    labelFormatter?: ChartLabelFormatter;
+}
+export interface ChartFormatters {
+    formatValue: ChartValueFormatter;
+    formatLabel: ChartLabelFormatter;
+}
+/**
+ * Resolves the value and label formatters once per chart.
+ *
+ * Doing this centrally is what keeps axis ticks, value labels and tooltip rows
+ * from drifting apart — the recurring failure when each call site formats for
+ * itself.
+ */
+export declare function useChartFormatters({ valueFormatter, valueUnit, labelFormatter, }: UseChartFormattersOptions): ChartFormatters;
+export {};

package/dist/charts/useChartFormatters.js

@@ -0,0 +1,20 @@
+import { resolveLabelFormatter, resolveValueFormatter } from "./chartFormat.js";
+import { useMemo } from "react";
+//#region src/charts/useChartFormatters.ts
+/**
+* Resolves the value and label formatters once per chart.
+*
+* Doing this centrally is what keeps axis ticks, value labels and tooltip rows
+* from drifting apart — the recurring failure when each call site formats for
+* itself.
+*/
+function useChartFormatters({ valueFormatter, valueUnit, labelFormatter }) {
+	const formatValue = useMemo(() => resolveValueFormatter(valueFormatter, valueUnit), [valueFormatter, valueUnit]);
+	const formatLabel = useMemo(() => resolveLabelFormatter(labelFormatter), [labelFormatter]);
+	return useMemo(() => ({
+		formatValue,
+		formatLabel
+	}), [formatValue, formatLabel]);
+}
+//#endregion
+export { useChartFormatters };

package/dist/charts/useChartInteraction.d.ts

@@ -0,0 +1,76 @@
+import { ChartMarkState } from "./types";
+/**
+ * Hover and pin interaction shared by every chart.
+ *
+ * Two independent axes:
+ *
+ * - **Category** — a numeric index along the plot. Hovering previews, clicking
+ *   pins so the tooltip survives the pointer leaving.
+ * - **Series** — a legend key. Hovering isolates that series, clicking pins the
+ *   isolation.
+ *
+ * Both live here rather than one of them in the charts, so there is a single
+ * `isEngaged` boolean. That matters more than it looks: `ChartPlotGroup` uses it
+ * to cancel the mark restore delay, and a second hover source that didn't feed
+ * it would sit through that delay before muting anything and feel broken.
+ *
+ * Escape or a click on the plot background clears both pins.
+ */
+interface UseChartInteractionOptions {
+    /** Number of hoverable categories. A shrinking count clears stale indices. */
+    categoryCount: number;
+    /** Legend keys currently rendered. A key that disappears clears a stale pin. */
+    seriesKeys?: string[];
+    /** Suppress all interaction — used while loading and when the tooltip is off. */
+    disabled?: boolean;
+    /**
+     * Render every mark muted, whatever the two axes say.
+     *
+     * Distinct from {@link disabled}, which suppresses *input*. Loading suppresses
+     * *emphasis*: there is nothing yet worth drawing attention to. Folded in here
+     * rather than left to each mark, because the alternative is the same
+     * `isLoading ? MUTED : getMarkState(…)` ternary hand-copied at every mark —
+     * which is exactly how one of them came to be missing it.
+     */
+    isLoading?: boolean;
+    /** Notified when the pinned category changes. */
+    onPinnedChange?: (index: number | null) => void;
+}
+interface MarkStateArgs {
+    /** Omit for marks that belong to no particular category, such as a line. */
+    categoryIndex?: number;
+    /** Omit for marks that belong to no particular series. */
+    seriesKey?: string;
+}
+export interface ChartInteraction {
+    pinnedIndex: number | null;
+    /** Pinned wins over hovered — this is what the tooltip follows. */
+    activeIndex: number | null;
+    hoveredSeriesKey: string | null;
+    pinnedSeriesKey: string | null;
+    /** True while *either* axis is engaged; cancels the mark restore delay. */
+    isEngaged: boolean;
+    /**
+     * Emphasis for one mark, composed from both axes.
+     *
+     * The grammar is inherited from the reference and is the opposite of the
+     * obvious one: engaging something does not brighten it, it softens everything
+     * else. With something pinned, the unrelated marks recede further still, so
+     * the pinned mark and the one under the pointer stay legible against them.
+     *
+     * A mark has to survive *both* filters to stay active — the two axes
+     * intersect rather than override, so pinning a series and then hovering a
+     * category leaves only their overlap lit.
+     */
+    getMarkState: (args: MarkStateArgs) => ChartMarkState;
+    onCategoryEnter: (categoryIndex: number) => void;
+    onCategoryLeave: () => void;
+    onCategoryClick: (categoryIndex: number) => void;
+    onSeriesEnter: (seriesKey: string) => void;
+    onSeriesLeave: () => void;
+    onSeriesClick: (seriesKey: string) => void;
+    /** Attach to the plot backdrop; clears both pins. */
+    onBackdropClick: () => void;
+}
+export declare function useChartInteraction({ categoryCount, seriesKeys, disabled, isLoading, onPinnedChange, }: UseChartInteractionOptions): ChartInteraction;
+export {};

package/dist/charts/useChartInteraction.js

@@ -0,0 +1,126 @@
+import { ChartMarkState } from "./types.js";
+import { match } from "ts-pattern";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+//#region src/charts/useChartInteraction.ts
+/** How far back a state sits, so two axes can be compared and the worse taken. */
+function severity(state) {
+	return match(state).with(ChartMarkState.ACTIVE, () => 0).with(ChartMarkState.MUTED, () => 1).with(ChartMarkState.FADED, () => 2).exhaustive();
+}
+function useChartInteraction({ categoryCount, seriesKeys, disabled = false, isLoading = false, onPinnedChange }) {
+	const [hoveredIndex, setHoveredIndex] = useState(null);
+	const [pinnedIndex, setPinnedIndex] = useState(null);
+	const [hoveredSeriesKey, setHoveredSeriesKey] = useState(null);
+	const [pinnedSeriesKey, setPinnedSeriesKey] = useState(null);
+	const onPinnedChangeRef = useRef(onPinnedChange);
+	useEffect(() => {
+		onPinnedChangeRef.current = onPinnedChange;
+	});
+	const safeHovered = hoveredIndex !== null && hoveredIndex < categoryCount ? hoveredIndex : null;
+	const safePinned = pinnedIndex !== null && pinnedIndex < categoryCount ? pinnedIndex : null;
+	const isKnownSeries = (key) => key !== null && (seriesKeys === void 0 || seriesKeys.includes(key));
+	const safeHoveredSeries = isKnownSeries(hoveredSeriesKey) ? hoveredSeriesKey : null;
+	const safePinnedSeries = isKnownSeries(pinnedSeriesKey) ? pinnedSeriesKey : null;
+	const clearPins = useCallback(() => {
+		setPinnedIndex(null);
+		setPinnedSeriesKey(null);
+		onPinnedChangeRef.current?.(null);
+	}, []);
+	const hasPin = safePinned !== null || safePinnedSeries !== null;
+	useEffect(() => {
+		if (disabled || !hasPin) return;
+		const onKeyDown = (event) => {
+			if (event.key === "Escape") clearPins();
+		};
+		window.addEventListener("keydown", onKeyDown);
+		return () => window.removeEventListener("keydown", onKeyDown);
+	}, [
+		disabled,
+		hasPin,
+		clearPins
+	]);
+	const onCategoryEnter = useCallback((categoryIndex) => {
+		if (disabled) return;
+		setHoveredIndex(categoryIndex);
+	}, [disabled]);
+	const onCategoryLeave = useCallback(() => {
+		if (disabled) return;
+		setHoveredIndex(null);
+	}, [disabled]);
+	const onCategoryClick = useCallback((categoryIndex) => {
+		if (disabled) return;
+		const next = pinnedIndex === categoryIndex ? null : categoryIndex;
+		setPinnedIndex(next);
+		onPinnedChangeRef.current?.(next);
+	}, [disabled, pinnedIndex]);
+	const onSeriesEnter = useCallback((seriesKey) => {
+		setHoveredSeriesKey(seriesKey);
+	}, []);
+	const onSeriesLeave = useCallback(() => {
+		setHoveredSeriesKey(null);
+	}, []);
+	const onSeriesClick = useCallback((seriesKey) => {
+		const next = pinnedSeriesKey === seriesKey ? null : seriesKey;
+		setPinnedSeriesKey(next);
+		if (next === null) setHoveredSeriesKey(null);
+	}, [pinnedSeriesKey]);
+	const getMarkState = useCallback(({ categoryIndex, seriesKey }) => {
+		if (isLoading) return ChartMarkState.MUTED;
+		const categoryState = (() => {
+			if (categoryIndex === void 0) return ChartMarkState.ACTIVE;
+			if (safePinned !== null) {
+				if (categoryIndex === safePinned) return ChartMarkState.ACTIVE;
+				if (categoryIndex === safeHovered) return ChartMarkState.MUTED;
+				return ChartMarkState.FADED;
+			}
+			if (safeHovered !== null) return categoryIndex === safeHovered ? ChartMarkState.ACTIVE : ChartMarkState.MUTED;
+			return ChartMarkState.ACTIVE;
+		})();
+		const seriesState = (() => {
+			if (seriesKey === void 0) return ChartMarkState.ACTIVE;
+			if (safePinnedSeries !== null) {
+				if (seriesKey === safePinnedSeries) return ChartMarkState.ACTIVE;
+				if (seriesKey === safeHoveredSeries) return ChartMarkState.MUTED;
+				return ChartMarkState.FADED;
+			}
+			if (safeHoveredSeries !== null) return seriesKey === safeHoveredSeries ? ChartMarkState.ACTIVE : ChartMarkState.MUTED;
+			return ChartMarkState.ACTIVE;
+		})();
+		return severity(categoryState) >= severity(seriesState) ? categoryState : seriesState;
+	}, [
+		isLoading,
+		safePinned,
+		safeHovered,
+		safePinnedSeries,
+		safeHoveredSeries
+	]);
+	return useMemo(() => ({
+		pinnedIndex: safePinned,
+		activeIndex: safePinned ?? safeHovered,
+		hoveredSeriesKey: safeHoveredSeries,
+		pinnedSeriesKey: safePinnedSeries,
+		isEngaged: safePinned !== null || safeHovered !== null || safePinnedSeries !== null || safeHoveredSeries !== null,
+		getMarkState,
+		onCategoryEnter,
+		onCategoryLeave,
+		onCategoryClick,
+		onSeriesEnter,
+		onSeriesLeave,
+		onSeriesClick,
+		onBackdropClick: clearPins
+	}), [
+		safeHovered,
+		safePinned,
+		safeHoveredSeries,
+		safePinnedSeries,
+		getMarkState,
+		onCategoryEnter,
+		onCategoryLeave,
+		onCategoryClick,
+		onSeriesEnter,
+		onSeriesLeave,
+		onSeriesClick,
+		clearPins
+	]);
+}
+//#endregion
+export { useChartInteraction };

package/dist/charts/useChartTooltipPosition.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Tooltip placement with edge collision handling.
+ *
+ * Computed in JS rather than CSS because clamping needs a percentage of the
+ * tooltip's own size measured against a percentage of the container's, and
+ * `min()`/`max()` cannot resolve two different percentage bases in one
+ * expression. Any CSS-only attempt works until the first long label.
+ */
+interface UseChartTooltipPositionOptions {
+    /** Anchor in container coordinates. */
+    anchorX: number;
+    anchorY: number;
+    /** The box to stay inside. */
+    containerWidth: number;
+    containerHeight: number;
+    /** Half-width of the anchored category, so the tooltip can sit beside it. */
+    anchorHalfWidth?: number;
+    /**
+     * An x coordinate to move away from, instead of flipping on the container's
+     * midline.
+     *
+     * Radial charts need this. Their anchor already sits on the arc's outer edge,
+     * so "which half of the container am I in" points the tooltip back over the
+     * middle of the chart — across the very slices it describes, and across any
+     * donut-hole content. Passing the centre pushes it outward instead.
+     */
+    placeAwayFromX?: number;
+    /**
+     * Where the tooltip sits vertically relative to its anchor.
+     *
+     * `ABOVE` suits an anchor that marks the top of something (a bar, the highest
+     * point in a column). `CENTERED` suits an anchor that marks a position rather
+     * than a top, such as a point on an arc.
+     */
+    verticalAlign?: ChartTooltipVerticalAlign;
+}
+export declare enum ChartTooltipVerticalAlign {
+    ABOVE = "ABOVE",
+    CENTERED = "CENTERED"
+}
+export interface ChartTooltipPosition {
+    /** Attach to the tooltip element so it can be measured. */
+    tooltipRef: React.RefObject<HTMLDivElement>;
+    x: number;
+    y: number;
+    /**
+     * False for the first frame after the content changes, while the measured
+     * size is still stale. Gating visibility on it hides the reflow.
+     */
+    isMeasured: boolean;
+}
+export declare function useChartTooltipPosition({ anchorX, anchorY, containerWidth, containerHeight, anchorHalfWidth, placeAwayFromX, verticalAlign, }: UseChartTooltipPositionOptions): ChartTooltipPosition;
+export {};

package/dist/charts/useChartTooltipPosition.js

@@ -0,0 +1,39 @@
+import { useElementClientSize } from "../hooks/useElementClientSize.js";
+import "./constants.js";
+import { clamp } from "./chartScales.js";
+import { useMemo, useRef } from "react";
+//#region src/charts/useChartTooltipPosition.ts
+var ChartTooltipVerticalAlign = /* @__PURE__ */ function(ChartTooltipVerticalAlign) {
+	ChartTooltipVerticalAlign["ABOVE"] = "ABOVE";
+	ChartTooltipVerticalAlign["CENTERED"] = "CENTERED";
+	return ChartTooltipVerticalAlign;
+}({});
+function useChartTooltipPosition({ anchorX, anchorY, containerWidth, containerHeight, anchorHalfWidth = 0, placeAwayFromX, verticalAlign = "ABOVE" }) {
+	const tooltipRef = useRef(null);
+	const { width: tooltipWidth, height: tooltipHeight } = useElementClientSize(tooltipRef);
+	return useMemo(() => {
+		const isMeasured = tooltipWidth !== void 0 && tooltipHeight !== void 0;
+		const w = tooltipWidth ?? 0;
+		const h = tooltipHeight ?? 0;
+		const rawX = (placeAwayFromX !== void 0 ? anchorX < placeAwayFromX : anchorX > containerWidth / 2) ? anchorX - anchorHalfWidth - 10 - w : anchorX + anchorHalfWidth + 10;
+		const rawY = verticalAlign === "CENTERED" ? anchorY - h / 2 : Math.min(anchorY, containerHeight / 2);
+		return {
+			tooltipRef,
+			x: clamp(rawX, 0, Math.max(0, containerWidth - w)),
+			y: clamp(rawY, 0, Math.max(0, containerHeight - h)),
+			isMeasured
+		};
+	}, [
+		anchorX,
+		anchorY,
+		containerWidth,
+		containerHeight,
+		anchorHalfWidth,
+		placeAwayFromX,
+		verticalAlign,
+		tooltipWidth,
+		tooltipHeight
+	]);
+}
+//#endregion
+export { ChartTooltipVerticalAlign, useChartTooltipPosition };

package/dist/charts/useSeriesColorResolver.d.ts

@@ -0,0 +1,37 @@
+import type { ChartPalette, ChartSeriesStyles } from "./types";
+/**
+ * Palette assignment for a chart's series, shared by all three charts.
+ *
+ * Every chart resolved colour the same way — look the key up in the `series`
+ * record, take its slot, fall back to the palette — but each spelled it
+ * differently and each rebuilt the key list itself. Doing it once here is what
+ * makes "adding a series never recolours the existing ones" a property of the
+ * design rather than of three separate call sites remembering to use
+ * `indexOf` instead of the loop counter.
+ */
+export interface SeriesColorResolver<TKey extends string> {
+    /**
+     * Series keys in `series` record order.
+     *
+     * Insertion order is what makes a key's palette slot stable regardless of
+     * which data happens to contain it, so this is never sorted.
+     */
+    keys: TKey[];
+    /** Colour for a series. The record's own `color` wins over the slot. */
+    resolve: (key: TKey, explicit?: ChartPalette) => string;
+    /**
+     * Colour by palette position, for marks that are not series.
+     *
+     * A stacked bar's segments are a second dimension with no record of their
+     * own, so they take the ramp by position rather than by key.
+     */
+    resolveByIndex: (index: number, explicit?: ChartPalette) => string;
+    /**
+     * Neutral, for a mark that names no series at all.
+     *
+     * The pie's folded bucket is not one of the slices, so borrowing a hue would
+     * imply it is.
+     */
+    neutral: string;
+}
+export declare function useSeriesColorResolver<TKey extends string>(series: ChartSeriesStyles<TKey>): SeriesColorResolver<TKey>;

package/dist/charts/useSeriesColorResolver.js

@@ -0,0 +1,27 @@
+import { useGalaxyTheme } from "../theme/GalaxyTheme.js";
+import { resolveChartPaletteColor, resolveSeriesColor } from "./chartTheme.js";
+import { useCallback, useMemo } from "react";
+//#region src/charts/useSeriesColorResolver.ts
+function useSeriesColorResolver(series) {
+	const { theme } = useGalaxyTheme();
+	const keys = useMemo(() => Object.keys(series), [series]);
+	const resolveByIndex = useCallback((index, explicit) => explicit ? resolveChartPaletteColor(theme, explicit) : resolveSeriesColor(theme, index), [theme]);
+	const resolve = useCallback((key, explicit) => resolveSeriesColor(theme, keys.indexOf(key), explicit ?? series[key]?.color), [
+		theme,
+		keys,
+		series
+	]);
+	return useMemo(() => ({
+		keys,
+		resolve,
+		resolveByIndex,
+		neutral: theme.color.text.tertiary
+	}), [
+		keys,
+		resolve,
+		resolveByIndex,
+		theme
+	]);
+}
+//#endregion
+export { useSeriesColorResolver };

package/dist/hooks/useElementClientSize.d.ts

@@ -0,0 +1,20 @@
+interface ElementClientSize {
+    width: number | undefined;
+    height: number | undefined;
+}
+/**
+ * Hook that tracks an element's *client* size — the padding box, excluding
+ * scrollbars and borders.
+ *
+ * Use this instead of {@link useElementWidth} when the measurement drives
+ * something that must line up with the scrollport (a sticky overlay, a
+ * viewport-width panel). `useElementWidth` measures the border box via
+ * `getBoundingClientRect`, which includes the scrollbar gutter and would make
+ * such an element overhang.
+ *
+ * @param ref - A ref to the element to measure
+ * @returns The current client width/height in pixels, or undefined before the
+ *   first measurement
+ */
+export declare const useElementClientSize: (ref: React.RefObject<HTMLElement | null>) => ElementClientSize;
+export {};