@kind-ui/charts 0.1.0 → 0.2.0

package/dist/polar-chart.d.ts

@@ -1,17 +1,22 @@
 import { type ComponentProps } from "react";
 import { RadarChart as EngineRadarChart, RadialBarChart as EngineRadialBarChart } from "recharts";
-import { type LineAnimation } from "./animation.js";
+import { type BaseAnimation } from "./animation.js";
 import type { CategoryKey } from "./category-cells.js";
 import { type RadarSelectionProps } from "./radar-interaction.js";
-export type RadarAnimation = LineAnimation;
-export type RadialBarAnimation = LineAnimation;
+export type RadarAnimation = BaseAnimation;
+export type RadialBarAnimation = BaseAnimation;
 export type RadarChartProps<DataPoint = unknown> = ComponentProps<typeof EngineRadarChart<DataPoint>> & RadarSelectionProps & {
     animate?: boolean | RadarAnimation | undefined;
+    loading?: boolean | undefined;
+    loadingLabel?: string | undefined;
 };
 export type RadialBarChartProps<DataPoint = unknown> = ComponentProps<typeof EngineRadialBarChart<DataPoint>> & {
     /** Opt-in category colors from Root.config, resolved from original chart rows. */
     categoryKey?: CategoryKey<DataPoint> | undefined;
+    interactionBinding?: "root";
     animate?: boolean | RadialBarAnimation | undefined;
+    loading?: boolean | undefined;
+    loadingLabel?: string | undefined;
     /** Entrance direction only; native chart and axis angles stay consumer-owned. */
     animationDirection?: "clockwise" | "anticlockwise" | undefined;
 };
@@ -29,5 +34,9 @@ export declare const RadialMotion: import("react").Context<{
     direction: "clockwise" | "anticlockwise";
 }>;
 /** Native polar composition with shared metadata, interaction and optional Motion. */
-export declare function RadarChart<DataPoint = unknown>({ animate, selection, selectedSeries, onSelectedSeriesChange, children, ...props }: RadarChartProps<DataPoint>): import("react").JSX.Element;
-export declare function RadialBarChart<DataPoint = unknown>({ animate, animationDirection, categoryKey, children, ...props }: RadialBarChartProps<DataPoint>): import("react").JSX.Element;
+export declare function RadarChart<DataPoint = unknown>({ animate, loading, loadingLabel, selection, selectedSeries, onSelectedSeriesChange, children, ...props }: RadarChartProps<DataPoint>): import("react").JSX.Element;
+export declare function RadialBarChart<DataPoint = unknown>(props: RadialBarChartProps<DataPoint>): import("react").JSX.Element;
+/** Private recipe integration; the public chart keeps its native prop contract. */
+export declare function RadialBarChartFrame<DataPoint = unknown>({ skeletonFamily, animate, loading, loadingLabel, animationDirection, categoryKey, interactionBinding, children, ...props }: RadialBarChartProps<DataPoint> & {
+    skeletonFamily?: "radial-bar" | "activity-rings";
+}): import("react").JSX.Element;

package/dist/polar-chart.js

@@ -4,7 +4,10 @@ import { animate as animateValue } from "motion/react";
 import { createContext, useCallback, useLayoutEffect, useRef, useState, useSyncExternalStore, } from "react";
 import { RadarChart as EngineRadarChart, RadialBarChart as EngineRadialBarChart } from "recharts";
 import { MotionContext } from "./animation.js";
+import { filterCategoryRows } from "./category-cells.js";
+import { useChartInteraction } from "./chart-interaction.js";
 import { LineChartFrame, useLineInteraction } from "./line-chart.js";
+import { PolarLoadingDesign } from "./loading-polar-designs.js";
 import { RadarSelectionProvider } from "./radar-interaction.js";
 import { RadialCategory } from "./radial-category.js";
 export const PolarMotion = createContext({
@@ -26,11 +29,18 @@ function subscribe(change) {
 const snapshot = () => window.matchMedia(query).matches;
 const serverSnapshot = () => true;
 const defaultHover = { type: "spring", stiffness: 210, damping: 28, mass: 0.8 };
-function usePolarMotion(animate) {
+function usePolarMotion(animate, loading) {
     const reduced = useSyncExternalStore(subscribe, snapshot, serverSnapshot);
     const [finished, setFinished] = useState(false);
-    const interrupt = useCallback(() => setFinished(true), []);
-    const enabled = animate !== false && !reduced;
+    const interrupt = useCallback(() => {
+        if (!loading)
+            setFinished(true);
+    }, [loading]);
+    useLayoutEffect(() => {
+        if (loading)
+            setFinished(false);
+    }, [loading]);
+    const enabled = animate !== false && !reduced && !loading;
     const options = typeof animate === "object" ? animate : {};
     return { enabled, options, reveal: enabled && !finished, interrupt };
 }
@@ -62,12 +72,16 @@ function PolarLifecycle({ layout, cx, cy, innerRadius, outerRadius, startAngle,
     return null;
 }
 /** Native polar composition with shared metadata, interaction and optional Motion. */
-export function RadarChart({ animate = false, selection, selectedSeries, onSelectedSeriesChange, children, ...props }) {
-    const { enabled, options, reveal, interrupt } = usePolarMotion(animate);
+export function RadarChart({ animate = false, loading, loadingLabel, selection, selectedSeries, onSelectedSeriesChange, children, ...props }) {
+    const { enabled, options, reveal, interrupt } = usePolarMotion(animate, loading);
     const [progress, setProgress] = useState(1);
     const duration = options.revealDurationMs ?? 1000;
     const easing = options.revealEasing ?? "easeOut";
     const started = useRef(false);
+    useLayoutEffect(() => {
+        if (loading)
+            started.current = false;
+    }, [loading]);
     const previous = useRef([duration, easing]);
     const previousEnabled = useRef(enabled);
     useLayoutEffect(() => {
@@ -93,15 +107,28 @@ export function RadarChart({ animate = false, selection, selectedSeries, onSelec
         });
         return () => controls.stop();
     }, [reveal, duration, easing, interrupt]);
-    return (_jsx(MotionContext, { value: { enabled, transition: options.hoverTransition ?? defaultHover }, children: _jsx(RadarMotion, { value: { reveal, progress }, children: _jsx(PolarMotion, { value: { reveal, options }, children: _jsx(RadarSelectionProvider, { selection: selection, selectedSeries: selectedSeries, onSelectedSeriesChange: onSelectedSeriesChange, children: _jsxs(LineChartFrame, { engine: (EngineRadarChart), chartProps: props, motionEnabled: enabled, interrupt: interrupt, children: [_jsx(PolarLifecycle, { ...props, children: children }), children] }) }) }) }) }));
+    return (_jsx(MotionContext, { value: { enabled, transition: options.hoverTransition ?? defaultHover }, children: _jsx(RadarMotion, { value: { reveal, progress }, children: _jsx(PolarMotion, { value: { reveal, options }, children: _jsx(RadarSelectionProvider, { selection: selection, selectedSeries: selectedSeries, onSelectedSeriesChange: onSelectedSeriesChange, children: _jsxs(LineChartFrame, { engine: (EngineRadarChart), loading: loading, loadingLabel: loadingLabel, loadingSkeleton: "radar", loadingDesign: (seed) => _jsx(PolarLoadingDesign, { family: "radar", seed: seed }), loadingAnimation: options, chartProps: props, motionEnabled: enabled, interrupt: interrupt, children: [_jsx(PolarLifecycle, { ...props, children: children }), children] }) }) }) }) }));
 }
-export function RadialBarChart({ animate = false, animationDirection = "clockwise", categoryKey, children, ...props }) {
+export function RadialBarChart(props) {
+    return _jsx(RadialBarChartFrame, { ...props });
+}
+/** Private recipe integration; the public chart keeps its native prop contract. */
+export function RadialBarChartFrame({ skeletonFamily = "radial-bar", animate = false, loading, loadingLabel, animationDirection = "clockwise", categoryKey, interactionBinding, children, ...props }) {
+    const interaction = useChartInteraction();
+    if (interactionBinding &&
+        (interaction.kind !== "category" || categoryKey === undefined || props.data === undefined))
+        throw new Error("RadialBarChart Root interaction binding requires category-kind Root, categoryKey and explicit data");
+    const filtered = interactionBinding && categoryKey !== undefined && props.data
+        ? filterCategoryRows(props.data, categoryKey, interaction.visible, null)
+        : undefined;
     if (categoryKey !== undefined && props.data === undefined)
         throw new Error("RadialBarChart categoryKey requires explicit chart data");
     const categories = categoryKey === undefined
         ? null
         : {
-            data: props.data ?? [],
+            data: filtered?.data ?? props.data ?? [],
+            originalData: props.data ?? [],
+            bound: interactionBinding === "root",
             key: (row) => {
                 if (typeof categoryKey === "function")
                     return categoryKey(row);
@@ -110,11 +137,15 @@ export function RadialBarChart({ animate = false, animationDirection = "clockwis
                     : "";
             },
         };
-    const { enabled, options, reveal, interrupt } = usePolarMotion(animate);
+    const { enabled, options, reveal, interrupt } = usePolarMotion(animate, loading);
     const [progress, setProgress] = useState(1);
     const duration = options.revealDurationMs ?? 1000;
     const easing = options.revealEasing ?? "easeOut";
     const started = useRef(false);
+    useLayoutEffect(() => {
+        if (loading)
+            started.current = false;
+    }, [loading]);
     const previous = useRef([duration, easing, animationDirection]);
     const previousEnabled = useRef(enabled);
     useLayoutEffect(() => {
@@ -141,5 +172,5 @@ export function RadialBarChart({ animate = false, animationDirection = "clockwis
         });
         return () => controls.stop();
     }, [reveal, duration, easing, interrupt]);
-    return (_jsx(RadialCategory, { value: categories, children: _jsx(MotionContext, { value: { enabled, transition: options.hoverTransition ?? defaultHover }, children: _jsx(RadialMotion, { value: { reveal, progress, direction: animationDirection }, children: _jsx(PolarMotion, { value: { reveal, options }, children: _jsxs(LineChartFrame, { engine: (EngineRadialBarChart), chartProps: props, motionEnabled: enabled, interrupt: interrupt, children: [_jsx(PolarLifecycle, { ...props, children: children }), children] }) }) }) }) }));
+    return (_jsx(RadialCategory, { value: categories, children: _jsx(MotionContext, { value: { enabled, transition: options.hoverTransition ?? defaultHover }, children: _jsx(RadialMotion, { value: { reveal, progress, direction: animationDirection }, children: _jsx(PolarMotion, { value: { reveal, options }, children: _jsxs(LineChartFrame, { engine: (EngineRadialBarChart), loading: loading, loadingLabel: loadingLabel, loadingSkeleton: skeletonFamily, loadingDesign: (seed) => _jsx(PolarLoadingDesign, { family: skeletonFamily, seed: seed }), loadingAnimation: { ...options, direction: animationDirection }, chartProps: { ...props, ...(filtered ? { data: filtered.data } : {}) }, motionEnabled: enabled, interrupt: interrupt, children: [_jsx(PolarLifecycle, { ...props, children: children }), children] }) }) }) }) }));
 }

package/dist/polar-series.js

@@ -5,25 +5,32 @@ import { animate, motion, useMotionValue } from "motion/react";
 import { memo, use, useId, useLayoutEffect, useRef, useState } from "react";
 import { DefaultZIndexes, Polygon, Radar, RadialBar, Sector, ZIndexLayer } from "recharts";
 import { ActiveMarker } from "./animation.js";
-import { categoryCells } from "./category-cells.js";
+import { categoryCells, filterCategoryRows } from "./category-cells.js";
 import { useChart } from "./chart-context.js";
+import { useChartInteraction, useInteractionFocus } from "./chart-interaction.js";
+import { EmphasisMark } from "./emphasis.js";
 import { useLineInteraction } from "./line-chart.js";
 import { PolarMotion, RadarMotion, RadialMotion } from "./polar-chart.js";
 import { PolarMaterialFilter } from "./polar-material.js";
 import { RadarSelectionLayer, useRadarSelectionDot } from "./radar-interaction.js";
 import { RadialCategory } from "./radial-category.js";
+import { SeriesInteractionLayer, useSeriesInteraction } from "./series-interaction.js";
 // Native Radar uses a props-identity animation key even with animation disabled.
 // Avoid replacing its polygon for unrelated frame state during a pointer press.
 const StableRadar = memo(Radar);
 const radarActiveDot = _jsx(ActiveMarker, {});
 function usePolarSeries(kind, props, geometry) {
-    const { config, visibleSeries } = useChart();
+    const { config, paints, visibleSeries } = useChart();
+    const interactionOwner = useChartInteraction();
     const { registerSeries, invalidate } = useLineInteraction();
     const { reveal, options } = use(PolarMotion);
     const generatedId = useId();
     const id = props.id || generatedId;
     const key = props.seriesKey ?? (typeof props.dataKey === "string" ? props.dataKey : undefined);
-    const hide = props.hide === true || (visibleSeries !== undefined && !visibleSeries.includes(key ?? ""));
+    const hide = props.hide === true ||
+        (interactionOwner.kind === "series" &&
+            visibleSeries !== undefined &&
+            !visibleSeries.includes(key ?? ""));
     const previous = useRef([...geometry, hide]);
     useLayoutEffect(() => {
         const inputs = [...geometry, hide];
@@ -56,7 +63,7 @@ function usePolarSeries(kind, props, geometry) {
     }, [reveal, hide, opacity, duration, easing]);
     if (key === undefined && visibleSeries !== undefined)
         throw new Error(`${kind} requires seriesKey for controlled non-string dataKey`);
-    const color = key !== undefined && Object.hasOwn(config, key) ? `var(--color-${key})` : undefined;
+    const color = key !== undefined && Object.hasOwn(config, key) ? paints[key] : undefined;
     return { id, hide, color, opacity };
 }
 // Recharts injects its original computed points and callback props into this renderer.
@@ -90,24 +97,50 @@ export function RadarSeries({ seriesKey, hide, stroke, fill, className, material
         props.baseLinePoints,
         props.isRange,
     ]);
+    const interaction = useSeriesInteraction(seriesKey ?? (typeof props.dataKey === "string" ? props.dataKey : undefined), series.hide, hide === true, undefined, props.onClick);
     const selectionDot = useRadarSelectionDot(props.dot, seriesKey ?? (typeof props.dataKey === "string" ? props.dataKey : undefined));
     const filterId = `kind-ui-polar-${useId().replace(/[^a-zA-Z0-9_-]/g, "_")}`;
     const materialized = material !== "plain" &&
         props.shape === undefined &&
         props.filter === undefined &&
         props.style?.filter === undefined;
-    return (_jsxs(ZIndexLayer, { zIndex: props.zIndex ?? DefaultZIndexes.area, children: [materialized && (_jsxs(_Fragment, { children: [_jsx(PolarMaterialFilter, { material: material, id: filterId }), _jsx("style", { children: `.${filterId} .recharts-radar-polygon > .recharts-polygon { filter: url(#${filterId}); }` })] })), _jsx(RadarSelectionLayer, { seriesKey: seriesKey ?? (typeof props.dataKey === "string" ? props.dataKey : undefined), hidden: series.hide, children: _jsx(motion.g, { "data-kind-ui": "radar-reveal", initial: false, children: _jsx(StableRadar, { activeDot: radarActiveDot, ...props, ...(props.shape === undefined ? { shape: renderRadarEntrance } : {}), ...(selectionDot !== undefined ? { dot: selectionDot } : {}), id: series.id, hide: series.hide, isAnimationActive: false, zIndex: 0, ...(stroke !== undefined
-                            ? { stroke }
-                            : series.color !== undefined
-                                ? { stroke: series.color }
-                                : {}), ...(fill !== undefined
-                            ? { fill }
-                            : series.color !== undefined
-                                ? { fill: series.color }
-                                : {}), className: ["kind-ui-radar-series", filterId, className].filter(Boolean).join(" ") }) }) })] }));
+    return (_jsxs(ZIndexLayer, { zIndex: props.zIndex ?? DefaultZIndexes.area, children: [materialized && (_jsxs(_Fragment, { children: [_jsx(PolarMaterialFilter, { material: material, id: filterId }), _jsx("style", { children: `.${filterId} .recharts-radar-polygon > .recharts-polygon { filter: url(#${filterId}); }` })] })), _jsx(SeriesInteractionLayer, { seriesKey: seriesKey ?? (typeof props.dataKey === "string" ? props.dataKey : undefined), hidden: series.hide, children: _jsx(RadarSelectionLayer, { seriesKey: seriesKey ?? (typeof props.dataKey === "string" ? props.dataKey : undefined), hidden: series.hide, children: _jsx(motion.g, { "data-kind-ui": "radar-reveal", initial: false, children: _jsx(StableRadar, { activeDot: radarActiveDot, ...props, ...(interaction.onClick !== undefined ? { onClick: interaction.onClick } : {}), ...(props.shape === undefined ? { shape: renderRadarEntrance } : {}), ...(selectionDot !== undefined ? { dot: selectionDot } : {}), id: series.id, hide: series.hide, isAnimationActive: false, zIndex: 0, ...(stroke !== undefined
+                                ? { stroke }
+                                : series.color !== undefined
+                                    ? { stroke: series.color }
+                                    : {}), ...(fill !== undefined
+                                ? { fill }
+                                : series.color !== undefined
+                                    ? { fill: series.color }
+                                    : {}), className: ["kind-ui-radar-series", filterId, className].filter(Boolean).join(" ") }) }) }) })] }));
 }
 // Recharts computes every arc; the entrance masks its paint without changing its path.
 function RadialEntranceSector(props) {
+    const categories = use(RadialCategory);
+    const interaction = useChartInteraction();
+    const key = categories?.bound ? categories.key(props.payload) : undefined;
+    const content = useRadialSector(props);
+    const interactive = key !== undefined &&
+        interaction.interactive &&
+        interaction.markActivation &&
+        interaction.eligible.includes(key);
+    const focusRef = useInteractionFocus(key, interactive);
+    return key === undefined ? (content) : (_jsx(EmphasisMark, { ref: focusRef, "data-interaction-focus-key": interactive ? key : undefined, target: { kind: "category", key, scope: "radial", seriesKey: key }, role: interactive ? "button" : undefined, tabIndex: interactive ? 0 : undefined, "aria-label": interactive ? `${interaction.mode === "focus" ? "Highlight" : "Toggle"} ${key}` : undefined, "aria-pressed": interactive
+            ? interaction.mode === "focus"
+                ? interaction.selected === key
+                : true
+            : undefined, onKeyDown: (event) => {
+            if (interactive &&
+                event.target === event.currentTarget &&
+                !event.defaultPrevented &&
+                (event.key === "Enter" || event.key === " ")) {
+                if (!event.repeat)
+                    interaction.activate({ kind: "category", key }, "mark", event);
+                event.preventDefault();
+            }
+        }, children: content }));
+}
+function useRadialSector(props) {
     const { reveal, progress, direction } = use(RadialMotion);
     const id = `kind-ui-radial-entrance-${useId().replace(/[^a-zA-Z0-9_-]/g, "_")}`;
     const group = useRef(null);
@@ -139,9 +172,13 @@ function RadialEntranceSector(props) {
 /** Series identity is independent from native category payload/Cell identity. */
 export function RadialBarSeries({ seriesKey, hide, fill, className, material = "plain", ...props }) {
     const categories = use(RadialCategory);
-    const { config } = useChart();
+    const { config, paints } = useChart();
+    const owner = useChartInteraction();
+    const filtered = categories?.bound
+        ? filterCategoryRows(categories.originalData, categories.key, owner.visible, props.children)
+        : undefined;
     const children = categories
-        ? categoryCells(categories.data, categories.key, config, props.children, fill)
+        ? categoryCells(categories.data, categories.key, config, paints, filtered?.children ?? props.children, fill)
         : props.children;
     const series = usePolarSeries("RadialBarSeries", { ...props, seriesKey, hide }, [
         props.dataKey,
@@ -153,17 +190,26 @@ export function RadialBarSeries({ seriesKey, hide, fill, className, material = "
         props.maxBarSize,
         props.minPointSize,
     ]);
+    const interaction = useSeriesInteraction(seriesKey ?? (typeof props.dataKey === "string" ? props.dataKey : undefined), series.hide, hide === true, undefined, props.onClick);
     const filterId = `kind-ui-polar-${useId().replace(/[^a-zA-Z0-9_-]/g, "_")}`;
     const materialized = material !== "plain" &&
         (props.shape === undefined || typeof props.shape === "boolean") &&
         (props.activeShape === undefined || typeof props.activeShape === "boolean") &&
         props.filter === undefined &&
         props.style?.filter === undefined;
-    return (_jsxs(ZIndexLayer, { zIndex: props.zIndex ?? DefaultZIndexes.bar, children: [materialized && _jsx(PolarMaterialFilter, { material: material, id: filterId }), _jsx(motion.g, { "data-kind-ui": "radial-bar-reveal", initial: false, children: _jsx(RadialBar, { ...props, ...(props.shape === undefined ? { shape: RadialEntranceSector } : {}), ...(props.background === true
-                        ? { background: { fill: "var(--kind-ui-radial-track, #f1f1f1)" } }
-                        : {}), ...(materialized ? { filter: `url(#${filterId})` } : {}), id: series.id, hide: series.hide, isAnimationActive: false, zIndex: 0, ...(fill !== undefined
-                        ? { fill }
-                        : series.color !== undefined
-                            ? { fill: series.color }
-                            : {}), className: ["kind-ui-radial-bar-series", className].filter(Boolean).join(" "), children: children }) })] }));
+    const onClick = categories?.bound
+        ? (...args) => {
+            props.onClick?.(...args);
+            owner.activate({ kind: "category", key: categories.key(args[0].payload) }, "mark", args[2]);
+        }
+        : interaction.onClick;
+    return (_jsxs(ZIndexLayer, { zIndex: props.zIndex ?? DefaultZIndexes.bar, children: [materialized && _jsx(PolarMaterialFilter, { material: material, id: filterId }), _jsx(SeriesInteractionLayer, { seriesKey: seriesKey ?? (typeof props.dataKey === "string" ? props.dataKey : undefined), hidden: series.hide, children: _jsx(motion.g, { "data-kind-ui": "radial-bar-reveal", initial: false, children: _jsx(RadialBar, { ...props, ...(onClick !== undefined ? { onClick } : {}), ...(props.shape === undefined ? { shape: RadialEntranceSector } : {}), ...(categories?.bound && props.shape === undefined && props.activeShape === undefined
+                            ? { activeShape: RadialEntranceSector }
+                            : {}), ...(props.background === true
+                            ? { background: { fill: "var(--kind-ui-radial-track, #f1f1f1)" } }
+                            : {}), ...(materialized ? { filter: `url(#${filterId})` } : {}), id: series.id, hide: series.hide, isAnimationActive: false, zIndex: 0, ...(fill !== undefined
+                            ? { fill }
+                            : series.color !== undefined
+                                ? { fill: series.color }
+                                : {}), className: ["kind-ui-radial-bar-series", className].filter(Boolean).join(" "), children: children }) }) })] }));
 }

package/dist/radar-interaction.js

@@ -3,7 +3,7 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { cloneElement, createContext, isValidElement, use, useCallback, useEffect, useId, useLayoutEffect, useMemo, useState, } from "react";
 import { Dot } from "recharts";
 import { useChart } from "./chart-context.js";
-import { useEmphasisActions } from "./emphasis.js";
+import { useChartInteraction } from "./chart-interaction.js";
 import { useLineInteraction } from "./line-chart.js";
 const Context = createContext(null);
 const Mode = createContext(false);
@@ -11,8 +11,11 @@ const Mode = createContext(false);
 export function RadarSelectionProvider({ selection = "none", selectedSeries, onSelectedSeriesChange, children, }) {
     if (selectedSeries !== undefined && onSelectedSeriesChange === undefined)
         throw new Error("RadarChart requires onSelectedSeriesChange for controlled selectedSeries");
-    const { enabled: emphasisEnabled } = useEmphasisActions();
-    const enabled = selection === "series" && emphasisEnabled;
+    const interaction = useChartInteraction();
+    if (interaction.mode === "focus" &&
+        (selection !== "none" || selectedSeries !== undefined || onSelectedSeriesChange !== undefined))
+        throw new Error("RadarChart selection controls conflict with Root focus; choose one selection owner");
+    const enabled = selection === "series";
     const [internal, setInternal] = useState(null);
     const [series, setSeries] = useState(() => new Map());
     const register = useCallback((owner, key, visible) => {
@@ -51,7 +54,10 @@ export function RadarSelectionProvider({ selection = "none", selectedSeries, onS
     const value = useMemo(() => ({ enabled, selected, register, toggle }), [enabled, selected, register, toggle]);
     return (_jsx(Mode, { value: enabled, children: _jsx(Context, { value: value, children: _jsx("div", { style: { display: "contents" }, onKeyDown: (event) => {
                     if (event.key === "Escape" && !event.defaultPrevented && enabled && requested !== null)
-                        change(null);
+                        queueMicrotask(() => {
+                            if (!event.defaultPrevented)
+                                change(null);
+                        });
                 }, children: children }) }) }));
 }
 /** An extra paint/control layer preserves native shape, data, refs and event handlers. */

package/dist/radial-category.d.ts

@@ -1,4 +1,6 @@
 export declare const RadialCategory: import("react").Context<{
     data: readonly unknown[];
+    originalData: readonly unknown[];
+    bound: boolean;
     key: (row: unknown) => string;
 } | null>;

package/dist/reveal-clip.d.ts

@@ -0,0 +1,16 @@
+import { type Transition } from "motion/react";
+export type RevealDirection = "left-to-right" | "right-to-left" | "center-out" | "edges-in";
+type Options = {
+    revealDirection?: RevealDirection;
+    revealDurationMs?: number;
+    revealEasing?: Transition["ease"];
+};
+/** Entrance paint only: percentage rectangles never transform native series geometry. */
+export declare function RevealClip({ id, family, combo, options, finish, }: {
+    id: string;
+    family?: "line" | "area";
+    combo?: boolean;
+    options: Options;
+    finish?: () => void;
+}): import("react").JSX.Element;
+export {};

package/dist/reveal-clip.js

@@ -0,0 +1,18 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { motion } from "motion/react";
+/** Entrance paint only: percentage rectangles never transform native series geometry. */
+export function RevealClip({ id, family, combo = false, options, finish, }) {
+    const direction = options.revealDirection ?? "left-to-right";
+    const split = direction === "edges-in";
+    const initialX = direction === "right-to-left" ? "100%" : direction === "center-out" ? "50%" : "0%";
+    const transition = {
+        duration: Math.max(0, options.revealDurationMs ?? 1000) / 1000,
+        ease: options.revealEasing ?? [0.25, 0.1, 0.25, 1],
+    };
+    return (_jsx("defs", { children: _jsxs("clipPath", { id: id, clipPathUnits: "userSpaceOnUse", "data-reveal-direction": direction, children: [_jsx(motion.rect, { ...(combo
+                        ? { "data-combo-reveal": family }
+                        : family === "area"
+                            ? { "data-area-reveal": "" }
+                            : {}), y: 0, height: "100%", initial: { attrX: initialX, width: "0%" }, animate: { attrX: "0%", width: split ? "50%" : "100%" }, ...(finish ? { onAnimationComplete: finish } : {}), transition: transition }), split && (_jsx(motion.rect, { y: 0, height: "100%", initial: { attrX: "100%", width: "0%" }, animate: { attrX: "50%", width: "50%" }, transition: transition }))] }) }));
+}

package/dist/root.d.ts

@@ -1,14 +1,10 @@
-import type { ComponentPropsWithRef } from "react";
+import { type ComponentPropsWithRef } from "react";
+import { type ChartInteractionConfig, type ChartVisibilityProps } from "./chart-interaction.js";
 import type { SeriesConfig } from "./types.js";
 export type RootProps = ComponentPropsWithRef<"div"> & {
     config: SeriesConfig;
     emphasis?: "auto" | "none";
-} & ({
-    visibleSeries?: undefined;
-    onVisibleSeriesChange?: never;
-} | {
-    visibleSeries: readonly string[];
-    onVisibleSeriesChange?: (next: string[]) => void;
-});
+    interaction?: ChartInteractionConfig;
+} & ChartVisibilityProps;
 /** Scopes presentation metadata and CSS colors; the consumer owns chart geometry and state. */
-export declare function Root({ config, emphasis, visibleSeries, onVisibleSeriesChange, style, children, ...props }: RootProps): import("react").JSX.Element;
+export declare function Root({ config, emphasis, interaction, defaultVisibleSeries, visibleSeries, onVisibleSeriesChange, style, children, ...props }: RootProps): import("react").JSX.Element;

package/dist/root.js

@@ -1,29 +1,64 @@
 "use client";
-import { jsx as _jsx } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useId } from "react";
 import { ChartContext } from "./chart-context.js";
+import { ChartInteractionProvider, ChartInteractionStatus, useChartInteraction, } from "./chart-interaction.js";
 import { EmphasisProvider, useEmphasisActions } from "./emphasis.js";
+import { colorResourceId, colorStopToken, resolveSeriesColor, } from "./series-color.js";
+import { resolveSeriesConfig } from "./series-label.js";
+import { SeriesColorDefinitions } from "./series-paint.js";
+import { StylesheetWarning } from "./stylesheet-warning.js";
 /** Scopes presentation metadata and CSS colors; the consumer owns chart geometry and state. */
-export function Root({ config, emphasis = "auto", visibleSeries, onVisibleSeriesChange, style, children, ...props }) {
-    if (onVisibleSeriesChange && !visibleSeries)
-        throw new Error("Root requires visibleSeries when onVisibleSeriesChange is provided");
+export function Root({ config, emphasis = "auto", interaction, defaultVisibleSeries, visibleSeries, onVisibleSeriesChange, style, children, ...props }) {
+    if (onVisibleSeriesChange && visibleSeries === undefined && defaultVisibleSeries === undefined)
+        throw new Error("Root requires visibleSeries or defaultVisibleSeries when onVisibleSeriesChange is provided");
+    if (visibleSeries !== undefined && defaultVisibleSeries !== undefined)
+        throw new Error("Root visibility cannot be both controlled and defaulted");
+    const id = useId();
     const colors = {};
+    const paints = {};
+    const colorStops = {};
     for (const [key, item] of Object.entries(config)) {
         if (!/^[a-zA-Z][\w-]*$/.test(key))
             throw new Error(`Chart series key "${key}" must start with a letter and contain only letters, numbers, underscores or hyphens`);
-        colors[`--color-${key}`] = item.color;
+        const resolved = resolveSeriesColor(item.color, key);
+        colors[`--color-${key}`] = resolved.colors[0];
+        for (const [index, color] of resolved.colors.entries())
+            colors[colorStopToken(key, index)] = color;
+        colorStops[key] = resolved;
+        const gradientId = colorResourceId(id, key);
+        const gradient = resolved.colors.length > 1;
+        paints[key] = gradient ? `url(#${gradientId})` : `var(--color-${key})`;
+        colors[colorStopToken(key, "gradient")] = gradient
+            ? `linear-gradient(to right in srgb, ${resolved.offsets.map((offset, index) => `var(${colorStopToken(key, index)}) ${offset * 100}%`).join(", ")})`
+            : `var(--color-${key})`;
     }
     const value = {
-        config,
+        config: resolveSeriesConfig(config),
+        paints,
+        colorId: id,
+        colorStops,
         ...(visibleSeries ? { visibleSeries } : {}),
         ...(onVisibleSeriesChange ? { onVisibleSeriesChange } : {}),
     };
-    return (_jsx(ChartContext, { value: value, children: _jsx(EmphasisProvider, { enabled: emphasis === "auto", children: _jsx(RootFrame, { ...props, style: { ...colors, ...style }, children: children }) }) }));
+    return (_jsx(ChartInteractionProvider, { config: value.config, ...(interaction ? { interaction } : {}), ...(visibleSeries !== undefined
+            ? { visibleSeries, ...(onVisibleSeriesChange ? { onVisibleSeriesChange } : {}) }
+            : defaultVisibleSeries !== undefined
+                ? { defaultVisibleSeries, ...(onVisibleSeriesChange ? { onVisibleSeriesChange } : {}) }
+                : {}), children: (visible, change) => (_jsx(ChartContext, { value: {
+                ...value,
+                ...(visible !== undefined ? { visibleSeries: visible } : {}),
+                ...(change ? { onVisibleSeriesChange: change } : {}),
+            }, children: _jsx(EmphasisProvider, { enabled: emphasis === "auto", children: _jsxs(RootFrame, { ...props, style: { ...colors, ...style }, children: [process.env.NODE_ENV === "development" && _jsx(StylesheetWarning, {}), Object.values(colorStops).some((stops) => stops.colors.length > 1) && (_jsx("svg", { "aria-hidden": "true", focusable: "false", width: 0, height: 0, style: { position: "absolute" }, "data-kind-ui": "color-resources", children: _jsx(SeriesColorDefinitions, {}) })), children] }) }) })) }));
 }
 function RootFrame({ children, ...props }) {
     const { reset } = useEmphasisActions();
-    return (_jsx("div", { ...props, "data-kind-ui": "chart", onKeyDownCapture: (event) => {
-            if (event.key === "Escape")
+    const interaction = useChartInteraction();
+    return (
+    // biome-ignore lint/a11y/noStaticElementInteractions: Delegates Escape from descendants after consumer handlers; this frame is not a control.
+    _jsxs("div", { ...props, "data-kind-ui": "chart", onKeyDown: (event) => {
+            props.onKeyDown?.(event);
+            if (event.key === "Escape" && interaction.reset(event))
                 reset();
-            props.onKeyDownCapture?.(event);
-        }, children: children }));
+        }, children: [children, _jsx(ChartInteractionStatus, {})] }));
 }

package/dist/sankey-chart.d.ts

@@ -14,6 +14,8 @@ export type SankeyChartProps = Omit<NativeProps, "data" | "node" | "link" | "onC
     data: SankeyFlowData;
     /** Explicit node-ID metadata; enables matching default Kind node/source-link paint. */
     nodeConfig?: SankeyNodeConfig | undefined;
+    /** Explicit node-focus binding; Root must use kind node and mode focus. */
+    interactionBinding?: "root";
     node?: Exclude<NativeProps["node"], (props: NativeNodeProps) => ReactNode> | ((props: SankeyNodeProps) => ReactNode);
     link?: Exclude<NativeProps["link"], (props: NativeLinkProps) => ReactNode> | ((props: SankeyLinkProps) => ReturnType<NonNullable<Extract<NativeProps["link"], (props: NativeLinkProps) => ReactNode>>>);
     onClick?: IdentityEvent;
@@ -21,6 +23,8 @@ export type SankeyChartProps = Omit<NativeProps, "data" | "node" | "link" | "onC
     onMouseLeave?: IdentityEvent;
     /** Kind SankeyLink paint flows along unchanged paths; custom renderers retain ownership. */
     animate?: boolean | SankeyAnimation;
+    loading?: boolean | undefined;
+    loadingLabel?: string | undefined;
     empty?: ReactNode;
 };
 export declare const SankeyMotion: import("react").Context<{
@@ -29,5 +33,5 @@ export declare const SankeyMotion: import("react").Context<{
     width: number;
 }>;
 /** Recharts owns layout, renderers, labels and events. Zero flows remain in the data alternative. */
-export declare function SankeyChart({ data, nodeConfig, animate, empty, ...props }: SankeyChartProps): import("react").JSX.Element;
+export declare function SankeyChart({ data, nodeConfig, interactionBinding, animate, loading, loadingLabel, empty, ...props }: SankeyChartProps): import("react").JSX.Element;
 export {};