@kind-ui/charts 0.1.1 → 0.3.0

package/dist/loading-polar-designs.js

@@ -0,0 +1,95 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { animate, motion, useMotionValue } from "motion/react";
+import { memo, use, useLayoutEffect, useMemo } from "react";
+import { LoadingProgress } from "./loading-motion.js";
+function point(radius, angle) {
+    const radians = (angle * Math.PI) / 180;
+    return [320 + Math.cos(radians) * radius, 120 + Math.sin(radians) * radius];
+}
+function arc(radius, start, end) {
+    const [sx, sy] = point(radius, start);
+    const [ex, ey] = point(radius, end);
+    return `M ${sx} ${sy} A ${radius} ${radius} 0 ${end - start > 180 ? 1 : 0} 1 ${ex} ${ey}`;
+}
+function polygon(radius) {
+    return [-90, -30, 30, 90, 150, 210].map((angle) => point(radius, angle).join(",")).join(" ");
+}
+/** A bounded decorative profile, independent of the native chart data. */
+export function PolarLoadingDesign({ family, seed = 0, }) {
+    const cycle = Math.abs(Math.trunc(seed));
+    const variant = cycle % 4;
+    // Four authored profiles guarantee visibly distinct adjacent pulses. Small
+    // deterministic deviations keep later cycles fresh without random render work.
+    const deviation = (index, amount) => {
+        let hash = (cycle ^ Math.imul(index + 1, 0x45d9f3b)) >>> 0;
+        hash = Math.imul(hash ^ (hash >>> 16), 0x45d9f3b) >>> 0;
+        return ((hash % 101) / 50 - 1) * amount;
+    };
+    const sectorProfiles = [
+        [70, 20, 10],
+        [9, 15, 7, 30, 12, 27],
+        [10, 45, 30, 15],
+        [35, 8, 12, 10, 35],
+    ];
+    if (family === "pie") {
+        const weights = (sectorProfiles[variant] ?? sectorProfiles[0] ?? []).map((weight, index) => Math.max(5, weight + deviation(index, 2)));
+        const total = weights.reduce((sum, weight) => sum + weight, 0);
+        let angle = -90;
+        return (_jsx("g", { fill: "currentColor", children: weights.map((weight) => {
+                const start = angle + 2;
+                angle += (weight / total) * 360;
+                return _jsx("path", { d: `${arc(100, start, angle - 2)} L 320 120 Z` }, start);
+            }) }));
+    }
+    if (family === "radar") {
+        const reduced = use(LoadingProgress)?.reduced ?? true;
+        return (_jsxs("g", { "data-kind-ui": "loading-radar-motion", stroke: "currentColor", fill: "none", strokeWidth: "2", vectorEffect: "non-scaling-stroke", children: [[34, 67, 100].map((radius) => (_jsx("polygon", { points: polygon(radius), opacity: "0.4" }, radius))), [-90, -30, 30, 90, 150, 210].map((angle) => {
+                    const [x, y] = point(100, angle);
+                    return _jsx("line", { x1: "320", y1: "120", x2: x, y2: y, opacity: "0.35" }, angle);
+                }), _jsx(RadarLoadingPolygon, { seed: seed, layer: 0, reduced: reduced }), _jsx(RadarLoadingPolygon, { seed: seed, layer: 1, reduced: reduced })] }));
+    }
+    const rings = family === "activity-rings" ? [91, 66, 41] : [97, 73, 49, 25];
+    const sweeps = family === "activity-rings"
+        ? [
+            [325, 80, 190],
+            [85, 315, 55],
+            [200, 50, 325],
+            [50, 205, 100],
+        ][variant]
+        : [
+            [325, 70, 190, 45],
+            [75, 310, 45, 220],
+            [195, 45, 325, 90],
+            [45, 200, 90, 315],
+        ][variant];
+    return (_jsx("g", { fill: "none", stroke: "currentColor", strokeWidth: family === "activity-rings" ? 17 : 13, children: rings.map((radius, index) => (_jsxs("g", { children: [_jsx("circle", { cx: "320", cy: "120", r: radius, opacity: "0.2" }), _jsx("path", { d: arc(radius, -90, -90 + Math.max(35, Math.min(338, (sweeps?.[index] ?? 180) + deviation(index, 9)))), strokeLinecap: "round" })] }, radius))) }));
+}
+const radarProfiles = [
+    [96, 28, 42, 90, 25, 35],
+    [30, 94, 32, 45, 94, 28],
+    [40, 35, 96, 28, 45, 94],
+    [86, 72, 28, 34, 82, 96],
+];
+/** Identical vertex order makes every interpolated shape valid and continuous. */
+const RadarLoadingPolygon = memo(function RadarLoadingPolygon({ seed, layer, reduced, }) {
+    const frames = useMemo(() => {
+        const first = (Math.abs(Math.trunc(seed)) + layer * 2) % radarProfiles.length;
+        const points = Array.from({ length: radarProfiles.length }, (_, step) => (radarProfiles[(first + step) % radarProfiles.length] ?? radarProfiles[0])
+            .map((radius, index) => point(radius * (layer === 0 ? 1 : 0.82), -90 + index * 60).join(","))
+            .join(" "));
+        return [...points, points[0] ?? ""];
+    }, [seed, layer]);
+    const points = useMotionValue(frames[0] ?? "");
+    useLayoutEffect(() => {
+        if (reduced) {
+            points.set(frames[0] ?? "");
+            return;
+        }
+        // A persistent MotionValue keeps host rerenders from resetting an in-flight
+        // SVG attribute back to its first keyframe.
+        const controls = animate(points, frames, { duration: 8, ease: "easeInOut", repeat: Infinity });
+        return () => controls.stop();
+    }, [points, frames, reduced]);
+    return (_jsx(motion.polygon, { "data-kind-ui": "loading-radar-polygon", points: points, fill: "currentColor", fillOpacity: layer === 0 ? 0.2 : 0.12, strokeWidth: layer === 0 ? 3 : 2, strokeLinejoin: "round" }));
+});

package/dist/loading-skeleton.d.ts

@@ -0,0 +1,29 @@
+import { type CSSProperties, type ReactNode } from "react";
+import { type LoadingAnimation } from "./loading-motion.js";
+export type LoadingFamily = "line" | "area" | "bar" | "combo" | "scatter" | "waterfall" | "histogram" | "box-plot" | "pie" | "radar" | "radial-bar" | "activity-rings" | "heatmap" | "sankey";
+/** Internal composition keeps unused family illustrations out of single-chart bundles. */
+export type LoadingDesign = (seed: number) => ReactNode;
+/** Fixed decorative design; native plot bounds supply only its available surface. */
+export declare function LoadingSkeletonSurface({ family, seed: suppliedSeed, width, height, x, y, style, animation, design, }: {
+    family: LoadingFamily;
+    seed?: number;
+    width?: number | string;
+    height?: number | string;
+    x?: number;
+    y?: number;
+    style?: CSSProperties;
+    animation?: LoadingAnimation | undefined;
+    design?: LoadingDesign | undefined;
+}): import("react").JSX.Element;
+export declare function ChartLoadingSkeleton({ family, seed, animation, design, }: {
+    family: LoadingFamily;
+    seed: number;
+    animation?: LoadingAnimation | undefined;
+    design?: LoadingDesign | undefined;
+}): import("react").JSX.Element | null;
+export declare function LoadingStatus({ loading, label, }: {
+    loading?: boolean | undefined;
+    label?: string | undefined;
+}): import("react").JSX.Element | null;
+/** Cycle state belongs to the persistent host, so resize/render cannot change a design. */
+export declare function useLoadingSeed(loading: boolean | undefined): number;

package/dist/loading-skeleton.js

@@ -0,0 +1,143 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { motion, useTransform } from "motion/react";
+import { useId, useState } from "react";
+import { usePlotArea } from "recharts";
+import { LoadingAngularBand, LoadingProgress, useLoadingProgress, } from "./loading-motion.js";
+const cartesianEase = [0.25, 0.1, 0.25, 1];
+const lineDesign = (seed) => (_jsx("path", { d: linePath(seed), fill: "none", stroke: "currentColor", strokeWidth: "2.25", vectorEffect: "non-scaling-stroke", strokeLinecap: "round" }));
+const lineProfiles = [
+    [212, 188, 155, 174, 105, 81, 45, 24],
+    [28, 62, 42, 110, 132, 178, 158, 215],
+    [38, 75, 151, 220, 203, 139, 63, 28],
+    [195, 43, 174, 26, 210, 73, 186, 42],
+];
+function linePath(seed) {
+    const profile = lineProfiles[seed % 4] ?? lineProfiles[0] ?? [];
+    const points = profile.map((y, index) => [
+        12 + index * 88,
+        Math.max(12, Math.min(225, y + ((Math.imul(seed + index * 11, 2654435761) >>> 0) % 23) - 11)),
+    ]);
+    let d = `M ${points[0]?.join(" ")}`;
+    for (let i = 1; i < points.length; i++) {
+        const previous = points[i - 1];
+        const point = points[i];
+        if (!previous || !point)
+            continue;
+        const middle = ((previous[0] ?? 0) + (point[0] ?? 0)) / 2;
+        d += ` C ${middle} ${previous[1]} ${middle} ${point[1]} ${point.join(" ")}`;
+    }
+    return d;
+}
+/** Fixed decorative design; native plot bounds supply only its available surface. */
+export function LoadingSkeletonSurface({ family, seed: suppliedSeed, width = "100%", height = "100%", x, y, style, animation, design = lineDesign, }) {
+    const id = useId().replace(/:/g, "");
+    const seed = suppliedSeed ??
+        Array.from(id).reduce((value, char) => (value * 31 + char.charCodeAt(0)) >>> 0, 7);
+    const [pulse, setPulse] = useState(0);
+    const designSeed = seed + pulse;
+    const isCartesian = [
+        "line",
+        "area",
+        "bar",
+        "waterfall",
+        "histogram",
+        "box-plot",
+        "combo",
+    ].includes(family);
+    const duration = Math.max(0, animation?.revealDurationMs ??
+        (family === "scatter" ? 700 : family === "heatmap" ? 800 : family === "sankey" ? 450 : 1000));
+    const easing = animation?.revealEasing ?? (isCartesian ? cartesianEase : "easeOut");
+    const part = (kind) => {
+        const option = animation?.[kind];
+        return {
+            duration: family !== "combo" || option === false
+                ? 0
+                : Math.max(0, option?.revealDurationMs ?? duration),
+            easing: option === false ? easing : (option?.revealEasing ?? easing),
+        };
+    };
+    const line = part("lineReveal");
+    const area = part("areaReveal");
+    const bar = part("barReveal");
+    const cycleDuration = family === "combo" ? Math.max(line.duration, area.duration, bar.duration) : duration;
+    const cycleMs = cycleDuration * 2 + 200;
+    const startDelay = cycleMs * 0.12;
+    const { progress, reduced } = useLoadingProgress(pulse, duration, easing, startDelay, family === "radial-bar");
+    const lineMotion = useLoadingProgress(pulse, line.duration, line.easing, startDelay);
+    const areaMotion = useLoadingProgress(pulse, area.duration, area.easing, startDelay);
+    const barMotion = useLoadingProgress(pulse, bar.duration, bar.easing, startDelay);
+    const horizontalProgress = family === "combo" ? lineMotion.progress : progress;
+    const verticalProgress = family === "combo" ? barMotion.progress : progress;
+    const horizontalReduced = family === "combo" ? lineMotion.reduced : reduced;
+    const verticalReduced = family === "combo" ? barMotion.reduced : reduced;
+    const horizontal = animation?.layout === "vertical";
+    const position = useTransform(horizontalProgress, (value) => (value - 0.5) * 640);
+    const verticalPosition = useTransform(verticalProgress, (value) => 240 - value * 240);
+    const areaPosition = useTransform(areaMotion.progress, (value) => (value - 0.5) * 640);
+    const barPosition = useTransform(barMotion.progress, (value) => (value - 0.5) * 640);
+    const pulseStyle = {
+        ...style,
+        // Radar's two polygon MotionValues continuously morph; disabling the CSS
+        // opacity pulse keeps them visible rather than disabling their animation.
+        ...(cycleDuration === 0 || family === "radar" ? { animation: "none" } : {}),
+        "--kind-ui-loading-cycle": `${cycleMs}ms`,
+        "--kind-ui-loading-horizontal": `url(#${id}-horizontal)`,
+        "--kind-ui-loading-vertical": `url(#${id}-vertical)`,
+        "--kind-ui-loading-area": `url(#${id}-area)`,
+    };
+    const polar = ["pie", "radar", "radial-bar", "activity-rings"].includes(family);
+    return (_jsxs("svg", { "data-kind-ui": "chart-loading-skeleton", "data-family": family, "data-loading-layout": animation?.layout, "data-loading-motion": family === "line" ||
+            family === "area" ||
+            ["bar", "waterfall", "histogram", "box-plot"].includes(family)
+            ? "sweep"
+            : family === "radar"
+                ? "morph"
+                : polar
+                    ? "angular"
+                    : family === "heatmap"
+                        ? "wave"
+                        : family === "sankey"
+                            ? "flow"
+                            : family === "scatter"
+                                ? "emerge"
+                                : family === "combo"
+                                    ? "combined"
+                                    : "grow", onAnimationIteration: (event) => {
+            if (event.target === event.currentTarget && event.animationName === "kind-ui-loading-pulse")
+                setPulse((value) => value + 1);
+        }, "aria-hidden": "true", focusable: "false", x: x, y: y, width: width, height: height, style: pulseStyle, "data-reveal-duration": duration, viewBox: polar ? "200 0 240 240" : "0 0 640 240", preserveAspectRatio: polar || family === "scatter" ? "xMidYMid meet" : "none", children: [_jsxs("defs", { children: [_jsxs("linearGradient", { id: `${id}-soft-x`, children: [_jsx("stop", { offset: "0", stopColor: "white", stopOpacity: "0" }), _jsx("stop", { offset: "0.35", stopColor: "white" }), _jsx("stop", { offset: "0.75", stopColor: "white" }), _jsx("stop", { offset: "1", stopColor: "white", stopOpacity: "0" })] }), _jsxs("linearGradient", { id: `${id}-soft-y`, x1: "0", y1: "1", x2: "0", y2: "0", children: [_jsx("stop", { offset: "0", stopColor: "white", stopOpacity: "0" }), _jsx("stop", { offset: "0.35", stopColor: "white" }), _jsx("stop", { offset: "0.75", stopColor: "white" }), _jsx("stop", { offset: "1", stopColor: "white", stopOpacity: "0" })] }), _jsx("mask", { id: `${id}-horizontal`, maskUnits: "userSpaceOnUse", x: "0", y: "0", width: "640", height: "240", children: horizontalReduced ? (_jsx("rect", { width: "640", height: "240", fill: "white" })) : (_jsx(motion.rect, { "data-kind-ui": "loading-leading-window", x: position, y: "0", width: "320", height: "240", fill: `url(#${id}-soft-x)` })) }), _jsx("mask", { id: `${id}-vertical`, maskUnits: "userSpaceOnUse", x: "0", y: "0", width: "640", height: "240", children: verticalReduced ? (_jsx("rect", { width: "640", height: "240", fill: "white" })) : (_jsx(motion.rect, { "data-kind-ui": "loading-leading-window", x: "0", y: verticalPosition, width: "640", height: "120", fill: `url(#${id}-soft-y)` })) }), _jsx("mask", { id: `${id}-area`, maskUnits: "userSpaceOnUse", x: "0", y: "0", width: "640", height: "240", children: areaMotion.reduced ? (_jsx("rect", { width: "640", height: "240", fill: "white" })) : (_jsx(motion.rect, { x: areaPosition, y: "0", width: "320", height: "240", fill: `url(#${id}-soft-x)` })) }), _jsx("mask", { id: `${id}-bar-horizontal`, maskUnits: "userSpaceOnUse", x: "0", y: "0", width: "640", height: "240", children: barMotion.reduced ? (_jsx("rect", { width: "640", height: "240", fill: "white" })) : (_jsx(motion.rect, { x: barPosition, y: "0", width: "320", height: "240", fill: `url(#${id}-soft-x)` })) }), _jsx("mask", { id: `${id}-angular`, maskUnits: "userSpaceOnUse", x: "0", y: "0", width: "640", height: "240", children: reduced ? (_jsx("rect", { width: "640", height: "240", fill: "white" })) : ([0, 18, 36, 54, 72, 90, 108, 126].map((angle) => (_jsx(LoadingAngularBand, { progress: progress, index: angle / 18, direction: animation?.direction ?? "clockwise" }, angle)))) })] }), _jsx("g", { "data-kind-ui": "loading-design", opacity: "0.48", mask: family === "radar"
+                    ? undefined
+                    : polar
+                        ? `url(#${id}-angular)`
+                        : family === "line" || family === "area"
+                            ? `url(#${id}-horizontal)`
+                            : family === "bar" ||
+                                family === "waterfall" ||
+                                family === "histogram" ||
+                                family === "box-plot"
+                                ? `url(#${id}-horizontal)`
+                                : undefined, children: _jsx(LoadingProgress, { value: { progress, reduced }, children: _jsx("g", { transform: horizontal && ["bar", "waterfall", "histogram", "box-plot"].includes(family)
+                            ? "matrix(0 .375 -2.6666667 0 640 0)"
+                            : undefined, children: design(family === "radar" ? seed : designSeed) }) }) })] }));
+}
+export function ChartLoadingSkeleton({ family, seed, animation, design, }) {
+    const plot = usePlotArea();
+    if (!plot || plot.width <= 0 || plot.height <= 0)
+        return null;
+    return (_jsx(LoadingSkeletonSurface, { family: family, seed: seed, animation: animation, design: design, x: plot.x, y: plot.y, width: plot.width, height: plot.height }));
+}
+export function LoadingStatus({ loading, label, }) {
+    return loading === undefined ? null : (_jsx("span", { role: "status", "data-kind-ui": "chart-loading-status", children: loading ? (label ?? "Loading chart") : "" }));
+}
+/** Cycle state belongs to the persistent host, so resize/render cannot change a design. */
+export function useLoadingSeed(loading) {
+    const id = useId();
+    const [state, setState] = useState({ pending: !!loading, cycle: 0 });
+    let cycle = state.cycle;
+    if (state.pending !== !!loading) {
+        cycle += loading ? 1 : 0;
+        setState({ pending: !!loading, cycle });
+    }
+    return Array.from(id).reduce((value, char) => (value * 31 + char.charCodeAt(0)) >>> 0, 7) + cycle;
+}

package/dist/loading-standalone-designs.d.ts

@@ -0,0 +1,5 @@
+/** Fixed illustrations; no user cells, flows, values, or native marks are sampled. */
+export declare function StandaloneLoadingDesign({ family, seed, }: {
+    family: "heatmap" | "sankey";
+    seed: number;
+}): import("react").JSX.Element | null;

package/dist/loading-standalone-designs.js

@@ -0,0 +1,126 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { LoadingPulseFlow, LoadingPulseMark } from "./loading-motion.js";
+// Authored clustered, diagonal, paired-hotspot and striped illustrations.
+const heatmapPatterns = [
+    [
+        9, 9, 7, 2, 1, 1, 1, 2, 9, 8, 6, 2, 1, 1, 2, 1, 7, 6, 4, 2, 1, 2, 1, 1, 2, 2, 1, 1, 2, 1, 1, 1,
+        1, 1, 1, 2, 1, 1, 2, 1,
+    ],
+    [
+        9, 7, 2, 1, 1, 1, 1, 1, 2, 8, 9, 6, 1, 1, 1, 1, 1, 1, 3, 9, 8, 3, 1, 1, 1, 1, 1, 1, 5, 9, 7, 2,
+        1, 1, 1, 1, 1, 2, 7, 9,
+    ],
+    [
+        1, 2, 1, 1, 1, 1, 1, 1, 2, 1, 1, 1, 1, 2, 1, 1, 2, 5, 3, 1, 1, 4, 7, 5, 6, 9, 8, 2, 2, 8, 9, 8,
+        4, 8, 6, 1, 1, 6, 8, 5,
+    ],
+    [
+        1, 8, 9, 1, 2, 1, 8, 9, 2, 7, 9, 1, 1, 1, 9, 7, 1, 9, 8, 2, 1, 2, 7, 9, 1, 8, 9, 1, 1, 1, 9, 8,
+        2, 9, 7, 1, 2, 1, 8, 9,
+    ],
+];
+// Each flow width is conserved at its node junctions. These are decorative authored layouts.
+const sankeyProfiles = [
+    {
+        nodes: [
+            [16, 20, 16, 60],
+            [16, 100, 16, 50],
+            [16, 170, 16, 50],
+            [298, 35, 24, 90],
+            [298, 145, 24, 70],
+            [608, 20, 16, 50],
+            [608, 95, 16, 40],
+            [608, 155, 16, 70],
+        ],
+        flows: [
+            [32, 20, 298, 35, 60],
+            [32, 100, 298, 95, 30],
+            [32, 130, 298, 145, 20],
+            [32, 170, 298, 165, 50],
+            [322, 35, 608, 20, 50],
+            [322, 85, 608, 95, 40],
+            [322, 145, 608, 155, 70],
+        ],
+    },
+    {
+        nodes: [
+            [16, 20, 16, 100],
+            [16, 140, 16, 80],
+            [298, 20, 24, 50],
+            [298, 90, 24, 60],
+            [298, 170, 24, 70],
+            [608, 25, 16, 100],
+            [608, 145, 16, 80],
+        ],
+        flows: [
+            [32, 20, 298, 20, 50],
+            [32, 70, 298, 90, 50],
+            [32, 140, 298, 140, 10],
+            [32, 150, 298, 170, 70],
+            [322, 20, 608, 25, 50],
+            [322, 90, 608, 75, 50],
+            [322, 140, 608, 145, 10],
+            [322, 170, 608, 155, 70],
+        ],
+    },
+    {
+        nodes: [
+            [16, 32, 16, 176],
+            [298, 12, 24, 64],
+            [298, 96, 24, 46],
+            [298, 162, 24, 66],
+            [608, 20, 16, 110],
+            [608, 154, 16, 66],
+        ],
+        flows: [
+            [32, 32, 298, 12, 64],
+            [32, 96, 298, 96, 46],
+            [32, 142, 298, 162, 66],
+            [322, 12, 608, 20, 64],
+            [322, 96, 608, 84, 46],
+            [322, 162, 608, 154, 66],
+        ],
+    },
+    {
+        nodes: [
+            [16, 12, 16, 30],
+            [16, 58, 16, 40],
+            [16, 114, 16, 50],
+            [16, 174, 16, 60],
+            [608, 20, 16, 60],
+            [608, 102, 16, 55],
+            [608, 174, 16, 65],
+        ],
+        flows: [
+            [32, 12, 608, 20, 30],
+            [32, 58, 608, 50, 30],
+            [32, 88, 608, 102, 10],
+            [32, 114, 608, 112, 45],
+            [32, 159, 608, 174, 5],
+            [32, 174, 608, 179, 60],
+        ],
+    },
+];
+/** Fixed illustrations; no user cells, flows, values, or native marks are sampled. */
+export function StandaloneLoadingDesign({ family, seed, }) {
+    const profile = seed % 4;
+    if (family === "heatmap") {
+        return (_jsx("g", { fill: "currentColor", "data-profile": profile, children: heatmapPatterns[profile]?.map((intensity, index) => {
+                const row = Math.floor(index / 8);
+                const column = index % 8;
+                return (_jsx(LoadingPulseMark, { delay: ((row + column) / 11) * (0.55 / 0.8), span: 0.25 / 0.8, children: _jsx("rect", { "data-motion": "heatmap-cell", x: 16 + column * 77, y: 10 + row * 45, width: "69", height: "37", rx: "3", opacity: 0.2 + (intensity / 9) * 0.8 }) }, `${row}-${column}`));
+            }) }));
+    }
+    const design = sankeyProfiles[profile];
+    if (!design)
+        return null;
+    const band = ([x0, y0, x1, y1, width]) => {
+        const middle = (x0 + x1) / 2;
+        return `M ${x0} ${y0} C ${middle} ${y0} ${middle} ${y1} ${x1} ${y1} L ${x1} ${y1 + width} C ${middle} ${y1 + width} ${middle} ${y0 + width} ${x0} ${y0 + width} Z`;
+    };
+    const flow = ([x0, y0, x1, y1, width]) => {
+        const middle = (x0 + x1) / 2;
+        return `M ${x0} ${y0 + width / 2} C ${middle} ${y0 + width / 2} ${middle} ${y1 + width / 2} ${x1} ${y1 + width / 2}`;
+    };
+    return (_jsxs("g", { fill: "currentColor", "data-profile": profile, children: [design.flows.map((item) => (_jsxs(LoadingPulseFlow, { d: flow(item), width: item[4], delay: (item[0] / 640) * 0.55, children: [_jsx("path", { d: band(item), opacity: "0.5" }), _jsx("path", { "data-motion": "sankey-flow", d: flow(item), fill: "none", stroke: "currentColor", strokeWidth: "2", strokeLinecap: "round", opacity: "0.55" })] }, item.join("-")))), design.nodes.map(([x, y, width, height]) => (_jsx(LoadingPulseMark, { delay: (x / 640) * 0.55, span: 0.45, children: _jsx("rect", { x: x, y: y, width: width, height: height, rx: "2" }) }, `${x}-${y}`)))] }));
+}

package/dist/percent-stack.d.ts

@@ -0,0 +1,18 @@
+import type { TooltipContentProps } from "recharts";
+type Entry = TooltipContentProps["payload"][number];
+/** Return a fraction for selected entries; undefined retains ordinary formatting. */
+export type NormalizedValue = (entry: Entry) => number | undefined;
+export type PercentStackOptions = {
+    /** Raw members of this entry's native expand stack, including its own value.
+     * Return undefined for other series/axes. Match native hidden-series membership.
+     */
+    values: (entry: Entry) => readonly (number | null | undefined)[] | undefined;
+};
+/** Formats an existing fraction; never normalizes chart data or changes domains. */
+export declare function formatPercent(value: number): string;
+/** Formatting only for native stackOffset="expand" scalar stacks. */
+export declare function createPercentStack({ values }: PercentStackOptions): {
+    tickFormatter: typeof formatPercent;
+    normalizedValue: NormalizedValue;
+};
+export {};

package/dist/percent-stack.js

@@ -0,0 +1,33 @@
+/** Formats an existing fraction; never normalizes chart data or changes domains. */
+export function formatPercent(value) {
+    return `${Number((value * 100).toFixed(1))}%`;
+}
+/** Formatting only for native stackOffset="expand" scalar stacks. */
+export function createPercentStack({ values }) {
+    const normalizedValue = (entry) => {
+        if (typeof entry.value !== "number" || !Number.isFinite(entry.value))
+            return undefined;
+        const members = values(entry);
+        if (!members || members.length === 0)
+            return undefined;
+        let total = 0;
+        let allZero = true;
+        for (const member of members) {
+            if (member == null)
+                continue;
+            if (!Number.isFinite(member))
+                return undefined;
+            total += member;
+            if (member !== 0)
+                allZero = false;
+        }
+        if (!Number.isFinite(total))
+            return undefined;
+        // Expand uses a signed sum. A cancelling sum has no normalized share.
+        if (total === 0)
+            return allZero && entry.value === 0 ? 0 : undefined;
+        const fraction = entry.value / total;
+        return Number.isFinite(fraction * 100) ? fraction : undefined;
+    };
+    return { tickFormatter: formatPercent, normalizedValue };
+}

package/dist/pie-chart.d.ts

@@ -1,9 +1,13 @@
 import { type ComponentProps } from "react";
 import { PieChart as EnginePieChart } from "recharts";
-import { type LineAnimation } from "./animation.js";
-export type PieAnimation = LineAnimation;
+import { type BaseAnimation } from "./animation.js";
+export type PieAnimation = BaseAnimation;
 export type PieChartProps = ComponentProps<typeof EnginePieChart> & {
+    /** Initial tooltip category; one direct categoryKey PieSeries with explicit data only. */
+    defaultPinnedCategory?: string | undefined;
     animate?: boolean | PieAnimation | undefined;
+    loading?: boolean | undefined;
+    loadingLabel?: string | undefined;
     /** Entrance sweep only; native start/end angles and data order are unchanged. */
     animationDirection?: "clockwise" | "anticlockwise" | undefined;
 };
@@ -14,4 +18,4 @@ export declare const PieMotion: import("react").Context<{
     direction: "clockwise" | "anticlockwise";
 }>;
 /** Native polar composition, shared interaction, and optional Motion-owned sector entrance. */
-export declare function PieChart({ animate, animationDirection, children, ...props }: PieChartProps): import("react").JSX.Element;
+export declare function PieChart({ animate, loading, loadingLabel, animationDirection, children, defaultPinnedCategory, ...props }: PieChartProps): import("react").JSX.Element;

package/dist/pie-chart.js

@@ -1,10 +1,13 @@
 "use client";
 import { jsx as _jsx } from "react/jsx-runtime";
 import { animate as animateValue } from "motion/react";
-import { createContext, useCallback, useLayoutEffect, useRef, useState, useSyncExternalStore, } from "react";
+import { createContext, memo, useCallback, useLayoutEffect, useRef, useState, useSyncExternalStore, } from "react";
 import { PieChart as EnginePieChart } from "recharts";
 import { MotionContext } from "./animation.js";
+import { useChart } from "./chart-context.js";
 import { LineChartFrame } from "./line-chart.js";
+import { PolarLoadingDesign } from "./loading-polar-designs.js";
+import { PieTooltipPin, pinnedPieIndex } from "./pie-tooltip-pin.js";
 export const PieMotion = createContext({
     reveal: false,
     options: {},
@@ -21,11 +24,33 @@ const snapshot = () => window.matchMedia(query).matches;
 const serverSnapshot = () => true;
 const defaultHover = { type: "spring", stiffness: 210, damping: 28, mass: 0.8 };
 /** Native polar composition, shared interaction, and optional Motion-owned sector entrance. */
-export function PieChart({ animate = false, animationDirection = "clockwise", children, ...props }) {
+export function PieChart({ animate = false, loading, loadingLabel, animationDirection = "clockwise", children, defaultPinnedCategory, ...props }) {
+    const { visibleSeries } = useChart();
+    const [initialCategory] = useState(defaultPinnedCategory);
+    const [pinCleared, setPinCleared] = useState(false);
+    const clearPin = useCallback(() => setPinCleared(true), []);
+    const pinIndex = initialCategory === undefined || pinCleared
+        ? undefined
+        : visibleSeries !== undefined && !visibleSeries.includes(initialCategory)
+            ? undefined
+            : pinnedPieIndex(children, initialCategory, visibleSeries);
+    useLayoutEffect(() => {
+        if (initialCategory !== undefined && pinIndex === undefined)
+            clearPin();
+    }, [initialCategory, pinIndex, clearPin]);
+    const chart = (_jsx(PieChartPlot, { ...props, animate: animate, loading: loading, loadingLabel: loadingLabel, animationDirection: animationDirection, children: children }));
+    return (_jsx(PieTooltipPin, { value: pinIndex, children: initialCategory === undefined ? (chart) : (_jsx("div", { style: { display: "contents" }, onPointerMoveCapture: clearPin, onPointerDownCapture: clearPin, onFocusCapture: clearPin, onKeyDownCapture: clearPin, children: chart })) }));
+}
+// Pin dismissal changes Tooltip context only. Keep the native plot's providers and
+// geometry inputs intact while a pressed sector is awaiting its native click.
+const PieChartPlot = memo(function PieChartPlot({ animate = false, loading, loadingLabel, animationDirection = "clockwise", children, ...props }) {
     const reduced = useSyncExternalStore(subscribe, snapshot, serverSnapshot);
     const [interacted, setInteracted] = useState(false);
-    const finish = useCallback(() => setInteracted(true), []);
-    const enabled = animate !== false && !reduced;
+    const finish = useCallback(() => {
+        if (!loading)
+            setInteracted(true);
+    }, [loading]);
+    const enabled = animate !== false && !reduced && !loading;
     const interrupt = useCallback(() => {
         if (enabled)
             finish();
@@ -42,6 +67,12 @@ export function PieChart({ animate = false, animationDirection = "clockwise", ch
     const duration = options.revealDurationMs ?? 1000;
     const easing = options.revealEasing ?? "easeOut";
     const started = useRef(false);
+    useLayoutEffect(() => {
+        if (loading) {
+            setInteracted(false);
+            started.current = false;
+        }
+    }, [loading]);
     const previous = useRef([duration, easing, animationDirection]);
     useLayoutEffect(() => {
         const inputs = [duration, easing, animationDirection];
@@ -64,5 +95,5 @@ export function PieChart({ animate = false, animationDirection = "clockwise", ch
         });
         return () => controls.stop();
     }, [reveal, duration, easing, finish]);
-    return (_jsx(MotionContext, { value: { enabled, transition: options.hoverTransition ?? defaultHover }, children: _jsx(PieMotion, { value: { reveal, options, progress, direction: animationDirection }, children: _jsx(LineChartFrame, { chartProps: props, engine: EnginePieChart, motionEnabled: enabled, interrupt: interrupt, children: children }) }) }));
-}
+    return (_jsx(MotionContext, { value: { enabled, transition: options.hoverTransition ?? defaultHover }, children: _jsx(PieMotion, { value: { reveal, options, progress, direction: animationDirection }, children: _jsx(LineChartFrame, { chartProps: props, engine: EnginePieChart, loading: loading, loadingLabel: loadingLabel, loadingSkeleton: "pie", loadingDesign: (seed) => _jsx(PolarLoadingDesign, { family: "pie", seed: seed }), loadingAnimation: { ...options, direction: animationDirection }, motionEnabled: enabled, interrupt: interrupt, children: children }) }) }));
+});

package/dist/pie-material.js

@@ -8,7 +8,7 @@ export function PieMaterialFilter({ material, id, radius, thickness, cx, cy, str
     const y = Math.floor(cy - radius - margin);
     const width = Math.ceil(cx + radius + margin) - x;
     const height = Math.ceil(cy + radius + margin) - y;
-    return (_jsx("filter", { id: id, filterUnits: "userSpaceOnUse", x: bounds?.x ?? x, y: bounds?.y ?? y, width: bounds?.width ?? width, height: bounds?.height ?? height, colorInterpolationFilters: "sRGB", children: material === "clay" ? (_jsxs(_Fragment, { children: [_jsx("feComponentTransfer", { in: "SourceAlpha", result: "footprint", children: _jsx("feFuncA", { type: "linear", slope: 100000 }) }), _jsx("feGaussianBlur", { in: "footprint", stdDeviation: relief, result: "rounded" }), _jsx("feOffset", { in: "rounded", dx: relief * 0.7, dy: relief * 0.9, result: "lower" }), _jsx("feComposite", { in: "footprint", in2: "lower", operator: "out", result: "top" }), _jsx("feGaussianBlur", { in: "top", stdDeviation: relief * 0.45, result: "softTop" }), _jsx("feFlood", { floodColor: "var(--kind-ui-pie-clay-light, #fff)", floodOpacity: "var(--kind-ui-pie-clay-highlight, 0.55)" }), _jsx("feComposite", { in2: "softTop", operator: "in", result: "light" }), _jsx("feOffset", { in: "rounded", dx: -relief * 0.8, dy: -relief, result: "upper" }), _jsx("feComposite", { in: "footprint", in2: "upper", operator: "out", result: "bottom" }), _jsx("feGaussianBlur", { in: "bottom", stdDeviation: relief * 0.45, result: "softBottom" }), _jsx("feFlood", { floodColor: "var(--kind-ui-pie-clay-shade, #17212b)", floodOpacity: "var(--kind-ui-pie-clay-shadow, 0.32)" }), _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: "finished" }), _jsx(NativePaintColor, {})] })) : material === "paper" ? (_jsxs(_Fragment, { children: [_jsx("feTurbulence", { type: "fractalNoise", x: bounds?.x ?? x, y: bounds?.y ?? y, width: 32, height: 32, baseFrequency: "0.2 0.3", numOctaves: 1, seed: 7, result: "fiberTile" }), _jsx("feTile", { in: "fiberTile", result: "fiber" }), _jsx("feFlood", { floodColor: "var(--kind-ui-pie-paper-fiber, #fff)", floodOpacity: "var(--kind-ui-pie-paper-grain, 0.16)" }), _jsx("feComposite", { in2: "fiber", operator: "in", result: "texture" }), _jsx("feComposite", { in: "texture", in2: "SourceGraphic", operator: "atop", result: "paper" }), _jsx("feComponentTransfer", { in: "SourceAlpha", result: "footprint", children: _jsx("feFuncA", { type: "linear", slope: 100000 }) }), _jsx("feGaussianBlur", { in: "footprint", stdDeviation: 1.2, result: "inside" }), _jsx("feComposite", { in: "footprint", in2: "inside", operator: "out", result: "edge" }), _jsx("feComponentTransfer", { in: "edge", result: "pencilEdge", children: _jsx("feFuncA", { type: "linear", slope: 6 }) }), _jsx("feColorMatrix", { in: "fiber", type: "luminanceToAlpha", result: "sketch" }), _jsx("feComposite", { in: "pencilEdge", in2: "sketch", operator: "in", result: "contour" }), _jsx("feFlood", { floodColor: "var(--kind-ui-pie-paper-ink, #17212b)", floodOpacity: 0.72 }), _jsx("feComposite", { in2: "contour", operator: "in", result: "ink" }), _jsx("feComposite", { in: "ink", in2: "paper", operator: "atop", result: "outlined" }), _jsx("feOffset", { in: "pencilEdge", dx: 1.2, dy: 1.2, result: "inset" }), _jsx("feComposite", { in: "inset", in2: "footprint", operator: "in", result: "pencilLine" }), _jsx("feComposite", { in: "pencilLine", in2: "sketch", operator: "in", result: "brokenLine" }), _jsx("feFlood", { floodColor: "var(--kind-ui-pie-paper-ink, #17212b)", floodOpacity: 0.45 }), _jsx("feComposite", { in2: "brokenLine", operator: "in", result: "pencilPaint" }), _jsx("feComposite", { in: "pencilPaint", in2: "outlined", operator: "atop", result: "finished" }), _jsx(NativePaintColor, {})] })) : (_jsxs(_Fragment, { children: [_jsx("feComponentTransfer", { in: "SourceAlpha", result: "footprint", children: _jsx("feFuncA", { type: "linear", slope: 100000 }) }), _jsx("feMorphology", { in: "footprint", operator: "dilate", radius: 1.5, result: "haloGuard" }), _jsx("feGaussianBlur", { in: "SourceGraphic", stdDeviation: 4.5, result: "soft" }), _jsx("feFlood", { floodOpacity: "var(--kind-ui-pie-glow-opacity, 0.8)", result: "strength" }), _jsx("feComposite", { in: "soft", in2: "strength", operator: "in", result: "haloPaint" }), _jsx("feComposite", { in: "haloPaint", in2: "haloGuard", operator: "out", result: "halo" }), _jsx("feMerge", { children: _jsx("feMergeNode", { in: "halo" }) })] })) }));
+    return (_jsx("filter", { id: id, filterUnits: "userSpaceOnUse", x: bounds?.x ?? x, y: bounds?.y ?? y, width: bounds?.width ?? width, height: bounds?.height ?? height, colorInterpolationFilters: "sRGB", children: material === "clay" ? (_jsxs(_Fragment, { children: [_jsx("feComponentTransfer", { in: "SourceAlpha", result: "footprint", children: _jsx("feFuncA", { type: "linear", slope: 100000 }) }), _jsx("feGaussianBlur", { in: "footprint", stdDeviation: relief, result: "rounded" }), _jsx("feOffset", { in: "rounded", dx: relief * 0.7, dy: relief * 0.9, result: "lower" }), _jsx("feComposite", { in: "footprint", in2: "lower", operator: "out", result: "top" }), _jsx("feGaussianBlur", { in: "top", stdDeviation: relief * 0.45, result: "softTop" }), _jsx("feFlood", { floodColor: "var(--kind-ui-pie-clay-light, #fff)", floodOpacity: "var(--kind-ui-pie-clay-highlight, 0.55)" }), _jsx("feComposite", { in2: "softTop", operator: "in", result: "light" }), _jsx("feOffset", { in: "rounded", dx: -relief * 0.8, dy: -relief, result: "upper" }), _jsx("feComposite", { in: "footprint", in2: "upper", operator: "out", result: "bottom" }), _jsx("feGaussianBlur", { in: "bottom", stdDeviation: relief * 0.45, result: "softBottom" }), _jsx("feFlood", { floodColor: "var(--kind-ui-pie-clay-shade, #17212b)", floodOpacity: "var(--kind-ui-pie-clay-shadow, 0.32)" }), _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: "finished" }), _jsx(NativePaintColor, {})] })) : (_jsxs(_Fragment, { children: [_jsx("feComponentTransfer", { in: "SourceAlpha", result: "footprint", children: _jsx("feFuncA", { type: "linear", slope: 100000 }) }), _jsx("feMorphology", { in: "footprint", operator: "dilate", radius: 1.5, result: "haloGuard" }), _jsx("feGaussianBlur", { in: "SourceGraphic", stdDeviation: 4.5, result: "soft" }), _jsx("feFlood", { floodOpacity: "var(--kind-ui-pie-glow-opacity, 0.8)", result: "strength" }), _jsx("feComposite", { in: "soft", in2: "strength", operator: "in", result: "haloPaint" }), _jsx("feComposite", { in: "haloPaint", in2: "haloGuard", operator: "out", result: "halo" }), _jsx("feMerge", { children: _jsx("feMergeNode", { in: "halo" }) })] })) }));
 }
 /** The enclosing native-paint mask owns alpha; this surface contributes color only. */
 function NativePaintColor() {

package/dist/pie-pin-identity.d.ts

@@ -0,0 +1,4 @@
+type PiePinComponentKind = "series" | "tooltip";
+export declare function registerPiePinComponent(component: object, kind: PiePinComponentKind): void;
+export declare function piePinComponentKind(component: unknown): PiePinComponentKind | undefined;
+export {};

package/dist/pie-pin-identity.js

@@ -0,0 +1,10 @@
+// Canonical exports register themselves; resolving children never imports their renderers.
+const components = new WeakMap();
+export function registerPiePinComponent(component, kind) {
+    components.set(component, kind);
+}
+export function piePinComponentKind(component) {
+    return typeof component === "function" || (typeof component === "object" && component !== null)
+        ? components.get(component)
+        : undefined;
+}

package/dist/pie-series.d.ts

@@ -5,8 +5,12 @@ import { type PieMaterial } from "./pie-material.js";
 export type PieSeriesProps<DataPoint = unknown, Value = unknown> = Omit<ComponentProps<typeof Pie<DataPoint, Value>>, "isAnimationActive"> & {
     /** Opt-in category colors from Root.config; requires explicit series data. */
     categoryKey?: CategoryKey<DataPoint> | undefined;
+    /** Explicitly share this Pie's category identities and actions with Root/Legend. */
+    interactionBinding?: "root";
     /** Finish on default native sectors; custom shapes, filters and CSS transforms keep ownership. */
     material?: PieMaterial | undefined;
+    /** Categories receiving glow instead of material; requires categoryKey and explicit data. Unknown IDs are ignored. */
+    glowCategories?: readonly string[] | undefined;
     /** Stable sector identity; defaults to the native nameKey value. */
     emphasisKey?: ((payload: unknown) => string | number | undefined) | undefined;
 };