@flikk/ui 1.0.0-beta.1

package/dist/components/core/Alert/Alert.theme.js

@@ -0,0 +1,27 @@
+/**
+ * Default theme configuration for Alert component
+ * Uses flat color organization matching Badge pattern
+ */
+const alertTheme = {
+    // Base styles applied to all alerts
+    baseStyle: "relative flex items-start gap-3 rounded-[var(--alert-radius)] p-4 text-sm border border-[var(--color-border)] backdrop-blur-md bg-white dark:bg-[var(--color-background-secondary)]/80",
+    // Visual style variants (structure only, no colors)
+    variants: {
+        default: "",
+        glass: "glass-effect",
+    },
+    // Icon color styles per color
+    iconColors: {
+        neutral: "text-[var(--color-text-primary)]",
+        primary: "text-[var(--color-primary)]",
+        success: "text-[var(--color-success)]",
+        warning: "text-[var(--color-warning)]",
+        danger: "text-[var(--color-danger)]",
+    },
+    // State styles
+    states: {
+        dismissible: "pr-10",
+    },
+};
+
+export { alertTheme };

package/dist/components/core/Alert/Alert.types.d.ts

@@ -0,0 +1,66 @@
+import { HTMLAttributes, ReactNode } from "react";
+/**
+ * Alert semantic colors (intent)
+ */
+export type AlertColor = "neutral" | "primary" | "success" | "warning" | "danger";
+/**
+ * Alert visual variant
+ */
+export type AlertVariant = "default" | "glass";
+/**
+ * Theme configuration for Alert component
+ */
+export interface AlertTheme {
+    /** Base styles applied to all alerts */
+    baseStyle: string;
+    /** Visual style variants (structure only, no colors) */
+    variants: Record<AlertVariant, string>;
+    /** Icon color styles per color */
+    iconColors: Record<AlertColor, string>;
+    /** State styles */
+    states: {
+        dismissible: string;
+    };
+}
+export interface AlertProps extends HTMLAttributes<HTMLDivElement> {
+    /** Visual variant */
+    variant?: AlertVariant;
+    /** Semantic color */
+    color?: AlertColor;
+    /** The main title/message of the alert */
+    title?: string;
+    /** Additional description text */
+    description?: string;
+    /** Whether the alert can be dismissed */
+    dismissible?: boolean;
+    /**
+     * Custom icon for the alert
+     * - Provide custom icon: overrides the default variant icon
+     * - Set to null: hides icon completely
+     * - Leave undefined: shows default variant icon
+     */
+    icon?: ReactNode | null;
+    /** Whether to show the default icon for the variant */
+    showIcon?: boolean;
+    /**
+     * Avatar to display (takes precedence over icons)
+     * Example: avatar={<Avatar src="..." alt="User name" size="md" />}
+     */
+    avatar?: ReactNode;
+    /**
+     * Action buttons as ReactNode
+     * Example: actions={<><Button>Cancel</Button><Button variant="filled">Save</Button></>}
+     */
+    actions?: ReactNode;
+    /** Callback when the alert is dismissed */
+    onDismiss?: () => void;
+    /** Custom class name */
+    className?: string;
+    /** Children content */
+    children?: ReactNode;
+    /**
+     * Enable dark mode styling.
+     * @default false
+     */
+    darkMode?: boolean;
+}

package/dist/components/core/Alert/index.d.ts

@@ -0,0 +1,3 @@
+export { Alert } from './Alert';
+export type { AlertProps, AlertVariant, AlertColor, AlertTheme } from './Alert.types';
+export { alertTheme } from './Alert.theme';

package/dist/components/core/AlertDialog/AlertDialog.d.ts

@@ -0,0 +1,5 @@
+import { AlertDialogProps } from "./AlertDialog.types";
+export declare const AlertDialog: {
+    ({ trigger, icon, title, description, footer, className, }: AlertDialogProps): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};

package/dist/components/core/AlertDialog/AlertDialog.js

@@ -0,0 +1,17 @@
+import { jsxs, Fragment, jsx } from 'react/jsx-runtime';
+import { useState, isValidElement, cloneElement } from 'react';
+import { Modal } from '../Modal/Modal.js';
+import { cn } from '../../../utils/cn.js';
+
+const AlertDialog = ({ trigger, icon, title, description, footer, className, }) => {
+    const [isOpen, setIsOpen] = useState(false);
+    const handleOpen = () => setIsOpen(true);
+    const handleClose = () => setIsOpen(false);
+    const triggerElement = isValidElement(trigger)
+        ? cloneElement(trigger, { onClick: handleOpen })
+        : null;
+    return (jsxs(Fragment, { children: [triggerElement, jsxs(Modal, { isOpen: isOpen, onClose: handleClose, size: "sm", closeOnOverlayClick: false, closeOnEsc: false, showCloseButton: false, role: "alertdialog", className: cn("!overflow-visible", className), children: [jsxs(Modal.Header, { children: [icon && (jsx("div", { className: "text-2xl rounded-full p-3  mb-3 w-fit glass-effect shadow-xl shadow-black/5", "aria-hidden": "true", children: icon })), jsx(Modal.Title, { children: title })] }), jsx(Modal.Body, { className: "pt-2", children: jsx("div", { className: "text-[var(--color-text-secondary)] text-sm", children: description }) }), footer && (jsx(Modal.Footer, { className: "pb-6", children: footer(handleClose) }))] })] }));
+};
+AlertDialog.displayName = "AlertDialog";
+
+export { AlertDialog };

package/dist/components/core/AlertDialog/AlertDialog.types.d.ts

@@ -0,0 +1,18 @@
+import React from "react";
+export interface AlertDialogProps {
+    /** The element that triggers the dialog to open. */
+    trigger: React.ReactNode;
+    /** An optional icon to display in the header. */
+    icon?: React.ReactNode;
+    /** The title of the dialog. */
+    title: React.ReactNode;
+    /** The main content/description of the dialog. */
+    description: React.ReactNode;
+    /**
+     * A render prop for the footer, which receives a `close` function.
+     * Use this to render action buttons.
+     */
+    footer?: (close: () => void) => React.ReactNode;
+    /** Additional class names for the dialog content container. */
+    className?: string;
+}

package/dist/components/core/AlertDialog/index.d.ts

@@ -0,0 +1,2 @@
+export { AlertDialog } from "./AlertDialog";
+export * from "./AlertDialog.types";

package/dist/components/core/AspectRatio/AspectRatio.d.ts

@@ -0,0 +1,14 @@
+import React from "react";
+import { AspectRatioProps } from "./AspectRatio.types";
+/**
+ * AspectRatio component maintains a specific width-to-height ratio for its children.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <AspectRatio ratio={16 / 9}>
+ *   <img src="photo.jpg" alt="Landscape" className="object-cover w-full h-full" />
+ * </AspectRatio>
+ * ```
+ */
+export declare const AspectRatio: React.ForwardRefExoticComponent<AspectRatioProps & React.RefAttributes<HTMLDivElement>>;

package/dist/components/core/AspectRatio/AspectRatio.js

@@ -0,0 +1,24 @@
+import { jsx } from 'react/jsx-runtime';
+import React__default from 'react';
+import { cn } from '../../../utils/cn.js';
+
+/**
+ * AspectRatio component maintains a specific width-to-height ratio for its children.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <AspectRatio ratio={16 / 9}>
+ *   <img src="photo.jpg" alt="Landscape" className="object-cover w-full h-full" />
+ * </AspectRatio>
+ * ```
+ */
+const AspectRatio = React__default.forwardRef(({ ratio = 1, children, className, style, ...props }, ref) => {
+    return (jsx("div", { ref: ref, className: cn("relative w-full", className), style: {
+            paddingBottom: `${100 / ratio}%`,
+            ...style,
+        }, ...props, children: jsx("div", { className: "absolute inset-0", children: children }) }));
+});
+AspectRatio.displayName = "AspectRatio";
+
+export { AspectRatio };

package/dist/components/core/AspectRatio/AspectRatio.types.d.ts

@@ -0,0 +1,9 @@
+import { HTMLAttributes, ReactNode } from "react";
+export interface AspectRatioProps extends HTMLAttributes<HTMLDivElement> {
+    /** The desired ratio (width / height). e.g., 16/9, 4/3, 1 */
+    ratio?: number;
+    /** Content to render inside the aspect ratio container */
+    children: ReactNode;
+    /** Custom class name */
+    className?: string;
+}

package/dist/components/core/AspectRatio/index.d.ts

@@ -0,0 +1,2 @@
+export { AspectRatio } from "./AspectRatio";
+export type { AspectRatioProps } from "./AspectRatio.types";

package/dist/components/core/Avatar/Avatar.d.ts

@@ -0,0 +1,3 @@
+import React from "react";
+import { AvatarProps } from "./Avatar.types";
+export declare const Avatar: React.ForwardRefExoticComponent<AvatarProps & React.RefAttributes<HTMLDivElement>>;

package/dist/components/core/Avatar/Avatar.js

@@ -0,0 +1,96 @@
+import { jsxs, jsx } from 'react/jsx-runtime';
+import React__default, { useState, useRef, useEffect, useCallback } from 'react';
+import { cn } from '../../../utils/cn.js';
+import { avatarTheme } from './Avatar.theme.js';
+import { Tooltip } from '../Tooltip/Tooltip.js';
+import '../Tooltip/Tooltip.animations.js';
+
+const Avatar = React__default.forwardRef(({ src, alt = "Avatar", // Default alt text for better accessibility
+size = "md", status = "none", fallback, className, role, lazyLoad = true, retryCount = 0, retryDelay = 1000, contextualLabel, groupPosition, showTooltip = false, ...props }, ref) => {
+    const [imageError, setImageError] = useState(false);
+    const [retries, setRetries] = useState(0);
+    const retryTimerRef = useRef(null);
+    // Clear timeout on unmount to prevent memory leaks
+    useEffect(() => {
+        return () => {
+            if (retryTimerRef.current) {
+                clearTimeout(retryTimerRef.current);
+            }
+        };
+    }, []);
+    // Handle image loading errors with retry functionality
+    const handleImageError = useCallback(() => {
+        if (retries < retryCount) {
+            // Log error and retry
+            if (process.env.NODE_ENV !== "production") {
+                // eslint-disable-next-line no-console
+                console.warn(`Avatar image load failed, retrying (${retries + 1}/${retryCount})...`);
+            }
+            // Set up retry with delay
+            retryTimerRef.current = setTimeout(() => {
+                setRetries((prev) => prev + 1);
+                setImageError(false); // Reset error state to trigger re-render and retry
+            }, retryDelay);
+        }
+        else {
+            // Max retries reached, show fallback
+            if (process.env.NODE_ENV !== "production") {
+                // eslint-disable-next-line no-console
+                console.warn("Avatar image load failed after maximum retries");
+            }
+            setImageError(true);
+        }
+    }, [retries, retryCount, retryDelay]);
+    // Handle fallback content
+    const getFallbackContent = () => {
+        if (fallback) {
+            return fallback;
+        }
+        // If no fallback provided and no alt text, use placeholder
+        if (alt === "Avatar") {
+            return jsx("span", { "aria-hidden": "true", children: "?" });
+        }
+        // Use initials from alt text
+        const initials = alt
+            .split(" ")
+            .map((part) => part[0])
+            .slice(0, 1)
+            .join("")
+            .toUpperCase();
+        return jsx("span", { "aria-hidden": "true", children: initials });
+    };
+    // Determine status indicator size based on avatar size
+    const getStatusSize = () => {
+        switch (size) {
+            case "xs":
+                return "size-1.5 left-0 bottom-0.5";
+            case "sm":
+                return "size-2 left-0 bottom-0";
+            case "md":
+                return "size-2 left-0 bottom-0";
+            case "lg":
+                return "size-2.5 left-0 bottom-0";
+            case "xl":
+                return "size-3 left-0 bottom-0";
+            default:
+                return "size-2 left-0 bottom-0";
+        }
+    };
+    // Create full accessibility label including context if provided
+    const accessibilityLabel = contextualLabel
+        ? `${alt}${contextualLabel}`
+        : alt;
+    // Determine appropriate ARIA role
+    const ariaRole = role || (src ? undefined : "img");
+    // Avatar content to potentially wrap in tooltip
+    const avatarContent = (jsxs("div", { ref: ref, className: cn("relative inline-flex avatar-wrapper", groupPosition), role: ariaRole === "presentation" ? "presentation" : undefined, "aria-label": ariaRole === "presentation" ? undefined : accessibilityLabel, "data-size": size, "data-status": status, "data-error": imageError ? "true" : "false", ...props, children: [jsx("div", { className: cn(avatarTheme.baseStyle, avatarTheme.sizes[size], className), "aria-hidden": ariaRole === "presentation" ? "true" : undefined, "data-size": size, children: src && !imageError ? (jsx("img", { src: src, alt: alt, className: "size-full object-cover object-top", onError: handleImageError, loading: lazyLoad ? "lazy" : undefined, "aria-hidden": ariaRole === "presentation" ? "true" : undefined, "data-loaded": "true" })) : (jsx("div", { className: "avatar-fallback", children: getFallbackContent() })) }), status !== "none" && (jsx("span", { className: cn("absolute rounded-full ring-2 ring-[var(--color-background)]", getStatusSize(), avatarTheme.statuses[status]), "aria-label": `Status: ${status}`, role: "status", "data-status": status }))] }));
+    // Conditionally wrap in tooltip
+    if (showTooltip && alt && alt !== "Avatar") {
+        return (jsx(Tooltip, { content: alt, placement: "top", children: avatarContent }));
+    }
+    return avatarContent;
+});
+// Set display name for dev tools and Storybook
+Avatar.displayName = "Avatar";
+
+export { Avatar };

package/dist/components/core/Avatar/Avatar.theme.d.ts

@@ -0,0 +1,14 @@
+import { AvatarSize, AvatarStatus } from "./Avatar.types";
+/**
+ * Internal theme structure for the Avatar component
+ */
+interface AvatarTheme {
+    baseStyle: string;
+    sizes: Record<AvatarSize, string>;
+    statuses: Record<AvatarStatus, string>;
+}
+/**
+ * Default theme for the Avatar component
+ */
+export declare const avatarTheme: AvatarTheme;
+export {};

package/dist/components/core/Avatar/Avatar.theme.js

@@ -0,0 +1,25 @@
+/**
+ * Default theme for the Avatar component
+ */
+const avatarTheme = {
+    // Base styles for the avatar element
+    baseStyle: "relative inline-flex items-center justify-center overflow-hidden bg-neutral-200 text-[var(--color-text-primary)] font-semibold tracking-tighter rounded-[var(--avatar-radius)] ring-2 ring-[var(--color-primary)]/10 border border-[var(--border)] transition-all duration-200 focus:outline-none focus-visible:ring-2 focus-visible:ring-[var(--color-primary)] focus-visible:ring-offset-2 glass-effect",
+    // Size variants using CSS variables
+    sizes: {
+        xs: "size-[var(--avatar-size-xs)] text-[var(--avatar-text-xs)]",
+        sm: "size-[var(--avatar-size-sm)] text-[var(--avatar-text-sm)]",
+        md: "size-[var(--avatar-size-md)] text-[var(--avatar-text-md)]",
+        lg: "size-[var(--avatar-size-lg)] text-[var(--avatar-text-lg)]",
+        xl: "size-[var(--avatar-size-xl)] text-[var(--avatar-text-xl)]",
+    },
+    // Status indicator styles
+    statuses: {
+        online: "bg-[var(--color-success)]",
+        offline: "bg-neutral-400",
+        busy: "bg-[var(--color-danger)]",
+        away: "bg-[var(--color-warning)]",
+        none: "",
+    },
+};
+
+export { avatarTheme };

package/dist/components/core/Avatar/Avatar.types.d.ts

@@ -0,0 +1,69 @@
+import { ReactNode } from 'react';
+export type AvatarSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+export type AvatarStatus = 'online' | 'offline' | 'busy' | 'away' | 'none';
+export interface AvatarProps extends React.HTMLAttributes<HTMLDivElement> {
+    /**
+     * The source URL for the avatar image
+     */
+    src?: string;
+    /**
+     * Alternative text for the avatar image.
+     * Should describe the person or entity represented by the avatar.
+     * @default "Avatar"
+     */
+    alt?: string;
+    /**
+     * The size of the avatar
+     * @default "md"
+     */
+    size?: AvatarSize;
+    /**
+     * Optional status indicator
+     * @default "none"
+     */
+    status?: AvatarStatus;
+    /**
+     * Fallback content to display when image fails to load or no src is provided
+     */
+    fallback?: ReactNode;
+    /**
+     * ARIA role for the avatar
+     * Use "presentation" for purely decorative avatars
+     */
+    role?: string;
+    /**
+     * Whether to enable lazy loading for the image
+     * @default true
+     */
+    lazyLoad?: boolean;
+    /**
+     * Maximum number of times to retry loading the image if it fails
+     * @default 0
+     */
+    retryCount?: number;
+    /**
+     * Delay in milliseconds between retry attempts
+     * @default 1000
+     */
+    retryDelay?: number;
+    /**
+     * Additional contextual information about the avatar
+     * Useful for avatar groups or when more context is needed
+     */
+    contextualLabel?: string;
+    /**
+     * CSS class for the group positioning
+     * e.g. "-mr-3 ring-2 ring-white" for overlapping avatars
+     */
+    groupPosition?: string;
+    /**
+     * Whether to show a tooltip with the person's name on hover
+     * @default false
+     */
+    showTooltip?: boolean;
+    /**
+     * Number of initials to display in the fallback
+     * @default 2
+     */
+    initialsCount?: number;
+}

package/dist/components/core/Avatar/index.d.ts

@@ -0,0 +1,2 @@
+export { Avatar } from './Avatar';
+export type { AvatarProps, AvatarSize, AvatarStatus, } from './Avatar.types';

package/dist/components/core/AvatarGroup/AvatarGroup.animations.d.ts

@@ -0,0 +1,13 @@
+import { Variants } from "motion/react";
+/**
+ * Animation variants for AvatarGroup hover effects
+ * Creates a "Fan Pop" effect where:
+ * 1. Hovered avatar leaps forward (scales up + lifts)
+ * 2. Neighboring avatars rotate slightly away ("bow out") and recede
+ * 3. Keeps visual footprint compact while adding dynamic interest
+ */
+export declare const getAvatarGroupVariants: (shouldReduceMotion?: boolean | null, enableAnimations?: boolean) => Variants;
+/**
+ * Determines which animation state to use based on hover index
+ */
+export declare const getAnimationState: (currentIndex: number, hoveredIndex: number | null, enableAnimations: boolean) => string;

package/dist/components/core/AvatarGroup/AvatarGroup.animations.js

@@ -0,0 +1,79 @@
+/**
+ * Animation variants for AvatarGroup hover effects
+ * Creates a "Fan Pop" effect where:
+ * 1. Hovered avatar leaps forward (scales up + lifts)
+ * 2. Neighboring avatars rotate slightly away ("bow out") and recede
+ * 3. Keeps visual footprint compact while adding dynamic interest
+ */
+const getAvatarGroupVariants = (shouldReduceMotion = false, enableAnimations = true) => {
+    if (shouldReduceMotion || !enableAnimations) {
+        return {
+            initial: { scale: 1, opacity: 1, x: 0, y: 0, rotate: 0 },
+            hover: { scale: 1, x: 0, y: 0, rotate: 0 },
+            notHovered: { scale: 1, opacity: 1, x: 0, y: 0, rotate: 0 },
+            default: { scale: 1, opacity: 1, x: 0, y: 0, rotate: 0 },
+        };
+    }
+    return {
+        initial: {
+            scale: 1,
+            opacity: 1,
+            x: 0,
+            y: 0,
+            rotate: 0,
+            filter: "saturate(1)",
+        },
+        hover: {
+            scale: 1.02,
+            y: -1,
+            rotate: 0,
+            opacity: 1,
+            filter: "saturate(1)",
+            transition: {
+                type: "spring",
+                stiffness: 400,
+                damping: 15,
+                mass: 0.8,
+            },
+        },
+        notHovered: () => {
+            return {
+                scale: 0.95,
+                y: 2,
+                filter: "saturate(0)",
+                transition: {
+                    type: "spring",
+                    stiffness: 300,
+                    damping: 20,
+                },
+            };
+        },
+        default: {
+            scale: 1,
+            opacity: 1,
+            x: 0,
+            y: 0,
+            rotate: 0,
+            filter: "saturate(1)",
+            transition: {
+                type: "spring",
+                stiffness: 300,
+                damping: 20,
+            },
+        },
+    };
+};
+/**
+ * Determines which animation state to use based on hover index
+ */
+const getAnimationState = (currentIndex, hoveredIndex, enableAnimations) => {
+    if (!enableAnimations)
+        return "default";
+    if (hoveredIndex === currentIndex)
+        return "hover";
+    if (hoveredIndex !== null)
+        return "notHovered"; // Apply to ALL other items
+    return "default";
+};
+
+export { getAnimationState, getAvatarGroupVariants };

package/dist/components/core/AvatarGroup/AvatarGroup.d.ts

@@ -0,0 +1,3 @@
+import React from "react";
+import { AvatarGroupProps } from "./AvatarGroup.types";
+export declare const AvatarGroup: React.ForwardRefExoticComponent<AvatarGroupProps & React.RefAttributes<HTMLDivElement>>;

package/dist/components/core/AvatarGroup/AvatarGroup.js

@@ -0,0 +1,57 @@
+import { jsxs, jsx } from 'react/jsx-runtime';
+import React__default, { useState, useMemo } from 'react';
+import { useReducedMotion, motion } from 'motion/react';
+import { Avatar } from '../Avatar/Avatar.js';
+import { cn } from '../../../utils/cn.js';
+import { avatarGroupTheme } from './AvatarGroup.theme.js';
+import { getAnimationState, getAvatarGroupVariants } from './AvatarGroup.animations.js';
+
+const AvatarGroup = React__default.forwardRef(({ avatars = [], max = 5, size = "md", spacing = "normal", direction = "row", overflowIndicator, className, ariaLabel = "Group of users", shouldAnimate = true, ...props }, ref) => {
+    const [hoveredIndex, setHoveredIndex] = useState(null);
+    const shouldReduceMotion = useReducedMotion();
+    const enableAnimations = shouldAnimate && !shouldReduceMotion;
+    // Memoize expensive calculations to prevent unnecessary re-renders
+    const memoizedData = useMemo(() => {
+        const visibleAvatars = avatars.slice(0, max);
+        const overflowCount = avatars.length > max ? avatars.length - max : 0;
+        const spacingClass = avatarGroupTheme.spacingStyles[spacing];
+        const directionClass = direction === "row-reverse" ? "flex-row-reverse" : "flex-row";
+        const totalPeople = avatars.length;
+        const groupDescription = avatars
+            .map((avatar) => avatar.alt || "User")
+            .join(", ");
+        return {
+            visibleAvatars,
+            overflowCount,
+            spacingClass,
+            directionClass,
+            totalPeople,
+            groupDescription,
+        };
+    }, [avatars, max, spacing, direction]);
+    const { visibleAvatars, overflowCount, spacingClass, directionClass, totalPeople, groupDescription, } = memoizedData;
+    return (jsxs("div", { ref: ref, className: cn(avatarGroupTheme.baseStyle, directionClass, className), role: "group", "aria-label": ariaLabel, "aria-description": `Contains ${totalPeople} users: ${groupDescription}`, "data-size": size, "data-spacing": spacing, "data-direction": direction, "data-total": totalPeople, "data-visible": visibleAvatars.length, "data-overflow": overflowCount > 0 ? "true" : "false", onMouseLeave: () => enableAnimations && setHoveredIndex(null), ...props, children: [visibleAvatars.map((avatarProps, index) => {
+                // Create contextual label for individual avatars in a group
+                const position = index + 1;
+                const contextLabel = avatarProps.contextualLabel || ` (${position} of ${totalPeople})`;
+                const MotionDiv = enableAnimations ? motion.div : "div";
+                const motionProps = enableAnimations
+                    ? {
+                        variants: getAvatarGroupVariants(shouldReduceMotion, enableAnimations),
+                        animate: getAnimationState(index, hoveredIndex, enableAnimations),
+                        onHoverStart: () => setHoveredIndex(index),
+                        whileHover: "hover",
+                    }
+                    : {};
+                return (jsx(MotionDiv, { className: cn(
+                    // First avatar doesn't need negative margin
+                    index > 0 ? spacingClass : "z-10"), "data-position": position, "data-index": index, ...motionProps, children: jsx(Avatar, { size: size, ...avatarProps, contextualLabel: contextLabel, 
+                        // Ensure that groupPosition is not passed to avoid conflicts
+                        groupPosition: undefined }) }, index));
+            }), overflowCount > 0 && (jsx("div", { className: cn(spacingClass, enableAnimations &&
+                    "transition-transform duration-200 hover:scale-110"), "data-overflow-count": overflowCount, children: overflowIndicator ? (overflowIndicator(overflowCount)) : (jsx(Avatar, { size: size, alt: `+${overflowCount} more`, fallback: jsxs("span", { children: ["+", overflowCount] }), className: avatarGroupTheme.overflowAvatarStyle, role: "img", "aria-label": `+ ${overflowCount} more users` })) }))] }));
+});
+// Set display name for dev tools and Storybook
+AvatarGroup.displayName = "AvatarGroup";
+
+export { AvatarGroup };

package/dist/components/core/AvatarGroup/AvatarGroup.theme.d.ts

@@ -0,0 +1,14 @@
+import { AvatarGroupSpacing } from "./AvatarGroup.types";
+/**
+ * Internal theme structure for the AvatarGroup component
+ */
+interface AvatarGroupTheme {
+    baseStyle: string;
+    spacingStyles: Record<AvatarGroupSpacing, string>;
+    overflowAvatarStyle: string;
+}
+/**
+ * Default theme for the AvatarGroup component
+ */
+export declare const avatarGroupTheme: AvatarGroupTheme;
+export {};

package/dist/components/core/AvatarGroup/AvatarGroup.theme.js

@@ -0,0 +1,17 @@
+/**
+ * Default theme for the AvatarGroup component
+ */
+const avatarGroupTheme = {
+    // Base styles for the avatar group
+    baseStyle: "flex items-start",
+    // Spacing options - separated from hover effects
+    spacingStyles: {
+        tight: "-ml-5 z-10",
+        normal: "-ml-3 z-10",
+        loose: "-ml-2 z-10",
+    },
+    // Overflow avatar styles
+    overflowAvatarStyle: "bg-[var(--color-neutral-100)] text-[var(--color-text-primary)] font-semibold text-sm flex items-center justify-center hover:bg-neutral-200 transition-colors duration-200",
+};
+
+export { avatarGroupTheme };

package/dist/components/core/AvatarGroup/AvatarGroup.types.d.ts

@@ -0,0 +1,44 @@
+import { ReactNode } from 'react';
+import type { AvatarProps } from '../Avatar/Avatar.types';
+export type AvatarGroupSpacing = 'tight' | 'normal' | 'loose';
+export type AvatarGroupDirection = 'row' | 'row-reverse';
+export interface AvatarGroupProps extends React.HTMLAttributes<HTMLDivElement> {
+    /**
+     * Array of avatar props to render in the group
+     */
+    avatars: AvatarProps[];
+    /**
+     * Maximum number of avatars to display before showing a count
+     * @default 5
+     */
+    max?: number;
+    /**
+     * Size for all avatars in the group
+     * @default "md"
+     */
+    size?: AvatarProps["size"];
+    /**
+     * Amount of overlap between avatars (higher value = more overlap)
+     * @default "normal"
+     */
+    spacing?: AvatarGroupSpacing;
+    /**
+     * Direction of the avatar stack
+     * @default "row"
+     */
+    direction?: AvatarGroupDirection;
+    /**
+     * Custom renderer for the overflow avatar
+     */
+    overflowIndicator?: (overflowCount: number) => ReactNode;
+    /**
+     * ARIA label for the avatar group for accessibility
+     * @default "Group of users"
+     */
+    ariaLabel?: string;
+    /**
+     * Enable motion animations for hover effects
+     * @default true
+     */
+    shouldAnimate?: boolean;
+}