@flikk/ui 1.0.0-beta.1

package/dist/components/charts/DonutChart/DonutChart.types.d.ts

@@ -0,0 +1,129 @@
+import React from "react";
+import { HTMLMotionProps } from "motion/react";
+/**
+ * Color configuration for the donut chart
+ */
+export interface DonutChartColors {
+    /** Primary color for solid color mode */
+    primary?: string;
+    /** Gradient start color */
+    from?: string;
+    /** Gradient end color */
+    to?: string;
+}
+/**
+ * Theme overrides for the DonutChart component
+ */
+export interface DonutChartThemeOverrides {
+    /** Base style for the container */
+    baseStyle?: string;
+    /** Track (background circle) styling */
+    track?: string;
+    /** Progress arc styling */
+    progress?: string;
+    /** Text styling */
+    text?: {
+        /** Main label styling */
+        label?: string;
+        /** Subtitle styling */
+        subtitle?: string;
+    };
+    /** Default colors */
+    colors?: {
+        /** Default primary color */
+        primary?: string;
+        /** Default secondary color for gradients */
+        secondary?: string;
+        /** Track color */
+        track?: string;
+    };
+}
+/**
+ * DonutChart component props
+ */
+export interface DonutChartProps extends Omit<HTMLMotionProps<"div">, "children"> {
+    /**
+     * Visual variant for the donut chart (solid or segmented)
+     * @default "solid"
+     */
+    variant?: "solid" | "segmented";
+    /**
+     * Percentage value to display (0-100)
+     * Values outside this range will be clamped
+     */
+    percentage: number;
+    /**
+     * Custom label to display in center
+     * If not provided, will show percentage with % symbol
+     */
+    label?: React.ReactNode;
+    /**
+     * Subtitle text to display below the main label
+     */
+    subtitle?: React.ReactNode;
+    /**
+     * Size of the donut chart
+     * Can be a number (pixels) or CSS size string
+     * @default 200
+     */
+    size?: number | string;
+    /**
+     * Thickness of the donut stroke
+     * Progress arc will be 2x this thickness
+     * @default 2
+     */
+    thickness?: number;
+    /**
+     * Total number of segments when using the segmented variant
+     * @default 32
+     */
+    segmentCount?: number;
+    /**
+     * Fraction of each segment kept empty to create spacing (0-0.8)
+     * Only applies to the segmented variant
+     * @default 0.35
+     */
+    segmentGap?: number;
+    /**
+     * Whether to show entrance animation
+     * @default true
+     */
+    showAnimation?: boolean;
+    /**
+     * Color configuration for the chart
+     */
+    colors?: DonutChartColors;
+    /**
+     * Component-level theme overrides
+     */
+    theme?: DonutChartThemeOverrides;
+    /**
+     * Additional content to display in the center
+     * Will be rendered below the label and subtitle
+     */
+    children?: React.ReactNode;
+    /**
+     * Additional CSS classes
+     */
+    className?: string;
+}
+/**
+ * Default theme configuration
+ */
+export interface DonutChartTheme extends Required<DonutChartThemeOverrides> {
+}
+/**
+ * Animation configuration (internal use)
+ */
+export interface DonutChartAnimationConfig {
+    /** Whether animations are enabled */
+    enabled: boolean;
+    /** Animation duration in seconds */
+    duration: number;
+    /** Animation delay in seconds */
+    delay: number;
+    /** Spring animation stiffness */
+    stiffness: number;
+    /** Spring animation damping */
+    damping: number;
+}

package/dist/components/charts/DonutChart/MultiSegmentDonutChart.d.ts

@@ -0,0 +1,7 @@
+import React from "react";
+import type { MultiSegmentDonutChartProps } from "./MultiSegmentDonutChart.types";
+/**
+ * MultiSegmentDonutChart component for displaying multiple data values in a circular chart
+ * Each segment represents a different data point with its own value and optional color
+ */
+export declare const MultiSegmentDonutChart: React.FC<MultiSegmentDonutChartProps>;

package/dist/components/charts/DonutChart/MultiSegmentDonutChart.js

@@ -0,0 +1,252 @@
+import { jsx, jsxs } from 'react/jsx-runtime';
+import React__default, { useState, useEffect, useMemo } from 'react';
+import { useMotionValue, useTransform, animate, motion, useReducedMotion } from 'motion/react';
+import { cn } from '../../../utils/cn.js';
+import { multiSegmentDonutChartTheme } from './MultiSegmentDonutChart.theme.js';
+import { describeRingSegmentPath, describeArcPathClockwise, clamp } from './donut-utils.js';
+
+const AnimatedSegmentInner = ({ center, innerRadius, outerRadius, startAngle, endAngle, color, delay, duration, shouldAnimate, shouldReduceMotion, isHovered, isFaded, onMouseEnter, onMouseLeave, onClick, clickable, }) => {
+    // Motion value for animation progress (0 to 1)
+    const progress = useMotionValue(0);
+    // Transform progress to current end angle
+    const currentEndAngle = useTransform(progress, [0, 1], [startAngle, endAngle]);
+    // Generate path based on current angle
+    const [path, setPath] = useState(() => describeRingSegmentPath(center, center, innerRadius, outerRadius, startAngle, startAngle // Start with zero-width segment
+    ));
+    // Update path when currentEndAngle changes
+    useEffect(() => {
+        const unsubscribe = currentEndAngle.on("change", (latest) => {
+            const newPath = describeRingSegmentPath(center, center, innerRadius, outerRadius, startAngle, latest);
+            setPath(newPath);
+        });
+        return () => unsubscribe();
+    }, [center, innerRadius, outerRadius, startAngle, currentEndAngle]);
+    // Trigger animation
+    useEffect(() => {
+        if (shouldReduceMotion) {
+            // Skip animation for accessibility - show full segment immediately
+            progress.set(1);
+        }
+        else if (shouldAnimate) {
+            // Run the drawing animation with spring physics (same as base DonutChart)
+            const controls = animate(progress, 1, {
+                type: "spring",
+                stiffness: 80, // Same as CIRCULAR_CHART_ANIMATIONS.donut.preset ('smooth')
+                damping: 20,
+                delay,
+            });
+            return () => controls.stop();
+        }
+        // If shouldAnimate is false, progress stays at 0 (waiting state)
+    }, [shouldAnimate, shouldReduceMotion, progress, duration, delay]);
+    return (jsx(motion.path, { d: path, fill: color, animate: {
+            opacity: isFaded ? 0.6 : 1,
+            scale: isHovered ? 1.025 : 1,
+        }, transition: {
+            scale: { duration: 0.2 },
+            opacity: { duration: 0.2 },
+        }, style: {
+            transformOrigin: "50% 50%",
+            cursor: clickable ? "pointer" : "default",
+            filter: isHovered
+                ? `drop-shadow(0 4px 8px ${color}60)`
+                : "none",
+        }, onMouseEnter: onMouseEnter, onMouseLeave: onMouseLeave, onClick: onClick }));
+};
+const AnimatedSegment = React__default.memo(AnimatedSegmentInner);
+const AnimatedStrokeSegmentInner = ({ center, radius, strokeWidth, startAngle, endAngle, color, delay, shouldAnimate, shouldReduceMotion, isHovered, isFaded, onMouseEnter, onMouseLeave, onClick, clickable, }) => {
+    // Calculate cap compensation - rounded caps extend by strokeWidth/2 at each end
+    // Convert to degrees: (strokeWidth/2) / radius * (180/π)
+    const capCompensationDegrees = ((strokeWidth / 2) / radius) * (180 / Math.PI);
+    // Adjust angles to account for rounded cap protrusion
+    const adjustedStartAngle = startAngle + capCompensationDegrees;
+    const adjustedEndAngle = endAngle - capCompensationDegrees;
+    // Ensure we have a valid arc (end > start)
+    const validEndAngle = Math.max(adjustedEndAngle, adjustedStartAngle + 1);
+    // Calculate arc path (clockwise for proper animation direction) and length
+    const arcPath = describeArcPathClockwise(center, center, radius, adjustedStartAngle, validEndAngle);
+    const sweepAngle = validEndAngle - adjustedStartAngle;
+    const arcLength = (sweepAngle / 360) * 2 * Math.PI * radius;
+    return (jsx(motion.path, { d: arcPath, fill: "none", stroke: color, strokeWidth: strokeWidth, strokeLinecap: "round", strokeDasharray: arcLength, initial: { strokeDashoffset: arcLength, opacity: 1, scale: 1 }, animate: {
+            strokeDashoffset: shouldAnimate ? 0 : arcLength,
+            opacity: isFaded ? 0.6 : 1,
+            scale: isHovered ? 1.025 : 1,
+        }, transition: {
+            strokeDashoffset: shouldReduceMotion
+                ? { duration: 0 }
+                : {
+                    type: "spring",
+                    stiffness: 80,
+                    damping: 20,
+                    delay,
+                },
+            scale: { duration: 0.2 },
+            opacity: { duration: 0.2 },
+        }, style: {
+            transformOrigin: "50% 50%",
+            cursor: clickable ? "pointer" : "default",
+            filter: isHovered ? `drop-shadow(0 4px 8px ${color}60)` : "none",
+        }, onMouseEnter: onMouseEnter, onMouseLeave: onMouseLeave, onClick: onClick }));
+};
+const AnimatedStrokeSegment = React__default.memo(AnimatedStrokeSegmentInner);
+/**
+ * MultiSegmentDonutChart component for displaying multiple data values in a circular chart
+ * Each segment represents a different data point with its own value and optional color
+ */
+const MultiSegmentDonutChart = ({ data, size = 200, thickness = 4, segmentGap = 0.05, showAnimation = true, showLegend = false, legendPosition = "right", centerContent, className, theme: themeOverrides, onSegmentHover, onSegmentClick, roundedCaps = true, ...restProps }) => {
+    const [hoveredSegment, setHoveredSegment] = useState(null);
+    const [hasAnimated, setHasAnimated] = useState(false);
+    const shouldReduceMotion = useReducedMotion();
+    // Merge theme with overrides
+    const theme = {
+        ...multiSegmentDonutChartTheme,
+        ...(themeOverrides || {}),
+        legend: {
+            ...multiSegmentDonutChartTheme.legend,
+            ...((themeOverrides === null || themeOverrides === void 0 ? void 0 : themeOverrides.legend) || {}),
+        },
+        colors: (themeOverrides === null || themeOverrides === void 0 ? void 0 : themeOverrides.colors) || multiSegmentDonutChartTheme.colors || [],
+    };
+    // Calculate SVG parameters
+    const svgSize = 100;
+    const center = svgSize / 2;
+    const strokeWidth = thickness * 2;
+    const radius = (svgSize - strokeWidth) / 2;
+    const innerRadius = Math.max(0, radius - strokeWidth / 2);
+    const outerRadius = radius + strokeWidth / 2;
+    // Validate and prepare data
+    const validatedData = useMemo(() => {
+        if (!data || data.length === 0) {
+            return [];
+        }
+        // Ensure percentages sum to 100 or less
+        const totalPercentage = data.reduce((sum, segment) => sum + segment.percentage, 0);
+        if (totalPercentage > 100) {
+            if (process.env.NODE_ENV !== 'production') {
+                console.warn(`[MultiSegmentDonutChart]: Total percentage (${totalPercentage}) exceeds 100%. Normalizing values.`);
+            }
+            // Normalize percentages
+            return data.map((segment) => ({
+                ...segment,
+                percentage: (segment.percentage / totalPercentage) * 100,
+            }));
+        }
+        return data;
+    }, [data]);
+    // Calculate segment paths, colors, and animation timings
+    const segments = useMemo(() => {
+        if (validatedData.length === 0) {
+            return [];
+        }
+        const gapRatio = clamp(segmentGap, 0, 0.8);
+        const totalGapDegrees = validatedData.length * 360 * gapRatio / validatedData.length;
+        const effectiveCircle = 360 - totalGapDegrees;
+        let currentAngle = 0; // Start at 12 o'clock (top)
+        let cumulativeDelay = 0; // Track cumulative delay for sequential animation
+        // Base duration for a full 100% segment (in seconds)
+        const baseDuration = 0.6;
+        return validatedData.map((segment, index) => {
+            // Calculate the angle for this segment
+            const segmentAngle = (segment.percentage / 100) * effectiveCircle;
+            const gapAngle = 360 * gapRatio / validatedData.length;
+            const startAngle = currentAngle;
+            const endAngle = currentAngle + segmentAngle;
+            // Get color from segment or theme palette
+            const color = segment.color ||
+                (theme.colors && theme.colors[index % theme.colors.length]) ||
+                "#3b82f6";
+            // Generate the SVG path (full segment)
+            const path = describeRingSegmentPath(center, center, innerRadius, outerRadius, startAngle, endAngle);
+            // Calculate animation duration proportional to segment size
+            // Minimum duration of 0.15s to ensure visibility
+            const duration = Math.max(0.15, (segment.percentage / 100) * baseDuration);
+            // This segment starts after all previous segments complete
+            const delay = cumulativeDelay;
+            // Add this segment's duration to cumulative delay for next segment
+            cumulativeDelay += duration;
+            // Move to next segment start position
+            currentAngle = endAngle + gapAngle;
+            return {
+                ...segment,
+                path,
+                color,
+                startAngle,
+                endAngle,
+                animationDuration: duration,
+                animationDelay: delay,
+            };
+        });
+    }, [
+        validatedData,
+        center,
+        innerRadius,
+        outerRadius,
+        segmentGap,
+        theme.colors,
+    ]);
+    // Handle component mount for animation
+    useEffect(() => {
+        if (showAnimation && !shouldReduceMotion) {
+            setHasAnimated(true);
+        }
+        else {
+            // If animations disabled, immediately show final state
+            setHasAnimated(true);
+        }
+    }, [showAnimation, shouldReduceMotion]);
+    // Handle hover interactions
+    const handleSegmentMouseEnter = (index) => {
+        setHoveredSegment(index);
+        if (onSegmentHover) {
+            onSegmentHover(segments[index]);
+        }
+    };
+    const handleSegmentMouseLeave = () => {
+        setHoveredSegment(null);
+        if (onSegmentHover) {
+            onSegmentHover(null);
+        }
+    };
+    const handleSegmentClick = (index) => {
+        if (onSegmentClick) {
+            onSegmentClick(segments[index]);
+        }
+    };
+    const containerSize = typeof size === "number" ? `${size}px` : size;
+    // Layout classes based on legend position
+    const getLayoutClasses = () => {
+        if (!showLegend) {
+            return "";
+        }
+        switch (legendPosition) {
+            case "top":
+                return "flex-col";
+            case "bottom":
+                return "flex-col-reverse";
+            case "left":
+                return "flex-row-reverse";
+            case "right":
+            default:
+                return "flex-row";
+        }
+    };
+    const renderLegend = () => {
+        var _a;
+        if (!showLegend) {
+            return null;
+        }
+        return (jsx("div", { className: cn((_a = theme.legend) === null || _a === void 0 ? void 0 : _a.container, legendPosition === "top" || legendPosition === "bottom" ? "flex-row flex-wrap" : "flex-col"), children: segments.map((segment, index) => {
+                var _a, _b, _c, _d;
+                return (jsxs("div", { className: cn((_a = theme.legend) === null || _a === void 0 ? void 0 : _a.item), onMouseEnter: () => handleSegmentMouseEnter(index), onMouseLeave: handleSegmentMouseLeave, onClick: () => handleSegmentClick(index), style: {
+                        opacity: hoveredSegment !== null && hoveredSegment !== index ? 0.5 : 1,
+                    }, children: [jsx("div", { className: cn((_b = theme.legend) === null || _b === void 0 ? void 0 : _b.colorDot), style: { backgroundColor: segment.color } }), segment.label && (jsx("span", { className: cn((_c = theme.legend) === null || _c === void 0 ? void 0 : _c.label), children: segment.label })), jsxs("span", { className: cn((_d = theme.legend) === null || _d === void 0 ? void 0 : _d.value), children: [segment.value, " (", segment.percentage.toFixed(1), "%)"] })] }, `legend-${index}`));
+            }) }));
+    };
+    if (!data || data.length === 0) {
+        return (jsx("div", { className: cn(theme.baseStyle, className), style: { width: containerSize, height: containerSize }, children: jsx("div", { className: "text-sm text-[var(--color-text-secondary)]", children: "No data" }) }));
+    }
+    return (jsxs("div", { className: cn("flex gap-4 items-center", getLayoutClasses(), className), children: [jsxs(motion.div, { className: cn(theme.baseStyle), style: { width: containerSize, height: containerSize }, role: "img", "aria-label": `Donut chart with ${segments.length} segments`, ...restProps, children: [jsxs("svg", { viewBox: `0 0 ${svgSize} ${svgSize}`, width: "100%", height: "100%", className: "overflow-visible relative z-10", children: [jsx("circle", { cx: center, cy: center, r: radius, fill: "none", stroke: "#000000", strokeWidth: strokeWidth > 2 ? strokeWidth - 2 : 1, opacity: 0.03 }), segments.map((segment, index) => roundedCaps ? (jsx(AnimatedStrokeSegment, { center: center, radius: radius, strokeWidth: strokeWidth, startAngle: segment.startAngle, endAngle: segment.endAngle, color: segment.color, delay: segment.animationDelay, shouldAnimate: showAnimation && hasAnimated, shouldReduceMotion: shouldReduceMotion, isHovered: hoveredSegment === index, isFaded: hoveredSegment !== null && hoveredSegment !== index, onMouseEnter: () => handleSegmentMouseEnter(index), onMouseLeave: handleSegmentMouseLeave, onClick: () => handleSegmentClick(index), clickable: !!onSegmentClick }, `segment-${index}`)) : (jsx(AnimatedSegment, { center: center, innerRadius: innerRadius, outerRadius: outerRadius, startAngle: segment.startAngle, endAngle: segment.endAngle, color: segment.color, delay: segment.animationDelay, duration: segment.animationDuration, shouldAnimate: showAnimation && hasAnimated, shouldReduceMotion: shouldReduceMotion, isHovered: hoveredSegment === index, isFaded: hoveredSegment !== null && hoveredSegment !== index, onMouseEnter: () => handleSegmentMouseEnter(index), onMouseLeave: handleSegmentMouseLeave, onClick: () => handleSegmentClick(index), clickable: !!onSegmentClick }, `segment-${index}`)))] }), centerContent && (jsx("div", { className: cn(theme.centerContent), children: centerContent }))] }), renderLegend()] }));
+};
+MultiSegmentDonutChart.displayName = "MultiSegmentDonutChart";
+
+export { MultiSegmentDonutChart };

package/dist/components/charts/DonutChart/MultiSegmentDonutChart.theme.d.ts

@@ -0,0 +1,50 @@
+import { MultiSegmentDonutChartThemeOverrides } from "./MultiSegmentDonutChart.types";
+/**
+ * Default theme for the MultiSegmentDonutChart component
+ */
+export declare const multiSegmentDonutChartTheme: MultiSegmentDonutChartThemeOverrides;
+/**
+ * Pre-defined color palettes for quick customization
+ */
+export declare const multiSegmentColorPalettes: {
+    readonly default: readonly ["#3b82f6", "#10b981", "#f59e0b", "#ef4444", "#8b5cf6", "#ec4899", "#06b6d4", "#84cc16"];
+    readonly pastel: readonly ["#93c5fd", "#86efac", "#fde68a", "#fca5a5", "#c4b5fd", "#f9a8d4", "#a5f3fc", "#d9f99d"];
+    readonly blues: readonly ["#dbeafe", "#bfdbfe", "#93c5fd", "#60a5fa", "#3b82f6", "#2563eb", "#1d4ed8", "#1e40af"];
+    readonly warm: readonly ["#fef3c7", "#fcd34d", "#f59e0b", "#f97316", "#ef4444", "#dc2626", "#b91c1c", "#991b1b"];
+    readonly cool: readonly ["#cffafe", "#a5f3fc", "#22d3ee", "#06b6d4", "#0891b2", "#0e7490", "#155e75", "#164e63"];
+    readonly earth: readonly ["#d6d3d1", "#a8a29e", "#78716c", "#57534e", "#44403c", "#292524", "#1c1917", "#0c0a09"];
+    readonly neon: readonly ["#fbbf24", "#facc15", "#84cc16", "#22c55e", "#14b8a6", "#06b6d4", "#0ea5e9", "#3b82f6"];
+    readonly professional: readonly ["#1e40af", "#0369a1", "#047857", "#65a30d", "#ca8a04", "#dc2626", "#9333ea", "#be123c"];
+    readonly highContrast: readonly ["#000000", "#dc2626", "#16a34a", "#0284c7", "#9333ea", "#ea580c", "#0891b2", "#4338ca"];
+};
+/**
+ * Size presets for common use cases
+ */
+export declare const multiSegmentDonutChartSizes: {
+    readonly xs: 120;
+    readonly sm: 160;
+    readonly md: 200;
+    readonly lg: 280;
+    readonly xl: 360;
+    readonly "2xl": 480;
+};
+/**
+ * Thickness presets
+ */
+export declare const multiSegmentDonutChartThickness: {
+    readonly thin: 1;
+    readonly normal: 2;
+    readonly thick: 3;
+    readonly bold: 4;
+    readonly extraBold: 6;
+};
+/**
+ * Utility function to get color palette by name
+ */
+export declare const getColorPalette: (name: keyof typeof multiSegmentColorPalettes) => readonly ["#3b82f6", "#10b981", "#f59e0b", "#ef4444", "#8b5cf6", "#ec4899", "#06b6d4", "#84cc16"] | readonly ["#93c5fd", "#86efac", "#fde68a", "#fca5a5", "#c4b5fd", "#f9a8d4", "#a5f3fc", "#d9f99d"] | readonly ["#dbeafe", "#bfdbfe", "#93c5fd", "#60a5fa", "#3b82f6", "#2563eb", "#1d4ed8", "#1e40af"] | readonly ["#fef3c7", "#fcd34d", "#f59e0b", "#f97316", "#ef4444", "#dc2626", "#b91c1c", "#991b1b"] | readonly ["#cffafe", "#a5f3fc", "#22d3ee", "#06b6d4", "#0891b2", "#0e7490", "#155e75", "#164e63"] | readonly ["#d6d3d1", "#a8a29e", "#78716c", "#57534e", "#44403c", "#292524", "#1c1917", "#0c0a09"] | readonly ["#fbbf24", "#facc15", "#84cc16", "#22c55e", "#14b8a6", "#06b6d4", "#0ea5e9", "#3b82f6"] | readonly ["#1e40af", "#0369a1", "#047857", "#65a30d", "#ca8a04", "#dc2626", "#9333ea", "#be123c"] | readonly ["#000000", "#dc2626", "#16a34a", "#0284c7", "#9333ea", "#ea580c", "#0891b2", "#4338ca"];
+/**
+ * Type definitions for exported constants
+ */
+export type MultiSegmentColorPalette = keyof typeof multiSegmentColorPalettes;
+export type MultiSegmentDonutChartSize = keyof typeof multiSegmentDonutChartSizes;
+export type MultiSegmentDonutChartThickness = keyof typeof multiSegmentDonutChartThickness;

package/dist/components/charts/DonutChart/MultiSegmentDonutChart.theme.js

@@ -0,0 +1,36 @@
+/**
+ * Default theme for the MultiSegmentDonutChart component
+ */
+const multiSegmentDonutChartTheme = {
+    // Base container styles
+    baseStyle: "relative flex items-center justify-center transition-all duration-300",
+    // Background track styling
+    track: "text-[var(--color-border)]",
+    // Legend styling
+    legend: {
+        container: "flex flex-col gap-2 text-sm",
+        item: "flex items-center gap-2 cursor-pointer hover:opacity-80 transition-opacity",
+        label: "text-[var(--color-text-primary)] font-medium",
+        value: "text-[var(--color-text-secondary)] ml-auto",
+        colorDot: "w-3 h-3 rounded-full flex-shrink-0",
+    },
+    // Center content area styling
+    centerContent: "absolute inset-0 flex flex-col items-center justify-center text-center z-20 pointer-events-none",
+    // Default color palette - using a vibrant, accessible palette
+    colors: [
+        "#3b82f6", // blue-500
+        "#10b981", // emerald-500
+        "#f59e0b", // amber-500
+        "#ef4444", // red-500
+        "#8b5cf6", // violet-500
+        "#ec4899", // pink-500
+        "#06b6d4", // cyan-500
+        "#84cc16", // lime-500
+        "#f97316", // orange-500
+        "#6366f1", // indigo-500
+        "#14b8a6", // teal-500
+        "#a855f7", // purple-500
+    ],
+};
+
+export { multiSegmentDonutChartTheme };

package/dist/components/charts/DonutChart/MultiSegmentDonutChart.types.d.ts

@@ -0,0 +1,124 @@
+import React from "react";
+import { HTMLMotionProps } from "motion/react";
+/**
+ * Data segment for the multi-segment donut chart
+ */
+export interface DonutSegment {
+    /**
+     * The actual value this segment represents
+     */
+    value: number;
+    /**
+     * The percentage this segment represents (0-100)
+     * This should be calculated based on the total of all values
+     */
+    percentage: number;
+    /**
+     * Optional label for this segment
+     */
+    label?: string;
+    /**
+     * Optional custom color for this segment
+     * If not provided, will use colors from the theme palette
+     */
+    color?: string;
+}
+/**
+ * Theme overrides for the MultiSegmentDonutChart component
+ */
+export interface MultiSegmentDonutChartThemeOverrides {
+    /** Base style for the container */
+    baseStyle?: string;
+    /** Track (background circle) styling */
+    track?: string;
+    /** Legend container styling */
+    legend?: {
+        /** Container styles */
+        container?: string;
+        /** Individual legend item styles */
+        item?: string;
+        /** Legend label text styles */
+        label?: string;
+        /** Legend value text styles */
+        value?: string;
+        /** Color indicator dot styles */
+        colorDot?: string;
+    };
+    /** Center content area styling */
+    centerContent?: string;
+    /** Default color palette for segments */
+    colors?: string[];
+}
+/**
+ * MultiSegmentDonutChart component props
+ */
+export interface MultiSegmentDonutChartProps extends Omit<HTMLMotionProps<"div">, "children"> {
+    /**
+     * Array of data segments to display
+     * Each segment should have value and percentage
+     */
+    data: DonutSegment[];
+    /**
+     * Size of the donut chart
+     * Can be a number (pixels) or CSS size string
+     * @default 200
+     */
+    size?: number | string;
+    /**
+     * Thickness of the donut stroke
+     * @default 2
+     */
+    thickness?: number;
+    /**
+     * Gap between segments as a fraction (0-0.8)
+     * 0 means no gap, 0.8 means large gaps
+     * @default 0.02
+     */
+    segmentGap?: number;
+    /**
+     * Whether to show entrance animation
+     * @default true
+     */
+    showAnimation?: boolean;
+    /**
+     * Whether to show a legend with labels and values
+     * @default false
+     */
+    showLegend?: boolean;
+    /**
+     * Position of the legend
+     * @default "right"
+     */
+    legendPosition?: "top" | "right" | "bottom" | "left";
+    /**
+     * Custom content to display in the center of the donut
+     */
+    centerContent?: React.ReactNode;
+    /**
+     * Component-level theme overrides
+     */
+    theme?: MultiSegmentDonutChartThemeOverrides;
+    /**
+     * Additional CSS classes
+     */
+    className?: string;
+    /**
+     * Callback when a segment is hovered
+     */
+    onSegmentHover?: (segment: DonutSegment | null) => void;
+    /**
+     * Callback when a segment is clicked
+     */
+    onSegmentClick?: (segment: DonutSegment) => void;
+    /**
+     * Whether to render segments with rounded end caps
+     * Uses stroke-based rendering with stroke-linecap="round"
+     * @default true
+     */
+    roundedCaps?: boolean;
+}
+/**
+ * Default theme configuration
+ */
+export interface MultiSegmentDonutChartTheme extends Required<MultiSegmentDonutChartThemeOverrides> {
+}

package/dist/components/charts/DonutChart/donut-utils.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Shared utility functions for DonutChart components
+ */
+/**
+ * Resolves a CSS variable to its computed value
+ * Falls back to the provided value if not a CSS variable or resolution fails
+ */
+export declare const resolveCssVariable: (value: string, fallback?: string) => string;
+/**
+ * Clamps a value between a minimum and maximum
+ */
+export declare const clamp: (value: number, min: number, max: number) => number;
+/**
+ * Converts polar coordinates to cartesian coordinates
+ */
+export declare const polarToCartesian: (centerX: number, centerY: number, radius: number, angleInDegrees: number) => {
+    x: number;
+    y: number;
+};
+/**
+ * Creates an SVG path for a ring segment (donut segment)
+ */
+export declare const describeRingSegmentPath: (centerX: number, centerY: number, innerRadius: number, outerRadius: number, startAngle: number, endAngle: number) => string;
+/**
+ * Creates an SVG path for an arc (no inner radius)
+ * Draws counter-clockwise (for backwards compatibility)
+ */
+export declare const describeArcPath: (centerX: number, centerY: number, radius: number, startAngle: number, endAngle: number) => string;
+/**
+ * Creates an SVG path for an arc that draws clockwise
+ * Used for stroke-dashoffset animation that reveals clockwise
+ */
+export declare const describeArcPathClockwise: (centerX: number, centerY: number, radius: number, startAngle: number, endAngle: number) => string;
+/**
+ * Converts a hex color to RGB components
+ */
+export declare const hexToRgb: (value: string) => {
+    r: number;
+    g: number;
+    b: number;
+} | null;
+/**
+ * Interpolates between two hex colors
+ */
+export declare const interpolateHexColor: (from: string, to: string, factor: number) => string;