@kind-ui/charts 0.1.1 → 0.2.0

package/dist/line-series.d.ts

@@ -1,15 +1,23 @@
 import { type ComponentProps } from "react";
 import { Line } from "recharts";
+import { type LineDashAnimation } from "./line-dash.js";
 import { type LineMaterial } from "./line-material.js";
+import { type PointStyle } from "./point-marker.js";
 type DefaultLineDataKey = Extract<ComponentProps<typeof Line>["dataKey"], (row: never) => unknown>;
 export type LineSeriesProps<DataPoint = Parameters<DefaultLineDataKey>[0], Value = ReturnType<DefaultLineDataKey>> = ComponentProps<typeof Line<DataPoint, Value>> & {
     /** Metadata/visibility key, required only for function or numeric data keys. */
     seriesKey?: string;
+    /** Optional point paint; explicit native dot takes precedence. */
+    pointStyle?: PointStyle;
+    /** Independent active point paint; explicit native activeDot takes precedence. */
+    activePointStyle?: PointStyle;
     /** Material on the default SVG curve; custom shape/filter retain consumer ownership. */
     material?: LineMaterial;
+    /** Continuous default-curve dashes; requires a numeric native strokeDasharray. */
+    dashAnimation?: false | LineDashAnimation;
 };
 /** A registered Recharts Line with Root colors and controlled visibility. */
-export declare function LineSeries<DataPoint = Parameters<DefaultLineDataKey>[0], Value = ReturnType<DefaultLineDataKey>>({ seriesKey, hide, stroke, className, material, renderWhileHidden, ...props }: LineSeriesProps<DataPoint, Value> & {
+export declare function LineSeries<DataPoint = Parameters<DefaultLineDataKey>[0], Value = ReturnType<DefaultLineDataKey>>({ seriesKey, pointStyle, activePointStyle: _activePointStyle, hide, stroke, className, material, dashAnimation, renderWhileHidden, ...props }: LineSeriesProps<DataPoint, Value> & {
     renderWhileHidden?: boolean;
 }): import("react").JSX.Element;
 export {};

package/dist/line-series.js

@@ -1,13 +1,16 @@
 "use client";
 import { jsx as _jsx } from "react/jsx-runtime";
 import { useId, useLayoutEffect, useRef } from "react";
-import { Line } from "recharts";
+import { DefaultZIndexes, Line, ZIndexLayer } from "recharts";
 import { useChart } from "./chart-context.js";
 import { useLineInteraction } from "./line-chart.js";
+import { dashCycle, dashDuration } from "./line-dash.js";
 import { MaterialCurve } from "./line-material.js";
+import { PointMarker } from "./point-marker.js";
+import { SeriesInteractionLayer, useSeriesInteraction } from "./series-interaction.js";
 /** A registered Recharts Line with Root colors and controlled visibility. */
-export function LineSeries({ seriesKey, hide, stroke, className, material = "plain", renderWhileHidden = false, ...props }) {
-    const { config, visibleSeries } = useChart();
+export function LineSeries({ seriesKey, pointStyle = "default", activePointStyle: _activePointStyle, hide, stroke, className, material = "plain", dashAnimation = false, renderWhileHidden = false, ...props }) {
+    const { config, paints, visibleSeries } = useChart();
     const { registerSeries, invalidate } = useLineInteraction();
     const generatedId = useId();
     const id = props.id || generatedId;
@@ -29,12 +32,36 @@ export function LineSeries({ seriesKey, hide, stroke, className, material = "pla
     }, [id, key, registerSeries]);
     if (key === undefined && visibleSeries !== undefined)
         throw new Error("LineSeries requires seriesKey for controlled non-string dataKey");
-    const color = stroke ?? (key && Object.hasOwn(config, key) ? `var(--color-${key})` : undefined);
-    return (_jsx(Line, { isAnimationActive: false, ...props, ...(material !== "plain" && props.shape === undefined && props.filter === undefined
-            ? {
-                shape: (_jsx(MaterialCurve, { material: material, filterId: `${generatedId}-material`, materialWidth: props.strokeWidth ?? (material === "clay" ? 6 : material === "paper" ? 2.5 : 3) })),
-                strokeLinecap: props.strokeLinecap ?? (props.strokeDasharray ? "butt" : "round"),
-                strokeLinejoin: props.strokeLinejoin ?? "round",
-            }
-            : {}), id: id, hide: renderedHide, ...(color !== undefined ? { stroke: color } : {}), className: ["kind-ui-line-series", className].filter(Boolean).join(" ") }));
+    const interaction = useSeriesInteraction(key, effectiveHide, hide === true, props.data, props.onClick);
+    const color = stroke ?? (key && Object.hasOwn(config, key) ? paints[key] : undefined);
+    const cycle = dashCycle(props.style?.strokeDasharray ?? props.strokeDasharray);
+    const duration = dashAnimation && dashDuration(dashAnimation);
+    const dashed = dashAnimation !== false &&
+        duration !== undefined &&
+        cycle !== undefined &&
+        !effectiveHide &&
+        props.shape === undefined &&
+        props.isAnimationActive !== true;
+    const offset = props.style?.strokeDashoffset ?? props.strokeDashoffset ?? 0;
+    const baseline = Number.isFinite(Number(offset)) ? `${Number(offset)}px` : offset;
+    return (_jsx(ZIndexLayer, { zIndex: props.zIndex ?? DefaultZIndexes.line, children: _jsx(SeriesInteractionLayer, { seriesKey: key, hidden: effectiveHide, children: _jsx(Line, { isAnimationActive: false, ...props, ...(interaction.onClick !== undefined ? { onClick: interaction.onClick } : {}), zIndex: 0, ...(props.dot === undefined && pointStyle !== "default"
+                    ? { dot: _jsx(PointMarker, { variant: pointStyle }) }
+                    : {}), ...(material !== "plain" && props.shape === undefined && props.filter === undefined
+                    ? {
+                        shape: (_jsx(MaterialCurve, { material: material, filterId: `${generatedId}-material`, materialWidth: props.strokeWidth ??
+                                (material === "clay" ? 6 : material === "paper" ? 2.5 : 3) })),
+                        strokeLinecap: props.strokeLinecap ?? (props.strokeDasharray ? "butt" : "round"),
+                        strokeLinejoin: props.strokeLinejoin ?? "round",
+                    }
+                    : {}), style: dashed
+                    ? {
+                        ...props.style,
+                        "--kind-ui-dash-cycle": `${cycle}px`,
+                        "--kind-ui-dash-offset": baseline,
+                        "--kind-ui-dash-duration": `${duration}ms`,
+                        "--kind-ui-dash-direction": dashAnimation && dashAnimation.direction === "reverse" ? "reverse" : "normal",
+                    }
+                    : props.style, id: id, hide: renderedHide, ...(color !== undefined ? { stroke: color } : {}), className: ["kind-ui-line-series", dashed && "kind-ui-line-dash", className]
+                    .filter(Boolean)
+                    .join(" ") }) }) }));
 }

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

@@ -0,0 +1,6 @@
+export type CartesianLoadingFamily = "area" | "bar" | "combo" | "scatter" | "waterfall" | "histogram" | "box-plot";
+/** Original bounded illustrations: seeded variation never reads consumer data or scales. */
+export declare function CartesianLoadingDesign({ family, seed, }: {
+    family: CartesianLoadingFamily;
+    seed: number;
+}): import("react").JSX.Element;

package/dist/loading-cartesian-designs.js

@@ -0,0 +1,123 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { LoadingPulseMark } from "./loading-motion.js";
+const barProfiles = [
+    [35, 64, 92, 128, 164, 188, 216],
+    [211, 178, 154, 114, 82, 57, 30],
+    [185, 74, 209, 47, 149, 91, 195],
+    [38, 105, 173, 218, 154, 90, 32],
+];
+const curveProfiles = [
+    [208, 181, 142, 115, 88, 51, 27],
+    [28, 52, 89, 116, 145, 180, 209],
+    [39, 88, 172, 210, 168, 87, 35],
+    [190, 51, 158, 33, 194, 74, 142],
+];
+const waterfallProfiles = [
+    [192, 131, 160, 70, 117, 48],
+    [39, 109, 66, 161, 131, 204],
+    [172, 41, 182, 64, 194, 106],
+    [203, 162, 91, 145, 55, 83],
+];
+const boxCenters = [
+    [174, 144, 114, 84, 54],
+    [55, 86, 117, 148, 179],
+    [131, 75, 159, 92, 143],
+    [86, 143, 61, 168, 111],
+];
+const bound = (value, low, high) => Math.max(low, Math.min(high, value));
+/** Original bounded illustrations: seeded variation never reads consumer data or scales. */
+export function CartesianLoadingDesign({ family, seed, }) {
+    const variation = (slot) => {
+        const value = Math.sin(seed * 13.37 + slot * 7.91) * 43758.5453;
+        return (value - Math.floor(value)) * 2 - 1;
+    };
+    const profile = ((Math.trunc(seed) % 4) + 4) % 4;
+    const heights = (barProfiles[profile] ?? barProfiles[0]).map((height, index) => ({
+        x: 16 + index * 91,
+        height: bound(height + variation(index) * 12, 20, 220),
+    }));
+    const ys = (curveProfiles[profile] ?? curveProfiles[0]).map((y, index) => bound(y + variation(index + 20) * 10, 15, 220));
+    let areaCurve = `M 12 ${ys[0] ?? 120}`;
+    for (let index = 1; index < ys.length; index++) {
+        const x = 12 + index * (616 / 6);
+        const previousX = 12 + (index - 1) * (616 / 6);
+        areaCurve += ` C ${previousX + 51} ${ys[index - 1]} ${x - 51} ${ys[index]} ${x} ${ys[index]}`;
+    }
+    if (family === "area")
+        return (_jsx("path", { "data-loading-motion": "reveal", d: `${areaCurve} L 628 238 L 12 238 Z`, fill: "currentColor" }));
+    if (family === "bar")
+        return (_jsx("g", { "data-loading-motion": "grow", children: heights.map(({ x, height }) => (_jsx("rect", { x: x, y: 238 - height, width: 60, height: height, rx: 3, fill: "currentColor" }, x))) }));
+    if (family === "combo")
+        return (_jsxs(_Fragment, { children: [_jsx("g", { "data-loading-motion": "grow", children: heights.map(({ x, height }) => (_jsx("rect", { x: x, y: 238 - height * 0.67, width: 50, height: height * 0.67, rx: 3, fill: "currentColor", opacity: 0.5 }, x))) }), _jsxs("g", { children: [_jsx("path", { "data-loading-motion": "area-reveal", d: `${areaCurve} L 628 238 L 12 238 Z`, fill: "currentColor", opacity: 0.22 }), _jsx("path", { "data-loading-motion": "reveal", d: areaCurve, fill: "none", stroke: "currentColor", strokeWidth: 2.25, vectorEffect: "non-scaling-stroke", strokeLinecap: "round" })] })] }));
+    if (family === "scatter") {
+        const points = Array.from({ length: 24 }, (_, index) => {
+            const u = (variation(index + 50) + 1) / 2;
+            const v = (variation(index + 80) + 1) / 2;
+            let cx;
+            let cy;
+            if (profile === 0 || profile === 1) {
+                cx = 24 + index * 25;
+                cy = profile === 0 ? 211 - index * 7.6 : 28 + index * 7.6;
+                cy += variation(index + 110) * 24;
+            }
+            else if (profile === 2) {
+                const cluster = index % 3;
+                cx = [114, 328, 528][cluster] ?? 328;
+                cy = [166, 62, 159][cluster] ?? 110;
+                cx += (u - 0.5) * 126;
+                cy += (v - 0.5) * 83;
+            }
+            else {
+                cx = 22 + u * 596;
+                cy = 18 + v * 204;
+            }
+            return {
+                id: `point-${index}`,
+                cx: bound(cx, 12, 628),
+                cy: bound(cy, 12, 228),
+                r: 4 + (variation(index + 140) + 1) * 3,
+            };
+        });
+        return (_jsx(_Fragment, { children: points.map(({ id, cx, cy, r }) => (_jsx(LoadingPulseMark, { delay: (cx / 640) * 0.65, span: 0.35, children: _jsx("circle", { "data-loading-motion": "point", cx: cx, cy: cy, r: r, fill: "currentColor" }) }, id))) }));
+    }
+    if (family === "histogram") {
+        const gaussian = (x, peak, spread) => Math.exp(-((x - peak) ** 2) / (2 * spread ** 2));
+        const bins = Array.from({ length: 12 }, (_, index) => {
+            const density = profile === 0
+                ? gaussian(index, 2.5, 1.8)
+                : profile === 1
+                    ? gaussian(index, 8.5, 1.8)
+                    : profile === 2
+                        ? Math.max(gaussian(index, 2, 1.15), gaussian(index, 8.5, 1.5))
+                        : index === 0
+                            ? 0.4
+                            : Math.exp(-(index - 1) / 3.8);
+            return {
+                x: 8 + index * 52,
+                height: bound(18 + density * 194 + variation(index + 170) * 8, 10, 220),
+            };
+        });
+        return (_jsx("g", { "data-loading-motion": "grow", children: bins.map(({ x, height }) => (_jsx("rect", { x: x, y: 238 - height, width: 50, height: height, fill: "currentColor" }, x))) }));
+    }
+    if (family === "waterfall") {
+        const tops = (waterfallProfiles[profile] ?? waterfallProfiles[0]).map((top, index) => bound(top + variation(index + 200) * 9, 16, 220));
+        const levels = [238, ...tops, 238];
+        return (_jsx("g", { "data-loading-motion": "grow", children: levels.slice(1).map((top, index) => {
+                const previous = levels[index] ?? 238;
+                const x = 16 + index * 91;
+                return (_jsxs("g", { children: [_jsx("rect", { x: x, y: Math.min(top, previous), width: 48, height: Math.abs(top - previous), rx: 2, fill: "currentColor" }), index < 6 && (_jsx("path", { d: `M ${x + 48} ${top} H ${x + 91}`, fill: "none", stroke: "currentColor", strokeWidth: 1.5, strokeDasharray: "4 4", vectorEffect: "non-scaling-stroke" }))] }, x));
+            }) }));
+    }
+    const boxes = (boxCenters[profile] ?? boxCenters[0]).map((center, index) => {
+        const median = center + variation(index + 230) * 9;
+        const lowerSpan = 14 + (variation(index + 250) + 1) * 19;
+        const upperSpan = 12 + (variation(index + 270) + 1) * 20;
+        const q1 = bound(median - lowerSpan, 22, median - 6);
+        const q3 = bound(median + upperSpan, median + 6, 216);
+        const low = bound(q1 - 10 - (variation(index + 290) + 1) * 14, 10, q1 - 5);
+        const high = bound(q3 + 10 + (variation(index + 310) + 1) * 14, q3 + 5, 230);
+        return { x: 60 + index * 124, low, q1, median, q3, high };
+    });
+    return (_jsx("g", { "data-loading-motion": "grow", children: boxes.map(({ x, low, q1, median, q3, high }) => (_jsxs("g", { stroke: "currentColor", strokeWidth: 2, vectorEffect: "non-scaling-stroke", children: [_jsx("path", { d: `M ${x} ${low} V ${q1} M ${x} ${q3} V ${high} M ${x - 18} ${low} H ${x + 18} M ${x - 18} ${high} H ${x + 18}`, fill: "none" }), _jsx("rect", { x: x - 27, y: q1, width: 54, height: q3 - q1, fill: "currentColor", fillOpacity: 0.4, rx: 2 }), _jsx("path", { d: `M ${x - 27} ${median} H ${x + 27}`, fill: "none" })] }, x))) }));
+}

package/dist/loading-motion.d.ts

@@ -0,0 +1,37 @@
+import { type MotionValue, type Transition } from "motion/react";
+import { type ReactNode } from "react";
+export type LoadingAnimation = {
+    revealDurationMs?: number;
+    revealEasing?: Transition["ease"];
+    layout?: "horizontal" | "vertical";
+    direction?: "clockwise" | "anticlockwise";
+    lineReveal?: false | Pick<LoadingAnimation, "revealDurationMs" | "revealEasing">;
+    areaReveal?: false | Pick<LoadingAnimation, "revealDurationMs" | "revealEasing">;
+    barReveal?: false | Pick<LoadingAnimation, "revealDurationMs" | "revealEasing">;
+};
+export declare function useLoadingProgress(pulse: number, duration: number, easing: Transition["ease"], startDelay?: number, continuousTrail?: boolean): {
+    progress: MotionValue<number>;
+    reduced: boolean;
+};
+export declare const LoadingProgress: import("react").Context<{
+    progress: MotionValue<number>;
+    reduced: boolean;
+} | null>;
+/** The same screen/diagonal ordering as native scatter and heatmap entrances, with a soft trail. */
+export declare function LoadingPulseMark({ delay, span, children, }: {
+    delay: number;
+    span: number;
+    children: ReactNode;
+}): import("react").JSX.Element;
+export declare function LoadingAngularBand({ progress, index, direction, }: {
+    progress: MotionValue<number>;
+    index: number;
+    direction: "clockwise" | "anticlockwise";
+}): import("react").JSX.Element;
+/** Native Sankey's source ordering and path-length reveal, with a following erase. */
+export declare function LoadingPulseFlow({ d, width, delay, children, }: {
+    d: string;
+    width: number;
+    delay: number;
+    children: ReactNode;
+}): import("react").JSX.Element;

package/dist/loading-motion.js

@@ -0,0 +1,88 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { animate, motion, useMotionValue, useTransform, } from "motion/react";
+import { createContext, use, useId, useLayoutEffect, useRef, useSyncExternalStore, } from "react";
+const query = "(prefers-reduced-motion: reduce)";
+function subscribe(change) {
+    const media = window.matchMedia(query);
+    media.addEventListener("change", change);
+    return () => media.removeEventListener("change", change);
+}
+export function useLoadingProgress(pulse, duration, easing, startDelay = 0, continuousTrail = false) {
+    const reduced = useSyncExternalStore(subscribe, () => window.matchMedia(query).matches, () => true);
+    const progress = useMotionValue(0);
+    const easingCache = useRef(easing);
+    if (Array.isArray(easing) && Array.isArray(easingCache.current)) {
+        if (JSON.stringify(easing) !== JSON.stringify(easingCache.current))
+            easingCache.current = easing;
+    }
+    else if (easing !== easingCache.current)
+        easingCache.current = easing;
+    const stableEasing = easingCache.current;
+    // biome-ignore lint/correctness/useExhaustiveDependencies: a new invisible pulse deliberately rearms the entrance.
+    useLayoutEffect(() => {
+        if (reduced || duration === 0) {
+            progress.set(1);
+            return;
+        }
+        progress.set(0);
+        // RadialBar keeps one angular velocity through the closing seam. Splitting
+        // an eased reveal and a linear trail nearly stops, then abruptly speeds up.
+        if (continuousTrail) {
+            const controls = animate(progress, 1.65, {
+                duration: (duration * 1.65) / 1000,
+                delay: startDelay / 1000,
+                ease: "linear",
+            });
+            return () => controls.stop();
+        }
+        let trail;
+        const controls = animate(progress, 1, {
+            duration: duration / 1000,
+            delay: startDelay / 1000,
+            ease: stableEasing ?? "easeOut",
+            onComplete: () => {
+                trail = animate(progress, 1.65, { duration: (duration * 0.65) / 1000, ease: "linear" });
+            },
+        });
+        return () => {
+            controls.stop();
+            trail?.stop();
+        };
+    }, [progress, pulse, duration, stableEasing, reduced, startDelay, continuousTrail]);
+    return { progress, reduced: reduced || duration === 0 };
+}
+export const LoadingProgress = createContext(null);
+/** The same screen/diagonal ordering as native scatter and heatmap entrances, with a soft trail. */
+export function LoadingPulseMark({ delay, span, children, }) {
+    const context = use(LoadingProgress);
+    const fallback = useMotionValue(1);
+    const opacity = useTransform(context?.progress ?? fallback, (value) => context?.reduced
+        ? 1
+        : Math.max(0, Math.min(1, (value - delay) / span, (delay + span + 0.4 - value) / 0.4)));
+    return (_jsx(motion.g, { "data-kind-ui": "loading-mark", style: { opacity }, children: children }));
+}
+export function LoadingAngularBand({ progress, index, direction, }) {
+    const sign = direction === "anticlockwise" ? -1 : 1;
+    const offset = useTransform(progress, (value) => -sign * value * 100);
+    const opacity = useTransform(progress, (value) => {
+        const angle = value * 360 - index * 18;
+        return (Math.max(0, Math.min(1, angle / 9, (360 - angle) / 9)) * Math.sin(((index + 1) / 9) * Math.PI));
+    });
+    return (_jsx(motion.circle, { "data-kind-ui": "loading-angular", cx: "320", cy: "120", r: "120", fill: "none", stroke: "white", strokeWidth: "240", pathLength: "100", strokeDasharray: "5 95", strokeDashoffset: offset, style: { opacity }, transform: `rotate(${-90 - sign * index * 18} 320 120)` }));
+}
+/** Native Sankey's source ordering and path-length reveal, with a following erase. */
+export function LoadingPulseFlow({ d, width, delay, children, }) {
+    const context = use(LoadingProgress);
+    const fallback = useMotionValue(1);
+    const id = `loading-flow-${useId().replace(/:/g, "")}`;
+    const dash = useTransform(context?.progress ?? fallback, (value) => {
+        if (context?.reduced)
+            return "1 1";
+        const lead = Math.max(0, Math.min(1, (value - delay) / 0.45));
+        const trail = Math.max(0, Math.min(1, (value - delay - 0.45) / 0.4));
+        return `${Math.max(0, lead - trail)} 1`;
+    });
+    const offset = useTransform(context?.progress ?? fallback, (value) => context?.reduced ? 0 : -Math.max(0, Math.min(1, (value - delay - 0.45) / 0.4)));
+    return (_jsxs("g", { children: [_jsx("defs", { children: _jsxs("mask", { id: id, maskUnits: "userSpaceOnUse", x: "0", y: "0", width: "640", height: "240", children: [_jsx("filter", { id: `${id}-soft`, filterUnits: "userSpaceOnUse", x: "-32", y: "-32", width: "704", height: "304", children: _jsx("feGaussianBlur", { stdDeviation: "2" }) }), _jsx(motion.path, { filter: `url(#${id}-soft)`, "data-kind-ui": "loading-flow-window", d: d, fill: "none", stroke: "white", strokeWidth: width + 2, pathLength: "1", strokeDasharray: dash, strokeDashoffset: offset })] }) }), _jsx("g", { mask: `url(#${id})`, children: children })] }));
+}

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

@@ -0,0 +1,6 @@
+export type PolarLoadingFamily = "pie" | "radar" | "radial-bar" | "activity-rings";
+/** A bounded decorative profile, independent of the native chart data. */
+export declare function PolarLoadingDesign({ family, seed, }: {
+    family: PolarLoadingFamily;
+    seed?: number;
+}): import("react").JSX.Element;

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;