@galaxy-io/dls 1.6.0 → 2.0.0

package/dist/charts/useChartFormatters.js

@@ -1,15 +1,10 @@
 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]);
+/** @internal Resolves a chart's value and label formatters once per render. */
+/** @internal Resolves `valueFormatter` (default `formatNumber(v, { precision: 2 })`) and `labelFormatter` (identity). */
+function useChartFormatters(valueFormatter, labelFormatter) {
+	const formatValue = useMemo(() => resolveValueFormatter(valueFormatter), [valueFormatter]);
 	const formatLabel = useMemo(() => resolveLabelFormatter(labelFormatter), [labelFormatter]);
 	return useMemo(() => ({
 		formatValue,

package/dist/charts/useChartInteraction.d.ts

@@ -1,135 +1,66 @@
-import { ChartMarkState } from "./types";
-import type { ChartSelectionInput } from "./types";
-/**
- * Hover interaction shared by every chart.
- *
- * Two independent axes, both hover-only:
- *
- * - **Category** — a numeric index along the plot. Hovering previews it: the
- *   tooltip opens and everything outside the category recedes.
- * - **Series** — a legend key. Hovering (or focusing) a legend entry isolates
- *   that series.
- *
- * Plus one read-only source: inside a `ChartGroupProvider`, a chart that
- * supplies {@link UseChartInteractionOptions.categoryKeys} follows the category
- * hovered in a sibling chart, matched by raw label. Following emphasizes; it
- * opens the tooltip only when the provider opts in via `sharedTooltip`, which
- * is what {@link ChartInteraction.showTooltip} folds together. The series axis
- * deliberately does not sync: series keys are chart-local vocabulary, and
- * isolating "Delivered" in a chart that happens to share the name would
- * correlate nothing.
- *
- * Plus one axis that is not hover at all: **selection**, supplied by the caller
- * and never changed here. A selection is a commitment rather than a preview —
- * it outranks both hover filters, and it releases only when the caller says so.
- *
- * Clicking deliberately does *not* pin the hover. That is what it used to do,
- * with no effect outside the chart, and it read as the plot getting stuck. A
- * click now only reports what was hit; whether anything lights up afterwards is
- * the caller's `selection` to decide.
- */
-interface UseChartInteractionOptions {
-    /** Number of hoverable categories. A shrinking count clears stale indices. */
+import { ChartMarkState, type ChartSelectionInput } from "./types.js";
+/** @internal Inputs of `useChartInteraction`. */
+export interface UseChartInteractionOptions {
+    /** Number of categories (slices, cells). A shrinking count clears stale indices. */
     categoryCount: number;
-    /** Legend keys currently rendered. A key that disappears clears stale hover. */
+    /** Legend keys rendered; a key that disappears clears a stale series hover. */
     seriesKeys?: string[];
-    /**
-     * Raw category labels, index-aligned with {@link categoryCount}. Raw labels,
-     * never `labelFormatter` output — two charts formatting the same label
-     * differently must still match, and so must a caller's `selection`.
-     *
-     * Identity only. Opting into `ChartGroupProvider` sync is
-     * {@link enableGroupSync}, which used to be implied by supplying these — the
-     * two were split once selection needed the labels in a chart (PieChart) that
-     * must stay out of the sync group.
-     */
+    /** Raw category labels, index-aligned. Needed for selection and sync. */
     categoryKeys?: string[];
-    /**
-     * Follow a `ChartGroupProvider` sibling's hovered category. PieChart passes
-     * `false`: it has no category axis, so there is nothing to correlate.
-     * @default true
-     */
+    /** Follow and publish to a `ChartGroupProvider`. PieChart and Heatmap pass `false`. @default true */
     enableGroupSync?: boolean;
-    /**
-     * Marks the caller has selected. Matching marks hold full strength and the
-     * rest recede — the same "soften everything else" grammar the hover axes use,
-     * which is why selection needs no visual vocabulary of its own.
-     *
-     * Presentational and strictly read-only: this hook never writes it. The state
-     * lives with whatever the selection is filtering, so the chart and that thing
-     * cannot drift apart, and the DLS never has to pick toggle or multi-select
-     * semantics.
-     *
-     * Normalized here rather than by each chart, so "one, several, or none" is
-     * spelled once.
-     */
-    selection?: ChartSelectionInput;
-    /**
-     * How marks outside the active category recede. Defaults to
-     * {@link ChartMarkState.MUTED}; BarChart passes
-     * {@link ChartMarkState.DIMMED} because its cursor band already carries the
-     * category highlight and strong muting on top of it would shout. Only the
-     * category axis softens — series (legend) isolation always mutes fully,
-     * since there the muting *is* the affordance.
-     */
+    /** The caller's selection. */
+    selection?: ChartSelectionInput | undefined;
+    /** How off-category marks recede. @default ChartMarkState.MUTED */
     categoryMuteState?: ChartMarkState;
-    /** Suppress all interaction — used while loading and when the tooltip is off. */
+    /** No category interaction (static plot, loading, empty). The legend stays live. */
     isDisabled?: boolean;
-    /**
-     * Render every mark muted, whatever the two axes say.
-     *
-     * Distinct from {@link isDisabled}, 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.
-     */
+    /** Every mark is muted and following pauses. */
     isLoading?: boolean;
+    /** Cells laid out in rows of `columns` (Heatmap): Up / Down move by a row, Home / End stay in the row. */
+    grid?: {
+        columns: number;
+    };
 }
-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;
+/** @internal Which marks a mark-state query is about. */
+export interface ChartMarkStateArgs {
+    /** Omit for marks that belong to no category (a line). */
+    categoryIndex?: number | undefined;
+    /** Omit for marks that belong to no series. */
+    seriesKey?: string | undefined;
 }
+/** @internal What `useChartInteraction` returns. */
 export interface ChartInteraction {
-    /**
-     * The active category — this chart's own hover, or failing that the category
-     * a `ChartGroupProvider` sibling is hovering, resolved to a local index.
-     */
+    /** The engaged category: this chart's own (pointer or keyboard), else the one a sibling follows. */
     activeIndex: number | null;
-    /**
-     * True when this chart should present its tooltip for {@link activeIndex}:
-     * its own pointer hover always, a synced sibling's only when the
-     * `ChartGroupProvider` opts in via `sharedTooltip`.
-     */
+    /** True when this chart shows its tooltip for `activeIndex`. */
     showTooltip: boolean;
+    /** The legend key being hovered. */
     hoveredSeriesKey: string | null;
-    /**
-     * Categories a {@link UseChartInteractionOptions.selection} names outright.
-     *
-     * Drives the persistent cursor a cartesian chart draws at a selected
-     * category. A descriptor carrying only a `seriesKey` names no category and
-     * contributes nothing here — "every failure" should mute the other series,
-     * not band every column on the axis.
-     */
+    /** Categories the selection names outright (persistent cursors). */
     selectedCategoryIndices: ReadonlySet<number>;
-    /**
-     * 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.
-     *
-     * A mark has to survive *both* filters to stay active — the two axes
-     * intersect rather than override, so hovering a legend entry and a category
-     * at once leaves only their overlap lit.
-     */
-    getMarkState: (args: MarkStateArgs) => ChartMarkState;
+    /** Emphasis of one mark, composed from selection, series and category. */
+    getMarkState: (args: ChartMarkStateArgs) => ChartMarkState;
+    /** Pointer entered a category's target. */
     onCategoryEnter: (categoryIndex: number) => void;
+    /** Pointer left the plot. */
     onCategoryLeave: () => void;
+    /** Pointer entered a legend entry. */
     onSeriesEnter: (seriesKey: string) => void;
+    /** Pointer left a legend entry. */
     onSeriesLeave: () => void;
+    /** Keyboard focus reached the plot: engage the last category, or the first. Returns it. */
+    onKeyboardFocus: () => number | null;
+    /** A navigation key; returns the newly engaged index, or `null` if the key does not navigate. */
+    onKeyboardMove: (key: string) => number | null;
+    /** Escape: clear the engaged category (focus stays). */
+    onKeyboardClear: () => void;
+    /** Focus left the plot. */
+    onKeyboardBlur: () => void;
 }
-export declare function useChartInteraction({ categoryCount, seriesKeys, categoryKeys, enableGroupSync, selection, categoryMuteState, isDisabled, isLoading, }: UseChartInteractionOptions): ChartInteraction;
-export {};
+/** @internal The next index for a navigation key, stopping at the ends (no wrap). */
+export declare function getNextCategoryIndex(current: number, key: string, count: number, grid?: {
+    columns: number;
+}): number | null;
+/** @internal Shared interaction model; see the module comment. */
+export declare function useChartInteraction({ categoryCount, seriesKeys, categoryKeys, enableGroupSync, selection, categoryMuteState, isDisabled, isLoading, grid, }: UseChartInteractionOptions): ChartInteraction;

package/dist/charts/useChartInteraction.js

@@ -1,32 +1,58 @@
 import { ChartMarkState } from "./types.js";
 import { ChartGroupContext } from "./ChartGroupProvider.js";
-import { useCallback, useContext, useEffect, useId, useMemo, useState } from "react";
+import { useCallback, useContext, useEffect, useId, useMemo, useRef, useState } from "react";
 //#region src/charts/useChartInteraction.ts
-/** Stable identity, so an absent selection never re-memoizes anything. */
+/**
+* @internal Hover, keyboard, selection and group sync for every chart.
+*
+* Two local axes:
+* - **Category**: an index along the plot, engaged by pointer hover or by the keyboard (the plot
+*   box is one tab stop; arrows move, Home / End jump, Escape clears). Engaging previews it: the
+*   tooltip opens and the rest recedes.
+* - **Series**: a legend key, engaged by hovering a legend entry. Isolates that series.
+*
+* Plus a read-only source: inside a `ChartGroupProvider`, a chart that passes `categoryKeys`
+* follows the category a sibling engages (matched by raw label). Following emphasizes; it opens
+* the tooltip only when the provider shares tooltips. Series hover never syncs.
+*
+* And **selection**, supplied by the caller and never written here: it outranks hover. Clicks do
+* not pin anything; they only report (the 1.x rationale).
+*/
 var NO_SELECTION = [];
 var NO_SELECTED_INDICES = /* @__PURE__ */ new Set();
-function useChartInteraction({ categoryCount, seriesKeys, categoryKeys, enableGroupSync = true, selection, categoryMuteState = ChartMarkState.MUTED, isDisabled = false, isLoading = false }) {
-	const [hoveredIndex, setHoveredIndex] = useState(null);
+/** @internal The next index for a navigation key, stopping at the ends (no wrap). */
+function getNextCategoryIndex(current, key, count, grid) {
+	if (count <= 0) return null;
+	const columns = grid ? Math.max(1, grid.columns) : count;
+	const rowStart = grid ? current - current % columns : 0;
+	const rowEnd = grid ? Math.min(count - 1, rowStart + columns - 1) : count - 1;
+	switch (key) {
+		case "ArrowRight": return Math.min(current + 1, rowEnd);
+		case "ArrowLeft": return Math.max(current - 1, rowStart);
+		case "Home": return rowStart;
+		case "End": return rowEnd;
+		case "ArrowDown": return grid && current + columns < count ? current + columns : grid ? current : null;
+		case "ArrowUp": return grid && current - columns >= 0 ? current - columns : grid ? current : null;
+		default: return null;
+	}
+}
+/** @internal Shared interaction model; see the module comment. */
+function useChartInteraction({ categoryCount, seriesKeys, categoryKeys, enableGroupSync = true, selection, categoryMuteState = ChartMarkState.MUTED, isDisabled = false, isLoading = false, grid }) {
+	const [pointerIndex, setPointerIndex] = useState(null);
+	const [keyboardIndex, setKeyboardIndex] = useState(null);
 	const [hoveredSeriesKey, setHoveredSeriesKey] = useState(null);
+	/** The last engaged category, where keyboard focus resumes. */
+	const lastIndexRef = useRef(null);
 	const sync = useContext(ChartGroupContext);
 	const syncId = useId();
 	const canSync = sync !== null && categoryKeys !== void 0 && enableGroupSync;
 	const setActive = sync?.setActive;
 	const clearActive = sync?.clearActive;
-	const safeHovered = hoveredIndex !== null && hoveredIndex < categoryCount ? hoveredIndex : null;
+	const inRange = (index) => index !== null && index < categoryCount && !isDisabled ? index : null;
+	const localIndex = inRange(pointerIndex) ?? inRange(keyboardIndex);
+	if (localIndex !== null) lastIndexRef.current = localIndex;
 	const safeHoveredSeries = hoveredSeriesKey !== null && (seriesKeys === void 0 || seriesKeys.includes(hoveredSeriesKey)) ? hoveredSeriesKey : null;
-	/**
-	* Publish this chart's hover to the sync group.
-	*
-	* An effect over the derived label rather than calls inside the pointer
-	* handlers, so three edge cases collapse into one place: data shrinking
-	* under a resting pointer (the `safeHovered` guard nulls the key → clears),
-	* the label at the resting index changing (republishes what is now under
-	* the pointer), and unmount while source (the cleanup effect below).
-	* Source-only writes still hold — `localKey` derives from `safeHovered`,
-	* which only this chart's own pointer sets.
-	*/
-	const localKey = canSync && safeHovered !== null ? categoryKeys[safeHovered] ?? null : null;
+	const localKey = canSync && localIndex !== null ? categoryKeys[localIndex] ?? null : null;
 	useEffect(() => {
 		if (!setActive || !clearActive) return;
 		if (localKey !== null) setActive({
@@ -41,16 +67,8 @@ function useChartInteraction({ categoryCount, seriesKeys, categoryKeys, enableGr
 		localKey
 	]);
 	useEffect(() => () => clearActive?.(syncId), [clearActive, syncId]);
-	/**
-	* The category a sibling is hovering, resolved to this chart's own index.
-	*
-	* `isLoading` blocks following — the marks are force-muted anyway, but
-	* without the guard LineChart would still draw its cursor and dots through
-	* a loading plot. An unmatched label resolves to no crosshair at all, which
-	* is how charts with partially overlapping categories degrade.
-	*/
 	const followedIndex = useMemo(() => {
-		if (!canSync || isLoading) return null;
+		if (!canSync || isLoading || isDisabled) return null;
 		const entry = sync.activeEntry;
 		if (entry === null || entry.sourceId === syncId) return null;
 		const index = categoryKeys.indexOf(entry.categoryKey);
@@ -58,43 +76,53 @@ function useChartInteraction({ categoryCount, seriesKeys, categoryKeys, enableGr
 	}, [
 		canSync,
 		isLoading,
+		isDisabled,
 		sync?.activeEntry,
 		syncId,
 		categoryKeys
 	]);
-	const effectiveIndex = safeHovered ?? followedIndex;
-	const showTooltip = safeHovered !== null || followedIndex !== null && (sync?.sharedTooltip ?? false);
+	const activeIndex = localIndex ?? followedIndex;
+	const showTooltip = localIndex !== null || followedIndex !== null && (sync?.shouldShareTooltip ?? false);
 	const onCategoryEnter = useCallback((categoryIndex) => {
 		if (isDisabled) return;
-		setHoveredIndex(categoryIndex);
-	}, [isDisabled]);
-	const onCategoryLeave = useCallback(() => {
-		if (isDisabled) return;
-		setHoveredIndex(null);
+		setPointerIndex(categoryIndex);
 	}, [isDisabled]);
-	const onSeriesEnter = useCallback((seriesKey) => {
-		setHoveredSeriesKey(seriesKey);
-	}, []);
-	const onSeriesLeave = useCallback(() => {
-		setHoveredSeriesKey(null);
+	const onCategoryLeave = useCallback(() => setPointerIndex(null), []);
+	const onSeriesEnter = useCallback((seriesKey) => setHoveredSeriesKey(seriesKey), []);
+	const onSeriesLeave = useCallback(() => setHoveredSeriesKey(null), []);
+	const onKeyboardFocus = useCallback(() => {
+		if (isDisabled || categoryCount === 0) return null;
+		const last = lastIndexRef.current;
+		const index = last !== null && last < categoryCount ? last : 0;
+		setKeyboardIndex(index);
+		return index;
+	}, [isDisabled, categoryCount]);
+	const onKeyboardMove = useCallback((key) => {
+		if (isDisabled || categoryCount === 0) return null;
+		const current = localIndex ?? lastIndexRef.current;
+		const next = current === null || current >= categoryCount ? getNextCategoryIndex(0, key, categoryCount, grid) === null ? null : 0 : getNextCategoryIndex(current, key, categoryCount, grid);
+		if (next === null) return null;
+		setPointerIndex(null);
+		setKeyboardIndex(next);
+		return next;
+	}, [
+		isDisabled,
+		categoryCount,
+		localIndex,
+		grid
+	]);
+	const onKeyboardClear = useCallback(() => {
+		setPointerIndex(null);
+		setKeyboardIndex(null);
 	}, []);
+	const onKeyboardBlur = useCallback(() => setKeyboardIndex(null), []);
 	const selectionList = useMemo(() => {
 		if (selection === void 0 || selection === null) return NO_SELECTION;
 		if (!Array.isArray(selection)) return [selection];
 		return selection.length === 0 ? NO_SELECTION : selection;
 	}, [selection]);
 	const hasSelection = selectionList.length > 0;
-	/**
-	* Whether one mark falls inside the selection.
-	*
-	* A descriptor is a conjunction of the fields it *carries*: an absent field
-	* constrains nothing, and a field the mark itself has no notion of cannot
-	* exclude it. The second half is what keeps `{ categoryKey: "00:00" }` from
-	* muting every LineChart stroke — a stroke spans all the categories and is
-	* asked about none — while still muting the bars outside that column.
-	*
-	* Several descriptors union: a mark inside any of them is selected.
-	*/
+	/** A descriptor is a conjunction of the fields it carries; a field the mark lacks never excludes it. */
 	const matchesSelection = useCallback(({ categoryIndex, seriesKey }) => {
 		if (!hasSelection) return true;
 		return selectionList.some((descriptor) => {
@@ -107,23 +135,13 @@ function useChartInteraction({ categoryCount, seriesKeys, categoryKeys, enableGr
 		selectionList,
 		categoryKeys
 	]);
-	/**
-	* Resolved once rather than per mark: the cursor a cartesian chart draws at a
-	* selected category needs the set, and every mark would otherwise re-scan
-	* every descriptor.
-	*
-	* Deliberately not pruned when the data shrinks under it, unlike the hover
-	* indices above. A selection is the caller's state and describes what they
-	* asked for; a key that is momentarily absent from the data — mid-refetch,
-	* say — simply matches nothing until it returns.
-	*/
 	const selectedCategoryIndices = useMemo(() => {
 		if (!hasSelection || categoryKeys === void 0) return NO_SELECTED_INDICES;
-		const selectedKeys = new Set(selectionList.map((descriptor) => descriptor.categoryKey).filter((key) => key !== void 0));
-		if (selectedKeys.size === 0) return NO_SELECTED_INDICES;
+		const keys = new Set(selectionList.map((descriptor) => descriptor.categoryKey).filter((key) => key !== void 0));
+		if (keys.size === 0) return NO_SELECTED_INDICES;
 		const indices = /* @__PURE__ */ new Set();
 		categoryKeys.forEach((key, index) => {
-			if (selectedKeys.has(key)) indices.add(index);
+			if (keys.has(key)) indices.add(index);
 		});
 		return indices;
 	}, [
@@ -137,19 +155,17 @@ function useChartInteraction({ categoryCount, seriesKeys, categoryKeys, enableGr
 			categoryIndex,
 			seriesKey
 		})) return ChartMarkState.MUTED;
-		const categoryMuted = categoryIndex !== void 0 && effectiveIndex !== null && categoryIndex !== effectiveIndex;
 		if (seriesKey !== void 0 && safeHoveredSeries !== null && seriesKey !== safeHoveredSeries) return ChartMarkState.MUTED;
-		if (categoryMuted) return categoryMuteState;
-		return ChartMarkState.ACTIVE;
+		return categoryIndex !== void 0 && activeIndex !== null && categoryIndex !== activeIndex ? categoryMuteState : ChartMarkState.ACTIVE;
 	}, [
 		isLoading,
 		matchesSelection,
-		effectiveIndex,
 		safeHoveredSeries,
+		activeIndex,
 		categoryMuteState
 	]);
 	return useMemo(() => ({
-		activeIndex: effectiveIndex,
+		activeIndex,
 		showTooltip,
 		hoveredSeriesKey: safeHoveredSeries,
 		selectedCategoryIndices,
@@ -157,9 +173,13 @@ function useChartInteraction({ categoryCount, seriesKeys, categoryKeys, enableGr
 		onCategoryEnter,
 		onCategoryLeave,
 		onSeriesEnter,
-		onSeriesLeave
+		onSeriesLeave,
+		onKeyboardFocus,
+		onKeyboardMove,
+		onKeyboardClear,
+		onKeyboardBlur
 	}), [
-		effectiveIndex,
+		activeIndex,
 		showTooltip,
 		safeHoveredSeries,
 		selectedCategoryIndices,
@@ -167,8 +187,12 @@ function useChartInteraction({ categoryCount, seriesKeys, categoryKeys, enableGr
 		onCategoryEnter,
 		onCategoryLeave,
 		onSeriesEnter,
-		onSeriesLeave
+		onSeriesLeave,
+		onKeyboardFocus,
+		onKeyboardMove,
+		onKeyboardClear,
+		onKeyboardBlur
 	]);
 }
 //#endregion
-export { useChartInteraction };
+export { getNextCategoryIndex, useChartInteraction };

package/dist/charts/useChartTooltipPosition.d.ts

@@ -1,53 +1,43 @@
 /**
- * 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.
+ * @internal Chart tooltip placement with edge collision handling (1.x logic): beside the anchor,
+ * flipped away from it, clamped inside the plot box. Computed in JS because clamping needs the
+ * tooltip's own measured size against the box's.
  */
-interface UseChartTooltipPositionOptions {
-    /** Anchor in container coordinates. */
+import { type RefObject } from "react";
+/** @internal Vertical placement of the tooltip relative to its anchor. */
+export declare enum ChartTooltipVerticalAlign {
+    /** The anchor marks the top of something (the highest point in a column). */
+    ABOVE = "ABOVE",
+    /** The anchor marks a position (a point on an arc). */
+    CENTERED = "CENTERED"
+}
+/** @internal Inputs of `useChartTooltipPosition`. */
+export interface UseChartTooltipPositionOptions {
+    /** Anchor x in plot-box coordinates. */
     anchorX: number;
+    /** Anchor y in plot-box coordinates. */
     anchorY: number;
-    /** The box to stay inside. */
+    /** Plot box width. */
     containerWidth: number;
+    /** Plot box height. */
     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"
+    /** Half the anchored category's width, so the tooltip sits beside it. */
+    anchorHalfWidth?: number | undefined;
+    /** An x to move away from instead of the box's midline (radial charts pass their center). */
+    placeAwayFromX?: number | undefined;
+    /** @default ChartTooltipVerticalAlign.ABOVE */
+    verticalAlign?: ChartTooltipVerticalAlign | undefined;
 }
+/** @internal The tooltip's measured position. */
 export interface ChartTooltipPosition {
     /** Attach to the tooltip element so it can be measured. */
-    tooltipRef: React.RefObject<HTMLDivElement>;
+    tooltipRef: RefObject<HTMLDivElement>;
+    /** Left edge in plot-box coordinates. */
     x: number;
+    /** Top edge in plot-box coordinates. */
     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.
-     */
+    /** `false` until the tooltip has been measured once. */
     isMeasured: boolean;
 }
+/** @internal Positions the chart tooltip. */
 export declare function useChartTooltipPosition({ anchorX, anchorY, containerWidth, containerHeight, anchorHalfWidth, placeAwayFromX, verticalAlign, }: UseChartTooltipPositionOptions): ChartTooltipPosition;
-export {};

package/dist/charts/useChartTooltipPosition.js

@@ -1,13 +1,22 @@
-import { useElementClientSize } from "../hooks/useElementClientSize.js";
-import "./constants.js";
+import { CHART_TOOLTIP_OFFSET } from "./constants.js";
 import { clamp } from "./chartScales.js";
+import { useElementClientSize } from "../hooks/useElementClientSize.js";
 import { useMemo, useRef } from "react";
 //#region src/charts/useChartTooltipPosition.ts
+/**
+* @internal Chart tooltip placement with edge collision handling (1.x logic): beside the anchor,
+* flipped away from it, clamped inside the plot box. Computed in JS because clamping needs the
+* tooltip's own measured size against the box's.
+*/
+/** @internal Vertical placement of the tooltip relative to its anchor. */
 var ChartTooltipVerticalAlign = /* @__PURE__ */ function(ChartTooltipVerticalAlign) {
+	/** The anchor marks the top of something (the highest point in a column). */
 	ChartTooltipVerticalAlign["ABOVE"] = "ABOVE";
+	/** The anchor marks a position (a point on an arc). */
 	ChartTooltipVerticalAlign["CENTERED"] = "CENTERED";
 	return ChartTooltipVerticalAlign;
 }({});
+/** @internal Positions the chart tooltip. */
 function useChartTooltipPosition({ anchorX, anchorY, containerWidth, containerHeight, anchorHalfWidth = 0, placeAwayFromX, verticalAlign = "ABOVE" }) {
 	const tooltipRef = useRef(null);
 	const { width: tooltipWidth, height: tooltipHeight } = useElementClientSize(tooltipRef);
@@ -15,12 +24,12 @@ function useChartTooltipPosition({ anchorX, anchorY, containerWidth, containerHe
 		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 rawX = (placeAwayFromX !== void 0 ? anchorX < placeAwayFromX : anchorX > containerWidth / 2) ? anchorX - anchorHalfWidth - CHART_TOOLTIP_OFFSET - w : anchorX + anchorHalfWidth + CHART_TOOLTIP_OFFSET;
 		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)),
+			x: Math.round(clamp(rawX, 0, Math.max(0, containerWidth - w))),
+			y: Math.round(clamp(rawY, 0, Math.max(0, containerHeight - h))),
 			isMeasured
 		};
 	}, [

package/dist/charts/useSeriesColorResolver.d.ts

@@ -1,37 +1,15 @@
-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.
- */
+import { type ChartSeriesColor } from "./chartPalette.js";
+import { ChartPalette, type ChartSeriesStyles } from "./types.js";
+/** @internal What `useSeriesColorResolver` returns. */
 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.
-     */
+    /** Series keys in `series` record order (never sorted: the order is what keeps slots stable). */
     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;
+    /** Color of a series: its `hex`, its `color` slot, or its position in the automatic order. */
+    resolve: (key: TKey) => ChartSeriesColor;
+    /** Color by position, for marks that are not series (a stack's components). */
+    resolveByIndex: (index: number, explicit?: ChartPalette) => ChartSeriesColor;
+    /** Neutral, for a mark that names no series. */
+    neutral: ChartSeriesColor;
 }
+/** @internal Resolves series colors from the `series` record. */
 export declare function useSeriesColorResolver<TKey extends string>(series: ChartSeriesStyles<TKey>): SeriesColorResolver<TKey>;