@kind-ui/charts 0.1.1 → 0.3.0

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 {};

package/dist/sankey-chart.js

@@ -3,8 +3,12 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { animate as animateValue, useMotionValue } from "motion/react";
 import { createContext, useCallback, useLayoutEffect, useRef, useState, useSyncExternalStore, } from "react";
 import { Sankey as EngineSankey, useChartHeight, useChartWidth, } from "recharts";
+import { useOptionalChartInteraction } from "./chart-interaction.js";
+import { LoadingSkeletonSurface, LoadingStatus, useLoadingSeed } from "./loading-skeleton.js";
+import { StandaloneLoadingDesign } from "./loading-standalone-designs.js";
 import { SankeyColors } from "./sankey-colors.js";
 import { prepareSankeyData } from "./sankey-data.js";
+import { SankeyFocusMark } from "./sankey-interaction.js";
 import { SankeyLink, SankeyNode, } from "./sankey-marks.js";
 const configuredNode = (shape) => _jsx(SankeyNode, { ...shape });
 const configuredLink = (shape) => _jsx(SankeyLink, { ...shape });
@@ -27,7 +31,25 @@ const snapshot = () => window.matchMedia(query).matches;
 const serverSnapshot = () => true;
 export const SankeyMotion = createContext({ reveal: false, progress: null, width: 1 });
 /** Recharts owns layout, renderers, labels and events. Zero flows remain in the data alternative. */
-export function SankeyChart({ data, nodeConfig, animate = false, empty = "No positive flows", ...props }) {
+export function SankeyChart({ data, nodeConfig, interactionBinding, animate = false, loading, loadingLabel, empty = "No positive flows", ...props }) {
+    const interaction = useOptionalChartInteraction();
+    if (interactionBinding &&
+        (!interaction || interaction.kind !== "node" || interaction.mode !== "focus"))
+        throw new Error("SankeyChart Root interaction binding requires node focus");
+    const adjacent = new Map();
+    for (const link of data.links) {
+        const source = typeof link.source === "string" ? link.source : data.nodes[link.source]?.id;
+        const target = typeof link.target === "string" ? link.target : data.nodes[link.target]?.id;
+        if (source && target) {
+            const from = adjacent.get(source) ?? new Set();
+            from.add(target);
+            adjacent.set(source, from);
+            const to = adjacent.get(target) ?? new Set();
+            to.add(source);
+            adjacent.set(target, to);
+        }
+    }
+    const loadingSeed = useLoadingSeed(loading);
     const duration = typeof animate === "object" ? (animate.revealDurationMs ?? 450) : 450;
     if (!Number.isFinite(duration) || duration < 0)
         throw new Error("Sankey revealDurationMs must be finite and nonnegative");
@@ -63,15 +85,21 @@ export function SankeyChart({ data, nodeConfig, animate = false, empty = "No pos
     const [interrupted, setInterrupted] = useState(false);
     const [size, setSize] = useState(null);
     const measured = useRef(null);
+    const previousLoading = useRef(loading);
+    const completing = previousLoading.current === true && loading !== true;
     const onSize = useCallback((width, height) => {
         const prior = measured.current;
         if (prior?.width === width && prior?.height === height)
             return;
-        if (prior)
+        if (prior && !loading && !completing)
             setInterrupted(true);
         measured.current = { width, height };
         setSize(measured.current);
-    }, []);
+    }, [loading, completing]);
+    useLayoutEffect(() => {
+        if (loading)
+            setInterrupted(false);
+    }, [loading]);
     const inputs = [
         duration,
         data,
@@ -91,17 +119,20 @@ export function SankeyChart({ data, nodeConfig, animate = false, empty = "No pos
     const started = useRef(false);
     const previous = useRef(inputs);
     useLayoutEffect(() => {
-        if (inputs.some((value, index) => (index !== 0 || started.current) && value !== previous.current[index]))
+        if (!loading &&
+            !completing &&
+            inputs.some((value, index) => (index !== 0 || started.current) && value !== previous.current[index]))
             setInterrupted(true);
         previous.current = inputs;
+        previousLoading.current = loading;
     });
-    const enabled = Boolean(animate) && !reduced;
+    const enabled = Boolean(animate) && !reduced && !loading;
     const previousEnabled = useRef(enabled);
     useLayoutEffect(() => {
-        if (previousEnabled.current && !enabled)
+        if (previousEnabled.current && !enabled && !loading)
             setInterrupted(true);
         previousEnabled.current = enabled;
-    }, [enabled]);
+    }, [enabled, loading]);
     const reveal = enabled && !interrupted && size !== null;
     const progress = useMotionValue(1);
     useLayoutEffect(() => {
@@ -133,10 +164,30 @@ export function SankeyChart({ data, nodeConfig, animate = false, empty = "No pos
             links.some((link) => link.value * minimumScale === 0))
             throw new Error("Sankey flows exceed native renderer numeric limits at this size; use explicitly rescaled input units.");
     }
-    return (_jsx(SankeyColors, { value: nodeConfig, children: _jsx(SankeyMotion, { value: { reveal, progress, width: size?.width ?? 1 }, children: _jsxs("div", { "data-kind-ui": "sankey", onPointerDownCapture: () => setInterrupted(true), onFocusCapture: () => setInterrupted(true), style: { position: "relative", width: "fit-content", height: "fit-content" }, children: [_jsxs(EngineSankey, { ...props, ...(nodeConfig
-                            ? {
-                                node: props.node ?? configuredNode,
-                                link: props.link ?? configuredLink,
-                            }
-                            : {}), data: drawable && links.length ? { nodes, links } : { nodes: [], links: [] }, children: [_jsx(NativeSize, { onSize: onSize }), props.children] }), !links.length ? (_jsx("div", { role: "status", style: { position: "absolute", inset: 0 }, children: empty })) : !drawable ? (_jsx("div", { role: "status", style: { position: "absolute", inset: 0 }, children: "Insufficient space for flows; use the data table" })) : null] }) }) }));
+    return (_jsx(SankeyColors, { value: nodeConfig, children: _jsx(SankeyMotion, { value: { reveal, progress, width: size?.width ?? 1 }, children: _jsxs("div", { "data-kind-ui": "sankey", onPointerDownCapture: () => {
+                    if (!loading)
+                        setInterrupted(true);
+                }, onFocusCapture: () => {
+                    if (!loading)
+                        setInterrupted(true);
+                }, style: { position: "relative", width: "fit-content", height: "fit-content" }, children: [_jsx("div", { "data-kind-ui": "sankey-content", "data-loading": loading || undefined, "aria-busy": loading, "aria-hidden": loading || undefined, inert: loading || undefined, style: { display: "contents" }, children: _jsxs(EngineSankey, { ...props, ...(nodeConfig
+                                ? {
+                                    node: props.node ?? configuredNode,
+                                    link: props.link ?? configuredLink,
+                                }
+                                : {}), onClick: (item, type, event) => {
+                                props.onClick?.(item, type, event);
+                                if (interactionBinding && type === "node")
+                                    interaction?.activate({ kind: "node", key: item.payload.id }, "mark", event);
+                            }, ...(interactionBinding
+                                ? {
+                                    node: props.node ??
+                                        ((shape) => (_jsx(SankeyFocusMark, { nodeKey: shape.payload.id, adjacent: adjacent, children: _jsx(SankeyNode, { ...shape }) }))),
+                                    link: props.link ??
+                                        ((shape) => (_jsx(SankeyFocusMark, { endpoints: [
+                                                shape.payload.source.id,
+                                                shape.payload.target.id,
+                                            ], adjacent: adjacent, children: _jsx(SankeyLink, { ...shape }) }))),
+                                }
+                                : {}), data: drawable && links.length ? { nodes, links } : { nodes: [], links: [] }, children: [_jsx(NativeSize, { onSize: onSize }), props.children] }) }), loading && (_jsx(LoadingSkeletonSurface, { family: "sankey", design: (seed) => _jsx(StandaloneLoadingDesign, { family: "sankey", seed: seed }), width: "100%", height: "100%", seed: loadingSeed, animation: { revealDurationMs: duration } })), _jsx(LoadingStatus, { loading: loading, label: loadingLabel }), !loading && !links.length ? (_jsx("div", { role: "status", style: { position: "absolute", inset: 0 }, children: empty })) : !loading && !drawable ? (_jsx("div", { role: "status", style: { position: "absolute", inset: 0 }, children: "Insufficient space for flows; use the data table" })) : null] }) }) }));
 }

package/dist/sankey-colors.d.ts

@@ -1,10 +1,13 @@
+import { type ReactNode } from "react";
 /** Sankey IDs are arbitrary nonempty strings, independent from Root CSS variable keys. */
 export type SankeyNodeConfig = Readonly<Record<string, {
     label: string;
     color: string;
+    icon?: ReactNode;
 }>>;
 export declare const SankeyColors: import("react").Context<Readonly<Record<string, {
     label: string;
     color: string;
+    icon?: ReactNode;
 }>> | undefined>;
 export declare function sankeyColor(config: SankeyNodeConfig | undefined, id: string): string | undefined;

package/dist/sankey-finish.d.ts

@@ -1,4 +1,4 @@
-export type SankeyFinish = "plain" | "paper" | "clay" | "glow";
+export type SankeyFinish = "plain" | "clay" | "glow";
 /** Sankey-local surface treatment. Never displace the quantitative silhouette. */
 export declare function SankeyFinishFilter({ id, finish, thickness, bounds, }: {
     id: string;

package/dist/sankey-finish.js

@@ -6,5 +6,5 @@ export function SankeyFinishFilter({ id, finish, thickness, bounds, }) {
     const relief = Math.min(4, thickness / 4);
     // A 0.6px blur disappeared in Chromium probes; retain a measured thin-flow halo.
     const halo = Math.min(1, Math.max(0.85, thickness / 4));
-    return (_jsxs("filter", { id: id, filterUnits: "userSpaceOnUse", primitiveUnits: "userSpaceOnUse", ...bounds, colorInterpolationFilters: "sRGB", children: [_jsx("feComponentTransfer", { in: "SourceAlpha", result: "footprint", children: _jsx("feFuncA", { type: "linear", slope: 100000 }) }), finish === "clay" ? (_jsxs(_Fragment, { children: [_jsx("feOffset", { in: "footprint", dx: relief, dy: relief, result: "lower" }), _jsx("feComposite", { in: "footprint", in2: "lower", operator: "arithmetic", k2: 1, k3: -1, result: "top" }), _jsx("feGaussianBlur", { in: "top", stdDeviation: relief * 0.8, result: "softTop" }), _jsx("feFlood", { floodColor: "#fff", floodOpacity: 0.48 }), _jsx("feComposite", { in2: "softTop", operator: "in", result: "light" }), _jsx("feOffset", { in: "footprint", dx: -relief, dy: -relief, result: "upper" }), _jsx("feComposite", { in: "footprint", in2: "upper", operator: "arithmetic", k2: 1, k3: -1, result: "bottom" }), _jsx("feGaussianBlur", { in: "bottom", stdDeviation: relief * 0.8, result: "softBottom" }), _jsx("feFlood", { floodColor: "#17212b", floodOpacity: 0.26 }), _jsx("feComposite", { in2: "softBottom", operator: "in", result: "shade" }), _jsx("feComposite", { in: "shade", in2: "SourceGraphic", operator: "atop", result: "shaded" }), _jsx("feComposite", { in: "light", in2: "shaded", operator: "atop", result: "body" })] })) : (_jsxs(_Fragment, { children: [_jsx("feMorphology", { in: "footprint", operator: "erode", radius: edge, result: "inside" }), _jsx("feComposite", { in: "footprint", in2: "inside", operator: "out", result: "edge" }), finish === "paper" ? (_jsxs(_Fragment, { children: [_jsx("feTurbulence", { type: "fractalNoise", baseFrequency: "0.08 0.2", numOctaves: 1, seed: 11, result: "pencil" }), _jsx("feColorMatrix", { in: "pencil", type: "luminanceToAlpha", result: "pencilMask" }), _jsx("feComponentTransfer", { in: "pencilMask", result: "sketch", children: _jsx("feFuncA", { type: "linear", slope: 1.6, intercept: -0.15 }) }), _jsx("feComposite", { in: "edge", in2: "sketch", operator: "in", result: "sketchEdge" }), _jsx("feFlood", { floodColor: "#17212b", floodOpacity: 0.5 }), _jsx("feComposite", { in2: "sketchEdge", operator: "in", result: "contour" }), _jsx("feComposite", { in: "contour", in2: "SourceGraphic", operator: "atop", result: "body" })] })) : (_jsxs(_Fragment, { children: [_jsx("feGaussianBlur", { in: "edge", stdDeviation: edge, result: "softEdge" }), _jsx("feFlood", { floodColor: "#fff", floodOpacity: 0.8 }), _jsx("feComposite", { in2: "softEdge", operator: "in", result: "light" }), _jsx("feComposite", { in: "light", in2: "SourceGraphic", operator: "atop", result: "body" })] }))] })), finish !== "glow" ? (_jsxs(_Fragment, { children: [_jsx("feTurbulence", { type: "fractalNoise", baseFrequency: "0.65 0.3", numOctaves: 1, seed: 7, result: "fiber" }), _jsx("feFlood", { floodColor: "#fff", floodOpacity: finish === "paper" ? 0.14 : 0.025 }), _jsx("feComposite", { in2: "fiber", operator: "in", result: "grain" }), _jsx("feComposite", { in: "grain", in2: "body", operator: "atop" })] })) : (_jsxs(_Fragment, { children: [_jsx("feGaussianBlur", { in: "SourceAlpha", stdDeviation: halo, result: "blur" }), _jsx("feComposite", { in: "blur", in2: "footprint", operator: "out", result: "exterior" }), _jsx("feFlood", { floodColor: "#fff", floodOpacity: 0.12 }), _jsx("feComposite", { in2: "exterior", operator: "in", result: "halo" }), _jsxs("feMerge", { children: [_jsx("feMergeNode", { in: "halo" }), _jsx("feMergeNode", { in: "body" })] })] }))] }));
+    return (_jsxs("filter", { id: id, filterUnits: "userSpaceOnUse", primitiveUnits: "userSpaceOnUse", ...bounds, colorInterpolationFilters: "sRGB", children: [_jsx("feComponentTransfer", { in: "SourceAlpha", result: "footprint", children: _jsx("feFuncA", { type: "linear", slope: 100000 }) }), finish === "clay" ? (_jsxs(_Fragment, { children: [_jsx("feOffset", { in: "footprint", dx: relief, dy: relief, result: "lower" }), _jsx("feComposite", { in: "footprint", in2: "lower", operator: "arithmetic", k2: 1, k3: -1, result: "top" }), _jsx("feGaussianBlur", { in: "top", stdDeviation: relief * 0.8, result: "softTop" }), _jsx("feFlood", { floodColor: "#fff", floodOpacity: 0.48 }), _jsx("feComposite", { in2: "softTop", operator: "in", result: "light" }), _jsx("feOffset", { in: "footprint", dx: -relief, dy: -relief, result: "upper" }), _jsx("feComposite", { in: "footprint", in2: "upper", operator: "arithmetic", k2: 1, k3: -1, result: "bottom" }), _jsx("feGaussianBlur", { in: "bottom", stdDeviation: relief * 0.8, result: "softBottom" }), _jsx("feFlood", { floodColor: "#17212b", floodOpacity: 0.26 }), _jsx("feComposite", { in2: "softBottom", operator: "in", result: "shade" }), _jsx("feComposite", { in: "shade", in2: "SourceGraphic", operator: "atop", result: "shaded" }), _jsx("feComposite", { in: "light", in2: "shaded", operator: "atop", result: "body" })] })) : (_jsxs(_Fragment, { children: [_jsx("feMorphology", { in: "footprint", operator: "erode", radius: edge, result: "inside" }), _jsx("feComposite", { in: "footprint", in2: "inside", operator: "out", result: "edge" }), _jsx("feGaussianBlur", { in: "edge", stdDeviation: edge, result: "softEdge" }), _jsx("feFlood", { floodColor: "#fff", floodOpacity: 0.8 }), _jsx("feComposite", { in2: "softEdge", operator: "in", result: "light" }), _jsx("feComposite", { in: "light", in2: "SourceGraphic", operator: "atop", result: "body" })] })), finish !== "glow" ? (_jsxs(_Fragment, { children: [_jsx("feTurbulence", { type: "fractalNoise", baseFrequency: "0.65 0.3", numOctaves: 1, seed: 7, result: "fiber" }), _jsx("feFlood", { floodColor: "#fff", floodOpacity: 0.025 }), _jsx("feComposite", { in2: "fiber", operator: "in", result: "grain" }), _jsx("feComposite", { in: "grain", in2: "body", operator: "atop" })] })) : (_jsxs(_Fragment, { children: [_jsx("feGaussianBlur", { in: "SourceAlpha", stdDeviation: halo, result: "blur" }), _jsx("feComposite", { in: "blur", in2: "footprint", operator: "out", result: "exterior" }), _jsx("feFlood", { floodColor: "#fff", floodOpacity: 0.12 }), _jsx("feComposite", { in2: "exterior", operator: "in", result: "halo" }), _jsxs("feMerge", { children: [_jsx("feMergeNode", { in: "halo" }), _jsx("feMergeNode", { in: "body" })] })] }))] }));
 }

package/dist/sankey-interaction.d.ts

@@ -0,0 +1,8 @@
+import type { ReactNode } from "react";
+/** Node-only focus includes incident links and endpoint nodes; no flow filtering. */
+export declare function SankeyFocusMark({ nodeKey, endpoints, adjacent, children, }: {
+    nodeKey?: string;
+    endpoints?: readonly string[];
+    adjacent: ReadonlyMap<string, ReadonlySet<string>>;
+    children: ReactNode;
+}): import("react").JSX.Element;

package/dist/sankey-interaction.js

@@ -0,0 +1,32 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useChartInteraction } from "./chart-interaction.js";
+import { useEmphasis } from "./emphasis.js";
+/** Node-only focus includes incident links and endpoint nodes; no flow filtering. */
+export function SankeyFocusMark({ nodeKey, endpoints, adjacent, children, }) {
+    const interaction = useChartInteraction();
+    const key = nodeKey ?? endpoints?.[0] ?? "";
+    const emphasis = useEmphasis({ kind: "series", key, scope: "sankey", seriesKey: key });
+    const inspected = emphasis.active?.kind === "series" ? emphasis.active.key : null;
+    const focus = inspected ?? interaction.selected;
+    const related = focus === null ||
+        (nodeKey !== undefined
+            ? nodeKey === focus || adjacent.get(focus)?.has(nodeKey)
+            : endpoints?.includes(focus));
+    const interactive = nodeKey !== undefined && interaction.markActivation && interaction.eligible.includes(nodeKey);
+    return (
+    // biome-ignore lint/a11y/noStaticElementInteractions lint/a11y/useAriaPropsSupportedByRole: Role, pressed state and handlers are enabled together for opted-in SVG controls.
+    _jsx("g", { "data-kind-ui": "sankey-focus-mark", "data-node": nodeKey, role: interactive ? "button" : undefined, tabIndex: interactive ? 0 : undefined, "aria-label": interactive ? `Highlight ${nodeKey}` : undefined, "aria-pressed": interactive ? interaction.selected === nodeKey : undefined, onPointerEnter: (event) => {
+            if (event.pointerType !== "touch")
+                emphasis.enter("pointer");
+        }, onPointerLeave: () => emphasis.leave("pointer"), onPointerCancel: () => emphasis.leave("pointer"), onFocus: () => emphasis.enter("keyboard"), onBlur: () => emphasis.leave("keyboard"), onKeyDown: (event) => {
+            if (interactive &&
+                event.target === event.currentTarget &&
+                !event.defaultPrevented &&
+                (event.key === "Enter" || event.key === " ")) {
+                if (!event.repeat)
+                    interaction.activate({ kind: "node", key: nodeKey }, "mark", event);
+                event.preventDefault();
+            }
+        }, children: _jsx("g", { style: { opacity: related ? 1 : 0.28 }, children: children }) }));
+}

package/dist/sankey-legend.d.ts

@@ -3,6 +3,7 @@ import type { SankeyNodeConfig } from "./sankey-colors.js";
 export type SankeyLegendProps = Omit<ComponentPropsWithRef<"ul">, "children"> & {
     /** Share this explicit reference with SankeyChart.nodeConfig. Config order owns legend order. */
     config: SankeyNodeConfig;
+    interactionBinding?: "root";
     children?: (item: {
         key: string;
         label: string;
@@ -11,4 +12,4 @@ export type SankeyLegendProps = Omit<ComponentPropsWithRef<"ul">, "children"> &
     }) => ReactNode;
 };
 /** Node identity legend; solid links inherit source color, gradient links use both endpoints. */
-export declare function SankeyLegend({ config, children, ...props }: SankeyLegendProps): import("react").JSX.Element;
+export declare function SankeyLegend({ config, interactionBinding, children, ...props }: SankeyLegendProps): import("react").JSX.Element;