@kind-ui/charts 0.1.0

package/dist/radar-interaction.js

@@ -0,0 +1,138 @@
+"use client";
+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 { useLineInteraction } from "./line-chart.js";
+const Context = createContext(null);
+const Mode = createContext(false);
+/** Persistent selection is local to one RadarChart and never changes Root visibility. */
+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 [internal, setInternal] = useState(null);
+    const [series, setSeries] = useState(() => new Map());
+    const register = useCallback((owner, key, visible) => {
+        setSeries((old) => {
+            if (old.get(owner)?.key === key && old.get(owner)?.visible === visible)
+                return old;
+            return new Map(old).set(owner, { key, visible });
+        });
+        return () => setSeries((old) => {
+            if (!old.has(owner))
+                return old;
+            const next = new Map(old);
+            next.delete(owner);
+            return next;
+        });
+    }, []);
+    const requested = selectedSeries === undefined ? internal : selectedSeries;
+    const visible = requested !== null &&
+        [...series.values()].some((item) => item.key === requested && item.visible);
+    const selected = enabled && visible ? requested : null;
+    // No synthetic consumer callbacks: only user selection/reset requests emit changes.
+    // A controlled value remains consumer-owned; hidden values simply have no visible paint.
+    useEffect(() => {
+        if (selectedSeries === undefined && internal !== null && (!enabled || !visible))
+            setInternal(null);
+    }, [selectedSeries, internal, enabled, visible]);
+    const change = useCallback((next) => {
+        if (selectedSeries === undefined)
+            setInternal(next);
+        onSelectedSeriesChange?.(next);
+    }, [selectedSeries, onSelectedSeriesChange]);
+    const toggle = useCallback((key) => {
+        if (enabled)
+            change(selected === key ? null : key);
+    }, [enabled, selected, change]);
+    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);
+                }, children: children }) }) }));
+}
+/** An extra paint/control layer preserves native shape, data, refs and event handlers. */
+export function RadarSelectionLayer({ seriesKey, hidden, children, }) {
+    const selection = use(Context);
+    const { config } = useChart();
+    const { data } = useLineInteraction();
+    const owner = useId();
+    const enabled = Boolean(selection?.enabled);
+    const present = !hidden && Boolean(data?.length);
+    useLayoutEffect(() => {
+        if (!enabled || seriesKey === undefined)
+            return;
+        return selection?.register(owner, seriesKey, present);
+    }, [enabled, selection?.register, owner, seriesKey, present]);
+    if (enabled && seriesKey === undefined)
+        throw new Error("RadarSeries requires seriesKey for selection with a non-string dataKey");
+    const interactive = enabled && present && seriesKey !== undefined;
+    const selected = interactive && selection?.selected === seriesKey;
+    const dimmed = interactive && selection?.selected != null && !selected;
+    return (
+    // biome-ignore lint/a11y/noStaticElementInteractions lint/a11y/useAriaPropsSupportedByRole: The role, pressed state and handlers are enabled together only for opted-in SVG controls.
+    _jsx("g", { "data-kind-ui": interactive ? "radar-selection" : undefined, "data-series": interactive ? seriesKey : undefined, "data-selection": interactive ? (selected ? "selected" : dimmed ? "dimmed" : "baseline") : undefined, role: interactive ? "button" : undefined, tabIndex: interactive ? 0 : undefined, "aria-label": interactive ? `Highlight ${config[seriesKey]?.label ?? seriesKey}` : undefined, "aria-pressed": interactive ? selected : undefined, onClick: (event) => {
+            // React portal events bubble through this component even when their paint is elsewhere.
+            // Annotations, native active-dot overlays and consumer portals retain their own interaction.
+            if (interactive &&
+                !event.defaultPrevented &&
+                event.button === 0 &&
+                event.currentTarget.contains(event.target))
+                selection?.toggle(seriesKey);
+        }, onKeyDown: (event) => {
+            if (interactive &&
+                event.target === event.currentTarget &&
+                !event.defaultPrevented &&
+                (event.key === "Enter" || event.key === " ")) {
+                event.preventDefault();
+                if (!event.repeat)
+                    selection?.toggle(seriesKey);
+            }
+        }, children: _jsx("g", { "data-kind-ui": "radar-selection-paint", style: { opacity: dimmed ? 0.28 : 1 }, children: children }) }));
+}
+/** Recharts clones this public dot element with its original computed dot props. */
+export function useRadarSelectionDot(dot, seriesKey) {
+    const enabled = use(Mode);
+    return useMemo(() => {
+        if (!enabled)
+            return dot;
+        const props = isValidElement(dot)
+            ? dot.props
+            : typeof dot === "object"
+                ? dot
+                : {};
+        return _jsx(RadarSelectionDot, { ...props, option: dot, seriesKey: seriesKey });
+    }, [enabled, dot, seriesKey]);
+}
+function RadarSelectionDot({ option, seriesKey, ...props }) {
+    const selection = use(Context);
+    // Native Radar draws a fallback dot for a one-point series even when dot is false.
+    if (!option && (!Array.isArray(props.points) || props.points.length !== 1))
+        return null;
+    const dimmed = selection?.enabled && selection.selected !== null && selection.selected !== seriesKey;
+    let paint;
+    if (isValidElement(option))
+        paint = cloneElement(option, props);
+    // The engine injects the complete public DotItemDotProps when cloning the adapter above.
+    else if (typeof option === "function")
+        paint = option(props);
+    else
+        paint = (_jsx(Dot, { ...props, className: [
+                "recharts-radar-dot",
+                typeof option === "object" ? option?.className : undefined,
+            ]
+                .filter(Boolean)
+                .join(" ") }));
+    return (
+    // biome-ignore lint/a11y/noStaticElementInteractions: Pointer target for the corresponding keyboard-operable series control, not an additional tab stop.
+    _jsx("g", { "data-kind-ui": "radar-selection-dot", style: { opacity: dimmed ? 0.28 : 1 }, onClick: (event) => {
+            if (!event.defaultPrevented &&
+                event.button === 0 &&
+                seriesKey !== undefined &&
+                event.currentTarget.contains(event.target))
+                selection?.toggle(seriesKey);
+        }, children: paint }));
+}

package/dist/radial-bar-label.d.ts

@@ -0,0 +1,15 @@
+import { type Ref } from "react";
+import type { LabelProps } from "recharts";
+export type RadialBarLabelProps = Omit<LabelProps, "fontSize" | "position" | "content" | "children" | "offset" | "labelRef" | "angle" | "textBreakAll" | "x" | "y" | "dx" | "dy" | "transform"> & {
+    /** Independently controls this visual label, without affecting payload or tooltip state. */
+    show?: boolean;
+    /** Numeric SVG pixels; reduced to fit the native ring band, never below minFontSize. */
+    fontSize?: number;
+    minFontSize?: number;
+    /** Space reserved at the arc endpoints and both edges of the band. */
+    padding?: number;
+    ref?: Ref<SVGTextElement>;
+    labelRef?: Ref<SVGTextElement>;
+};
+/** LabelList content placed along the actual native sector's mid-radius, within its endpoints. */
+export declare function RadialBarLabel({ show, fontSize, minFontSize, padding, viewBox, parentViewBox: _parentViewBox, value, formatter, index: _index, zIndex: _zIndex, id, ref, labelRef, style, fill, pointerEvents, ...props }: RadialBarLabelProps): import("react").JSX.Element | null;

package/dist/radial-bar-label.js

@@ -0,0 +1,136 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useId, useLayoutEffect, useState } from "react";
+function attach(ref, node) {
+    if (typeof ref === "function")
+        return ref(node);
+    if (ref)
+        ref.current = node;
+}
+// Native Label forwards these layout/content fields to custom content; they are not SVG attributes.
+function svgAttributes({ x: _x, y: _y, dx: _dx, dy: _dy, transform: _transform, position: _position, content: _content, offset: _offset, children: _children, angle: _angle, textBreakAll: _textBreakAll, viewBox: _viewBox, parentViewBox: _parentViewBox, value: _value, formatter: _formatter, index: _index, zIndex: _zIndex, labelRef: _labelRef, ...props }) {
+    return props;
+}
+/** LabelList content placed along the actual native sector's mid-radius, within its endpoints. */
+export function RadialBarLabel({ show = true, fontSize = 11, minFontSize = 9, padding = 2, viewBox, parentViewBox: _parentViewBox, value, formatter, index: _index, zIndex: _zIndex, id, ref, labelRef, style, fill = "white", pointerEvents = "none", ...props }) {
+    const generatedId = useId();
+    const pathId = `${id ?? generatedId}-arc`;
+    const [node, setNode] = useState(null);
+    const [measurement, setMeasurement] = useState({
+        length: Infinity,
+        fontSize: Infinity,
+        contained: false,
+    });
+    const [fitSize, setFitSize] = useState(fontSize);
+    const text = formatter ? formatter(value) : value;
+    const textKey = typeof text === "string" || typeof text === "number" ? String(text) : String(value);
+    const box = viewBox && "cx" in viewBox ? viewBox : undefined;
+    const band = box ? box.outerRadius - box.innerRadius : 0;
+    const inset = Number.isFinite(padding) ? Math.max(0, padding) : 2;
+    const size = Math.min(fontSize, fitSize, band - inset * 2);
+    const radius = box ? (box.innerRadius + box.outerRadius) / 2 : 0;
+    const rawDelta = box ? box.endAngle - box.startAngle : 0;
+    const delta = Math.sign(rawDelta) * Math.min(Math.abs(rawDelta), 359.999);
+    const length = ((Math.abs(delta) * Math.PI) / 180) * radius;
+    const valid = box !== undefined &&
+        [box.cx, box.cy, radius, delta, band, size, fontSize, minFontSize].every(Number.isFinite) &&
+        box.innerRadius >= 0 &&
+        radius > 0 &&
+        band > 0 &&
+        fontSize > 0 &&
+        minFontSize > 0 &&
+        Math.abs(delta) > 0 &&
+        size >= minFontSize;
+    const attachRef = useCallback((element) => {
+        setNode(element);
+        const first = attach(ref, element);
+        const second = attach(labelRef, element);
+        return () => {
+            if (first)
+                first();
+            else
+                attach(ref, null);
+            if (second)
+                second();
+            else
+                attach(labelRef, null);
+        };
+    }, [ref, labelRef]);
+    // biome-ignore lint/correctness/useExhaustiveDependencies: New geometry or text retries the requested size before measuring its fit.
+    useLayoutEffect(() => {
+        setFitSize(fontSize);
+    }, [fontSize, textKey, band, radius, delta, minFontSize, inset, box?.startAngle]);
+    // biome-ignore lint/correctness/useExhaustiveDependencies: Text and font/style changes must remeasure the retained SVG node before paint.
+    useLayoutEffect(() => {
+        if (!node)
+            return;
+        const measure = () => {
+            const cx = Number(node.dataset.cx), cy = Number(node.dataset.cy);
+            const inner = Number(node.dataset.innerRadius), outer = Number(node.dataset.outerRadius);
+            const start = Number(node.dataset.startAngle), end = Number(node.dataset.endAngle);
+            const direction = Math.sign(end - start), span = Math.abs(end - start);
+            const contained = Array.from({ length: node.getNumberOfChars() }, (_, index) => {
+                const extent = node.getExtentOfChar(index);
+                return [extent.x, extent.x + extent.width].every((x) => [extent.y, extent.y + extent.height].every((y) => {
+                    const r = Math.hypot(x - cx, y - cy);
+                    const angle = (Math.atan2(cy - y, x - cx) * 180) / Math.PI;
+                    const along = (((direction * (angle - start)) % 360) + 360) % 360;
+                    return r >= inner && r <= outer && along <= span;
+                }));
+            }).every(Boolean);
+            const next = {
+                contained,
+                length: node.getComputedTextLength(),
+                fontSize: Number.parseFloat(getComputedStyle(node).fontSize),
+            };
+            if ((!contained || next.length > length - inset * 2) && size > minFontSize)
+                setFitSize(minFontSize);
+            setMeasurement((old) => old.length === next.length &&
+                old.fontSize === next.fontSize &&
+                old.contained === next.contained
+                ? old
+                : next);
+        };
+        measure();
+        const observer = new ResizeObserver(measure);
+        observer.observe(node);
+        document.fonts?.addEventListener("loadingdone", measure);
+        return () => {
+            observer.disconnect();
+            document.fonts?.removeEventListener("loadingdone", measure);
+        };
+    }, [
+        node,
+        text,
+        size,
+        length,
+        inset,
+        minFontSize,
+        style,
+        box?.cx,
+        box?.cy,
+        box?.innerRadius,
+        box?.outerRadius,
+        box?.startAngle,
+        box?.endAngle,
+    ]);
+    if (!show || !valid || !box || text == null || typeof text === "boolean")
+        return null;
+    const middle = box.startAngle + delta / 2;
+    // Reverse a left-facing tangent so text reads upright on either sweep direction.
+    const reverse = -Math.sign(delta) * Math.sin((middle * Math.PI) / 180) < 0;
+    const start = reverse ? box.startAngle + delta : box.startAngle;
+    const sweep = reverse ? -delta : delta;
+    const point = (angle) => {
+        const radians = (angle * Math.PI) / 180;
+        return `${box.cx + radius * Math.cos(radians)},${box.cy - radius * Math.sin(radians)}`;
+    };
+    const pieces = Math.ceil(Math.abs(sweep) / 180);
+    let path = `M${point(start)}`;
+    for (let part = 1; part <= pieces; part++)
+        path += ` A${radius},${radius} 0 0 ${sweep < 0 ? 1 : 0} ${point(start + (sweep * part) / pieces)}`;
+    const fits = measurement.contained &&
+        measurement.length <= length - inset * 2 &&
+        measurement.fontSize <= band - inset * 2;
+    return (_jsxs("g", { "data-kind-ui": "radial-label-frame", children: [_jsx("defs", { children: _jsx("path", { id: pathId, d: path }) }), _jsx("text", { ...svgAttributes(props), ref: attachRef, id: id, fill: fill, pointerEvents: pointerEvents, "data-kind-ui": "radial-label", "data-fit": fits ? "yes" : "no", "data-cx": box.cx, "data-cy": box.cy, "data-inner-radius": box.innerRadius, "data-outer-radius": box.outerRadius, "data-start-angle": box.startAngle, "data-end-angle": box.startAngle + delta, "data-arc-length": length, "data-text-length": measurement.length, dominantBaseline: "central", textAnchor: "middle", style: { fontSize: size, ...style, visibility: fits ? style?.visibility : "hidden" }, children: _jsx("textPath", { href: `#${pathId}`, startOffset: "50%", children: text }) })] }));
+}

package/dist/radial-category.d.ts

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

package/dist/radial-category.js

@@ -0,0 +1,4 @@
+"use client";
+import { createContext } from "react";
+// The native RadialBar reads chart data, so category identity is scoped there.
+export const RadialCategory = createContext(null);

package/dist/root.d.ts

@@ -0,0 +1,14 @@
+import type { ComponentPropsWithRef } from "react";
+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;
+});
+/** 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;

package/dist/root.js

@@ -0,0 +1,29 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { ChartContext } from "./chart-context.js";
+import { EmphasisProvider, useEmphasisActions } from "./emphasis.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");
+    const colors = {};
+    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 value = {
+        config,
+        ...(visibleSeries ? { visibleSeries } : {}),
+        ...(onVisibleSeriesChange ? { onVisibleSeriesChange } : {}),
+    };
+    return (_jsx(ChartContext, { value: value, children: _jsx(EmphasisProvider, { enabled: emphasis === "auto", children: _jsx(RootFrame, { ...props, style: { ...colors, ...style }, children: children }) }) }));
+}
+function RootFrame({ children, ...props }) {
+    const { reset } = useEmphasisActions();
+    return (_jsx("div", { ...props, "data-kind-ui": "chart", onKeyDownCapture: (event) => {
+            if (event.key === "Escape")
+                reset();
+            props.onKeyDownCapture?.(event);
+        }, children: children }));
+}

package/dist/sankey-chart.d.ts

@@ -0,0 +1,33 @@
+import { type MotionValue } from "motion/react";
+import { type ComponentProps, type ReactNode } from "react";
+import { Sankey as EngineSankey, type SankeyLinkProps as NativeLinkProps, type SankeyNodeProps as NativeNodeProps } from "recharts";
+import { type SankeyNodeConfig } from "./sankey-colors.js";
+import { type SankeyFlowData } from "./sankey-data.js";
+import { type SankeyLinkProps, type SankeyNodeProps } from "./sankey-marks.js";
+type NativeProps = ComponentProps<typeof EngineSankey>;
+type NativeEvent = NonNullable<NativeProps["onClick"]>;
+type IdentityEvent = (item: SankeyNodeProps | SankeyLinkProps, type: Parameters<NativeEvent>[1], event: Parameters<NativeEvent>[2]) => void;
+export interface SankeyAnimation {
+    revealDurationMs?: number;
+}
+export type SankeyChartProps = Omit<NativeProps, "data" | "node" | "link" | "onClick" | "onMouseEnter" | "onMouseLeave"> & {
+    data: SankeyFlowData;
+    /** Explicit node-ID metadata; enables matching default Kind node/source-link paint. */
+    nodeConfig?: SankeyNodeConfig | undefined;
+    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;
+    onMouseEnter?: IdentityEvent;
+    onMouseLeave?: IdentityEvent;
+    /** Kind SankeyLink paint flows along unchanged paths; custom renderers retain ownership. */
+    animate?: boolean | SankeyAnimation;
+    empty?: ReactNode;
+};
+export declare const SankeyMotion: import("react").Context<{
+    reveal: boolean;
+    progress: MotionValue<number> | null;
+    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 {};

package/dist/sankey-chart.js

@@ -0,0 +1,142 @@
+"use client";
+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 { SankeyColors } from "./sankey-colors.js";
+import { prepareSankeyData } from "./sankey-data.js";
+import { SankeyLink, SankeyNode, } from "./sankey-marks.js";
+const configuredNode = (shape) => _jsx(SankeyNode, { ...shape });
+const configuredLink = (shape) => _jsx(SankeyLink, { ...shape });
+function NativeSize({ onSize }) {
+    const width = useChartWidth();
+    const height = useChartHeight();
+    useLayoutEffect(() => {
+        if (width !== undefined && height !== undefined)
+            onSize(width, height);
+    }, [width, height, onSize]);
+    return 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;
+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 }) {
+    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");
+    const validated = prepareSankeyData(data);
+    if (nodeConfig) {
+        for (const node of validated.nodes) {
+            if (!Object.hasOwn(nodeConfig, node.id))
+                throw new Error(`Sankey nodeConfig requires metadata for node "${node.id}"`);
+        }
+    }
+    const positive = validated.links.filter((link) => link.value > 0);
+    const nativeKeys = new Set();
+    for (const link of positive) {
+        const key = `${link.source}-${link.target}-${link.value}`;
+        if (nativeKeys.has(key))
+            throw new Error("Sankey native renderer cannot distinguish equal-value parallel links; keep the table or supply a renderer that supports them.");
+        nativeKeys.add(key);
+    }
+    const used = new Set(positive.flatMap((link) => [link.source, link.target]));
+    const mapping = new Map();
+    const nodes = validated.nodes.filter((_, index) => {
+        if (!used.has(index))
+            return false;
+        mapping.set(index, mapping.size);
+        return true;
+    });
+    const links = positive.map((link) => ({
+        ...link,
+        source: mapping.get(link.source),
+        target: mapping.get(link.target),
+    }));
+    const reduced = useSyncExternalStore(subscribe, snapshot, serverSnapshot);
+    const [interrupted, setInterrupted] = useState(false);
+    const [size, setSize] = useState(null);
+    const measured = useRef(null);
+    const onSize = useCallback((width, height) => {
+        const prior = measured.current;
+        if (prior?.width === width && prior?.height === height)
+            return;
+        if (prior)
+            setInterrupted(true);
+        measured.current = { width, height };
+        setSize(measured.current);
+    }, []);
+    const inputs = [
+        duration,
+        data,
+        props.width,
+        props.height,
+        props.nodePadding,
+        props.nodeWidth,
+        props.iterations,
+        props.sort,
+        props.align,
+        props.verticalAlign,
+        props.margin,
+        props.linkCurvature,
+        props.node,
+        props.link,
+    ];
+    const started = useRef(false);
+    const previous = useRef(inputs);
+    useLayoutEffect(() => {
+        if (inputs.some((value, index) => (index !== 0 || started.current) && value !== previous.current[index]))
+            setInterrupted(true);
+        previous.current = inputs;
+    });
+    const enabled = Boolean(animate) && !reduced;
+    const previousEnabled = useRef(enabled);
+    useLayoutEffect(() => {
+        if (previousEnabled.current && !enabled)
+            setInterrupted(true);
+        previousEnabled.current = enabled;
+    }, [enabled]);
+    const reveal = enabled && !interrupted && size !== null;
+    const progress = useMotionValue(1);
+    useLayoutEffect(() => {
+        if (!reveal) {
+            progress.set(1);
+            return;
+        }
+        started.current = true;
+        progress.set(0);
+        const playback = animateValue(progress, 1, {
+            duration: duration / 1000,
+            onComplete: () => setInterrupted(true),
+        });
+        return () => playback.stop();
+    }, [reveal, progress, duration]);
+    const margin = { top: 5, bottom: 5, left: 5, right: 5, ...props.margin };
+    const height = size ? size.height - margin.top - margin.bottom : 0;
+    const width = size ? size.width - margin.left - margin.right : 0;
+    const padding = props.nodePadding ?? 10;
+    const drawable = height > Math.max(0, nodes.length - 1) * padding && width > (props.nodeWidth ?? 10);
+    if (drawable && links.length) {
+        const total = links.reduce((sum, link) => sum + link.value, 0);
+        const scale = height / total;
+        const minimumScale = (height - Math.max(0, nodes.length - 1) * padding) / total;
+        if (!Number.isFinite(total) ||
+            !Number.isFinite(scale) ||
+            scale <= 0 ||
+            !Number.isFinite(total * height) ||
+            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] }) }) }));
+}

package/dist/sankey-colors.d.ts

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

package/dist/sankey-colors.js

@@ -0,0 +1,6 @@
+"use client";
+import { createContext } from "react";
+export const SankeyColors = createContext(undefined);
+export function sankeyColor(config, id) {
+    return config && Object.hasOwn(config, id) ? config[id]?.color : undefined;
+}

package/dist/sankey-data.d.ts

@@ -0,0 +1,30 @@
+export interface SankeyFlowNode {
+    id: string;
+    name: string;
+    [key: string]: unknown;
+}
+export interface SankeyFlowLink {
+    id: string;
+    source: string | number;
+    target: string | number;
+    value: number;
+    [key: string]: unknown;
+}
+export interface SankeyFlowData {
+    nodes: readonly SankeyFlowNode[];
+    links: readonly SankeyFlowLink[];
+}
+/** Validate the entire DAG, including zero flows. Never infer a missing flow. */
+export declare function prepareSankeyData(data: SankeyFlowData): {
+    nodes: {
+        [key: string]: unknown;
+        id: string;
+        name: string;
+    }[];
+    links: {
+        source: number;
+        target: number;
+        id: string;
+        value: number;
+    }[];
+};

package/dist/sankey-data.js

@@ -0,0 +1,65 @@
+/** Validate the entire DAG, including zero flows. Never infer a missing flow. */
+export function prepareSankeyData(data) {
+    const ids = new Map();
+    const checkId = (id, kind) => {
+        if (typeof id !== "string" || !id.trim())
+            throw new Error(`Sankey ${kind} requires a nonempty string id`);
+    };
+    data.nodes.forEach((node, index) => {
+        checkId(node.id, "node");
+        if (ids.has(node.id))
+            throw new Error(`Duplicate Sankey node id: ${node.id}`);
+        if (typeof node.name !== "string")
+            throw new Error(`Sankey node ${node.id} requires a name`);
+        ids.set(node.id, index);
+    });
+    const endpoint = (value) => {
+        const index = typeof value === "string" ? ids.get(value) : value;
+        if (index === undefined || !Number.isInteger(index) || index < 0 || index >= data.nodes.length)
+            throw new Error(`Invalid Sankey endpoint: ${String(value)}`);
+        return index;
+    };
+    const linkIds = new Set();
+    const incoming = data.nodes.map(() => 0);
+    const outgoing = data.nodes.map(() => 0);
+    const edges = data.nodes.map(() => []);
+    const indegrees = data.nodes.map(() => 0);
+    const hasIncoming = data.nodes.map(() => false);
+    const links = data.links.map((link) => {
+        checkId(link.id, "link");
+        if (linkIds.has(link.id))
+            throw new Error(`Duplicate Sankey link id: ${link.id}`);
+        linkIds.add(link.id);
+        if (typeof link.value !== "number" || !Number.isFinite(link.value) || link.value < 0)
+            throw new Error(`Sankey link ${link.id} requires a finite nonnegative value`);
+        const source = endpoint(link.source);
+        const target = endpoint(link.target);
+        outgoing[source] = (outgoing[source] ?? 0) + link.value;
+        incoming[target] = (incoming[target] ?? 0) + link.value;
+        edges[source]?.push(target);
+        hasIncoming[target] = true;
+        indegrees[target] = (indegrees[target] ?? 0) + 1;
+        return { ...link, source, target };
+    });
+    const queue = indegrees.flatMap((degree, index) => (degree === 0 ? [index] : []));
+    for (let cursor = 0; cursor < queue.length; cursor++) {
+        for (const target of edges[queue[cursor] ?? 0] ?? []) {
+            indegrees[target] = (indegrees[target] ?? 0) - 1;
+            if (indegrees[target] === 0)
+                queue.push(target);
+        }
+    }
+    if (queue.length !== data.nodes.length)
+        throw new Error("Sankey cycles are unsupported (including zero-value cycles)");
+    data.nodes.forEach((node, index) => {
+        const input = incoming[index] ?? 0;
+        const output = outgoing[index] ?? 0;
+        if (!Number.isFinite(input) || !Number.isFinite(output))
+            throw new Error(`Sankey totals overflow at ${node.id}`);
+        const hasInput = hasIncoming[index];
+        const hasOutput = edges[index]?.length;
+        if (hasInput && hasOutput && Math.abs(input - output) > 1e-9 * Math.max(input, output))
+            throw new Error(`Inconsistent Sankey totals at ${node.id}: incoming ${input}, outgoing ${output}. Supply explicit loss/gain flows.`);
+    });
+    return { nodes: data.nodes.map((node) => ({ ...node })), links };
+}

package/dist/sankey-finish.d.ts

@@ -0,0 +1,13 @@
+export type SankeyFinish = "plain" | "paper" | "clay" | "glow";
+/** Sankey-local surface treatment. Never displace the quantitative silhouette. */
+export declare function SankeyFinishFilter({ id, finish, thickness, bounds, }: {
+    id: string;
+    finish: Exclude<SankeyFinish, "plain">;
+    thickness: number;
+    bounds: {
+        x: number | string;
+        y: number | string;
+        width: number | string;
+        height: number | string;
+    };
+}): import("react").JSX.Element;