@kind-ui/charts 0.1.0 → 0.2.0

package/dist/loading-standalone-designs.js

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

package/dist/percent-stack.d.ts

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

package/dist/percent-stack.js

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

package/dist/pie-chart.d.ts

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

package/dist/pie-chart.js

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

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

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

package/dist/pie-pin-identity.js

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

package/dist/pie-series.d.ts

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

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`;
@@ -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 }));
+}