@galaxy-io/dls 1.2.6 → 1.3.0

package/dist/charts/types.js

@@ -0,0 +1,136 @@
+//#region src/charts/types.ts
+/**
+* Shared types for the chart components (`BarChart`, `LineChart`, `PieChart`).
+*
+* Every data type is generic over its key unions, and the inference is
+* deliberately one-directional: `TMetric` comes from the keys of the `series`
+* record and from nowhere else, with {@link NoInfer} applied to every
+* data-shaped prop.
+*
+* That asymmetry is what makes the guarantees real. Were `TMetric` also
+* inferred from the data, an inline `{ metric: "revenue" }` would widen to
+* `string`, TypeScript would pick the supertype, and every check below would
+* quietly become a no-op — type safety that looks present but is not.
+*
+* ```ts
+* <BarChart
+*   series={{
+*     revenue: { label: "Revenue" },
+*     cost: { label: "Cost" },
+*   }}
+*   groups={[
+*     { label: "Q1", bars: [{ metric: "revenu", components: [] }] },
+*     //                              ^ Type '"revenu"' is not assignable to
+*     //                                type '"revenue" | "cost"'.
+*   ]}
+* />
+* ```
+*
+* The same union then makes aggregates exhaustive, spell-checks legend and
+* ordering props, and narrows callback parameters for `ts-pattern`.
+*/
+/**
+* Semantic color slot for a series, resolved against the active theme at render
+* time by `resolveChartPaletteColor` in `chartTheme.ts`.
+*
+* Deliberately an enum of slots rather than a hex string: consumer data should
+* never carry raw color, and every rendered color has to come from
+* `theme.color.*` so both themes stay correct.
+*/
+var ChartPalette = /* @__PURE__ */ function(ChartPalette) {
+	ChartPalette["PURPLE"] = "PURPLE";
+	ChartPalette["PINK"] = "PINK";
+	ChartPalette["BLUE"] = "BLUE";
+	ChartPalette["TEAL"] = "TEAL";
+	ChartPalette["LIME"] = "LIME";
+	ChartPalette["ORANGE"] = "ORANGE";
+	ChartPalette["YELLOW"] = "YELLOW";
+	ChartPalette["GREEN"] = "GREEN";
+	ChartPalette["RED"] = "RED";
+	return ChartPalette;
+}({});
+/**
+* Built-in value formats. Supplies an `Intl`-based default for axis ticks,
+* value labels and tooltip rows so callers don't have to write the same
+* formatter three times.
+*
+* A `valueFormatter` prop always wins over this when both are given.
+*/
+var ChartValueUnit = /* @__PURE__ */ function(ChartValueUnit) {
+	/** Locale-grouped integer, e.g. `1,250`. */
+	ChartValueUnit["PLAIN"] = "PLAIN";
+	/** Locale currency with no decimals, e.g. `$1,250`. */
+	ChartValueUnit["CURRENCY"] = "CURRENCY";
+	/** Percentage of a 0–100 value, e.g. `42%`. */
+	ChartValueUnit["PERCENT"] = "PERCENT";
+	/** Abbreviated magnitude, e.g. `1.3K`, `4.2M`. */
+	ChartValueUnit["COMPACT"] = "COMPACT";
+	return ChartValueUnit;
+}({});
+/** How the category axis copes when labels outgrow their slots. */
+var ChartCategoryLabelMode = /* @__PURE__ */ function(ChartCategoryLabelMode) {
+	/** Render every label that fits; otherwise show every nth. The default. */
+	ChartCategoryLabelMode["AUTO"] = "AUTO";
+	/** Render every label, ellipsizing any that overflow its slot. */
+	ChartCategoryLabelMode["TRUNCATE"] = "TRUNCATE";
+	/** Render every label unconditionally, overlap included. */
+	ChartCategoryLabelMode["ALL"] = "ALL";
+	return ChartCategoryLabelMode;
+}({});
+/**
+* Emphasis level of a rendered mark.
+*
+* Travels to the DOM as a `data-state` attribute rather than a styled-component
+* prop: `@linaria/react` skips prop filtering entirely for SVG tags (its
+* `allTagsSet` is built with a missing spread, so `has('rect')` is false and
+* `propsAsIs` turns on), which would forward a `$`-prefixed prop straight to the
+* DOM and trigger a React warning.
+*/
+var ChartMarkState = /* @__PURE__ */ function(ChartMarkState) {
+	/** Full strength — the default, and the hovered or pinned category. */
+	ChartMarkState["ACTIVE"] = "active";
+	/** Softened, for categories other than the hovered one. */
+	ChartMarkState["MUTED"] = "muted";
+	/** Furthest back, for categories outside a pinned one. */
+	ChartMarkState["FADED"] = "faded";
+	return ChartMarkState;
+}({});
+/** Which pair of a rectangle's corners carries the radius. */
+var BarCorners = /* @__PURE__ */ function(BarCorners) {
+	/** Cap for a bar growing up from the baseline. */
+	BarCorners["TOP"] = "TOP";
+	/** Cap for a bar growing down from the baseline. */
+	BarCorners["BOTTOM"] = "BOTTOM";
+	/** Interior stack segment — square on both ends. */
+	BarCorners["NONE"] = "NONE";
+	return BarCorners;
+}({});
+/**
+* How bar values are scaled before rendering.
+*
+* Note there is no grouped-vs-stacked mode: with the group → bar → component
+* hierarchy, several `bars` in a group render side by side and several
+* `components` in a bar render on top of each other, so a chart can be grouped
+* and stacked at the same time.
+*/
+var BarChartNormalization = /* @__PURE__ */ function(BarChartNormalization) {
+	/** Plot raw values. */
+	BarChartNormalization["NONE"] = "NONE";
+	/** Scale each bar's components to fill the axis — a 100% stacked chart. */
+	BarChartNormalization["PERCENT"] = "PERCENT";
+	return BarChartNormalization;
+}({});
+/** How the segments between points are interpolated. */
+var LineChartCurve = /* @__PURE__ */ function(LineChartCurve) {
+	/** Straight segments. */
+	LineChartCurve["LINEAR"] = "LINEAR";
+	/** Monotone cubic — smooth without overshooting the data. */
+	LineChartCurve["SMOOTH"] = "SMOOTH";
+	/** Right-angled steps. */
+	LineChartCurve["STEP"] = "STEP";
+	return LineChartCurve;
+}({});
+/** React key used for the bucket that absorbs slices below the fold threshold. */
+var AGGREGATED_SLICE_KEY = "__other__";
+//#endregion
+export { AGGREGATED_SLICE_KEY, BarChartNormalization, BarCorners, ChartCategoryLabelMode, ChartMarkState, ChartPalette, ChartValueUnit, LineChartCurve };

package/dist/charts/useChartDimensions.d.ts

@@ -0,0 +1,40 @@
+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>;
+}
+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;
+    /** Makes the plot box claim the flex track instead of reserving a height. */
+    fillHeight?: boolean;
+}
+export declare function useChartDimensions({ containerRef, width, height, fillWidth, fillHeight, aspectRatio, margin: marginOverride, }: UseChartDimensionsOptions): ChartDimensions;
+export {};

package/dist/charts/useChartDimensions.js

@@ -0,0 +1,53 @@
+import { useElementClientSize } from "../hooks/useElementClientSize.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 }) {
+	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 margin = useMemo(() => resolveMargin({
+		top: marginTop,
+		right: marginRight,
+		bottom: marginBottom,
+		left: marginLeft
+	}), [
+		marginTop,
+		marginRight,
+		marginBottom,
+		marginLeft
+	]);
+	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,
+		fillHeight
+	}), [
+		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,71 @@
+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 a 300ms 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;
+    /** Notified when the pinned category changes. */
+    onPinnedChange?: (index: number | null) => void;
+    /** Notified when the pinned series changes. */
+    onPinnedSeriesChange?: (seriesKey: string | 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 {
+    hoveredIndex: number | null;
+    pinnedIndex: number | null;
+    /** Pinned wins over hovered — this is what the tooltip follows. */
+    activeIndex: number | null;
+    hoveredSeriesKey: string | null;
+    pinnedSeriesKey: string | null;
+    /** Pinned wins over hovered, matching the category axis. */
+    activeSeriesKey: 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, onPinnedChange, onPinnedSeriesChange, }: UseChartInteractionOptions): ChartInteraction;
+export {};

package/dist/charts/useChartInteraction.js

@@ -0,0 +1,130 @@
+import { ChartMarkState } from "./types.js";
+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. */
+var severity = (state) => {
+	if (state === ChartMarkState.ACTIVE) return 0;
+	return state === ChartMarkState.MUTED ? 1 : 2;
+};
+function useChartInteraction({ categoryCount, seriesKeys, disabled = false, onPinnedChange, onPinnedSeriesChange }) {
+	const [hoveredIndex, setHoveredIndex] = useState(null);
+	const [pinnedIndex, setPinnedIndex] = useState(null);
+	const [hoveredSeriesKey, setHoveredSeriesKey] = useState(null);
+	const [pinnedSeriesKey, setPinnedSeriesKey] = useState(null);
+	const onPinnedChangeRef = useRef(onPinnedChange);
+	const onPinnedSeriesChangeRef = useRef(onPinnedSeriesChange);
+	useEffect(() => {
+		onPinnedChangeRef.current = onPinnedChange;
+		onPinnedSeriesChangeRef.current = onPinnedSeriesChange;
+	});
+	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);
+		onPinnedSeriesChangeRef.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);
+		onPinnedSeriesChangeRef.current?.(next);
+	}, [pinnedSeriesKey]);
+	const getMarkState = useCallback(({ categoryIndex, seriesKey }) => {
+		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;
+	}, [
+		safePinned,
+		safeHovered,
+		safePinnedSeries,
+		safeHoveredSeries
+	]);
+	return useMemo(() => ({
+		hoveredIndex: safeHovered,
+		pinnedIndex: safePinned,
+		activeIndex: safePinned ?? safeHovered,
+		hoveredSeriesKey: safeHoveredSeries,
+		pinnedSeriesKey: safePinnedSeries,
+		activeSeriesKey: safePinnedSeries ?? safeHoveredSeries,
+		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/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 {};

package/dist/hooks/useElementClientSize.js

@@ -0,0 +1,43 @@
+import { useEffect, useState } from "react";
+//#region src/hooks/useElementClientSize.ts
+/**
+* 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
+*/
+var useElementClientSize = (ref) => {
+	const [size, setSize] = useState({
+		width: void 0,
+		height: void 0
+	});
+	useEffect(() => {
+		const element = ref.current;
+		if (!element) return;
+		const update = () => {
+			setSize((current) => current.width === element.clientWidth && current.height === element.clientHeight ? current : {
+				width: element.clientWidth,
+				height: element.clientHeight
+			});
+		};
+		update();
+		if (typeof ResizeObserver === "undefined") {
+			window.addEventListener("resize", update);
+			return () => window.removeEventListener("resize", update);
+		}
+		const observer = new ResizeObserver(update);
+		observer.observe(element);
+		return () => observer.disconnect();
+	}, [ref]);
+	return size;
+};
+//#endregion
+export { useElementClientSize };

package/dist/inputs/CheckboxInput.d.ts

@@ -14,7 +14,12 @@ export interface CheckboxInputProps {
     label?: string;
     isRequired?: boolean;
     isDisabled?: boolean;
-    onChange: (checked: boolean) => void;
+    /** The originating event is passed through so callers can read modifiers. */
+    onChange: (checked: boolean, event?: React.MouseEvent | React.KeyboardEvent) => void;
+    /** Accessible name — required when the checkbox renders without a `label`. */
+    ariaLabel?: string;
+    /** Stops the click from bubbling, e.g. into a clickable table row. */
+    stopClickPropagation?: boolean;
 }
-declare const CheckboxInput: ({ variant, size, isChecked, isIndeterminate, label, isRequired, isDisabled, onChange, }: CheckboxInputProps) => import("react").JSX.Element;
+declare const CheckboxInput: ({ variant, size, isChecked, isIndeterminate, label, isRequired, isDisabled, onChange, ariaLabel, stopClickPropagation, }: CheckboxInputProps) => import("react").JSX.Element;
 export default CheckboxInput;