@kind-ui/charts 0.1.1 → 0.2.0

package/dist/activity-rings.d.ts

@@ -6,6 +6,7 @@ import { type RadialBarChartProps } from "./polar-chart.js";
 import { type RadialBarSeriesProps } from "./polar-series.js";
 import { type RootProps } from "./root.js";
 import type { SeriesConfig } from "./types.js";
+type ActivityRootProps = RootProps extends infer Props ? Props extends object ? Omit<Props, "config" | "children"> : never : never;
 export type ActivityRing = {
     /** Stable metadata identity in config. Array order controls ring order. */
     key: string;
@@ -40,7 +41,7 @@ export type ActivityRingsProps = Omit<RadialBarChartProps<ActivityRingDatum>, "d
     legend?: false | LegendProps;
     /** Custom content receives native payload with original value and normalized progress. */
     tooltip?: false | TooltipProps;
-    rootProps?: Omit<RootProps, "config" | "children" | "visibleSeries" | "onVisibleSeriesChange">;
+    rootProps?: ActivityRootProps;
 };
 /** A narrow progress recipe; native RadialBarChart remains the full composition escape hatch. */
 export declare function ActivityRings({ rings, config, domain, series, labels, legend, tooltip, rootProps, width, height, style, className, responsive, accessibilityLayer, ...chartProps }: ActivityRingsProps): import("react").JSX.Element;

package/dist/activity-rings.js

@@ -5,10 +5,11 @@ import { Cell, LabelList, PolarAngleAxis, PolarRadiusAxis } from "recharts";
 import { Tooltip } from "./animation.js";
 import { ChartContext } from "./chart-context.js";
 import { Legend } from "./legend.js";
-import { RadialBarChart } from "./polar-chart.js";
+import { RadialBarChartFrame } from "./polar-chart.js";
 import { RadialBarSeries } from "./polar-series.js";
 import { RadialBarLabel } from "./radial-bar-label.js";
 import { Root } from "./root.js";
+import { resolveSeriesLabel } from "./series-label.js";
 import { TooltipContent } from "./tooltip-content.js";
 /** A narrow progress recipe; native RadialBarChart remains the full composition escape hatch. */
 export function ActivityRings({ rings, config, domain = [0, 100], series, labels = false, legend, tooltip, rootProps, width, height, style, className, responsive = true, accessibilityLayer = true, ...chartProps }) {
@@ -33,7 +34,7 @@ export function ActivityRings({ rings, config, domain = [0, 100], series, labels
         return {
             ...ring,
             // biome-ignore lint/style/noNonNullAssertion: Object.hasOwn above rejects ring keys absent from config.
-            label: config[ring.key].label,
+            label: resolveSeriesLabel(ring.key, config[ring.key].label),
             rawValue: ring.value,
             progress: Math.max(0, Math.min(100, ((ring.value - min) / (max - min)) * 100)),
         };
@@ -41,7 +42,9 @@ export function ActivityRings({ rings, config, domain = [0, 100], series, labels
     // biome-ignore lint/style/noNonNullAssertion: Every key was validated against config while constructing data.
     const activeConfig = Object.fromEntries(keys.map((key) => [key, config[key]]));
     const describedBy = [chartProps["aria-describedby"], descriptionId].filter(Boolean).join(" ");
-    return (_jsxs(Root, { ...rootProps, config: activeConfig, children: [_jsx("dl", { id: descriptionId, "data-kind-ui": "chart-instructions", children: data.map((ring) => (_jsxs("div", { children: [_jsx("dt", { children: ring.label }), _jsx("dd", { children: config[ring.key].formatValue?.(ring.rawValue) ?? ring.rawValue })] }, ring.key))) }), _jsxs(RadialBarChart, { innerRadius: "30%", outerRadius: "90%", startAngle: 90, endAngle: -270, barCategoryGap: "15%", ...chartProps, "aria-describedby": describedBy, data: data, categoryKey: "key", layout: "radial", accessibilityLayer: accessibilityLayer, responsive: responsive, ...(width !== undefined ? { width } : {}), ...(height !== undefined ? { height } : {}), className: ["kind-ui-activity-rings", className].filter(Boolean).join(" "), style: { width: width ?? "100%", height: height ?? 300, ...style }, children: [_jsx(PolarAngleAxis, { type: "number", domain: [0, 100], tick: false, axisLine: false }), _jsx(PolarRadiusAxis, { type: "category", dataKey: "key", tick: false, axisLine: false }), _jsxs(RadialBarSeries, { background: true, cornerRadius: "50%", ...series, dataKey: "progress", children: [data.some((ring) => ring.cellProps !== undefined) &&
+    return (_jsxs(Root, { ...rootProps, config: activeConfig, children: [_jsx("dl", { id: descriptionId, "data-kind-ui": "chart-instructions", "aria-hidden": chartProps.loading || undefined, children: data.map((ring) => (_jsxs("div", { children: [_jsx("dt", { children: ring.label }), _jsx("dd", { children: config[ring.key].formatValue?.(ring.rawValue) ?? ring.rawValue })] }, ring.key))) }), _jsxs(RadialBarChartFrame, { skeletonFamily: "activity-rings", innerRadius: "30%", outerRadius: "90%", startAngle: 90, endAngle: -270, barCategoryGap: "15%", ...chartProps, "aria-describedby": describedBy, data: data, categoryKey: "key", ...(rootProps?.interaction?.kind === "category"
+                    ? { interactionBinding: "root" }
+                    : {}), layout: "radial", accessibilityLayer: accessibilityLayer, responsive: responsive, ...(width !== undefined ? { width } : {}), ...(height !== undefined ? { height } : {}), className: ["kind-ui-activity-rings", className].filter(Boolean).join(" "), style: { width: width ?? "100%", height: height ?? 300, ...style }, children: [_jsx(PolarAngleAxis, { type: "number", domain: [0, 100], tick: false, axisLine: false }), _jsx(PolarRadiusAxis, { type: "category", dataKey: "key", tick: false, axisLine: false }), _jsxs(RadialBarSeries, { background: true, cornerRadius: "50%", ...series, dataKey: "progress", children: [data.some((ring) => ring.cellProps !== undefined) &&
                                 data.map((ring) => _jsx(Cell, { ...ring.cellProps }, ring.key)), labels !== false && (_jsx(LabelList, { content: _jsx(RadialBarLabel, {}), ...labels, dataKey: "label" }))] }), tooltip !== false && (_jsx(Tooltip, { content: (native) => (_jsx(TooltipContent, { tooltip: {
                                 ...native,
                                 payload: native.payload.map((entry) => {

package/dist/animation.d.ts

@@ -3,12 +3,18 @@ import { type ReactElement } from "react";
 import { type DotProps } from "recharts";
 import { type LineChartProps as StaticLineChartProps } from "./line-chart.js";
 import { type LineSeriesProps as StaticLineSeriesProps } from "./line-series.js";
+import { type PointStyle } from "./point-marker.js";
+import { type RevealDirection } from "./reveal-clip.js";
 import { type TooltipProps } from "./tooltip.js";
-export type LineAnimation = {
+export type BaseAnimation = {
     revealDurationMs?: number;
     revealEasing?: Transition["ease"];
     hoverTransition?: Transition;
 };
+export type LineAnimation = BaseAnimation & {
+    /** Physical horizontal entrance direction, independent of native chart layout. */
+    revealDirection?: RevealDirection;
+};
 type DefaultLineDataKey = Extract<StaticLineSeriesProps["dataKey"], (row: never) => unknown>;
 export type LineSeriesProps<DataPoint = Parameters<DefaultLineDataKey>[0], Value = ReturnType<DefaultLineDataKey>> = Omit<StaticLineSeriesProps<DataPoint, Value>, "isAnimationActive">;
 export type LineChartProps = StaticLineChartProps & {
@@ -19,8 +25,10 @@ export declare const MotionContext: import("react").Context<{
     transition: Transition;
 }>;
 /** Motion owns the shared entrance clip and default active marks. */
-export declare function LineChart({ animate, children, ...props }: LineChartProps): import("react").JSX.Element;
-export declare function ActiveMarker({ cx, cy, fill, stroke }: DotProps): import("react").JSX.Element | null;
+export declare function LineChart({ animate, loading, loadingLabel, children, ...props }: LineChartProps): import("react").JSX.Element;
+export declare function ActiveMarker({ cx, cy, fill, stroke, variant, }: DotProps & {
+    variant?: PointStyle | undefined;
+}): import("react").JSX.Element | null;
 export declare function LineSeries<DataPoint = Parameters<DefaultLineDataKey>[0], Value = ReturnType<DefaultLineDataKey>>(props: LineSeriesProps<DataPoint, Value>): ReactElement;
 export declare function LineSeries(props: LineSeriesProps): ReactElement;
 export declare function Tooltip(props: TooltipProps): import("react").JSX.Element;

package/dist/animation.js

@@ -6,6 +6,9 @@ import { DefaultZIndexes, LineChart as EngineLineChart, ZIndexLayer, } from "rec
 import { useChart } from "./chart-context.js";
 import { LineChartFrame, useLineInteraction, } from "./line-chart.js";
 import { LineSeries as StaticLineSeries, } from "./line-series.js";
+import { registerPiePinComponent } from "./pie-pin-identity.js";
+import { markerPaint } from "./point-marker.js";
+import { RevealClip } from "./reveal-clip.js";
 import { TooltipBase } from "./tooltip.js";
 const defaultHover = { type: "spring", stiffness: 210, damping: 28, mass: 0.8 };
 export const MotionContext = createContext({ enabled: false, transition: defaultHover });
@@ -18,19 +21,23 @@ function subscribe(change) {
 const snapshot = () => window.matchMedia(query).matches;
 const serverSnapshot = () => true;
 /** Motion owns the shared entrance clip and default active marks. */
-export function LineChart({ animate = false, children, ...props }) {
+export function LineChart({ animate = false, loading, loadingLabel, children, ...props }) {
     const id = useId();
     const reduced = useSyncExternalStore(subscribe, snapshot, serverSnapshot);
     const [interacted, setInteracted] = useState(false);
     const options = typeof animate === "object" ? animate : {};
-    const enabled = animate !== false && !reduced;
-    const interrupt = useCallback(() => setInteracted(true), []);
+    const enabled = animate !== false && !reduced && !loading;
+    const interrupt = useCallback(() => {
+        if (!loading)
+            setInteracted(true);
+    }, [loading]);
+    useLayoutEffect(() => {
+        if (loading)
+            setInteracted(false);
+    }, [loading]);
     const reveal = enabled && !interacted;
     const transition = options.hoverTransition ?? defaultHover;
-    return (_jsx(MotionContext, { value: { enabled, transition }, children: _jsxs(LineChartFrame, { chartProps: props, engine: EngineLineChart, motionEnabled: enabled, interrupt: interrupt, ...(reveal ? { clip: `url(#${id}-reveal)` } : {}), children: [reveal && (_jsx("defs", { children: _jsx("clipPath", { id: `${id}-reveal`, clipPathUnits: "userSpaceOnUse", children: _jsx(motion.rect, { x: 0, y: 0, height: "100%", initial: { width: "0%" }, animate: { width: "100%" }, transition: {
-                                duration: Math.max(0, options.revealDurationMs ?? 1000) / 1000,
-                                ease: options.revealEasing ?? [0.25, 0.1, 0.25, 1],
-                            } }) }) })), children] }) }));
+    return (_jsx(MotionContext, { value: { enabled, transition }, children: _jsxs(LineChartFrame, { chartProps: props, loading: loading, loadingLabel: loadingLabel, loadingSkeleton: "line", loadingAnimation: options, engine: EngineLineChart, motionEnabled: enabled, interrupt: interrupt, ...(reveal ? { clip: `url(#${id}-reveal)` } : {}), children: [reveal && (_jsx(RevealClip, { id: `${id}-reveal`, options: options, ...(options.revealDirection === undefined ? {} : { finish: interrupt }) })), children] }) }));
 }
 // Stop the previous target before retargeting or snapping, without remounting consumer DOM.
 function useAnimatedCoordinate(target, enabled, transition) {
@@ -45,7 +52,7 @@ function useAnimatedCoordinate(target, enabled, transition) {
     }, [value, target, enabled, transition]);
     return value;
 }
-export function ActiveMarker({ cx, cy, fill, stroke }) {
+export function ActiveMarker({ cx, cy, fill, stroke, variant = "default", }) {
     const { enabled, transition } = use(MotionContext);
     const { motionReady } = useLineInteraction();
     const animate = enabled && motionReady;
@@ -53,7 +60,7 @@ export function ActiveMarker({ cx, cy, fill, stroke }) {
     const y = useAnimatedCoordinate(cy ?? 0, animate, transition);
     if (cx == null || cy == null)
         return null;
-    return (_jsx(motion.circle, { "data-kind-ui": "active-marker", initial: false, cx: x, cy: y, r: 5, fill: fill ?? stroke, stroke: "var(--card, white)", strokeWidth: 2, strokeDasharray: "none", pointerEvents: "none" }));
+    return (_jsx(motion.circle, { "data-kind-ui": "active-marker", initial: false, cx: x, cy: y, r: 5, fill: fill ?? stroke, stroke: "var(--card, white)", strokeWidth: 2, strokeDasharray: "none", ...markerPaint(variant, fill ?? stroke), "data-point-style": variant, pointerEvents: "none" }));
 }
 export function LineSeries(props) {
     const { enabled } = use(MotionContext);
@@ -87,7 +94,7 @@ export function LineSeries(props) {
         });
         return () => controls.stop();
     }, [visible, enabled, opacity]);
-    return (_jsx(ZIndexLayer, { zIndex: props.zIndex ?? DefaultZIndexes.line, children: _jsx(motion.g, { initial: false, style: { opacity }, pointerEvents: visible ? undefined : "none", "aria-hidden": visible ? undefined : true, children: _jsx(StaticLineSeries, { ...props, activeDot: visible ? (props.activeDot ?? _jsx(ActiveMarker, {})) : false, zIndex: 0, renderWhileHidden: enabled && drawn, isAnimationActive: false }) }) }));
+    return (_jsx(ZIndexLayer, { zIndex: props.zIndex ?? DefaultZIndexes.line, children: _jsx(motion.g, { initial: false, style: { opacity }, pointerEvents: visible ? undefined : "none", "aria-hidden": visible ? undefined : true, children: _jsx(StaticLineSeries, { ...props, activeDot: visible ? (props.activeDot ?? _jsx(ActiveMarker, { variant: props.activePointStyle })) : false, zIndex: 0, renderWhileHidden: enabled && drawn, isAnimationActive: false }) }) }));
 }
 function MovingFrame({ x, y, maxX, maxY, ref, style, frameProps, children }) {
     const { enabled, transition } = use(MotionContext);
@@ -100,3 +107,4 @@ function MovingFrame({ x, y, maxX, maxY, ref, style, frameProps, children }) {
 export function Tooltip(props) {
     return _jsx(TooltipBase, { ...props, Frame: MovingFrame });
 }
+registerPiePinComponent(Tooltip, "tooltip");

package/dist/area-chart.d.ts

@@ -4,6 +4,8 @@ import { type LineAnimation } from "./animation.js";
 export type AreaAnimation = LineAnimation;
 export type AreaChartProps = ComponentProps<typeof EngineAreaChart> & {
     animate?: boolean | AreaAnimation | undefined;
+    loading?: boolean | undefined;
+    loadingLabel?: string | undefined;
 };
 /** Native Recharts geometry and composition with a shared Motion entrance and tooltip. */
-export declare function AreaChart({ animate, children, ...props }: AreaChartProps): import("react").JSX.Element;
+export declare function AreaChart({ animate, loading, loadingLabel, children, ...props }: AreaChartProps): import("react").JSX.Element;

package/dist/area-chart.js

@@ -1,10 +1,11 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { motion } from "motion/react";
-import { useCallback, useId, useState, useSyncExternalStore } from "react";
+import { useCallback, useId, useLayoutEffect, useState, useSyncExternalStore, } from "react";
 import { AreaChart as EngineAreaChart } from "recharts";
 import { MotionContext } from "./animation.js";
 import { LineChartFrame } from "./line-chart.js";
+import { CartesianLoadingDesign } from "./loading-cartesian-designs.js";
+import { RevealClip } from "./reveal-clip.js";
 const defaultHover = { type: "spring", stiffness: 210, damping: 28, mass: 0.8 };
 const query = "(prefers-reduced-motion: reduce)";
 function subscribe(change) {
@@ -15,19 +16,23 @@ function subscribe(change) {
 const snapshot = () => window.matchMedia(query).matches;
 const serverSnapshot = () => true;
 /** Native Recharts geometry and composition with a shared Motion entrance and tooltip. */
-export function AreaChart({ animate = false, children, ...props }) {
+export function AreaChart({ animate = false, loading, loadingLabel, children, ...props }) {
     const id = useId();
     const reduced = useSyncExternalStore(subscribe, snapshot, serverSnapshot);
     const [interacted, setInteracted] = useState(false);
     const options = typeof animate === "object" ? animate : {};
-    const enabled = animate !== false && reduced === false;
-    const interrupt = useCallback(() => setInteracted(true), []);
+    const enabled = animate !== false && reduced === false && !loading;
+    const interrupt = useCallback(() => {
+        if (!loading)
+            setInteracted(true);
+    }, [loading]);
+    useLayoutEffect(() => {
+        if (loading)
+            setInteracted(false);
+    }, [loading]);
     const reveal = enabled && !interacted;
-    return (_jsx(MotionContext, { value: { enabled, transition: options.hoverTransition ?? defaultHover }, children: _jsxs(LineChartFrame, { chartProps: {
+    return (_jsx(MotionContext, { value: { enabled, transition: options.hoverTransition ?? defaultHover }, children: _jsxs(LineChartFrame, { loading: loading, loadingLabel: loadingLabel, loadingSkeleton: "area", loadingDesign: (seed) => _jsx(CartesianLoadingDesign, { family: "area", seed: seed }), loadingAnimation: options, chartProps: {
                 ...props,
                 className: ["kind-ui-area-chart", props.className].filter(Boolean).join(" "),
-            }, engine: EngineAreaChart, motionEnabled: enabled, interrupt: interrupt, ...(reveal ? { clip: `url(#${id}-area-reveal)` } : {}), children: [reveal && (_jsx("defs", { children: _jsx("clipPath", { id: `${id}-area-reveal`, clipPathUnits: "userSpaceOnUse", children: _jsx(motion.rect, { "data-area-reveal": "", x: 0, y: 0, height: "100%", initial: { width: "0%" }, animate: { width: "100%" }, onAnimationComplete: interrupt, transition: {
-                                duration: Math.max(0, options.revealDurationMs ?? 1000) / 1000,
-                                ease: options.revealEasing ?? [0.25, 0.1, 0.25, 1],
-                            } }) }) })), children] }) }));
+            }, engine: EngineAreaChart, motionEnabled: enabled, interrupt: interrupt, ...(reveal ? { clip: `url(#${id}-area-reveal)` } : {}), children: [reveal && (_jsx(RevealClip, { id: `${id}-area-reveal`, family: "area", options: options, finish: interrupt })), children] }) }));
 }

package/dist/area-series.d.ts

@@ -1,11 +1,19 @@
 import { type ComponentProps } from "react";
 import { Area } from "recharts";
 import { type AreaMaterial } from "./area-material.js";
+import { type FillPattern } from "./fill-pattern.js";
+import { type PointStyle } from "./point-marker.js";
 export type AreaSeriesProps<DataPoint = unknown, Value = unknown> = Omit<ComponentProps<typeof Area<DataPoint, Value>>, "isAnimationActive"> & {
     /** 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;
     /** Finish on the native area; explicit shape/filter retain consumer ownership. */
     material?: AreaMaterial;
+    /** Static fill encoding; false opts out of configured patterns. Native paint/shape wins. */
+    pattern?: FillPattern | false | undefined;
 };
 /** A registered Recharts Area with Root colors and controlled visibility. */
-export declare function AreaSeries<DataPoint = unknown, Value = unknown>({ seriesKey, material, hide, stroke, fill, className, ...props }: AreaSeriesProps<DataPoint, Value>): import("react").JSX.Element;
+export declare function AreaSeries<DataPoint = unknown, Value = unknown>({ seriesKey, pointStyle, activePointStyle, material, pattern, hide, stroke, fill, className, ...props }: AreaSeriesProps<DataPoint, Value>): import("react").JSX.Element;

package/dist/area-series.js

@@ -1,14 +1,23 @@
 "use client";
-import { jsx as _jsx } from "react/jsx-runtime";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 import { useId, useLayoutEffect, useRef } from "react";
-import { Area } from "recharts";
+import { Area, DefaultZIndexes, ZIndexLayer } from "recharts";
 import { ActiveMarker } from "./animation.js";
 import { MaterialArea } from "./area-material.js";
 import { useChart } from "./chart-context.js";
+import { FillPatternDefinition, patternResourceId } from "./fill-pattern.js";
 import { useLineInteraction } from "./line-chart.js";
+import { PointMarker } from "./point-marker.js";
+import { SeriesInteractionLayer, useSeriesInteraction } from "./series-interaction.js";
 /** A registered Recharts Area with Root colors and controlled visibility. */
-export function AreaSeries({ seriesKey, material = "plain", hide, stroke, fill, className, ...props }) {
-    const { config, visibleSeries } = useChart();
+export function AreaSeries({ seriesKey, pointStyle = "default", activePointStyle = "default", material = "plain", pattern, hide, stroke, fill, className, ...props }) {
+    // Diagnose unsupported JavaScript/spread input without adding it to the public Area API.
+    const { dashAnimation, ...nativeProps } = props;
+    useLayoutEffect(() => {
+        if (dashAnimation !== undefined && process.env.NODE_ENV === "development")
+            console.warn("AreaSeries does not support dashAnimation. Remove it or use LineSeries with strokeDasharray for animated dashes.");
+    }, [dashAnimation]);
+    const { config, paints, visibleSeries } = useChart();
     const { registerSeries, invalidate } = useLineInteraction();
     const generatedId = useId();
     const id = props.id || generatedId;
@@ -27,8 +36,26 @@ export function AreaSeries({ seriesKey, material = "plain", hide, stroke, fill,
     }, [id, key, registerSeries]);
     if (key === undefined && visibleSeries !== undefined)
         throw new Error("AreaSeries requires seriesKey for controlled non-string dataKey");
-    const color = stroke ?? (key && Object.hasOwn(config, key) ? `var(--color-${key})` : undefined);
-    return (_jsx(Area, { activeDot: _jsx(ActiveMarker, {}), ...props, ...(material !== "plain" && props.shape === undefined && props.filter === undefined
-            ? { shape: _jsx(MaterialArea, { material: material, filterId: `${generatedId}-area-material` }) }
-            : {}), isAnimationActive: false, id: id, hide: effectiveHide, ...(color !== undefined ? { stroke: color } : {}), ...(fill !== undefined ? { fill } : color !== undefined ? { fill: color } : {}), className: ["kind-ui-area-series", className].filter(Boolean).join(" ") }));
+    const configuredPattern = key && Object.hasOwn(config, key) ? config[key]?.pattern : undefined;
+    const resolvedPattern = pattern === false ? undefined : (pattern ?? configuredPattern);
+    const patternId = patternResourceId(generatedId);
+    const patterned = resolvedPattern !== undefined &&
+        fill === undefined &&
+        props.style?.fill === undefined &&
+        props.shape === undefined;
+    const interaction = useSeriesInteraction(key, effectiveHide, hide === true, props.data, props.onClick);
+    const color = stroke ?? (key && Object.hasOwn(config, key) ? paints[key] : undefined);
+    return (_jsxs(_Fragment, { children: [patterned && (_jsx("defs", { pointerEvents: "none", children: _jsx(FillPatternDefinition, { id: patternId, pattern: resolvedPattern, baseColor: stroke ?? (key && Object.hasOwn(config, key) ? `var(--color-${key})` : "currentColor") }) })), _jsx(ZIndexLayer, { zIndex: props.zIndex ?? DefaultZIndexes.area, children: _jsx(SeriesInteractionLayer, { seriesKey: key, hidden: effectiveHide, children: _jsx(Area, { activeDot: _jsx(ActiveMarker, { variant: activePointStyle }), ...nativeProps, ...(props.dot === undefined && pointStyle !== "default"
+                            ? { dot: _jsx(PointMarker, { variant: pointStyle }) }
+                            : {}), ...(interaction.onClick !== undefined ? { onClick: interaction.onClick } : {}), ...(material !== "plain" && props.shape === undefined && props.filter === undefined
+                            ? {
+                                shape: (_jsx(MaterialArea, { material: material, filterId: `${generatedId}-area-material` })),
+                            }
+                            : {}), isAnimationActive: false, id: id, zIndex: 0, hide: effectiveHide, ...(color !== undefined ? { stroke: color } : {}), ...(fill !== undefined
+                            ? { fill }
+                            : patterned
+                                ? { fill: `url(#${patternId})` }
+                                : color !== undefined
+                                    ? { fill: color }
+                                    : {}), className: ["kind-ui-area-series", className].filter(Boolean).join(" ") }) }) })] }));
 }

package/dist/bar-chart.d.ts

@@ -1,9 +1,11 @@
 import { type ComponentProps } from "react";
 import { BarChart as EngineBarChart } from "recharts";
-import { type LineAnimation } from "./animation.js";
-export type BarAnimation = LineAnimation;
+import { type BaseAnimation } from "./animation.js";
+export type BarAnimation = BaseAnimation;
 export type BarChartProps = ComponentProps<typeof EngineBarChart> & {
     animate?: boolean | BarAnimation | undefined;
+    loading?: boolean | undefined;
+    loadingLabel?: string | undefined;
     /** Opt in only for complete native category comparisons; any unsafe visible peer falls back. */
     emphasis?: "none" | "category" | undefined;
 };
@@ -14,4 +16,9 @@ export declare const BarMotion: import("react").Context<{
 }>;
 export declare function BarLifecycle({ layout, barGap, barCategoryGap, barSize, stackOffset, reverseStackOrder, }: BarChartProps): null;
 /** Native Recharts composition with Kind interaction and optional Motion. */
-export declare function BarChart({ animate, emphasis, children, ...props }: BarChartProps): import("react").JSX.Element;
+export declare function BarChartImplementation({ chartProps, family, }: {
+    chartProps: BarChartProps;
+    family: "bar" | "waterfall" | "histogram" | "box-plot";
+}): import("react").JSX.Element;
+/** Native bar composition with a deterministic loading silhouette. */
+export declare function BarChart(props: BarChartProps): import("react").JSX.Element;

package/dist/bar-chart.js

@@ -5,6 +5,7 @@ import { BarChart as EngineBarChart } from "recharts";
 import { MotionContext } from "./animation.js";
 import { BarCategoryBoundary } from "./bar-category.js";
 import { LineChartFrame, useLineInteraction } from "./line-chart.js";
+import { CartesianLoadingDesign } from "./loading-cartesian-designs.js";
 export const BarMotion = createContext({
     reveal: false,
     options: {},
@@ -32,11 +33,23 @@ export function BarLifecycle({ layout, barGap, barCategoryGap, barSize, stackOff
     return null;
 }
 /** Native Recharts composition with Kind interaction and optional Motion. */
-export function BarChart({ animate = false, emphasis = "none", children, ...props }) {
+export function BarChartImplementation({ chartProps, family, }) {
+    const { animate = false, loading, loadingLabel, emphasis = "none", children, ...props } = chartProps;
     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]);
+    useLayoutEffect(() => {
+        if (loading)
+            setInteracted(false);
+    }, [loading]);
+    const enabled = animate !== false && !reduced && !loading;
     const options = typeof animate === "object" ? animate : {};
-    return (_jsx(MotionContext, { value: { enabled, transition: options.hoverTransition ?? defaultHover }, children: _jsx(BarMotion, { value: { reveal: enabled && !interacted, options, finish }, children: _jsx(BarCategoryBoundary, { children: _jsxs(LineChartFrame, { chartProps: props, categoryEmphasis: emphasis === "category", engine: EngineBarChart, motionEnabled: enabled, interrupt: finish, children: [_jsx(BarLifecycle, { ...props }), children] }) }) }) }));
+    return (_jsx(MotionContext, { value: { enabled, transition: options.hoverTransition ?? defaultHover }, children: _jsx(BarMotion, { value: { reveal: enabled && !interacted, options, finish }, children: _jsx(BarCategoryBoundary, { children: _jsxs(LineChartFrame, { chartProps: props, loadingSkeleton: family, loadingDesign: (seed) => _jsx(CartesianLoadingDesign, { family: family, seed: seed }), loadingAnimation: { ...options, ...(props.layout ? { layout: props.layout } : {}) }, loading: loading, loadingLabel: loadingLabel, categoryEmphasis: emphasis === "category", engine: EngineBarChart, motionEnabled: enabled, interrupt: finish, children: [_jsx(BarLifecycle, { ...props }), children] }) }) }) }));
+}
+/** Native bar composition with a deterministic loading silhouette. */
+export function BarChart(props) {
+    return _jsx(BarChartImplementation, { chartProps: props, family: "bar" });
 }

package/dist/bar-series.d.ts

@@ -1,6 +1,12 @@
 import { type ComponentProps } from "react";
 import { Bar } from "recharts";
 import { type BarMaterial } from "./bar-material.js";
+import { type FillPattern } from "./fill-pattern.js";
+/** Caller-owned identity selection; this component never computes forecast values. */
+export type BarProjection<DataPoint> = {
+    isProjected: (datum: DataPoint) => boolean;
+    pattern: FillPattern;
+};
 export type BarSeriesProps<DataPoint = unknown, Value = unknown> = Omit<ComponentProps<typeof Bar<DataPoint, Value>>, "isAnimationActive"> & {
     /** Metadata/visibility key, required for controlled function or numeric data keys. */
     seriesKey?: string;
@@ -8,6 +14,10 @@ export type BarSeriesProps<DataPoint = unknown, Value = unknown> = Omit<Componen
     emphasisKey?: ((payload: unknown) => string | number | undefined) | undefined;
     /** Finish on native rectangles; custom shapes and filters retain ownership. */
     material?: BarMaterial | undefined;
+    /** Static encoding for implicit fills; explicit fills/Cells/custom shapes retain ownership. */
+    pattern?: FillPattern | false | undefined;
+    /** Pattern selected rows; selection remains caller-owned. */
+    projection?: BarProjection<DataPoint> | undefined;
 };
 /** A registered native Bar; axes, shape, cells, labels and handlers stay consumer-owned. */
-export declare function BarSeries<DataPoint = unknown, Value = unknown>({ seriesKey, emphasisKey, hide, fill, className, style, material, ...props }: BarSeriesProps<DataPoint, Value>): import("react").JSX.Element;
+export declare function BarSeries<DataPoint = unknown, Value = unknown>({ seriesKey, emphasisKey, hide, fill, className, style, material, pattern, projection, children, ...props }: BarSeriesProps<DataPoint, Value>): import("react").JSX.Element;

package/dist/bar-series.js

@@ -1,17 +1,19 @@
 "use client";
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 import { motion } from "motion/react";
-import { use, useCallback, useId, useLayoutEffect, useRef } from "react";
-import { Bar, Rectangle, useActiveTooltipDataPoints, useActiveTooltipLabel, useChartLayout, useIsTooltipActive, usePlotArea, useXAxisDomain, useXAxisScale, useYAxisDomain, useYAxisScale, } from "recharts";
+import { Children, isValidElement, use, useCallback, useId, useLayoutEffect, useRef, } from "react";
+import { Bar, Cell, DefaultZIndexes, Rectangle, useActiveTooltipDataPoints, useActiveTooltipLabel, useChartLayout, useIsTooltipActive, usePlotArea, useXAxisDomain, useXAxisScale, useYAxisDomain, useYAxisScale, ZIndexLayer, } from "recharts";
 import { useBarCategoryHover } from "./bar-category.js";
 import { BarMotion } from "./bar-chart.js";
 import { BarMaterialFilter } from "./bar-material.js";
 import { useChart } from "./chart-context.js";
 import { useEmphasis } from "./emphasis.js";
+import { FillPatternDefinition, patternResourceId } from "./fill-pattern.js";
 import { useChartKeyboard, useLineInteraction } from "./line-chart.js";
+import { SeriesInteractionLayer, useSeriesInteraction } from "./series-interaction.js";
 /** A registered native Bar; axes, shape, cells, labels and handlers stay consumer-owned. */
-export function BarSeries({ seriesKey, emphasisKey, hide, fill, className, style, material = "plain", ...props }) {
-    const { config, visibleSeries } = useChart();
+export function BarSeries({ seriesKey, emphasisKey, hide, fill, className, style, material = "plain", pattern, projection, children, ...props }) {
+    const { config, paints, visibleSeries } = useChart();
     const { registerSeries, invalidate, data, categoryEmphasis, registerCategoryEligibility } = useLineInteraction();
     const { reveal, options, finish } = use(BarMotion);
     const generatedId = useId();
@@ -102,7 +104,28 @@ export function BarSeries({ seriesKey, emphasisKey, hide, fill, className, style
     }, [id, key, registerSeries]);
     if (key === undefined && visibleSeries !== undefined)
         throw new Error("BarSeries requires seriesKey for controlled non-string dataKey");
-    const color = fill ?? (key && Object.hasOwn(config, key) ? `var(--color-${key})` : undefined);
+    const configuredPattern = key && Object.hasOwn(config, key) ? config[key]?.pattern : undefined;
+    const resolvedPattern = pattern === false ? undefined : (pattern ?? configuredPattern);
+    const patternId = patternResourceId(generatedId);
+    const patterned = resolvedPattern !== undefined &&
+        fill === undefined &&
+        style?.fill === undefined &&
+        props.shape === undefined &&
+        (props.activeBar === undefined || typeof props.activeBar === "boolean");
+    const interaction = useSeriesInteraction(key, effectiveHide, hide === true, undefined, props.onClick);
+    const projectionId = `${patternId}-projection`;
+    // Explicit Cell composition owns per-datum paint, including nested native Cells.
+    // Do not override consumer Cells or flatten their markup.
+    const hasCells = (nodes) => Children.toArray(nodes).some((node) => isValidElement(node) &&
+        (node.type === Cell || hasCells(node.props.children)));
+    const projectionPaint = projection !== undefined &&
+        pattern !== false &&
+        fill === undefined &&
+        style?.fill === undefined &&
+        props.shape === undefined &&
+        (props.activeBar === undefined || typeof props.activeBar === "boolean") &&
+        !hasCells(children);
+    const color = fill ?? (key && Object.hasOwn(config, key) ? paints[key] : undefined);
     const nativeRows = (!("data" in props) &&
         data?.every((row) => {
             if (typeof props.dataKey !== "string" ||
@@ -130,18 +153,47 @@ export function BarSeries({ seriesKey, emphasisKey, hide, fill, className, style
         props.shape === undefined &&
         (props.activeBar === undefined || typeof props.activeBar === "boolean");
     useLayoutEffect(() => registerCategoryEligibility(id, eligible, effectiveHide), [id, eligible, effectiveHide, registerCategoryEligibility]);
-    const categoryShape = useCallback((shapeProps) => (_jsx(CategoryBar, { ...shapeProps, seriesKey: key, emphasisKey: emphasisKey, axisId: horizontal ? props.yAxisId : props.xAxisId })), [key, emphasisKey, horizontal, props.xAxisId, props.yAxisId]);
+    const categoryShape = useCallback((shapeProps) => {
+        // Select the actual displayed payload, not the Cell index: native Brush
+        // slices and missing-value filtering must not shift projection identity.
+        const datum = shapeProps.payload;
+        const datumPaint = typeof datum === "object" && datum !== null
+            ? datum
+            : undefined;
+        const projected = projectionPaint &&
+            datum != null &&
+            projection.isProjected(datum) &&
+            datumPaint?.fill === undefined &&
+            datumPaint?.style?.fill === undefined;
+        const nativeProps = projected ? { ...shapeProps, fill: `url(#${projectionId})` } : shapeProps;
+        return categoryEmphasis && eligible ? (_jsx(CategoryBar, { ...nativeProps, seriesKey: key, emphasisKey: emphasisKey, axisId: horizontal ? props.yAxisId : props.xAxisId })) : (_jsx(Rectangle, { ...nativeProps }));
+    }, [
+        key,
+        emphasisKey,
+        horizontal,
+        props.xAxisId,
+        props.yAxisId,
+        projectionPaint,
+        projection,
+        projectionId,
+        categoryEmphasis,
+        eligible,
+    ]);
     const clipped = reveal && !effectiveHide && usablePlot;
     return (_jsxs(_Fragment, { children: [_jsx("style", { children: `.${selector} { --kind-ui-bar-clip: ${clipped ? `url(#${clipId})` : "none"}; }` }), clipped && (_jsx("defs", { children: _jsx("clipPath", { id: clipId, clipPathUnits: "userSpaceOnUse", children: _jsx(motion.rect, { "data-kind-ui": "bar-reveal", initial: horizontal
                             ? { x: zero, y: area.y, width: 0, height: area.height }
                             : { x: area.x, y: zero, height: 0, width: area.width }, animate: { x: area.x, y: area.y, width: area.width, height: area.height }, transition: {
                             duration: Math.max(0, options.revealDurationMs ?? 1000) / 1000,
                             ease: options.revealEasing ?? [0.25, 0.1, 0.25, 1],
-                        }, onAnimationComplete: finish }, geometry) }) })), materialized && (_jsx("defs", { "data-kind-ui": "bar-material", "data-material": material, pointerEvents: "none", children: _jsx(BarMaterialFilter, { material: material, id: filterId, horizontal: horizontal }) })), _jsx(Bar, { ...props, ...(categoryEmphasis && eligible
-                    ? {
-                        shape: categoryShape,
-                    }
-                    : {}), ...(materialized ? { filter: `url(#${filterId})` } : {}), id: id, hide: effectiveHide, ...(color !== undefined ? { fill: color } : {}), className: ["kind-ui-bar-series", selector, className].filter(Boolean).join(" "), style: style, isAnimationActive: false })] }));
+                        }, onAnimationComplete: finish }, geometry) }) })), patterned && (_jsx("defs", { pointerEvents: "none", children: _jsx(FillPatternDefinition, { id: patternId, pattern: resolvedPattern, baseColor: key && Object.hasOwn(config, key) ? `var(--color-${key})` : (color ?? "currentColor") }) })), projectionPaint && (_jsx("defs", { pointerEvents: "none", children: _jsx(FillPatternDefinition, { id: projectionId, pattern: projection.pattern, baseColor: key && Object.hasOwn(config, key) ? `var(--color-${key})` : (color ?? "currentColor") }) })), materialized && (_jsx("defs", { "data-kind-ui": "bar-material", "data-material": material, pointerEvents: "none", children: _jsx(BarMaterialFilter, { material: material, id: filterId, horizontal: horizontal }) })), _jsx(ZIndexLayer, { zIndex: props.zIndex ?? DefaultZIndexes.bar, children: _jsx(SeriesInteractionLayer, { seriesKey: key, hidden: effectiveHide, children: _jsx(Bar, { ...props, ...(interaction.onClick !== undefined ? { onClick: interaction.onClick } : {}), ...(projectionPaint || (categoryEmphasis && eligible)
+                            ? {
+                                shape: categoryShape,
+                            }
+                            : {}), ...(materialized ? { filter: `url(#${filterId})` } : {}), id: id, zIndex: 0, hide: effectiveHide, ...(patterned
+                            ? { fill: `url(#${patternId})` }
+                            : color !== undefined
+                                ? { fill: color }
+                                : {}), className: ["kind-ui-bar-series", selector, className].filter(Boolean).join(" "), style: style, isAnimationActive: false, children: children }) }) })] }));
 }
 function CategoryBar({ seriesKey, emphasisKey, axisId, ...props }) {
     const { emphasisScope, pointer } = useLineInteraction();
@@ -163,7 +215,7 @@ function CategoryBar({ seriesKey, emphasisKey, axisId, ...props }) {
         key: String(semantic),
         scope: `${emphasisScope}/${String(axisId ?? 0)}`,
         seriesKey,
-    }, eligible);
+    }, eligible, false);
     // Native axis inspection owns the category, including whitespace above and between bars.
     // A painted mark's leave must not clear a category while the cursor remains in its band.
     useLayoutEffect(() => {
@@ -174,5 +226,5 @@ function CategoryBar({ seriesKey, emphasisKey, axisId, ...props }) {
         else if (!hover || (pointer && !active))
             emphasis.leave("pointer");
     }, [active, keyboard, pointer, hover, emphasis.enter, emphasis.leave]);
-    return (_jsx("g", { "data-kind-ui": "emphasis-mark", "data-emphasis": emphasis.dimmed ? "dimmed" : "baseline", children: _jsx("g", { "data-kind-ui": "emphasis-paint", style: { opacity: emphasis.factor }, children: _jsx(Rectangle, { ...props }) }) }));
+    return (_jsx("g", { "data-kind-ui": "emphasis-mark", "data-emphasis": emphasis.dimmed ? "dimmed" : "baseline", children: _jsx("g", { "data-kind-ui": "emphasis-paint", style: { opacity: emphasis.active?.kind === "series" ? 1 : emphasis.factor }, children: _jsx(Rectangle, { ...props }) }) }));
 }

package/dist/box-plot.js

@@ -2,7 +2,7 @@
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 import { useCallback, useId, useImperativeHandle, useLayoutEffect, useMemo, useRef, useState, } from "react";
 import { useChartLayout, useXAxisScale, useYAxisScale } from "recharts";
-import { BarChart } from "./bar-chart.js";
+import { BarChartImplementation } from "./bar-chart.js";
 import { BarSeries } from "./bar-series.js";
 import { BoxMaterialFilter } from "./box-material.js";
 const fields = ["lowerWhisker", "q1", "median", "q3", "upperWhisker"];
@@ -48,7 +48,7 @@ export function boxPlotExtent(summary) {
 }
 /** Public Bar composition; Recharts owns axes, layout, domains and keyboard selection. */
 export function BoxPlotChart(props) {
-    return _jsx(BarChart, { ...props });
+    return _jsx(BarChartImplementation, { chartProps: props, family: "box-plot" });
 }
 /** A reusable SVG mark. Zero IQR remains a line; no minimum numeric extent is invented. */
 export function BoxPlotMark({ coordinates: c, center, size, orientation = "vertical", outlierRadius = 3, strokeWidth = 1.5, material = "plain", ...props }) {

package/dist/category-cells.d.ts

@@ -3,4 +3,10 @@ import type { SeriesConfig } from "./types.js";
 /** Category identity is an own field or an accessor, never an array position. */
 export type CategoryKey<Row> = (keyof Row & string) | ((row: Row) => string);
 /** Only Pie and Radial category mode use this native Cell defaulting seam. */
-export declare function categoryCells<Row>(data: readonly Row[] | undefined, categoryKey: CategoryKey<Row>, config: SeriesConfig, children: ReactNode, fill: string | undefined): ReactNode;
+export declare function categoryCells<Row>(data: readonly Row[] | undefined, categoryKey: CategoryKey<Row>, config: SeriesConfig, paints: Readonly<Record<string, string>>, children: ReactNode, fill: string | undefined): ReactNode;
+/** Filter original rows and positional Cells together before native geometry is computed. */
+export declare function filterCategoryRows<Row>(data: readonly Row[], categoryKey: CategoryKey<Row>, visible: readonly string[] | undefined, children: ReactNode): {
+    data: Row[];
+    children: ReactNode;
+    keyOf: (row: Row) => string;
+};

package/dist/category-cells.js

@@ -3,7 +3,7 @@ import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-run
 import { Children, cloneElement, Fragment, isValidElement } from "react";
 import { Cell } from "recharts";
 /** Only Pie and Radial category mode use this native Cell defaulting seam. */
-export function categoryCells(data, categoryKey, config, children, fill) {
+export function categoryCells(data, categoryKey, config, paints, children, fill) {
     if (!data)
         throw new Error("Category color defaults require explicit data");
     const colors = data.map((row) => {
@@ -15,7 +15,7 @@ export function categoryCells(data, categoryKey, config, children, fill) {
         if (typeof key !== "string" || !Object.hasOwn(config, key))
             throw new Error("categoryKey must resolve to a string key in Root.config for every row");
         const datumFill = row !== null && typeof row === "object" && "fill" in row ? row.fill : undefined;
-        return fill === undefined && datumFill === undefined ? `var(--color-${key})` : undefined;
+        return fill === undefined && datumFill === undefined ? paints[key] : undefined;
     });
     if (fill !== undefined)
         return children;
@@ -39,3 +39,33 @@ export function categoryCells(data, categoryKey, config, children, fill) {
             // biome-ignore lint/suspicious/noArrayIndexKey: Native Cell alignment is positional; Cells hold no consumer state.
             _jsx(Cell, { ...(color ? { fill: color } : {}) }, `kind-category-${index + offset}`)))] }));
 }
+/** Filter original rows and positional Cells together before native geometry is computed. */
+export function filterCategoryRows(data, categoryKey, visible, children) {
+    const keyOf = (row) => {
+        const key = typeof categoryKey === "function"
+            ? categoryKey(row)
+            : row !== null && typeof row === "object" && Object.hasOwn(row, categoryKey)
+                ? row[categoryKey]
+                : undefined;
+        if (typeof key !== "string" || !key)
+            throw new Error("Root interaction binding requires stable string category keys");
+        return key;
+    };
+    const keys = data.map(keyOf);
+    if (new Set(keys).size !== keys.length)
+        throw new Error("Root interaction binding requires unique category keys");
+    const keep = keys.map((key) => visible === undefined || visible.includes(key));
+    let index = 0;
+    function filter(parts) {
+        return Children.map(parts, (child) => {
+            if (!isValidElement(child))
+                return child;
+            if (child.type === Fragment)
+                return cloneElement(child, {}, filter(child.props.children));
+            if (child.type !== Cell)
+                return child;
+            return keep[index++] ? child : null;
+        });
+    }
+    return { data: data.filter((_row, index) => keep[index]), children: filter(children), keyOf };
+}