@kind-ui/charts 0.1.1 → 0.3.0

package/dist/pie-series.js

@@ -1,13 +1,18 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { Children, Fragment, isValidElement, use, useCallback, useId, useLayoutEffect, useRef, useState, } from "react";
+import { Children, cloneElement, Fragment, isValidElement, memo, use, useCallback, useId, useLayoutEffect, useMemo, useRef, useState, } from "react";
 import { Cell, Pie, Sector } from "recharts";
-import { categoryCells } from "./category-cells.js";
+import { categoryCells, filterCategoryRows } from "./category-cells.js";
 import { useChart } from "./chart-context.js";
+import { useChartInteraction, useInteractionFocus } from "./chart-interaction.js";
 import { EmphasisMark } from "./emphasis.js";
 import { useChartKeyboard, useLineInteraction } from "./line-chart.js";
 import { PieMotion } from "./pie-chart.js";
 import { PieMaterialFilter } from "./pie-material.js";
+import { registerPiePinComponent } from "./pie-pin-identity.js";
+// Native Pie keys its animation subtree by props identity even with animation disabled.
+// Pointer/pin context updates must not replace an unchanged pressed native sector.
+const StablePie = memo(Pie);
 // Recharts also supports Cell props as data when neither the chart nor Pie supplies rows.
 function cellProps(children) {
     const result = [];
@@ -30,11 +35,45 @@ function sameCells(previous, next) {
                 Object.keys(props).every((key) => Object.is(old[key], props[key])));
         }));
 }
+// Capture original rendered identity before an inner Cell handler can commit new rows.
+function captureCellIdentity(children, keyAt, identities) {
+    let index = 0;
+    function capture(parts) {
+        return Children.map(parts, (child) => {
+            if (!isValidElement(child))
+                return child;
+            if (child.type === Fragment)
+                return cloneElement(child, {}, capture(child.props.children));
+            if (child.type !== Cell)
+                return child;
+            const key = keyAt(index++);
+            if (key === undefined)
+                return child;
+            return cloneElement(child, {
+                onClick: (event) => {
+                    identities.set(event.nativeEvent, key);
+                    child.props.onClick?.(event);
+                },
+            });
+        });
+    }
+    return capture(children);
+}
 // One chart-level angular window reveals unchanged native sectors.
-function EntranceSector({ material, emphasisKey, scope, enabled, seriesStartAngle, seriesEndAngle, ...props }) {
+function EntranceSector({ material, emphasisKey, scope, enabled, interactionKey, seriesStartAngle, seriesEndAngle, ...props }) {
     const keyboard = useChartKeyboard();
+    const interaction = useChartInteraction();
     const { reveal, progress, direction } = use(PieMotion);
-    const semantic = emphasisKey ? emphasisKey(props.payload) : props.name;
+    const semantic = interactionKey
+        ? interactionKey(props.index ?? -1)
+        : emphasisKey
+            ? emphasisKey(props.payload)
+            : props.name;
+    const interactive = interactionKey !== undefined &&
+        interaction.interactive &&
+        interaction.markActivation &&
+        interaction.eligible.includes(String(semantic));
+    const focusRef = useInteractionFocus(String(semantic), interactive);
     const generatedId = useId();
     const sourceId = `kind-ui-pie-${generatedId.replace(/[^a-zA-Z0-9_-]/g, "_")}-paint`;
     const maskId = `${sourceId}-alpha`;
@@ -45,7 +84,7 @@ function EntranceSector({ material, emphasisKey, scope, enabled, seriesStartAngl
     const markGroup = useRef(null);
     const [paintFilter, setPaintFilter] = useState("none");
     const [paintClip, setPaintClip] = useState("none");
-    // Measure native ownership before attaching paint, including the first non-Plain render.
+    // Measure native ownership before attaching paint, including the first non-default render.
     const [cssTransformOwned, setCssTransformOwned] = useState();
     const [clipTransform, setClipTransform] = useState({ forward: "", inverse: "" });
     const [paintBounds, setPaintBounds] = useState();
@@ -151,25 +190,102 @@ function EntranceSector({ material, emphasisKey, scope, enabled, seriesStartAngl
     const revealStart = fromStart ? seriesStartAngle : seriesStartAngle + nativeSpan;
     const revealSpan = Math.abs(nativeSpan) * (clockwise ? -1 : 1);
     const { className, cornerRadius, onClick, onMouseDown, onMouseUp, onMouseMove, onMouseOver, onMouseOut, onMouseEnter, onMouseLeave, ...sector } = props;
-    return (_jsx(EmphasisMark, { enabled: enabled &&
-            (emphasisKey !== undefined ? semantic !== undefined : typeof semantic === "string"), target: { kind: "sector", key: String(semantic), scope, seriesKey: String(semantic) }, keyboardActive: keyboard && props.isActive, children: _jsxs("g", { ref: markGroup, children: [maskEntrance && (_jsx("defs", { children: _jsx("mask", { id: entranceId, maskUnits: "userSpaceOnUse", x: props.cx - props.outerRadius - margin, y: props.cy - props.outerRadius - margin, width: (props.outerRadius + margin) * 2, height: (props.outerRadius + margin) * 2, style: { maskType: "alpha" }, children: _jsx(Sector, { fill: "white", "data-kind-ui": "pie-entrance-window", "data-direction": direction, "data-progress": progress, cx: props.cx, cy: props.cy, innerRadius: 0, outerRadius: props.outerRadius + margin, startAngle: revealStart, endAngle: revealStart + revealSpan * progress }) }) })), _jsxs("g", { mask: maskEntrance ? `url(#${entranceId})` : undefined, children: [materialized && (_jsxs("defs", { "data-kind-ui": "pie-material", "data-material": material, pointerEvents: "none", children: [_jsx(PieMaterialFilter, { material: material, id: filterId, strokeWidth: Math.max(0, Number.isFinite(resolvedStroke) ? resolvedStroke : 0, paintStroke), cx: props.cx, cy: props.cy, radius: props.outerRadius, thickness: props.outerRadius - props.innerRadius, bounds: paintBounds }), inset && (_jsx("mask", { id: maskId, maskUnits: "userSpaceOnUse", x: paintBounds?.x ?? Math.floor(props.cx - props.outerRadius - margin), y: paintBounds?.y ?? Math.floor(props.cy - props.outerRadius - margin), width: paintBounds?.width ?? Math.ceil(props.outerRadius * 2 + margin * 2) + 1, height: paintBounds?.height ?? Math.ceil(props.outerRadius * 2 + margin * 2) + 1, style: { maskType: "alpha" }, children: _jsx("use", { href: `#${sourceId}` }) }))] })), materialized && material === "glow" && (
+    return (_jsx(EmphasisMark, { ref: focusRef, "data-interaction-focus-key": interactive ? String(semantic) : undefined, persistent: interactionKey !== undefined, enabled: enabled &&
+            (emphasisKey !== undefined ? semantic !== undefined : typeof semantic === "string"), target: { kind: "sector", key: String(semantic), scope, seriesKey: String(semantic) }, keyboardActive: keyboard && props.isActive === true, role: interactive ? "button" : undefined, tabIndex: interactive ? 0 : undefined, "aria-label": interactive
+            ? `${interaction.mode === "focus" ? "Highlight" : "Toggle"} ${String(semantic)}`
+            : undefined, "aria-pressed": interactive
+            ? interaction.mode === "focus"
+                ? interaction.selected === semantic
+                : true
+            : undefined, onKeyDown: (event) => {
+            if (interactive &&
+                event.target === event.currentTarget &&
+                !event.defaultPrevented &&
+                (event.key === "Enter" || event.key === " ")) {
+                if (!event.repeat)
+                    interaction.activate({ kind: "category", key: String(semantic) }, "mark", event);
+                event.preventDefault();
+            }
+        }, children: _jsxs("g", { ref: markGroup, children: [maskEntrance && (_jsx("defs", { children: _jsx("mask", { id: entranceId, maskUnits: "userSpaceOnUse", x: props.cx - props.outerRadius - margin, y: props.cy - props.outerRadius - margin, width: (props.outerRadius + margin) * 2, height: (props.outerRadius + margin) * 2, style: { maskType: "alpha" }, children: _jsx(Sector, { fill: "white", "data-kind-ui": "pie-entrance-window", "data-direction": direction, "data-progress": progress, cx: props.cx, cy: props.cy, innerRadius: 0, outerRadius: props.outerRadius + margin, startAngle: revealStart, endAngle: revealStart + revealSpan * progress }) }) })), _jsxs("g", { mask: maskEntrance ? `url(#${entranceId})` : undefined, children: [materialized && (_jsxs("defs", { "data-kind-ui": "pie-material", "data-material": material, pointerEvents: "none", children: [_jsx(PieMaterialFilter, { material: material, id: filterId, strokeWidth: Math.max(0, Number.isFinite(resolvedStroke) ? resolvedStroke : 0, paintStroke), cx: props.cx, cy: props.cy, radius: props.outerRadius, thickness: props.outerRadius - props.innerRadius, bounds: paintBounds }), inset && (_jsx("mask", { id: maskId, maskUnits: "userSpaceOnUse", x: paintBounds?.x ?? Math.floor(props.cx - props.outerRadius - margin), y: paintBounds?.y ?? Math.floor(props.cy - props.outerRadius - margin), width: paintBounds?.width ?? Math.ceil(props.outerRadius * 2 + margin * 2) + 1, height: paintBounds?.height ?? Math.ceil(props.outerRadius * 2 + margin * 2) + 1, style: { maskType: "alpha" }, children: _jsx("use", { href: `#${sourceId}` }) }))] })), materialized && material === "glow" && (
                         // biome-ignore lint/a11y/noAriaHiddenOnFocusable: SVG decoration is explicitly nonfocusable and ignores pointer events.
-                        _jsx("g", { pointerEvents: "none", focusable: "false", "aria-hidden": "true", "data-kind-ui": "pie-halo", style: { clipPath: paintClip }, transform: paintClip !== "none" ? clipTransform.forward : undefined, children: _jsx("g", { transform: paintClip !== "none" ? clipTransform.inverse : undefined, filter: `url(#${filterId})`, children: _jsx("use", { href: `#${sourceId}` }) }) })), _jsx("g", { ...(inset ? { filter: `url(#${filterId})` } : {}), ...(inset ? { mask: `url(#${maskId})` } : {}), children: _jsxs("g", { id: sourceId, children: [materialized && (_jsx("rect", { x: paintBounds?.x ?? props.cx - props.outerRadius - margin, y: paintBounds?.y ?? props.cy - props.outerRadius - margin, width: paintBounds?.width ?? props.outerRadius * 2 + margin * 2, height: paintBounds?.height ?? props.outerRadius * 2 + margin * 2, fill: "white", fillOpacity: 0, pointerEvents: "none" })), _jsx(Sector, { ...sector, ...(onClick ? { onClick } : {}), ...(onMouseDown ? { onMouseDown } : {}), ...(onMouseUp ? { onMouseUp } : {}), ...(onMouseMove ? { onMouseMove } : {}), ...(onMouseOver ? { onMouseOver } : {}), ...(onMouseOut ? { onMouseOut } : {}), ...(onMouseEnter ? { onMouseEnter } : {}), ...(onMouseLeave ? { onMouseLeave } : {}), ...(className !== undefined ? { className } : {}), ...(cornerRadius !== undefined ? { cornerRadius } : {}), "data-kind-ui": "pie-sector", "data-reveal": maskEntrance ? "on" : "off" })] }) })] })] }) }));
+                        _jsx("g", { pointerEvents: "none", focusable: "false", "aria-hidden": "true", "data-kind-ui": "pie-halo", style: { clipPath: paintClip }, transform: paintClip !== "none" ? clipTransform.forward : undefined, children: _jsx("g", { transform: paintClip !== "none" ? clipTransform.inverse : undefined, filter: `url(#${filterId})`, children: _jsx("use", { href: `#${sourceId}` }) }) })), _jsx("g", { ...(inset ? { filter: `url(#${filterId})` } : {}), ...(inset ? { mask: `url(#${maskId})` } : {}), children: _jsxs("g", { id: sourceId, children: [materialized && (_jsx("rect", { x: paintBounds?.x ?? props.cx - props.outerRadius - margin, y: paintBounds?.y ?? props.cy - props.outerRadius - margin, width: paintBounds?.width ?? props.outerRadius * 2 + margin * 2, height: paintBounds?.height ?? props.outerRadius * 2 + margin * 2, fill: "white", fillOpacity: 0, pointerEvents: "none" })), _jsx(Sector, { ...sector, ...(onClick ? { onClick } : {}), ...(onMouseDown ? { onMouseDown } : {}), ...(onMouseUp ? { onMouseUp } : {}), ...(onMouseMove ? { onMouseMove } : {}), ...(onMouseOver ? { onMouseOver } : {}), ...(onMouseOut ? { onMouseOut } : {}), ...(onMouseEnter ? { onMouseEnter } : {}), ...(onMouseLeave ? { onMouseLeave } : {}), ...(className !== undefined ? { className } : {}), ...(cornerRadius !== undefined ? { cornerRadius } : {}), "data-kind-ui": "pie-sector", "data-sector-span": props.endAngle - props.startAngle, "data-reveal": maskEntrance ? "on" : "off" })] }) })] })] }) }));
 }
 /** A native Pie. Use innerRadius for donuts; category data, Cells and visibility are consumer-owned. */
 export function PieSeries(props) {
-    const { material = "plain", emphasisKey, categoryKey, ...nativeProps } = props;
-    const { config } = useChart();
-    const children = categoryKey === undefined
-        ? props.children
-        : categoryCells(props.data, categoryKey, config, props.children, props.fill);
+    const { material = "plain", glowCategories, emphasisKey, categoryKey, interactionBinding, ...nativeProps } = props;
+    const interaction = useChartInteraction();
+    if (interactionBinding &&
+        (interaction.kind !== "category" || categoryKey === undefined || props.data === undefined))
+        throw new Error("PieSeries Root interaction binding requires category-kind Root, categoryKey and explicit data");
+    const filtered = useMemo(() => interactionBinding && props.data && categoryKey !== undefined
+        ? filterCategoryRows(props.data, categoryKey, interaction.visible, props.children)
+        : undefined, [interactionBinding, props.data, categoryKey, interaction.visible, props.children]);
+    const data = filtered?.data ?? props.data;
+    const originalChildren = filtered?.children ?? props.children;
+    const resolveInteractionKey = useCallback((index) => {
+        // Cell props can override native payload fields; native index still addresses our rendered rows.
+        const row = data?.[index];
+        if (row === undefined)
+            return undefined;
+        if (typeof categoryKey === "function")
+            return categoryKey(row);
+        if (categoryKey !== undefined &&
+            typeof row === "object" &&
+            row !== null &&
+            Object.hasOwn(row, categoryKey))
+            return String(row[categoryKey]);
+        throw new Error("PieSeries interaction requires a stable category key");
+    }, [categoryKey, data]);
+    const interactionKey = interactionBinding ? resolveInteractionKey : undefined;
+    const { config, paints } = useChart();
+    const children = useMemo(() => categoryKey === undefined
+        ? originalChildren
+        : categoryCells(data, categoryKey, config, paints, originalChildren, props.fill), [categoryKey, data, config, paints, originalChildren, props.fill]);
+    const identities = useRef(new WeakMap());
+    const boundChildren = useMemo(() => interactionKey && interaction.interactive && interaction.markActivation
+        ? captureCellIdentity(children, interactionKey, identities.current)
+        : children, [children, interactionKey, interaction.interactive, interaction.markActivation]);
+    const latestClick = useRef({ handler: props.onClick, interactionKey, interaction });
+    useLayoutEffect(() => {
+        latestClick.current = { handler: props.onClick, interactionKey, interaction };
+    });
+    const activate = useCallback((...args) => {
+        // Capture the pressed row before a consumer can synchronously reorder/filter the data.
+        const pressed = latestClick.current;
+        const key = identities.current.get(args[2].nativeEvent) ?? pressed.interactionKey?.(args[1]);
+        pressed.handler?.(...args);
+        if (key !== undefined)
+            latestClick.current.interaction.activate({ kind: "category", key }, "mark", args[2]);
+    }, []);
+    const onClick = interactionBinding && interaction.interactive && interaction.markActivation
+        ? activate
+        : props.onClick;
+    if (glowCategories !== undefined && categoryKey === undefined)
+        throw new Error("glowCategories requires categoryKey and explicit series data");
+    // Native sector indices align with explicit data, but membership uses the original
+    // row identity, before native Cell props can override payload fields.
+    const glowRows = useMemo(() => {
+        if (categoryKey === undefined || glowCategories === undefined)
+            return undefined;
+        const glowing = new Set(glowCategories);
+        return data?.map((row) => {
+            const key = typeof categoryKey === "function"
+                ? categoryKey(row)
+                : row !== null && typeof row === "object" && Object.hasOwn(row, categoryKey)
+                    ? row[categoryKey]
+                    : undefined;
+            return typeof key === "string" && glowing.has(key);
+        });
+    }, [data, categoryKey, glowCategories]);
     const seriesId = useId();
     const { invalidate, emphasisScope } = useLineInteraction();
     const scope = `${emphasisScope}/${seriesId}`;
-    const sectorShape = useCallback((sector) => (_jsx(EntranceSector, { ...sector, material: material, scope: scope, emphasisKey: emphasisKey, enabled: props.activeShape === undefined && props.inactiveShape === undefined, seriesStartAngle: props.startAngle ?? 0, seriesEndAngle: props.endAngle ?? 360 })), [
+    const sectorShape = useCallback((sector) => (_jsx(EntranceSector, { ...sector, material: sector.index !== undefined && glowRows?.[sector.index] ? "glow" : material, interactionKey: interactionKey, scope: scope, emphasisKey: emphasisKey, enabled: props.activeShape === undefined && props.inactiveShape === undefined, seriesStartAngle: props.startAngle ?? 0, seriesEndAngle: props.endAngle ?? 360 })), [
         material,
+        glowRows,
         scope,
         emphasisKey,
+        interactionKey,
         props.activeShape,
         props.inactiveShape,
         props.startAngle,
@@ -193,6 +309,8 @@ export function PieSeries(props) {
         props.activeShape,
         props.inactiveShape,
         material,
+        categoryKey,
+        glowCategories,
     ];
     const cells = cellProps(props.children);
     const previousCells = useRef(cells);
@@ -204,5 +322,10 @@ export function PieSeries(props) {
         previousCells.current = cells;
         previous.current = inputs;
     });
-    return (_jsx(Pie, { ...nativeProps, stroke: props.stroke ?? "none", shape: props.shape ?? sectorShape, isAnimationActive: false, children: children }));
+    return (_jsx(StablePie, { ...nativeProps, ...(data !== undefined ? { data } : {}), ...(onClick !== undefined ? { onClick } : {}), stroke: props.stroke ?? "none", shape: props.shape ?? sectorShape, ...(interactionBinding && props.shape === undefined && props.activeShape === undefined
+            ? { activeShape: sectorShape }
+            : {}), ...(interactionBinding && props.shape === undefined && props.inactiveShape === undefined
+            ? { inactiveShape: sectorShape }
+            : {}), isAnimationActive: false, children: boundChildren }));
 }
+registerPiePinComponent(PieSeries, "series");

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

@@ -0,0 +1,4 @@
+import { type ReactNode } from "react";
+export declare const PieTooltipPin: import("react").Context<number | undefined>;
+/** Resolve against current rows; the returned index is never retained as identity. */
+export declare function pinnedPieIndex(children: ReactNode, category: string, visibleSeries?: readonly string[]): number | undefined;

package/dist/pie-tooltip-pin.js

@@ -0,0 +1,52 @@
+"use client";
+import { Children, createContext, Fragment, isValidElement } from "react";
+import { piePinComponentKind } from "./pie-pin-identity.js";
+export const PieTooltipPin = createContext(undefined);
+/** Resolve against current rows; the returned index is never retained as identity. */
+export function pinnedPieIndex(children, category, visibleSeries) {
+    const series = [];
+    let tooltips = 0;
+    let unsupported = false;
+    function collect(nodes) {
+        Children.forEach(nodes, (child) => {
+            if (!isValidElement(child)) {
+                if (child !== null && child !== undefined && typeof child !== "boolean")
+                    unsupported = true;
+                return;
+            }
+            if (child.type === Fragment)
+                collect(child.props.children);
+            else if (piePinComponentKind(child.type) === "series")
+                series.push(child.props);
+            else if (piePinComponentKind(child.type) === "tooltip")
+                tooltips += 1;
+            else
+                unsupported = true;
+        });
+    }
+    collect(children);
+    const candidate = series[0];
+    if (series.length !== 1 ||
+        tooltips !== 1 ||
+        unsupported ||
+        !candidate?.data ||
+        candidate.categoryKey === undefined)
+        throw new Error("defaultPinnedCategory requires one direct PieSeries with explicit data and categoryKey, and one direct Tooltip");
+    const { data, categoryKey, hide } = candidate;
+    if (hide)
+        return undefined;
+    const keys = data.map((row) => typeof categoryKey === "function"
+        ? categoryKey(row)
+        : row !== null && typeof row === "object" && Object.hasOwn(row, categoryKey)
+            ? row[categoryKey]
+            : undefined);
+    // Ambiguous identities are never silently resolved by position, including hidden rows.
+    if (keys.filter((key) => key === category).length !== 1)
+        return undefined;
+    // Only a bound Pie filters its native data. Unbound composition keeps its original indices.
+    const renderedKeys = candidate.interactionBinding === "root" && visibleSeries !== undefined
+        ? keys.filter((key) => typeof key === "string" && visibleSeries.includes(key))
+        : keys;
+    const index = renderedKeys.indexOf(category);
+    return index < 0 ? undefined : index;
+}

package/dist/point-marker.d.ts

@@ -0,0 +1,19 @@
+import { type DotProps } from "recharts";
+export type PointStyle = "default" | "border" | "colored-border";
+export type PointMarkerProps = DotProps & {
+    variant?: PointStyle | undefined;
+};
+/** Paint only: native coordinates, radius, events and inspection remain owned by Recharts. */
+export declare function markerPaint(variant: PointStyle, color: string | undefined): {
+    fill?: never;
+    stroke?: never;
+    strokeWidth?: never;
+    strokeDasharray?: never;
+} | {
+    fill: string | undefined;
+    stroke: string | undefined;
+    strokeWidth: number;
+    strokeDasharray: string;
+};
+/** Native Dot renderer: variant paint wins engine paint; SVG style remains consumer-owned. */
+export declare function PointMarker({ variant, ...props }: PointMarkerProps): import("react").JSX.Element;

package/dist/point-marker.js

@@ -0,0 +1,19 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Dot } from "recharts";
+/** Paint only: native coordinates, radius, events and inspection remain owned by Recharts. */
+export function markerPaint(variant, color) {
+    if (variant === "default")
+        return {};
+    const surface = "var(--kind-ui-chart-marker-surface, var(--card, white))";
+    return {
+        fill: variant === "border" ? color : surface,
+        stroke: variant === "border" ? surface : color,
+        strokeWidth: 2,
+        strokeDasharray: "none",
+    };
+}
+/** Native Dot renderer: variant paint wins engine paint; SVG style remains consumer-owned. */
+export function PointMarker({ variant = "default", ...props }) {
+    return (_jsx(Dot, { ...props, ...markerPaint(variant, props.stroke ?? props.fill), "data-kind-ui": "point-marker", "data-point-style": variant }));
+}

package/dist/polar-chart.d.ts

@@ -1,17 +1,22 @@
 import { type ComponentProps } from "react";
 import { RadarChart as EngineRadarChart, RadialBarChart as EngineRadialBarChart } from "recharts";
-import { type LineAnimation } from "./animation.js";
+import { type BaseAnimation } from "./animation.js";
 import type { CategoryKey } from "./category-cells.js";
 import { type RadarSelectionProps } from "./radar-interaction.js";
-export type RadarAnimation = LineAnimation;
-export type RadialBarAnimation = LineAnimation;
+export type RadarAnimation = BaseAnimation;
+export type RadialBarAnimation = BaseAnimation;
 export type RadarChartProps<DataPoint = unknown> = ComponentProps<typeof EngineRadarChart<DataPoint>> & RadarSelectionProps & {
     animate?: boolean | RadarAnimation | undefined;
+    loading?: boolean | undefined;
+    loadingLabel?: string | undefined;
 };
 export type RadialBarChartProps<DataPoint = unknown> = ComponentProps<typeof EngineRadialBarChart<DataPoint>> & {
     /** Opt-in category colors from Root.config, resolved from original chart rows. */
     categoryKey?: CategoryKey<DataPoint> | undefined;
+    interactionBinding?: "root";
     animate?: boolean | RadialBarAnimation | undefined;
+    loading?: boolean | undefined;
+    loadingLabel?: string | undefined;
     /** Entrance direction only; native chart and axis angles stay consumer-owned. */
     animationDirection?: "clockwise" | "anticlockwise" | undefined;
 };
@@ -29,5 +34,9 @@ export declare const RadialMotion: import("react").Context<{
     direction: "clockwise" | "anticlockwise";
 }>;
 /** Native polar composition with shared metadata, interaction and optional Motion. */
-export declare function RadarChart<DataPoint = unknown>({ animate, selection, selectedSeries, onSelectedSeriesChange, children, ...props }: RadarChartProps<DataPoint>): import("react").JSX.Element;
-export declare function RadialBarChart<DataPoint = unknown>({ animate, animationDirection, categoryKey, children, ...props }: RadialBarChartProps<DataPoint>): import("react").JSX.Element;
+export declare function RadarChart<DataPoint = unknown>({ animate, loading, loadingLabel, selection, selectedSeries, onSelectedSeriesChange, children, ...props }: RadarChartProps<DataPoint>): import("react").JSX.Element;
+export declare function RadialBarChart<DataPoint = unknown>(props: RadialBarChartProps<DataPoint>): import("react").JSX.Element;
+/** Private recipe integration; the public chart keeps its native prop contract. */
+export declare function RadialBarChartFrame<DataPoint = unknown>({ skeletonFamily, animate, loading, loadingLabel, animationDirection, categoryKey, interactionBinding, children, ...props }: RadialBarChartProps<DataPoint> & {
+    skeletonFamily?: "radial-bar" | "activity-rings";
+}): import("react").JSX.Element;

package/dist/polar-chart.js

@@ -4,7 +4,10 @@ import { animate as animateValue } from "motion/react";
 import { createContext, useCallback, useLayoutEffect, useRef, useState, useSyncExternalStore, } from "react";
 import { RadarChart as EngineRadarChart, RadialBarChart as EngineRadialBarChart } from "recharts";
 import { MotionContext } from "./animation.js";
+import { filterCategoryRows } from "./category-cells.js";
+import { useChartInteraction } from "./chart-interaction.js";
 import { LineChartFrame, useLineInteraction } from "./line-chart.js";
+import { PolarLoadingDesign } from "./loading-polar-designs.js";
 import { RadarSelectionProvider } from "./radar-interaction.js";
 import { RadialCategory } from "./radial-category.js";
 export const PolarMotion = createContext({
@@ -26,11 +29,18 @@ function subscribe(change) {
 const snapshot = () => window.matchMedia(query).matches;
 const serverSnapshot = () => true;
 const defaultHover = { type: "spring", stiffness: 210, damping: 28, mass: 0.8 };
-function usePolarMotion(animate) {
+function usePolarMotion(animate, loading) {
     const reduced = useSyncExternalStore(subscribe, snapshot, serverSnapshot);
     const [finished, setFinished] = useState(false);
-    const interrupt = useCallback(() => setFinished(true), []);
-    const enabled = animate !== false && !reduced;
+    const interrupt = useCallback(() => {
+        if (!loading)
+            setFinished(true);
+    }, [loading]);
+    useLayoutEffect(() => {
+        if (loading)
+            setFinished(false);
+    }, [loading]);
+    const enabled = animate !== false && !reduced && !loading;
     const options = typeof animate === "object" ? animate : {};
     return { enabled, options, reveal: enabled && !finished, interrupt };
 }
@@ -62,12 +72,16 @@ function PolarLifecycle({ layout, cx, cy, innerRadius, outerRadius, startAngle,
     return null;
 }
 /** Native polar composition with shared metadata, interaction and optional Motion. */
-export function RadarChart({ animate = false, selection, selectedSeries, onSelectedSeriesChange, children, ...props }) {
-    const { enabled, options, reveal, interrupt } = usePolarMotion(animate);
+export function RadarChart({ animate = false, loading, loadingLabel, selection, selectedSeries, onSelectedSeriesChange, children, ...props }) {
+    const { enabled, options, reveal, interrupt } = usePolarMotion(animate, loading);
     const [progress, setProgress] = useState(1);
     const duration = options.revealDurationMs ?? 1000;
     const easing = options.revealEasing ?? "easeOut";
     const started = useRef(false);
+    useLayoutEffect(() => {
+        if (loading)
+            started.current = false;
+    }, [loading]);
     const previous = useRef([duration, easing]);
     const previousEnabled = useRef(enabled);
     useLayoutEffect(() => {
@@ -93,15 +107,28 @@ export function RadarChart({ animate = false, selection, selectedSeries, onSelec
         });
         return () => controls.stop();
     }, [reveal, duration, easing, interrupt]);
-    return (_jsx(MotionContext, { value: { enabled, transition: options.hoverTransition ?? defaultHover }, children: _jsx(RadarMotion, { value: { reveal, progress }, children: _jsx(PolarMotion, { value: { reveal, options }, children: _jsx(RadarSelectionProvider, { selection: selection, selectedSeries: selectedSeries, onSelectedSeriesChange: onSelectedSeriesChange, children: _jsxs(LineChartFrame, { engine: (EngineRadarChart), chartProps: props, motionEnabled: enabled, interrupt: interrupt, children: [_jsx(PolarLifecycle, { ...props, children: children }), children] }) }) }) }) }));
+    return (_jsx(MotionContext, { value: { enabled, transition: options.hoverTransition ?? defaultHover }, children: _jsx(RadarMotion, { value: { reveal, progress }, children: _jsx(PolarMotion, { value: { reveal, options }, children: _jsx(RadarSelectionProvider, { selection: selection, selectedSeries: selectedSeries, onSelectedSeriesChange: onSelectedSeriesChange, children: _jsxs(LineChartFrame, { engine: (EngineRadarChart), loading: loading, loadingLabel: loadingLabel, loadingSkeleton: "radar", loadingDesign: (seed) => _jsx(PolarLoadingDesign, { family: "radar", seed: seed }), loadingAnimation: options, chartProps: props, motionEnabled: enabled, interrupt: interrupt, children: [_jsx(PolarLifecycle, { ...props, children: children }), children] }) }) }) }) }));
 }
-export function RadialBarChart({ animate = false, animationDirection = "clockwise", categoryKey, children, ...props }) {
+export function RadialBarChart(props) {
+    return _jsx(RadialBarChartFrame, { ...props });
+}
+/** Private recipe integration; the public chart keeps its native prop contract. */
+export function RadialBarChartFrame({ skeletonFamily = "radial-bar", animate = false, loading, loadingLabel, animationDirection = "clockwise", categoryKey, interactionBinding, children, ...props }) {
+    const interaction = useChartInteraction();
+    if (interactionBinding &&
+        (interaction.kind !== "category" || categoryKey === undefined || props.data === undefined))
+        throw new Error("RadialBarChart Root interaction binding requires category-kind Root, categoryKey and explicit data");
+    const filtered = interactionBinding && categoryKey !== undefined && props.data
+        ? filterCategoryRows(props.data, categoryKey, interaction.visible, null)
+        : undefined;
     if (categoryKey !== undefined && props.data === undefined)
         throw new Error("RadialBarChart categoryKey requires explicit chart data");
     const categories = categoryKey === undefined
         ? null
         : {
-            data: props.data ?? [],
+            data: filtered?.data ?? props.data ?? [],
+            originalData: props.data ?? [],
+            bound: interactionBinding === "root",
             key: (row) => {
                 if (typeof categoryKey === "function")
                     return categoryKey(row);
@@ -110,11 +137,15 @@ export function RadialBarChart({ animate = false, animationDirection = "clockwis
                     : "";
             },
         };
-    const { enabled, options, reveal, interrupt } = usePolarMotion(animate);
+    const { enabled, options, reveal, interrupt } = usePolarMotion(animate, loading);
     const [progress, setProgress] = useState(1);
     const duration = options.revealDurationMs ?? 1000;
     const easing = options.revealEasing ?? "easeOut";
     const started = useRef(false);
+    useLayoutEffect(() => {
+        if (loading)
+            started.current = false;
+    }, [loading]);
     const previous = useRef([duration, easing, animationDirection]);
     const previousEnabled = useRef(enabled);
     useLayoutEffect(() => {
@@ -141,5 +172,5 @@ export function RadialBarChart({ animate = false, animationDirection = "clockwis
         });
         return () => controls.stop();
     }, [reveal, duration, easing, interrupt]);
-    return (_jsx(RadialCategory, { value: categories, children: _jsx(MotionContext, { value: { enabled, transition: options.hoverTransition ?? defaultHover }, children: _jsx(RadialMotion, { value: { reveal, progress, direction: animationDirection }, children: _jsx(PolarMotion, { value: { reveal, options }, children: _jsxs(LineChartFrame, { engine: (EngineRadialBarChart), chartProps: props, motionEnabled: enabled, interrupt: interrupt, children: [_jsx(PolarLifecycle, { ...props, children: children }), children] }) }) }) }) }));
+    return (_jsx(RadialCategory, { value: categories, children: _jsx(MotionContext, { value: { enabled, transition: options.hoverTransition ?? defaultHover }, children: _jsx(RadialMotion, { value: { reveal, progress, direction: animationDirection }, children: _jsx(PolarMotion, { value: { reveal, options }, children: _jsxs(LineChartFrame, { engine: (EngineRadialBarChart), loading: loading, loadingLabel: loadingLabel, loadingSkeleton: skeletonFamily, loadingDesign: (seed) => _jsx(PolarLoadingDesign, { family: skeletonFamily, seed: seed }), loadingAnimation: { ...options, direction: animationDirection }, chartProps: { ...props, ...(filtered ? { data: filtered.data } : {}) }, motionEnabled: enabled, interrupt: interrupt, children: [_jsx(PolarLifecycle, { ...props, children: children }), children] }) }) }) }) }));
 }

package/dist/polar-material.js

@@ -5,5 +5,5 @@ import { useChartHeight, useChartWidth } from "recharts";
 export function PolarMaterialFilter({ material, id, }) {
     const width = useChartWidth();
     const height = useChartHeight();
-    return (_jsx("defs", { "data-kind-ui": "polar-material", "data-material": material, pointerEvents: "none", children: _jsxs("filter", { id: id, filterUnits: "userSpaceOnUse", x: -16, y: -16, width: (width ?? 0) + 32, height: (height ?? 0) + 32, colorInterpolationFilters: "sRGB", children: [_jsx("feComponentTransfer", { in: "SourceAlpha", result: "footprint", children: _jsx("feFuncA", { type: "linear", slope: 100000 }) }), material === "paper" ? (_jsxs(_Fragment, { children: [_jsx("feTurbulence", { type: "fractalNoise", baseFrequency: "0.65 0.3", numOctaves: 1, seed: 7, result: "fiber" }), _jsx("feFlood", { floodColor: "var(--kind-ui-polar-paper-fiber, #fff)", floodOpacity: "var(--kind-ui-polar-paper-grain, 0.14)" }), _jsx("feComposite", { in2: "fiber", operator: "in", result: "texture" }), _jsx("feComposite", { in: "texture", in2: "SourceGraphic", operator: "atop", result: "paper" }), _jsx("feMorphology", { in: "footprint", operator: "erode", radius: 1.2, result: "inside" }), _jsx("feComposite", { in: "footprint", in2: "inside", operator: "arithmetic", k2: 1, k3: -1, result: "edge" }), _jsx("feTurbulence", { type: "fractalNoise", baseFrequency: "0.08 0.2", numOctaves: 1, seed: 11, result: "pencil" }), _jsx("feColorMatrix", { in: "pencil", type: "luminanceToAlpha", result: "pencilMask" }), _jsx("feComponentTransfer", { in: "pencilMask", result: "sketch", children: _jsx("feFuncA", { type: "linear", slope: 1.6, intercept: -0.15 }) }), _jsx("feComposite", { in: "edge", in2: "sketch", operator: "in", result: "sketchEdge" }), _jsx("feColorMatrix", { in: "SourceGraphic", type: "matrix", values: "0.35 0 0 0 0 0 0.35 0 0 0 0 0 0.35 0 0 0 0 0 1 0", result: "ink" }), _jsx("feComposite", { in: "ink", in2: "sketchEdge", operator: "in", result: "contour" }), _jsx("feComposite", { in: "contour", in2: "paper", operator: "atop" })] })) : material === "clay" ? (_jsxs(_Fragment, { children: [_jsx("feOffset", { in: "footprint", dx: 4, dy: 4, result: "lower" }), _jsx("feComposite", { in: "footprint", in2: "lower", operator: "arithmetic", k2: 1, k3: -1, result: "top" }), _jsx("feGaussianBlur", { in: "top", stdDeviation: 3, result: "softTop" }), _jsx("feFlood", { floodColor: "var(--kind-ui-polar-clay-light, #fff)", floodOpacity: "var(--kind-ui-polar-clay-highlight, 0.55)" }), _jsx("feComposite", { in2: "softTop", operator: "in", result: "light" }), _jsx("feOffset", { in: "footprint", dx: -4, dy: -4, result: "upper" }), _jsx("feComposite", { in: "footprint", in2: "upper", operator: "arithmetic", k2: 1, k3: -1, result: "bottom" }), _jsx("feGaussianBlur", { in: "bottom", stdDeviation: 3, result: "softBottom" }), _jsx("feFlood", { floodColor: "var(--kind-ui-polar-clay-shade, #17212b)", floodOpacity: "var(--kind-ui-polar-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: "body" }), _jsx("feTurbulence", { type: "fractalNoise", baseFrequency: 0.7, numOctaves: 1, seed: 17, result: "grain" }), _jsx("feFlood", { floodColor: "var(--kind-ui-polar-clay-light, #fff)", floodOpacity: 0.025 }), _jsx("feComposite", { in2: "grain", operator: "in", result: "texture" }), _jsx("feComposite", { in: "texture", in2: "body", operator: "atop" })] })) : (_jsxs(_Fragment, { children: [_jsx("feColorMatrix", { in: "SourceGraphic", type: "matrix", values: "0.6 0 0 0 0.4 0 0.6 0 0 0.4 0 0 0.6 0 0.4 0 0 0 1 0", result: "luminousPaint" }), _jsx("feGaussianBlur", { in: "luminousPaint", stdDeviation: 3, result: "halo" }), _jsx("feFlood", { floodOpacity: "var(--kind-ui-polar-glow-opacity, 0.65)", result: "strength" }), _jsx("feComposite", { in: "halo", in2: "strength", operator: "in", result: "softHalo" }), _jsx("feMorphology", { in: "footprint", operator: "dilate", radius: 1, result: "haloGuard" }), _jsx("feComposite", { in: "softHalo", in2: "haloGuard", operator: "out", result: "exterior" }), _jsx("feMorphology", { in: "footprint", operator: "erode", radius: 2.2, result: "inside" }), _jsx("feComposite", { in: "footprint", in2: "inside", operator: "arithmetic", k2: 1, k3: -1, result: "edge" }), _jsx("feFlood", { floodColor: "var(--kind-ui-polar-glow-light, #fff)", floodOpacity: 0.8 }), _jsx("feComposite", { in2: "edge", operator: "in", result: "light" }), _jsx("feComposite", { in: "light", in2: "SourceGraphic", operator: "atop", result: "body" }), _jsxs("feMerge", { children: [_jsx("feMergeNode", { in: "exterior" }), _jsx("feMergeNode", { in: "body" })] })] }))] }) }));
+    return (_jsx("defs", { "data-kind-ui": "polar-material", "data-material": material, pointerEvents: "none", children: _jsxs("filter", { id: id, filterUnits: "userSpaceOnUse", x: -16, y: -16, width: (width ?? 0) + 32, height: (height ?? 0) + 32, colorInterpolationFilters: "sRGB", children: [_jsx("feComponentTransfer", { in: "SourceAlpha", result: "footprint", children: _jsx("feFuncA", { type: "linear", slope: 100000 }) }), material === "clay" ? (_jsxs(_Fragment, { children: [_jsx("feOffset", { in: "footprint", dx: 4, dy: 4, result: "lower" }), _jsx("feComposite", { in: "footprint", in2: "lower", operator: "arithmetic", k2: 1, k3: -1, result: "top" }), _jsx("feGaussianBlur", { in: "top", stdDeviation: 3, result: "softTop" }), _jsx("feFlood", { floodColor: "var(--kind-ui-polar-clay-light, #fff)", floodOpacity: "var(--kind-ui-polar-clay-highlight, 0.55)" }), _jsx("feComposite", { in2: "softTop", operator: "in", result: "light" }), _jsx("feOffset", { in: "footprint", dx: -4, dy: -4, result: "upper" }), _jsx("feComposite", { in: "footprint", in2: "upper", operator: "arithmetic", k2: 1, k3: -1, result: "bottom" }), _jsx("feGaussianBlur", { in: "bottom", stdDeviation: 3, result: "softBottom" }), _jsx("feFlood", { floodColor: "var(--kind-ui-polar-clay-shade, #17212b)", floodOpacity: "var(--kind-ui-polar-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: "body" }), _jsx("feTurbulence", { type: "fractalNoise", baseFrequency: 0.7, numOctaves: 1, seed: 17, result: "grain" }), _jsx("feFlood", { floodColor: "var(--kind-ui-polar-clay-light, #fff)", floodOpacity: 0.025 }), _jsx("feComposite", { in2: "grain", operator: "in", result: "texture" }), _jsx("feComposite", { in: "texture", in2: "body", operator: "atop" })] })) : (_jsxs(_Fragment, { children: [_jsx("feColorMatrix", { in: "SourceGraphic", type: "matrix", values: "0.6 0 0 0 0.4 0 0.6 0 0 0.4 0 0 0.6 0 0.4 0 0 0 1 0", result: "luminousPaint" }), _jsx("feGaussianBlur", { in: "luminousPaint", stdDeviation: 3, result: "halo" }), _jsx("feFlood", { floodOpacity: "var(--kind-ui-polar-glow-opacity, 0.65)", result: "strength" }), _jsx("feComposite", { in: "halo", in2: "strength", operator: "in", result: "softHalo" }), _jsx("feMorphology", { in: "footprint", operator: "dilate", radius: 1, result: "haloGuard" }), _jsx("feComposite", { in: "softHalo", in2: "haloGuard", operator: "out", result: "exterior" }), _jsx("feMorphology", { in: "footprint", operator: "erode", radius: 2.2, result: "inside" }), _jsx("feComposite", { in: "footprint", in2: "inside", operator: "arithmetic", k2: 1, k3: -1, result: "edge" }), _jsx("feFlood", { floodColor: "var(--kind-ui-polar-glow-light, #fff)", floodOpacity: 0.8 }), _jsx("feComposite", { in2: "edge", operator: "in", result: "light" }), _jsx("feComposite", { in: "light", in2: "SourceGraphic", operator: "atop", result: "body" }), _jsxs("feMerge", { children: [_jsx("feMergeNode", { in: "exterior" }), _jsx("feMergeNode", { in: "body" })] })] }))] }) }));
 }