@kind-ui/charts 0.1.0

package/dist/sankey-finish.js

@@ -0,0 +1,10 @@
+"use client";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+/** Sankey-local surface treatment. Never displace the quantitative silhouette. */
+export function SankeyFinishFilter({ id, finish, thickness, bounds, }) {
+    const edge = Math.min(1.2, thickness / 6);
+    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" })] })] }))] }));
+}

package/dist/sankey-legend.d.ts

@@ -0,0 +1,14 @@
+import type { ComponentPropsWithRef, ReactNode } from "react";
+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;
+    children?: (item: {
+        key: string;
+        label: string;
+        color: string;
+        marker: ReactNode;
+    }) => 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;

package/dist/sankey-legend.js

@@ -0,0 +1,9 @@
+"use client";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+/** 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]) => {
+            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));
+        }) }));
+}

package/dist/sankey-marks.d.ts

@@ -0,0 +1,31 @@
+import { type SVGProps } from "react";
+import type { SankeyLinkProps as NativeLinkProps, SankeyNodeProps as NativeNodeProps } from "recharts";
+import { type SankeyFinish } from "./sankey-finish.js";
+export type SankeyMaterial = "solid" | "gradient";
+export type SankeyLinkProps = Omit<NativeLinkProps, "payload"> & {
+    payload: NativeLinkProps["payload"] & {
+        id: string;
+        source: NativeNodeProps["payload"] & {
+            id: string;
+        };
+        target: NativeNodeProps["payload"] & {
+            id: string;
+        };
+    };
+    material?: SankeyMaterial;
+    finish?: SankeyFinish;
+    color?: string | undefined;
+    targetColor?: string | undefined;
+    /** Presentation and handlers; computed path and flow width always win. */
+    pathProps?: SVGProps<SVGPathElement>;
+};
+export declare function SankeyLink({ sourceX, sourceY, targetX, targetY, sourceControlX, targetControlX, linkWidth, sourceRelativeY: _sourceRelativeY, targetRelativeY: _targetRelativeY, index: _index, payload, material, finish, color, targetColor, pathProps, ...presentation }: SankeyLinkProps): import("react").JSX.Element;
+export type SankeyNodeProps = Omit<NativeNodeProps, "payload"> & {
+    payload: NativeNodeProps["payload"] & {
+        id: string;
+    };
+    color?: string | undefined;
+    rectProps?: SVGProps<SVGRectElement>;
+    finish?: SankeyFinish;
+};
+export declare function SankeyNode({ x, y, width, height, color, rectProps, finish, index: _index, payload, ...presentation }: SankeyNodeProps): import("react").JSX.Element;

package/dist/sankey-marks.js

@@ -0,0 +1,67 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { motion, useMotionValue, useTransform } from "motion/react";
+import { use, useId, useLayoutEffect, useRef, useState } from "react";
+import { SankeyMotion } from "./sankey-chart.js";
+import { SankeyColors, sankeyColor } from "./sankey-colors.js";
+import { SankeyFinishFilter } from "./sankey-finish.js";
+export function SankeyLink({ sourceX, sourceY, targetX, targetY, sourceControlX, targetControlX, linkWidth, sourceRelativeY: _sourceRelativeY, targetRelativeY: _targetRelativeY, index: _index, payload, material = "solid", finish = "plain", color, targetColor, pathProps, ...presentation }) {
+    const config = use(SankeyColors);
+    color ??= (config ? sankeyColor(config, payload.source.id) : undefined) ?? "#4f46e5";
+    targetColor ??= (config ? sankeyColor(config, payload.target.id) : undefined) ?? "#06b6d4";
+    const id = `sankey-${useId().replace(/:/g, "")}`;
+    const { reveal, progress, width } = use(SankeyMotion);
+    const settled = useMotionValue(1);
+    const delay = Math.max(0, Math.min(1, sourceX / Math.max(1, width))) * 0.55;
+    const dash = useTransform(progress ?? settled, (value) => `${Math.max(0, Math.min(1, (value - delay) / 0.45))} 1`);
+    const native = useRef(null);
+    const [transformed, setTransformed] = useState();
+    // biome-ignore lint/correctness/useExhaustiveDependencies: consumer styles/classes can own transforms.
+    useLayoutEffect(() => {
+        const path = native.current?.querySelector("path:not([data-kind-ui])");
+        if (!path)
+            return;
+        const css = getComputedStyle(path);
+        setTransformed(css.transform !== "none" ||
+            css.translate !== "none" ||
+            css.rotate !== "none" ||
+            css.scale !== "none");
+    }, [pathProps, presentation.className, presentation.style, presentation.transform]);
+    const mask = reveal &&
+        transformed === false &&
+        presentation.transform === undefined &&
+        pathProps?.transform === undefined;
+    const d = `M${sourceX},${sourceY}C${sourceControlX},${sourceY} ${targetControlX},${targetY} ${targetX},${targetY}`;
+    const finished = finish !== "plain" &&
+        presentation.filter == null &&
+        pathProps?.filter == null &&
+        presentation.style?.filter == null &&
+        pathProps?.style?.filter == null;
+    const pad = linkWidth / 2 + 3;
+    const bounds = {
+        x: Math.min(sourceX, targetX, sourceControlX, targetControlX) - pad,
+        y: Math.min(sourceY, targetY) - pad,
+        width: Math.max(sourceX, targetX, sourceControlX, targetControlX) -
+            Math.min(sourceX, targetX, sourceControlX, targetControlX) +
+            pad * 2,
+        height: Math.abs(targetY - sourceY) + pad * 2,
+    };
+    return (_jsxs("g", { ref: native, mask: mask ? `url(#${id}-entrance)` : undefined, children: [mask && (_jsx("defs", { children: _jsx("mask", { id: `${id}-entrance`, maskUnits: "userSpaceOnUse", ...bounds, style: { maskType: "alpha" }, children: _jsx(motion.path, { "data-kind-ui": "sankey-link-entrance", d: d, fill: "none", stroke: "white", strokeWidth: linkWidth + 6, pathLength: 1, strokeDasharray: dash }) }) })), finished && (_jsx("defs", { children: _jsx(SankeyFinishFilter, { id: `${id}-finish`, finish: finish, thickness: linkWidth, bounds: bounds }) })), material === "gradient" && (_jsx("defs", { children: _jsxs("linearGradient", { id: id, gradientUnits: "userSpaceOnUse", x1: sourceX, y1: sourceY, x2: targetX, y2: targetY, children: [_jsx("stop", { stopColor: color }), _jsx("stop", { offset: "1", stopColor: targetColor })] }) })), _jsx("path", { ...presentation, ...pathProps, filter: pathProps?.filter ?? presentation.filter ?? (finished ? `url(#${id}-finish)` : undefined), d: d, fill: "none", stroke: material === "gradient" ? `url(#${id})` : color, strokeWidth: linkWidth, style: { ...presentation.style, ...pathProps?.style, strokeWidth: linkWidth } })] }));
+}
+export function SankeyNode({ x, y, width, height, color, rectProps, finish = "plain", index: _index, payload, ...presentation }) {
+    const config = use(SankeyColors);
+    color ??= (config ? sankeyColor(config, payload.id) : undefined) ?? "#4f46e5";
+    const id = `sankey-node-${useId().replace(/:/g, "")}`;
+    const finished = finish !== "plain" &&
+        presentation.filter == null &&
+        rectProps?.filter == null &&
+        presentation.style?.filter == null &&
+        rectProps?.style?.filter == null;
+    const rect = (_jsx("rect", { ...presentation, ...rectProps, filter: rectProps?.filter ?? presentation.filter ?? (finished ? `url(#${id})` : undefined), x: x, y: y, width: width, height: height, fill: color, style: { ...presentation.style, ...rectProps?.style, width, height } }));
+    if (!finished)
+        return rect;
+    return (_jsxs("g", { children: [_jsx("defs", { children: _jsx(SankeyFinishFilter, { id: id, finish: finish, thickness: Math.min(width, height), 
+                    // Viewport-relative bounds preserve inherited/class-based and em/percent strokes.
+                    // The native SVG viewport still clips output; no DOM measurements or style parsing.
+                    bounds: { x: "-100%", y: "-100%", width: "300%", height: "300%" } }) }), rect] }));
+}

package/dist/sankey-table.d.ts

@@ -0,0 +1,11 @@
+import type { ComponentPropsWithRef } from "react";
+import { type SankeyFlowData, type SankeyFlowLink } from "./sankey-data.js";
+export type SankeyTableProps = Omit<ComponentPropsWithRef<"table">, "children"> & {
+    data: SankeyFlowData;
+    caption: string;
+    formatValue?: (value: number) => string;
+    onInspect?: (link: SankeyFlowLink) => void;
+    activeLinkId?: string | null;
+};
+/** Native table and buttons provide an independent, complete keyboard flow inspector. */
+export declare function SankeyTable({ data, caption, formatValue, onInspect, activeLinkId, ...props }: SankeyTableProps): import("react").JSX.Element;

package/dist/sankey-table.js

@@ -0,0 +1,8 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { prepareSankeyData } from "./sankey-data.js";
+/** Native table and buttons provide an independent, complete keyboard flow inspector. */
+export function SankeyTable({ data, caption, formatValue = String, onInspect, activeLinkId, ...props }) {
+    const validated = prepareSankeyData(data);
+    return (_jsxs("table", { ...props, children: [_jsx("caption", { children: caption }), _jsx("thead", { children: _jsxs("tr", { children: [_jsx("th", { scope: "col", children: "Flow" }), _jsx("th", { scope: "col", children: "Source" }), _jsx("th", { scope: "col", children: "Target" }), _jsx("th", { scope: "col", children: "Value" })] }) }), _jsx("tbody", { children: validated.links.map((link, index) => (_jsxs("tr", { "data-active": activeLinkId === link.id || undefined, children: [_jsx("th", { scope: "row", children: onInspect ? (_jsx("button", { type: "button", "aria-pressed": activeLinkId === link.id, onClick: () => onInspect(data.links[index]), children: link.id })) : (link.id) }), _jsx("td", { children: validated.nodes[link.source]?.name }), _jsx("td", { children: validated.nodes[link.target]?.name }), _jsx("td", { children: formatValue(link.value) })] }, link.id))) })] }));
+}

package/dist/scatter-chart.d.ts

@@ -0,0 +1,16 @@
+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;
+export type ScatterChartProps = ComponentProps<typeof EngineScatterChart> & {
+    animate?: boolean | ScatterAnimation | undefined;
+};
+export declare const ScatterMotion: import("react").Context<{
+    reveal: boolean;
+    options: ScatterAnimation;
+    finish: () => void;
+    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;

package/dist/scatter-chart.js

@@ -0,0 +1,64 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { animate as animateValue, useMotionValue } from "motion/react";
+import { createContext, useCallback, useLayoutEffect, useRef, useState, useSyncExternalStore, } from "react";
+import { ScatterChart as EngineScatterChart } from "recharts";
+import { MotionContext } from "./animation.js";
+import { LineChartFrame } from "./line-chart.js";
+export const ScatterMotion = createContext({
+    reveal: false,
+    options: {},
+    finish: () => { },
+    progress: null,
+});
+const query = "(prefers-reduced-motion: reduce)";
+function subscribe(change) {
+    const media = window.matchMedia(query);
+    media.addEventListener("change", change);
+    return () => media.removeEventListener("change", change);
+}
+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 }) {
+    const reduced = useSyncExternalStore(subscribe, snapshot, serverSnapshot);
+    const [interacted, setInteracted] = useState(false);
+    const enabled = animate !== false && !reduced;
+    const interact = useCallback(() => setInteracted(true), []);
+    const finish = useCallback(() => {
+        if (enabled)
+            setInteracted(true);
+    }, [enabled]);
+    const options = typeof animate === "object" ? animate : {};
+    const reveal = enabled && !interacted;
+    const progress = useMotionValue(1);
+    const duration = options.revealDurationMs ?? 700;
+    const easing = options.revealEasing ?? "easeOut";
+    const started = useRef(false);
+    const previous = useRef([duration, easing]);
+    const previousEnabled = useRef(enabled);
+    useLayoutEffect(() => {
+        const inputs = [duration, easing];
+        if ((started.current && inputs.some((value, index) => value !== previous.current[index])) ||
+            (previousEnabled.current && !enabled))
+            interact();
+        previous.current = inputs;
+        previousEnabled.current = enabled;
+    });
+    useLayoutEffect(() => {
+        if (!reveal) {
+            progress.set(1);
+            return;
+        }
+        started.current = true;
+        progress.set(0);
+        const controls = animateValue(progress, 1, {
+            duration: Math.max(0, duration) / 1000,
+            ease: easing,
+            onComplete: interact,
+        });
+        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 }) }) }) }));
+}

package/dist/scatter-material.d.ts

@@ -0,0 +1,8 @@
+import { type ComponentProps } from "react";
+import { Symbols } from "recharts";
+import type { LineMaterial } from "./line-material.js";
+export type ScatterMaterial = LineMaterial;
+/** Finish only a native symbol. Quantitative path, paint alpha and point props survive. */
+export declare function ScatterMaterialSymbol({ material, ...props }: ComponentProps<typeof Symbols> & {
+    material: Exclude<ScatterMaterial, "plain">;
+}): import("react").JSX.Element;

package/dist/scatter-material.js

@@ -0,0 +1,39 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useId } from "react";
+import { Symbols } from "recharts";
+/** Finish only a native symbol. Quantitative path, paint alpha and point props survive. */
+export function ScatterMaterialSymbol({ material, ...props }) {
+    const generatedId = useId();
+    const id = `kind-ui-scatter-${generatedId.replace(/[^a-zA-Z0-9_-]/g, "_")}`;
+    // Do not compete with per-Cell paint pipelines or unresolved native geometry.
+    if (props.filter !== undefined ||
+        props.style?.filter !== undefined ||
+        props.clipPath !== undefined ||
+        props.style?.clipPath !== undefined ||
+        props.cx == null ||
+        props.cy == null ||
+        !Number.isFinite(props.size) ||
+        (props.size ?? 0) <= 0)
+        return _jsx(Symbols, { ...props });
+    // No minimum pixel radius: effects shrink with small marks rather than enlarging them.
+    const span = props.sizeType === "diameter" ? (props.size ?? 64) : Math.sqrt(props.size ?? 64);
+    const declaredStroke = props.style?.stroke ?? props.stroke;
+    const stroke = declaredStroke === undefined || declaredStroke === "none"
+        ? 0
+        : Number(props.style?.strokeWidth ?? props.strokeWidth ?? 1);
+    const round = (props.type ?? "circle") === "circle" ||
+        (props.style?.strokeLinejoin ?? props.strokeLinejoin) === "round";
+    const miter = Number(props.style?.strokeMiterlimit ?? props.strokeMiterlimit ?? 4);
+    const strokeExtent = Math.abs(stroke) * (round ? 0.5 : Math.max(1, Number.isFinite(miter) ? miter : 4) / 2);
+    // A consumer stroke wider than the bounded filter region keeps native rendering.
+    if (!Number.isFinite(stroke) || strokeExtent > span)
+        return _jsx(Symbols, { ...props });
+    const guard = 1 + strokeExtent;
+    const rim = Math.min(0.9, span * 0.055);
+    const relief = Math.min(3, span * 0.17);
+    const soft = Math.min(2, span * 0.1);
+    const halo = Math.min(1.8, span * 0.065);
+    const extent = span * 3 + strokeExtent;
+    return (_jsxs(_Fragment, { children: [_jsxs("defs", { "data-kind-ui": "scatter-material", "data-material": material, pointerEvents: "none", children: [material === "glow" && (_jsxs(_Fragment, { children: [_jsx("clipPath", { id: `${id}-geometry`, clipPathUnits: "userSpaceOnUse", children: _jsx(Symbols, { cx: props.cx, cy: props.cy, size: props.size ?? 64, ...(props.type !== undefined ? { type: props.type } : {}), ...(props.sizeType !== undefined ? { sizeType: props.sizeType } : {}), fill: "#000", stroke: "#000", strokeWidth: props.strokeWidth ?? 0 }) }), _jsx("filter", { id: `${id}-guard`, x: -1, y: -1, width: 3, height: 3, filterUnits: "objectBoundingBox", primitiveUnits: "userSpaceOnUse", children: _jsx("feMorphology", { in: "SourceGraphic", operator: "dilate", radius: guard }) }), _jsxs("mask", { id: `${id}-outside`, maskUnits: "userSpaceOnUse", x: (props.cx ?? 0) - extent, y: (props.cy ?? 0) - extent, width: extent * 2, height: extent * 2, children: [_jsx("rect", { x: (props.cx ?? 0) - extent, y: (props.cy ?? 0) - extent, width: extent * 2, height: extent * 2, fill: "#fff" }), _jsx("g", { filter: `url(#${id}-guard)`, children: _jsx("rect", { x: (props.cx ?? 0) - extent, y: (props.cy ?? 0) - extent, width: extent * 2, height: extent * 2, fill: "#000", clipPath: `url(#${id}-geometry)` }) })] }), _jsxs("filter", { id: `${id}-halo`, x: -1, y: -1, width: 3, height: 3, filterUnits: "objectBoundingBox", primitiveUnits: "userSpaceOnUse", colorInterpolationFilters: "sRGB", children: [_jsx("feComponentTransfer", { in: "SourceAlpha", result: "painted", children: _jsx("feFuncA", { type: "linear", slope: 100000 }) }), _jsx("feGaussianBlur", { in: "SourceGraphic", stdDeviation: halo, result: "halo" }), _jsx("feFlood", { floodOpacity: "var(--kind-ui-scatter-glow-opacity, 0.65)", result: "strength" }), _jsx("feComposite", { in: "halo", in2: "strength", operator: "in", result: "softHalo" }), _jsx("feComposite", { in: "softHalo", in2: "painted", operator: "out" })] })] })), _jsxs("filter", { id: id, x: -1, y: -1, width: 3, height: 3, filterUnits: "objectBoundingBox", primitiveUnits: "userSpaceOnUse", colorInterpolationFilters: "sRGB", children: [_jsx("feComponentTransfer", { in: "SourceAlpha", result: "footprint", children: _jsx("feFuncA", { type: "linear", slope: 100000 }) }), material === "paper" ? (_jsxs(_Fragment, { children: [_jsx("feTurbulence", { type: "fractalNoise", baseFrequency: "0.65 0.3", numOctaves: 1, seed: 7, result: "fiber" }), _jsx("feFlood", { floodColor: "var(--kind-ui-scatter-paper-fiber, #fff)", floodOpacity: "var(--kind-ui-scatter-paper-grain, 0.13)" }), _jsx("feComposite", { in2: "fiber", operator: "in", result: "texture" }), _jsx("feComposite", { in: "texture", in2: "SourceGraphic", operator: "atop", result: "paper" }), _jsx("feMorphology", { in: "footprint", operator: "erode", radius: rim, result: "inside" }), _jsx("feComposite", { in: "footprint", in2: "inside", operator: "out", result: "edge" }), _jsx("feTurbulence", { type: "fractalNoise", baseFrequency: "0.13 0.22", 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: 2, intercept: -0.2 }) }), _jsx("feComposite", { in: "edge", in2: "sketch", operator: "in", result: "sketchEdge" }), _jsx("feColorMatrix", { in: "SourceGraphic", type: "matrix", values: "0.25 0 0 0 0 0 0.25 0 0 0 0 0 0.25 0 0 0 0 0 1 0", result: "ink" }), _jsx("feComposite", { in: "ink", in2: "sketchEdge", operator: "in", result: "contour" }), _jsx("feComposite", { in: "contour", in2: "paper", operator: "atop" })] })) : material === "clay" ? (_jsxs(_Fragment, { children: [_jsx("feOffset", { in: "footprint", dx: relief, dy: relief, result: "lower" }), _jsx("feComposite", { in: "footprint", in2: "lower", operator: "out", result: "top" }), _jsx("feGaussianBlur", { in: "top", stdDeviation: soft, result: "softTop" }), _jsx("feFlood", { floodColor: "var(--kind-ui-scatter-clay-light, #fff)", floodOpacity: 0.62 }), _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: "out", result: "bottom" }), _jsx("feGaussianBlur", { in: "bottom", stdDeviation: soft, result: "softBottom" }), _jsx("feFlood", { floodColor: "var(--kind-ui-scatter-clay-shade, #17212b)", floodOpacity: 0.38 }), _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" }), _jsx("feTurbulence", { type: "fractalNoise", baseFrequency: 0.7, numOctaves: 1, seed: 17, result: "grain" }), _jsx("feFlood", { floodColor: "#fff", floodOpacity: 0.035 }), _jsx("feComposite", { in2: "grain", operator: "in", result: "texture" }), _jsx("feComposite", { in: "texture", in2: "body", operator: "atop" })] })) : (_jsxs(_Fragment, { children: [_jsx("feMorphology", { in: "footprint", operator: "erode", radius: rim, result: "inside" }), _jsx("feComposite", { in: "footprint", in2: "inside", operator: "out", result: "edge" }), _jsx("feFlood", { floodColor: "var(--kind-ui-scatter-glow-light, #fff)", floodOpacity: 0.55 }), _jsx("feComposite", { in2: "edge", operator: "in", result: "light" }), _jsx("feComposite", { in: "light", in2: "SourceGraphic", operator: "atop", result: "body" }), _jsx("feFlood", { floodColor: "var(--kind-ui-scatter-glow-light, #fff)", floodOpacity: 0.12, result: "bloom" }), _jsx("feComposite", { in: "bloom", in2: "body", operator: "atop", result: "luminousBody" })] }))] })] }), material === "glow" ? (_jsxs(_Fragment, { children: [_jsx("use", { "data-kind-ui": "scatter-light", href: `#${id}-body`, filter: `url(#${id}-halo)`, mask: `url(#${id}-outside)`, pointerEvents: "none", "aria-hidden": "true", focusable: "false", tabIndex: -1 }), _jsx("g", { id: `${id}-body`, children: _jsx(Symbols, { ...props, filter: `url(#${id})` }) })] })) : (_jsx(Symbols, { ...props, filter: `url(#${id})` }))] }));
+}

package/dist/scatter-series.d.ts

@@ -0,0 +1,11 @@
+import { type ComponentProps } from "react";
+import { Scatter } from "recharts";
+import { type ScatterMaterial } from "./scatter-material.js";
+export type ScatterSeriesProps = Omit<ComponentProps<typeof Scatter>, "isAnimationActive"> & {
+    /** Series identity is separate from numeric axis data keys. Required for controlled visibility. */
+    seriesKey?: string;
+    /** Finish built-in symbols; custom shapes and consumer filters retain ownership. */
+    material?: ScatterMaterial | undefined;
+};
+/** Native Scatter owns marks, Cells, labels, handlers, axis mapping and point payloads. */
+export declare function ScatterSeries({ seriesKey, hide, fill, material, ...props }: ScatterSeriesProps): import("react").JSX.Element;

package/dist/scatter-series.js

@@ -0,0 +1,74 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { motion, useMotionValue, useTransform } from "motion/react";
+import { use, useId, useLayoutEffect, useMemo, useRef } from "react";
+import { DefaultZIndexes, Scatter, Symbols, usePlotArea, useXAxisDomain, useXAxisScale, useYAxisDomain, useYAxisScale, ZIndexLayer, } from "recharts";
+import { useChart } from "./chart-context.js";
+import { useLineInteraction } from "./line-chart.js";
+import { ScatterMotion } from "./scatter-chart.js";
+import { ScatterMaterialSymbol } from "./scatter-material.js";
+// Delay by native screen X, rather than sorting or changing quantitative data.
+function EntranceSymbol({ material, type, ...props }) {
+    const { progress } = use(ScatterMotion);
+    const settled = useMotionValue(1);
+    const area = usePlotArea();
+    const x = area && area.width > 0
+        ? Math.max(0, Math.min(1, ((props.cx ?? area.x) - area.x) / area.width))
+        : 0;
+    const opacity = useTransform(progress ?? settled, (value) => Math.max(0, Math.min(1, (value - x * 0.65) / 0.35)));
+    return (_jsx(motion.g, { "data-kind-ui": "scatter-point-entrance", "data-entrance-x": props.cx, initial: false, style: { opacity }, children: material === "plain" ? (_jsx(Symbols, { ...props, ...(type !== undefined ? { type } : {}) })) : (_jsx(ScatterMaterialSymbol, { ...props, material: material, ...(type !== undefined ? { type } : {}) })) }));
+}
+/** 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 { registerSeries, invalidate } = useLineInteraction();
+    const shapes = useMemo(() => {
+        function finish(option) {
+            if (option !== undefined && typeof option !== "string" && typeof option !== "boolean")
+                return option;
+            return (point) => (_jsx(EntranceSymbol, { material: material, type: typeof option === "string" ? option : "circle", ...point }));
+        }
+        return {
+            shape: finish(props.shape),
+            // Undefined activeShape must stay undefined: native activation/portal semantics.
+            activeShape: props.activeShape === undefined || props.activeShape === false
+                ? props.activeShape
+                : finish(props.activeShape),
+        };
+    }, [material, props.shape, props.activeShape]);
+    const generatedId = useId();
+    const id = props.id ?? generatedId;
+    const key = seriesKey ?? (typeof props.dataKey === "string" ? props.dataKey : undefined);
+    const hidden = hide === true || (visibleSeries !== undefined && !visibleSeries.includes(key ?? ""));
+    const area = usePlotArea();
+    const xDomain = useXAxisDomain(props.xAxisId);
+    const yDomain = useYAxisDomain(props.yAxisId);
+    const xScale = useXAxisScale(props.xAxisId);
+    const yScale = useYAxisScale(props.yAxisId);
+    const geometry = area && area.width > 0 && area.height > 0 && xDomain && yDomain && xScale && yScale
+        ? JSON.stringify([area, xDomain.map((v) => xScale?.(v)), yDomain.map((v) => yScale?.(v))])
+        : undefined;
+    const inputs = [
+        props.data,
+        props.dataKey,
+        props.xAxisId,
+        props.yAxisId,
+        props.zAxisId,
+        hidden,
+        geometry,
+    ];
+    const previous = useRef(inputs);
+    useLayoutEffect(() => {
+        if (inputs.some((v, i) => v !== previous.current[i] && (i !== 6 || previous.current[i] !== undefined)))
+            invalidate();
+        previous.current = inputs;
+    });
+    useLayoutEffect(() => {
+        if (key !== undefined)
+            return registerSeries(id, key);
+    }, [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 }) }) }));
+}

package/dist/scatter-tooltip.d.ts

@@ -0,0 +1,24 @@
+import { type ComponentPropsWithRef, type ReactNode } from "react";
+import type { TooltipContentProps as NativeContentProps } from "recharts";
+import { type TooltipProps } from "./animation.js";
+import type { TooltipContentProps } from "./tooltip-content.js";
+export type ScatterSizeDimension<Row = unknown> = {
+    /** Own top-level property key, or the same typed record accessor used by ZAxis. */
+    dataKey: string | ((record: Row) => number | null | undefined);
+    name?: string;
+    unit?: string;
+};
+export type ScatterTooltipContentProps<Row = unknown> = Omit<ComponentPropsWithRef<"div">, "children"> & {
+    tooltip: NativeContentProps;
+    /** Receives the selected native record, never a categorical label or chart-wide index. */
+    pointLabel?: (record: Row) => ReactNode;
+    /** Recovers zero/missing Z entries omitted by native Recharts, without changing marker geometry. */
+    zDimension?: ScatterSizeDimension<Row>;
+    missingValue?: ReactNode;
+    valueAnimation?: TooltipContentProps["valueAnimation"];
+};
+/** Dimension metadata uses each entry's dataKey; series identity only controls visibility/title. */
+export declare function ScatterTooltipContent<Row = unknown>({ tooltip, pointLabel, zDimension, missingValue, valueAnimation, ...props }: ScatterTooltipContentProps<Row>): import("react").JSX.Element | null;
+export type ScatterTooltipProps<Row = unknown> = TooltipProps & Pick<ScatterTooltipContentProps<Row>, "pointLabel" | "zDimension" | "missingValue">;
+/** Shared bounded positioning/Motion with Scatter-aware default dimension content. */
+export declare function ScatterTooltip<Row = unknown>({ pointLabel, zDimension, missingValue, valueAnimation, content, ...props }: ScatterTooltipProps<Row>): import("react").JSX.Element;

package/dist/scatter-tooltip.js

@@ -0,0 +1,96 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { use } from "react";
+import { Tooltip } from "./animation.js";
+import { useChart } from "./chart-context.js";
+import { LineInteraction } from "./line-chart.js";
+import { TooltipNumber } from "./tooltip-number.js";
+/** Dimension metadata uses each entry's dataKey; series identity only controls visibility/title. */
+export function ScatterTooltipContent({ tooltip, pointLabel, zDimension, missingValue = "No data", valueAnimation, ...props }) {
+    const { config, visibleSeries } = useChart();
+    const interaction = use(LineInteraction);
+    const seriesIdentity = (id) => id ? (interaction?.seriesKeys.get(id) ?? id) : undefined;
+    let entries = tooltip.active
+        ? tooltip.payload.filter((entry) => {
+            const series = seriesIdentity(entry.graphicalItemId);
+            return (!entry.hide &&
+                entry.type !== "none" &&
+                (visibleSeries === undefined || (series !== undefined && visibleSeries.includes(series))));
+        })
+        : [];
+    const first = entries[0];
+    if (zDimension &&
+        first &&
+        entries.length <= 2 &&
+        !entries.some((entry) => entry.dataKey === zDimension.dataKey)) {
+        const record = first.payload;
+        const raw = typeof zDimension.dataKey === "function"
+            ? zDimension.dataKey(first.payload)
+            : record !== null && typeof record === "object" && Object.hasOwn(record, zDimension.dataKey)
+                ? Reflect.get(record, zDimension.dataKey)
+                : undefined;
+        // Native Scatter omits only zero/missing Z. Nonzero entries survive filterNull,
+        // and Recharts wraps function keys, so reference equality cannot identify them.
+        if (raw === 0 || raw == null) {
+            const { value: _nativeValue, ...identity } = first;
+            entries = [
+                ...entries,
+                {
+                    ...identity,
+                    dataKey: zDimension.dataKey,
+                    name: zDimension.name ?? "Size",
+                    unit: zDimension.unit ?? "",
+                    ...(typeof raw === "number" && Number.isFinite(raw) ? { value: raw } : {}),
+                },
+            ];
+        }
+    }
+    if (!entries.some((entry) => entry.value != null))
+        return null;
+    const series = seriesIdentity(first?.graphicalItemId);
+    const seriesLabel = series !== undefined ? config[series]?.label : undefined;
+    const title = pointLabel?.(first?.payload) ?? seriesLabel;
+    let hasValue = false;
+    const items = entries.map((entry, index) => {
+        // Native Scatter payload slots are X/Y/Z identities, including equal dataKey/name pairs.
+        const dimension = ["x", "y", "z"][index] ?? String(index);
+        const key = String(entry.dataKey ?? entry.name ?? dimension);
+        const meta = Object.hasOwn(config, key) ? config[key] : undefined;
+        let name = meta?.label ?? entry.name ?? key;
+        let value = missingValue;
+        if (entry.value != null) {
+            const format = entry.formatter ?? tooltip.formatter;
+            if (format) {
+                const result = format(entry.value, entry.name, entry, index, entries);
+                if (result == null)
+                    return null;
+                if (Array.isArray(result))
+                    [value, name] = result;
+                else
+                    value = result;
+            }
+            else
+                value = meta?.formatValue
+                    ? meta.formatValue(entry.value)
+                    : Array.isArray(entry.value)
+                        ? entry.value.join(" – ")
+                        : `${entry.value}${entry.unit ?? ""}`;
+            hasValue = true;
+        }
+        return (_jsxs("li", { "data-kind-ui": "chart-tooltip-item", "data-dimension": key, children: [_jsx("span", { children: name }), _jsx("strong", { "data-kind-ui": "chart-tooltip-value", children: valueAnimation === "shuffle" &&
+                        typeof entry.value === "number" &&
+                        Number.isFinite(entry.value) &&
+                        (typeof value === "string" || (typeof value === "number" && Number.isFinite(value))) ? (_jsx(TooltipNumber, { value: value })) : (value) })] }, `${entry.graphicalItemId ?? "point"}-${dimension}`));
+    });
+    if (!hasValue)
+        return null;
+    return (_jsxs("div", { role: tooltip.accessibilityLayer ? "status" : undefined, "aria-live": tooltip.accessibilityLayer ? "assertive" : undefined, "aria-atomic": "true", ...props, "data-kind-ui": "chart-tooltip", children: [title != null && (_jsx("strong", { "data-kind-ui": "chart-tooltip-label", children: tooltip.labelFormatter ? tooltip.labelFormatter(title, entries) : title })), _jsx("ul", { "data-kind-ui": "chart-tooltip-list", children: items })] }));
+}
+// A stable native-content adapter retains digit/width state across consumer rerenders.
+function DefaultScatterContent({ pointLabel, zDimension, missingValue, valueAnimation, ...tooltip }) {
+    return (_jsx(ScatterTooltipContent, { tooltip: tooltip, ...(pointLabel ? { pointLabel } : {}), ...(zDimension ? { zDimension } : {}), ...(missingValue !== undefined ? { missingValue } : {}), ...(valueAnimation ? { valueAnimation } : {}) }));
+}
+/** Shared bounded positioning/Motion with Scatter-aware default dimension content. */
+export function ScatterTooltip({ pointLabel, zDimension, missingValue, valueAnimation, content, ...props }) {
+    return (_jsx(Tooltip, { ...props, content: content ?? (_jsx(DefaultScatterContent, { active: false, payload: [], coordinate: undefined, activeIndex: undefined, accessibilityLayer: false, ...(pointLabel ? { pointLabel } : {}), ...(zDimension ? { zDimension } : {}), ...(missingValue !== undefined ? { missingValue } : {}), ...(valueAnimation ? { valueAnimation } : {}) })) }));
+}