@kind-ui/charts 0.1.1 → 0.3.0

package/dist/line-chart.js

@@ -4,6 +4,8 @@ import { createContext, use, useCallback, useId, useLayoutEffect, useRef, useSta
 import { LineChart as EngineLineChart, getRelativeCoordinate, useChartHeight, useChartWidth, } from "recharts";
 import { useChart } from "./chart-context.js";
 import { useEmphasisActions } from "./emphasis.js";
+import { ChartLoadingSkeleton, useLoadingSeed, } from "./loading-skeleton.js";
+import { SeriesColorDefinitions, SeriesPaintBoundary } from "./series-paint.js";
 export const LineInteraction = createContext(null);
 export function useLineInteraction() {
     const value = use(LineInteraction);
@@ -53,7 +55,8 @@ function Lifecycle({ data, invalidate }) {
     }, [width, height, data, visibleSeries, invalidate]);
     return null;
 }
-export function LineChartFrame({ engine: EngineChart, interrupt = () => { }, clip, motionEnabled, categoryEmphasis = false, chartProps: props, children = props.children, }) {
+export function LineChartFrame({ engine: EngineChart, interrupt = () => { }, clip, motionEnabled, categoryEmphasis = false, loading, loadingLabel, loadingSkeleton, loadingAnimation, loadingDesign, chartProps: props, children = props.children, }) {
+    const loadingSeed = useLoadingSeed(loading);
     const { onMouseMove, onMouseLeave } = props;
     const emphasis = useEmphasisActions();
     const frame = useRef(null);
@@ -105,12 +108,36 @@ export function LineChartFrame({ engine: EngineChart, interrupt = () => { }, cli
             return next;
         });
     }, []);
+    const previousLoading = useRef(loading);
+    const completing = previousLoading.current === true && loading !== true;
+    useLayoutEffect(() => {
+        previousLoading.current = loading;
+    });
     const invalidate = useCallback(() => {
         setPointer(null);
         setMotionReady(false);
-        interrupt();
-    }, [interrupt]);
-    return (_jsx(LineInteraction, { value: {
+        if (!completing)
+            interrupt();
+    }, [interrupt, completing]);
+    const chart = (_jsx(SeriesPaintBoundary, { children: _jsxs(EngineChart, { ...props, className: [
+                "kind-ui-line-chart",
+                loading !== undefined && "kind-ui-loading-chart",
+                loading && "kind-ui-loading-chart-pending",
+                props.className,
+            ]
+                .filter(Boolean)
+                .join(" "), style: { ...props.style, "--kind-ui-line-clip": clip ?? "none" }, onMouseMove: (state, event) => {
+                const { relativeX, relativeY } = getRelativeCoordinate(event);
+                setKeyboard(false);
+                setMotionReady(true);
+                setPointer({ x: relativeX, y: relativeY });
+                interrupt();
+                onMouseMove?.(state, event);
+            }, onMouseLeave: (state, event) => {
+                setPointer(null);
+                onMouseLeave?.(state, event);
+            }, children: [_jsx(SeriesColorDefinitions, { viewport: true }), _jsx(Lifecycle, { data: props.data, invalidate: invalidate }), children, loading && loadingSkeleton && (_jsx(ChartLoadingSkeleton, { family: loadingSkeleton, seed: loadingSeed, animation: loadingAnimation, design: loadingDesign }))] }) }));
+    return (_jsxs(LineInteraction, { value: {
             pointer,
             keyboard,
             emphasisScope,
@@ -121,40 +148,33 @@ export function LineChartFrame({ engine: EngineChart, interrupt = () => { }, cli
             invalidate,
             seriesKeys,
             registerSeries,
-        }, children: _jsx("div", { ref: frame, "data-kind-ui": "line-frame", "data-motion": motionEnabled === undefined ? undefined : motionEnabled ? "on" : "off", style: { display: "contents" }, onFocusCapture: (event) => {
-                interrupt();
-                if (event.target.matches(":focus-visible"))
-                    setKeyboard(true);
-            }, onPointerDownCapture: () => {
-                setKeyboard(false);
-                interrupt();
-            }, onPointerLeave: () => emphasis.clearScope(emphasisScope), onPointerCancel: () => emphasis.clearScope(emphasisScope), onPointerOverCapture: () => setKeyboard(false), onPointerMoveCapture: () => {
-                setKeyboard(false);
-                interrupt();
-            }, onKeyDownCapture: (event) => {
-                setKeyboard(event.key !== "Escape");
-                interrupt();
-                setMotionReady(true);
-                setPointer(null);
-            }, onBlurCapture: (event) => {
-                if (!event.currentTarget.contains(event.relatedTarget)) {
-                    setPointer(null);
+        }, children: [_jsx("div", { ref: frame, "aria-busy": loading, "aria-hidden": loading || undefined, inert: loading || undefined, "data-kind-ui": "line-frame", "data-motion": motionEnabled === undefined ? undefined : motionEnabled ? "on" : "off", style: { display: "contents" }, onFocusCapture: (event) => {
+                    interrupt();
+                    if (event.target.matches(":focus-visible"))
+                        setKeyboard(true);
+                }, onPointerDownCapture: () => {
                     setKeyboard(false);
-                    emphasis.clear("keyboard");
-                }
-            }, children: _jsxs(EngineChart, { ...props, className: ["kind-ui-line-chart", props.className].filter(Boolean).join(" "), style: { ...props.style, "--kind-ui-line-clip": clip ?? "none" }, onMouseMove: (state, event) => {
-                    const { relativeX, relativeY } = getRelativeCoordinate(event);
+                    interrupt();
+                }, onPointerLeave: () => emphasis.clearScope(emphasisScope), onPointerCancel: () => emphasis.clearScope(emphasisScope), onPointerOverCapture: () => setKeyboard(false), onPointerMoveCapture: () => {
                     setKeyboard(false);
-                    setMotionReady(true);
-                    setPointer({ x: relativeX, y: relativeY });
                     interrupt();
-                    onMouseMove?.(state, event);
-                }, onMouseLeave: (state, event) => {
+                }, onKeyDownCapture: (event) => {
+                    if ((event.key === "Enter" || event.key === " " || event.key === "Escape") &&
+                        event.target.closest('[data-kind-ui="emphasis-mark"][role="button"], [data-kind-ui="series-interaction"][role="button"]'))
+                        return;
+                    setKeyboard(event.key !== "Escape");
+                    interrupt();
+                    setMotionReady(true);
                     setPointer(null);
-                    onMouseLeave?.(state, event);
-                }, children: [_jsx(Lifecycle, { data: props.data, invalidate: invalidate }), children] }) }) }));
+                }, onBlurCapture: (event) => {
+                    if (!event.currentTarget.contains(event.relatedTarget)) {
+                        setPointer(null);
+                        setKeyboard(false);
+                        emphasis.clear("keyboard");
+                    }
+                }, children: chart }), loading !== undefined && (_jsx("span", { "data-kind-ui": "chart-loading-status", role: "status", "aria-atomic": "true", children: loading ? (loadingLabel ?? "Loading chart") : "" }))] }));
 }
 /** Recharts owns geometry and keyboard selection; Kind shares pointer/keyboard modality. */
-export function LineChart(props) {
-    return _jsx(LineChartFrame, { chartProps: props, engine: EngineLineChart });
+export function LineChart({ loading, loadingLabel, ...props }) {
+    return (_jsx(LineChartFrame, { chartProps: props, engine: EngineLineChart, loading: loading, loadingLabel: loadingLabel, loadingSkeleton: "line" }));
 }

package/dist/line-dash.d.ts

@@ -0,0 +1,8 @@
+/** Timing for one complete numeric dash-pattern cycle. */
+export type LineDashAnimation = {
+    durationMs?: number;
+    direction?: "forward" | "reverse";
+};
+/** Unitless SVG lengths only: native CSS/percentage patterns remain consumer-owned. */
+export declare function dashCycle(pattern: string | number | undefined): number | undefined;
+export declare function dashDuration(options: LineDashAnimation): number | undefined;

package/dist/line-dash.js

@@ -0,0 +1,18 @@
+/** Unitless SVG lengths only: native CSS/percentage patterns remain consumer-owned. */
+export function dashCycle(pattern) {
+    if (pattern === undefined)
+        return undefined;
+    const tokens = String(pattern)
+        .trim()
+        .split(/[\s,]+/);
+    if (!tokens.length || tokens.some((token) => !/^(?:\d+\.?\d*|\.\d+)$/.test(token)))
+        return undefined;
+    const values = tokens.map(Number);
+    const sum = values.reduce((total, value) => total + value, 0);
+    const cycle = sum * (values.length % 2 ? 2 : 1);
+    return Number.isFinite(cycle) && cycle > 0 ? cycle : undefined;
+}
+export function dashDuration(options) {
+    const duration = options.durationMs ?? 1000;
+    return Number.isFinite(duration) && duration > 0 ? duration : undefined;
+}

package/dist/line-material.d.ts

@@ -1,5 +1,5 @@
 import { type LineDrawShapeProps } from "recharts";
-export type LineMaterial = "plain" | "paper" | "clay" | "glow";
+export type LineMaterial = "plain" | "clay" | "glow";
 /** Uses engine points only for filter bounds; Curve retains the original geometry and pathRef. */
 export declare function MaterialCurve({ material, filterId, materialWidth, animationElapsedTime: _time, isAnimating: _active, isEntrance: _entrance, visibleLength: _length, clipPath, ...props }: Omit<LineDrawShapeProps, "pathRef"> & {
     pathRef?: LineDrawShapeProps["pathRef"];

package/dist/line-material.js

@@ -20,5 +20,5 @@ export function MaterialCurve({ material, filterId, materialWidth, animationElap
     const pad = (Number.isFinite(width) ? width : 12) / 2 + 6;
     const x = minX - pad;
     const y = minY - pad;
-    return (_jsxs("g", { "data-kind-ui": "line-material", "data-material": material, clipPath: clipPath, children: [_jsx("defs", { pointerEvents: "none", children: _jsx("filter", { id: filterId, filterUnits: "userSpaceOnUse", x: x, y: y, width: maxX - x + pad, height: maxY - y + pad, colorInterpolationFilters: "sRGB", children: material === "paper" ? (_jsxs(_Fragment, { children: [_jsx("feTurbulence", { type: "fractalNoise", baseFrequency: "0.7 0.25", numOctaves: 1, seed: 7, result: "fiber" }), _jsx("feFlood", { floodColor: "var(--kind-ui-line-paper-fiber, #fff)", floodOpacity: "var(--kind-ui-line-paper-grain, 0.38)" }), _jsx("feComposite", { in2: "fiber", operator: "in", result: "texture" }), _jsx("feComposite", { in: "texture", in2: "SourceAlpha", operator: "in", result: "grain" }), _jsxs("feMerge", { children: [_jsx("feMergeNode", { in: "SourceGraphic" }), _jsx("feMergeNode", { in: "grain" })] })] })) : material === "glow" ? (_jsxs(_Fragment, { children: [_jsx("feGaussianBlur", { in: "SourceGraphic", stdDeviation: 2, result: "halo" }), _jsx("feGaussianBlur", { in: "SourceGraphic", stdDeviation: 0.65, result: "nearHalo" }), _jsx("feFlood", { floodOpacity: "var(--kind-ui-line-glow-opacity, 0.5)", result: "strength" }), _jsx("feComposite", { in: "halo", in2: "strength", operator: "in", result: "softHalo" }), _jsx("feComposite", { in: "nearHalo", in2: "strength", operator: "in", result: "closeHalo" }), _jsx("feMorphology", { in: "SourceAlpha", operator: "erode", radius: 0.55, result: "core" }), _jsx("feFlood", { floodColor: "var(--kind-ui-line-glow-light, #fff)", floodOpacity: 0.5 }), _jsx("feComposite", { in2: "core", operator: "in", result: "lightCore" }), _jsxs("feMerge", { children: [_jsx("feMergeNode", { in: "softHalo" }), _jsx("feMergeNode", { in: "closeHalo" }), _jsx("feMergeNode", { in: "SourceGraphic" }), _jsx("feMergeNode", { in: "lightCore" })] })] })) : (_jsxs(_Fragment, { children: [_jsx("feGaussianBlur", { in: "SourceAlpha", stdDeviation: 0.8, result: "rounded" }), _jsx("feSpecularLighting", { in: "rounded", surfaceScale: 1.5, specularConstant: 0.4, specularExponent: 8, lightingColor: "var(--kind-ui-line-clay-light, #fff)", result: "light", children: _jsx("feDistantLight", { azimuth: 225, elevation: 45 }) }), _jsx("feComposite", { in: "light", in2: "SourceAlpha", operator: "in", result: "bevel" }), _jsx("feOffset", { in: "SourceAlpha", dx: -0.6, dy: -1, result: "offset" }), _jsx("feComposite", { in: "SourceAlpha", in2: "offset", operator: "out", result: "edge" }), _jsx("feFlood", { floodColor: "var(--kind-ui-line-clay-shade, #17212b)", floodOpacity: 0.16 }), _jsx("feComposite", { in2: "edge", operator: "in", result: "shade" }), _jsxs("feMerge", { result: "body", children: [_jsx("feMergeNode", { in: "SourceGraphic" }), _jsx("feMergeNode", { in: "shade" })] }), _jsx("feComposite", { in: "body", in2: "bevel", operator: "arithmetic", k2: 1, k3: 0.7, result: "lit" }), _jsx("feOffset", { in: "rounded", dx: 0, dy: 1.5, result: "dropped" }), _jsx("feFlood", { floodColor: "var(--kind-ui-line-clay-shade, #17212b)", floodOpacity: 0.16 }), _jsx("feComposite", { in2: "dropped", operator: "in", result: "shadow" }), _jsxs("feMerge", { children: [_jsx("feMergeNode", { in: "shadow" }), _jsx("feMergeNode", { in: "lit" })] })] })) }) }), _jsx(Curve, { ...props, strokeWidth: materialWidth, filter: `url(#${filterId})` })] }));
+    return (_jsxs("g", { "data-kind-ui": "line-material", "data-material": material, clipPath: clipPath, children: [_jsx("defs", { pointerEvents: "none", children: _jsx("filter", { id: filterId, filterUnits: "userSpaceOnUse", x: x, y: y, width: maxX - x + pad, height: maxY - y + pad, colorInterpolationFilters: "sRGB", children: material === "glow" ? (_jsxs(_Fragment, { children: [_jsx("feGaussianBlur", { in: "SourceGraphic", stdDeviation: 2, result: "halo" }), _jsx("feGaussianBlur", { in: "SourceGraphic", stdDeviation: 0.65, result: "nearHalo" }), _jsx("feFlood", { floodOpacity: "var(--kind-ui-line-glow-opacity, 0.5)", result: "strength" }), _jsx("feComposite", { in: "halo", in2: "strength", operator: "in", result: "softHalo" }), _jsx("feComposite", { in: "nearHalo", in2: "strength", operator: "in", result: "closeHalo" }), _jsx("feMorphology", { in: "SourceAlpha", operator: "erode", radius: 0.55, result: "core" }), _jsx("feFlood", { floodColor: "var(--kind-ui-line-glow-light, #fff)", floodOpacity: 0.5 }), _jsx("feComposite", { in2: "core", operator: "in", result: "lightCore" }), _jsxs("feMerge", { children: [_jsx("feMergeNode", { in: "softHalo" }), _jsx("feMergeNode", { in: "closeHalo" }), _jsx("feMergeNode", { in: "SourceGraphic" }), _jsx("feMergeNode", { in: "lightCore" })] })] })) : (_jsxs(_Fragment, { children: [_jsx("feGaussianBlur", { in: "SourceAlpha", stdDeviation: 0.8, result: "rounded" }), _jsx("feSpecularLighting", { in: "rounded", surfaceScale: 1.5, specularConstant: 0.4, specularExponent: 8, lightingColor: "var(--kind-ui-line-clay-light, #fff)", result: "light", children: _jsx("feDistantLight", { azimuth: 225, elevation: 45 }) }), _jsx("feComposite", { in: "light", in2: "SourceAlpha", operator: "in", result: "bevel" }), _jsx("feOffset", { in: "SourceAlpha", dx: -0.6, dy: -1, result: "offset" }), _jsx("feComposite", { in: "SourceAlpha", in2: "offset", operator: "out", result: "edge" }), _jsx("feFlood", { floodColor: "var(--kind-ui-line-clay-shade, #17212b)", floodOpacity: 0.16 }), _jsx("feComposite", { in2: "edge", operator: "in", result: "shade" }), _jsxs("feMerge", { result: "body", children: [_jsx("feMergeNode", { in: "SourceGraphic" }), _jsx("feMergeNode", { in: "shade" })] }), _jsx("feComposite", { in: "body", in2: "bevel", operator: "arithmetic", k2: 1, k3: 0.7, result: "lit" }), _jsx("feOffset", { in: "rounded", dx: 0, dy: 1.5, result: "dropped" }), _jsx("feFlood", { floodColor: "var(--kind-ui-line-clay-shade, #17212b)", floodOpacity: 0.16 }), _jsx("feComposite", { in2: "dropped", operator: "in", result: "shadow" }), _jsxs("feMerge", { children: [_jsx("feMergeNode", { in: "shadow" }), _jsx("feMergeNode", { in: "lit" })] })] })) }) }), _jsx(Curve, { ...props, strokeWidth: materialWidth, filter: `url(#${filterId})` })] }));
 }

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,35 @@ 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 : 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;