@kind-ui/charts 0.1.0 → 0.2.0

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

package/dist/sankey-legend.js

@@ -1,9 +1,24 @@
 "use client";
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { useOptionalChartInteraction } from "./chart-interaction.js";
 /** Node identity legend; solid links inherit source color, gradient links use both endpoints. */
-export function SankeyLegend({ config, children, ...props }) {
-    return (_jsx("ul", { "aria-label": "Chart legend", ...props, "data-kind-ui": "chart-legend", children: Object.entries(config).map(([key, item]) => {
+export function SankeyLegend({ config, interactionBinding, children, ...props }) {
+    const interaction = useOptionalChartInteraction();
+    if (interactionBinding &&
+        (!interaction || interaction.kind !== "node" || interaction.mode !== "focus"))
+        throw new Error("SankeyLegend Root interaction binding requires node focus");
+    return (
+    // biome-ignore lint/a11y/useKeyWithClickEvents: Delegates clicks from native buttons, which already implement Enter and Space.
+    _jsx("ul", { "aria-label": "Chart legend", ...props, "data-kind-ui": "chart-legend", onClick: (event) => {
+            props.onClick?.(event);
+            const button = event.target.closest("button[data-node-key]");
+            if (interactionBinding &&
+                button?.dataset.nodeKey !== undefined &&
+                event.currentTarget.contains(button))
+                interaction?.activate({ kind: "node", key: button.dataset.nodeKey }, "legend", event);
+        }, children: Object.entries(config).map(([key, item]) => {
             const marker = (_jsx("span", { "aria-hidden": "true", "data-kind-ui": "chart-indicator", style: { "--kind-ui-chart-indicator-color": item.color } }));
-            return (_jsx("li", { "data-kind-ui": "chart-legend-item", "data-node": key, children: _jsx("span", { children: children ? (children({ key, label: item.label, color: item.color, marker })) : (_jsxs(_Fragment, { children: [marker, item.label] })) }) }, key));
+            const content = children ? (children({ key, label: item.label, color: item.color, marker })) : (_jsxs(_Fragment, { children: [marker, item.label] }));
+            return (_jsx("li", { "data-kind-ui": "chart-legend-item", "data-node": key, children: interactionBinding && interaction?.eligible.includes(key) ? (_jsx("button", { type: "button", "aria-pressed": interaction.selected === key, "data-node-key": key, children: content })) : (_jsx("span", { children: content })) }, key));
         }) }));
 }

package/dist/sankey-node-label.d.ts

@@ -0,0 +1,22 @@
+import { type ComponentPropsWithRef } from "react";
+import type { SankeyNodeConfig } from "./sankey-colors.js";
+import { type SankeyFlowData } from "./sankey-data.js";
+import type { SankeyNodeProps } from "./sankey-marks.js";
+export type SankeyNodeLabelProps = Omit<ComponentPropsWithRef<"text">, "position"> & {
+    /** Geometry from the native node callback; identity comes from payload.id, never index. */
+    node: Pick<SankeyNodeProps, "x" | "y" | "width" | "height" | "payload">;
+    data: SankeyFlowData;
+    /** Explicit metadata; icons are looked up by payload.id. Labels still use data names. */
+    nodeConfig?: SankeyNodeConfig;
+    /** Square SVG viewport size and gap in chart units; inside icons share the node clip. */
+    iconSize?: number;
+    iconGap?: number;
+    position?: "inside" | "outside";
+    /** Outside defaults to left for sinks and right otherwise. Reserve chart margins for text. */
+    side?: "left" | "right";
+    showValues?: boolean;
+    valueFormatter?: (value: number) => string;
+    offset?: number;
+};
+/** Explicit sibling of SankeyNode; preserves native renderer and consumer text ownership. */
+export declare function SankeyNodeLabel({ node, data, nodeConfig, iconSize, iconGap, position, side, showValues, valueFormatter, offset, children, ...textProps }: SankeyNodeLabelProps): import("react").JSX.Element;

package/dist/sankey-node-label.js

@@ -0,0 +1,34 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useId } from "react";
+import { prepareSankeyData } from "./sankey-data.js";
+/** Explicit sibling of SankeyNode; preserves native renderer and consumer text ownership. */
+export function SankeyNodeLabel({ node, data, nodeConfig, iconSize = 16, iconGap = 4, position = "outside", side, showValues = false, valueFormatter = String, offset = 8, children, ...textProps }) {
+    const clipId = `sankey-label-${useId().replace(/:/g, "")}`;
+    const validated = prepareSankeyData(data);
+    const index = validated.nodes.findIndex((item) => item.id === node.payload.id);
+    const item = validated.nodes[index];
+    if (!item)
+        throw new Error(`SankeyNodeLabel requires node id "${node.payload.id}" in data`);
+    if (![node.x, node.y, node.width, node.height, offset, iconSize, iconGap].every(Number.isFinite) ||
+        node.width < 0 ||
+        node.height < 0 ||
+        offset < 0 ||
+        iconSize < 0 ||
+        iconGap < 0)
+        throw new Error("SankeyNodeLabel requires finite geometry and nonnegative dimensions/offset/icon size/gap");
+    const incoming = validated.links.reduce((sum, link) => sum + (link.target === index ? link.value : 0), 0);
+    const outgoing = validated.links.reduce((sum, link) => sum + (link.source === index ? link.value : 0), 0);
+    const value = Math.max(incoming, outgoing);
+    const label = showValues ? `${item.name}: ${valueFormatter(value)}` : item.name;
+    const left = (side ?? (validated.links.some((link) => link.source === index) ? "right" : "left")) === "left";
+    const inside = position === "inside";
+    const icon = nodeConfig && Object.hasOwn(nodeConfig, item.id) ? nodeConfig[item.id]?.icon : undefined;
+    const hasIcon = icon !== undefined && icon !== null && typeof icon !== "boolean" && iconSize > 0;
+    const iconSpace = hasIcon ? iconSize + iconGap : 0;
+    const edge = left ? node.x - offset : node.x + node.width + offset;
+    // Inside uses a centered icon above centered text; outside puts the icon nearest the node.
+    const iconX = inside ? node.x + (node.width - iconSize) / 2 : left ? edge - iconSize : edge;
+    const centerY = node.y + node.height / 2;
+    return (_jsxs("g", { "data-kind-ui": "sankey-node-label", "data-node-id": item.id, children: [_jsx("title", { children: label }), inside && (_jsx("defs", { children: _jsx("clipPath", { id: clipId, children: _jsx("rect", { x: node.x, y: node.y, width: node.width, height: node.height }) }) })), _jsxs("g", { clipPath: inside ? `url(#${clipId})` : undefined, children: [hasIcon && (_jsx("svg", { "data-kind-ui": "sankey-node-icon", x: iconX, y: inside ? centerY - iconSize - iconGap / 2 : centerY - iconSize / 2, width: iconSize, height: iconSize, viewBox: "0 0 24 24", "aria-hidden": "true", focusable: "false", pointerEvents: "none", overflow: "hidden", children: icon })), _jsx("text", { x: inside ? node.x + node.width / 2 : left ? edge - iconSpace : edge + iconSpace, y: inside && hasIcon ? centerY + iconGap / 2 + 6 : centerY, textAnchor: inside ? "middle" : left ? "end" : "start", dominantBaseline: "middle", pointerEvents: "none", fontSize: 12, ...textProps, children: children === undefined ? label : children })] })] }));
+}

package/dist/scatter-chart.d.ts

@@ -1,10 +1,12 @@
 import { type MotionValue } from "motion/react";
 import { type ComponentProps } from "react";
 import { ScatterChart as EngineScatterChart } from "recharts";
-import { type LineAnimation } from "./animation.js";
-export type ScatterAnimation = LineAnimation;
+import { type BaseAnimation } from "./animation.js";
+export type ScatterAnimation = BaseAnimation;
 export type ScatterChartProps = ComponentProps<typeof EngineScatterChart> & {
     animate?: boolean | ScatterAnimation | undefined;
+    loading?: boolean | undefined;
+    loadingLabel?: string | undefined;
 };
 export declare const ScatterMotion: import("react").Context<{
     reveal: boolean;
@@ -13,4 +15,4 @@ export declare const ScatterMotion: import("react").Context<{
     progress: MotionValue<number> | null;
 }>;
 /** Native numeric geometry and item selection, with optional entrance fade and shared tooltip Motion. */
-export declare function ScatterChart({ animate, children, ...props }: ScatterChartProps): import("react").JSX.Element;
+export declare function ScatterChart({ animate, loading, loadingLabel, children, ...props }: ScatterChartProps): import("react").JSX.Element;

package/dist/scatter-chart.js

@@ -5,6 +5,7 @@ import { createContext, useCallback, useLayoutEffect, useRef, useState, useSyncE
 import { ScatterChart as EngineScatterChart } from "recharts";
 import { MotionContext } from "./animation.js";
 import { LineChartFrame } from "./line-chart.js";
+import { CartesianLoadingDesign } from "./loading-cartesian-designs.js";
 export const ScatterMotion = createContext({
     reveal: false,
     options: {},
@@ -21,11 +22,20 @@ const snapshot = () => window.matchMedia(query).matches;
 const serverSnapshot = () => true;
 const defaultHover = { type: "spring", stiffness: 210, damping: 28, mass: 0.8 };
 /** Native numeric geometry and item selection, with optional entrance fade and shared tooltip Motion. */
-export function ScatterChart({ animate = false, children, ...props }) {
+export function ScatterChart({ animate = false, loading, loadingLabel, children, ...props }) {
     const reduced = useSyncExternalStore(subscribe, snapshot, serverSnapshot);
     const [interacted, setInteracted] = useState(false);
-    const enabled = animate !== false && !reduced;
-    const interact = useCallback(() => setInteracted(true), []);
+    const enabled = animate !== false && !reduced && !loading;
+    const interact = useCallback(() => {
+        if (!loading)
+            setInteracted(true);
+    }, [loading]);
+    useLayoutEffect(() => {
+        if (loading) {
+            setInteracted(false);
+            started.current = false;
+        }
+    }, [loading]);
     const finish = useCallback(() => {
         if (enabled)
             setInteracted(true);
@@ -60,5 +70,5 @@ export function ScatterChart({ animate = false, children, ...props }) {
         });
         return () => controls.stop();
     }, [reveal, duration, easing, progress, interact]);
-    return (_jsx(MotionContext, { value: { enabled, transition: options.hoverTransition ?? defaultHover }, children: _jsx(ScatterMotion, { value: { reveal, options, finish, progress }, children: _jsx("div", { style: { display: "contents" }, onFocusCapture: interact, onPointerDownCapture: interact, onPointerMoveCapture: interact, onKeyDownCapture: interact, children: _jsx(LineChartFrame, { chartProps: props, engine: EngineScatterChart, motionEnabled: enabled, interrupt: finish, children: children }) }) }) }));
+    return (_jsx(MotionContext, { value: { enabled, transition: options.hoverTransition ?? defaultHover }, children: _jsx(ScatterMotion, { value: { reveal, options, finish, progress }, children: _jsx("div", { style: { display: "contents" }, onFocusCapture: interact, onPointerDownCapture: interact, onPointerMoveCapture: interact, onKeyDownCapture: interact, children: _jsx(LineChartFrame, { loading: loading, loadingLabel: loadingLabel, loadingSkeleton: "scatter", loadingDesign: (seed) => _jsx(CartesianLoadingDesign, { family: "scatter", seed: seed }), loadingAnimation: options, chartProps: props, engine: EngineScatterChart, motionEnabled: enabled, interrupt: finish, children: children }) }) }) }));
 }

package/dist/scatter-series.js

@@ -7,6 +7,7 @@ import { useChart } from "./chart-context.js";
 import { useLineInteraction } from "./line-chart.js";
 import { ScatterMotion } from "./scatter-chart.js";
 import { ScatterMaterialSymbol } from "./scatter-material.js";
+import { SeriesInteractionLayer, useSeriesInteraction } from "./series-interaction.js";
 // Delay by native screen X, rather than sorting or changing quantitative data.
 function EntranceSymbol({ material, type, ...props }) {
     const { progress } = use(ScatterMotion);
@@ -20,7 +21,7 @@ function EntranceSymbol({ material, type, ...props }) {
 }
 /** Native Scatter owns marks, Cells, labels, handlers, axis mapping and point payloads. */
 export function ScatterSeries({ seriesKey, hide, fill, material = "plain", ...props }) {
-    const { config, visibleSeries } = useChart();
+    const { config, paints, visibleSeries } = useChart();
     const { registerSeries, invalidate } = useLineInteraction();
     const shapes = useMemo(() => {
         function finish(option) {
@@ -69,6 +70,7 @@ export function ScatterSeries({ seriesKey, hide, fill, material = "plain", ...pr
     }, [id, key, registerSeries]);
     if (key === undefined && visibleSeries !== undefined)
         throw new Error("ScatterSeries requires seriesKey for controlled non-string dataKey");
-    const color = fill ?? (key && Object.hasOwn(config, key) ? `var(--color-${key})` : undefined);
-    return (_jsx(ZIndexLayer, { zIndex: props.zIndex ?? DefaultZIndexes.scatter, children: _jsx("g", { "data-kind-ui": "scatter-fade", children: _jsx(Scatter, { ...props, ...(shapes.shape !== undefined ? { shape: shapes.shape } : {}), ...(shapes.activeShape !== undefined ? { activeShape: shapes.activeShape } : {}), id: id, hide: hidden, ...(color !== undefined ? { fill: color } : {}), zIndex: 0, isAnimationActive: false }) }) }));
+    const interaction = useSeriesInteraction(key, hidden, hide === true, props.data, props.onClick);
+    const color = fill ?? (key && Object.hasOwn(config, key) ? paints[key] : undefined);
+    return (_jsx(ZIndexLayer, { zIndex: props.zIndex ?? DefaultZIndexes.scatter, children: _jsx(SeriesInteractionLayer, { seriesKey: key, hidden: hidden, children: _jsx("g", { "data-kind-ui": "scatter-fade", children: _jsx(Scatter, { ...props, ...(interaction.onClick !== undefined ? { onClick: interaction.onClick } : {}), ...(shapes.shape !== undefined ? { shape: shapes.shape } : {}), ...(shapes.activeShape !== undefined ? { activeShape: shapes.activeShape } : {}), id: id, hide: hidden, ...(color !== undefined ? { fill: color } : {}), zIndex: 0, isAnimationActive: false }) }) }) }));
 }

package/dist/series-color.d.ts

@@ -0,0 +1,10 @@
+import type { SeriesColor } from "./types.js";
+export type ColorStops = {
+    offsets: number[];
+    colors: string[];
+};
+/** Preserve each theme's evenly spaced stops, even with unequal stop counts. */
+export declare function resolveSeriesColor(color: SeriesColor, key: string): ColorStops;
+export declare function colorResourceId(id: string, key: string): string;
+/** Disjoint from legacy --color-<key>, whose valid keys include numeric suffixes. */
+export declare function colorStopToken(key: string, index: number | "gradient"): string;

package/dist/series-color.js

@@ -0,0 +1,48 @@
+function stops(value, path) {
+    const values = typeof value === "string" ? [value] : value;
+    if (!Array.isArray(values) || values.length === 0)
+        throw new Error(`Series color ${path} requires a nonempty string or nonempty array of color strings`);
+    for (let index = 0; index < values.length; index++) {
+        if (typeof values[index] !== "string" || values[index].trim() === "")
+            throw new Error(`Series color ${path}${Array.isArray(value) ? `[${index}]` : ""} requires a nonempty color string`);
+    }
+    return values;
+}
+function at(colors, offset) {
+    if (colors.length === 1)
+        return colors[0];
+    const position = offset * (colors.length - 1);
+    const index = Math.floor(position);
+    const fraction = position - index;
+    if (fraction < 1e-10)
+        return colors[index];
+    return `color-mix(in srgb, ${colors[index]} ${(1 - fraction) * 100}%, ${colors[index + 1]} ${fraction * 100}%)`;
+}
+/** Preserve each theme's evenly spaced stops, even with unequal stop counts. */
+export function resolveSeriesColor(color, key) {
+    const path = `config[${JSON.stringify(key)}].color`;
+    const themed = color !== null && typeof color === "object" && !Array.isArray(color);
+    if (themed &&
+        (!Object.hasOwn(color, "light") ||
+            !Object.hasOwn(color, "dark") ||
+            Object.keys(color).some((key) => key !== "light" && key !== "dark")))
+        throw new Error(`Series color ${path} requires both light and dark definitions and no other fields`);
+    const variants = color;
+    const light = stops(themed ? variants.light : color, themed ? `${path}.light` : path);
+    const dark = stops(themed ? variants.dark : color, themed ? `${path}.dark` : path);
+    const offsets = [
+        ...new Set([light, dark].flatMap((values) => values.length === 1 ? [0] : values.map((_, index) => index / (values.length - 1)))),
+    ].sort((a, b) => a - b);
+    return {
+        offsets,
+        colors: offsets.map((offset) => themed ? `light-dark(${at(light, offset)}, ${at(dark, offset)})` : at(light, offset)),
+    };
+}
+export function colorResourceId(id, key) {
+    return `kind-ui-color-${Array.from(`${id}:${key}`, (char) => char.codePointAt(0)?.toString(16)).join("-")}`;
+}
+/** Disjoint from legacy --color-<key>, whose valid keys include numeric suffixes. */
+export function colorStopToken(key, index) {
+    const encoded = Array.from(key, (char) => char.codePointAt(0)?.toString(16)).join("-");
+    return `--kind-ui-series-${encoded}-${index}`;
+}

package/dist/series-interaction.d.ts

@@ -0,0 +1,12 @@
+import { type KeyboardEventHandler, type ReactNode } from "react";
+/** Native handlers retain their original data/index/event tuple and run first. */
+export declare function useSeriesInteraction<Args extends unknown[]>(key: string | undefined, hidden: boolean, nativeHidden: boolean | undefined, seriesData: readonly unknown[] | undefined, handler: ((...args: Args) => void) | undefined): {
+    onClick: ((...args: Args) => void) | undefined;
+};
+/** One keyboard target per logical series, within its native ZIndex portal. */
+export declare function SeriesInteractionLayer({ seriesKey, hidden, children, onKeyDown, }: {
+    seriesKey: string | undefined;
+    hidden: boolean;
+    onKeyDown?: KeyboardEventHandler<SVGElement> | undefined;
+    children: ReactNode;
+}): import("react").JSX.Element;

package/dist/series-interaction.js

@@ -0,0 +1,82 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useCallback, useLayoutEffect, useRef, } from "react";
+import { useChart } from "./chart-context.js";
+import { useChartInteraction, useInteractionAvailability, useInteractionRegistration, } from "./chart-interaction.js";
+import { useEmphasis } from "./emphasis.js";
+import { useChartKeyboard, useLineInteraction } from "./line-chart.js";
+/** Native handlers retain their original data/index/event tuple and run first. */
+export function useSeriesInteraction(key, hidden, nativeHidden = false, seriesData, handler) {
+    const interaction = useChartInteraction();
+    const { data } = useLineInteraction();
+    const { visibleSeries } = useChart();
+    const rootHidden = key !== undefined && visibleSeries !== undefined && !visibleSeries.includes(key);
+    // Some consumers mirror Root visibility into native hide. Their hidden IDs stay restorable.
+    useInteractionAvailability(interaction.kind === "series" ? key : undefined, nativeHidden && !rootHidden);
+    useInteractionRegistration(interaction.kind === "series" && key !== undefined && (seriesData ?? data)?.length ? [key] : []);
+    const interactive = key !== undefined &&
+        !hidden &&
+        interaction.kind === "series" &&
+        interaction.interactive &&
+        interaction.markActivation &&
+        interaction.eligible.includes(key);
+    const latest = useRef({ handler, interaction, interactive, key });
+    useLayoutEffect(() => {
+        latest.current = { handler, interaction, interactive, key };
+    });
+    const onClick = useCallback((...args) => {
+        latest.current.handler?.(...args);
+        const current = latest.current;
+        const event = args[args.length - 1];
+        if (current.interactive && current.key !== undefined && event?.button === 0)
+            current.interaction.activate({ kind: "series", key: current.key }, "mark", event);
+    }, []);
+    // Native animation IDs include handler identity even when native animation is disabled.
+    return { onClick: interactive ? onClick : handler };
+}
+/** One keyboard target per logical series, within its native ZIndex portal. */
+export function SeriesInteractionLayer({ seriesKey, hidden, children, onKeyDown, }) {
+    const interaction = useChartInteraction();
+    const { config } = useChart();
+    const enabled = seriesKey !== undefined && !hidden && interaction.kind === "series" && interaction.configured;
+    const emphasis = useEmphasis({ kind: "series", key: seriesKey ?? "", scope: "series", seriesKey }, enabled);
+    const keyboard = useChartKeyboard();
+    const interactive = enabled &&
+        interaction.interactive &&
+        interaction.markActivation &&
+        interaction.eligible.includes(seriesKey);
+    // Native axis inspection includes all series at this category, so keep their paint readable.
+    const nativeInspection = keyboard &&
+        typeof document !== "undefined" &&
+        document.activeElement?.getAttribute("role") === "application";
+    const factor = nativeInspection && emphasis.active === null ? 1 : emphasis.factor;
+    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": "series-interaction", "data-series": seriesKey, role: interactive ? "button" : undefined, tabIndex: interactive ? 0 : undefined, "aria-label": interactive
+            ? `${interaction.mode === "focus" ? "Highlight" : "Toggle"} ${config[seriesKey]?.label ?? seriesKey}`
+            : undefined, "aria-pressed": interactive
+            ? interaction.mode === "focus"
+                ? interaction.selected === seriesKey
+                : (interaction.visible?.includes(seriesKey) ?? true)
+            : undefined, onPointerEnter: (event) => {
+            if (event.pointerType !== "touch")
+                emphasis.enter("pointer");
+        }, onPointerMove: (event) => {
+            if (event.pointerType !== "touch")
+                emphasis.enter("pointer");
+        }, onPointerLeave: () => emphasis.leave("pointer"), onPointerCancel: () => emphasis.leave("pointer"), onFocus: (event) => {
+            if (event.target.matches(":focus-visible"))
+                emphasis.enter("keyboard");
+        }, onBlur: () => emphasis.leave("keyboard"), onKeyDown: (event) => {
+            if (event.target === event.currentTarget)
+                onKeyDown?.(event);
+            if (interactive &&
+                event.target === event.currentTarget &&
+                !event.defaultPrevented &&
+                (event.key === "Enter" || event.key === " ")) {
+                if (!event.repeat)
+                    interaction.activate({ kind: "series", key: seriesKey }, "mark", event);
+                event.preventDefault();
+            }
+        }, children: _jsx("g", { "data-kind-ui": "series-interaction-paint", style: { opacity: factor }, children: children }) }));
+}

package/dist/series-label.d.ts

@@ -0,0 +1,7 @@
+import type { SeriesConfig } from "./types.js";
+/** Presentation only: never rewrite metadata identity, paint or consumer data. */
+export declare function resolveSeriesLabel(key: string, label?: string): string;
+export type ResolvedSeriesConfig = Readonly<Record<string, SeriesConfig[string] & {
+    label: string;
+}>>;
+export declare function resolveSeriesConfig(config: SeriesConfig): ResolvedSeriesConfig;

package/dist/series-label.js

@@ -0,0 +1,18 @@
+/** Presentation only: never rewrite metadata identity, paint or consumer data. */
+export function resolveSeriesLabel(key, label) {
+    if (label !== undefined)
+        return label;
+    const words = key
+        .replace(/([A-Z])([A-Z][a-z])/g, "$1 $2")
+        .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+        .replace(/[_-]+/g, " ")
+        .trim()
+        .toLowerCase();
+    return words.charAt(0).toUpperCase() + words.slice(1);
+}
+export function resolveSeriesConfig(config) {
+    return Object.fromEntries(Object.entries(config).map(([key, item]) => [
+        key,
+        { ...item, label: resolveSeriesLabel(key, item.label) },
+    ]));
+}

package/dist/series-paint.d.ts

@@ -0,0 +1,8 @@
+import { type ReactNode } from "react";
+/** Each native SVG owns its viewport-relative resources; metadata stays Root-owned. */
+export declare function SeriesPaintBoundary({ children }: {
+    children: ReactNode;
+}): string | number | bigint | boolean | import("react").JSX.Element | Iterable<ReactNode> | Promise<string | number | bigint | boolean | import("react").ReactPortal | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | null | undefined;
+export declare function SeriesColorDefinitions({ viewport }: {
+    viewport?: boolean;
+}): import("react").JSX.Element | null;

package/dist/series-paint.js

@@ -0,0 +1,27 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { use, useId, useMemo } from "react";
+import { ChartContext } from "./chart-context.js";
+import { colorResourceId, colorStopToken } from "./series-color.js";
+/** Each native SVG owns its viewport-relative resources; metadata stays Root-owned. */
+export function SeriesPaintBoundary({ children }) {
+    const chart = use(ChartContext);
+    const colorId = useId();
+    const colorStops = chart?.colorStops;
+    const paints = useMemo(() => Object.fromEntries(Object.entries(colorStops ?? {}).map(([key, stops]) => [
+        key,
+        stops.colors.length > 1
+            ? `url(#${colorResourceId(colorId, key)})`
+            : `var(--color-${key})`,
+    ])), [colorStops, colorId]);
+    const value = useMemo(() => (chart ? { ...chart, colorId, paints } : null), [chart, colorId, paints]);
+    return value ? _jsx(ChartContext, { value: value, children: children }) : children;
+}
+export function SeriesColorDefinitions({ viewport = false }) {
+    const chart = use(ChartContext);
+    if (!chart)
+        return null;
+    return (_jsx("defs", { "data-kind-ui": "series-color-definitions", children: Object.entries(chart.colorStops)
+            .filter(([, stops]) => stops.colors.length > 1)
+            .map(([key, stops]) => (_jsx("linearGradient", { id: colorResourceId(chart.colorId, key), x1: "0", y1: "0", x2: viewport ? "100%" : "1", y2: "0", gradientUnits: viewport ? "userSpaceOnUse" : "objectBoundingBox", children: stops.offsets.map((offset, index) => (_jsx("stop", { offset: offset, stopColor: `var(${colorStopToken(key, index)})` }, offset))) }, key))) }));
+}