@react-fabric/core 1.0.0-beta.8 → 1.0.1

package/src/components/animations/LoadingLine.tsx

@@ -0,0 +1,51 @@
+/**
+ * React Fabric
+ * @version 1.0.0
+ * @license MIT
+ * @copyright 2024 Adarsh Pastakia
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+/**
+ * Inline loading indicator that renders a top-border shimmer animation.
+ *
+ * A lightweight loading bar displayed as a thin horizontal line at the top
+ * of its container. Useful for page-level or section-level loading states
+ * where a full overlay would be too intrusive.
+ *
+ * @example
+ * ```tsx
+ * import { LoadingLine } from "@react-fabric/core";
+ *
+ * // Page-level loading indicator
+ * <div>
+ *     <LoadingLine />
+ *     <p>Content loads below...</p>
+ * </div>
+ * ```
+ */
+export function LoadingLine() {
+  // Renders a thin shimmer bar at the top of the container using CSS animations
+  return (
+    <div className="fabric-loader area-loader relative overflow-x-clip h-0" data-ref="loading">
+      <div className="absolute inset-x-0 top-0 z-10 py-px overflow-hidden after:absolute after:block after:inset-0" />
+    </div>
+  );
+}

package/src/components/animations/LoadingSpinner.tsx

@@ -0,0 +1,70 @@
+/**
+ * React Fabric
+ * @version 1.0.0
+ * @license MIT
+ * @copyright 2024 Adarsh Pastakia
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import type { CustomColors } from "../../types";
+import { AnimationLoader } from "./Loader";
+
+export interface LoadingSpinnerProps {
+  /**
+   * Spinner color. Accepts palette tokens or any CSS color.
+   */
+  color?: CustomColors;
+
+  /**
+   * Spinner size. Accepts CSS size values (px, em, rem).
+   */
+  size?: number | string;
+
+  /**
+   * Blur intensity for the background mask. Defaults to no blur.
+   */
+  maskBlur?: "sm" | "md" | "lg";
+}
+
+/**
+ * Animated loading indicator that renders an "eclipse" spinner.
+ *
+ * A thin wrapper around `AnimationLoader` that provides a pre-configured
+ * circular loading animation. Useful for inline loading indicators in
+ * images, charts, and data cards.
+ *
+ * @example
+ * ```tsx
+ * import { LoadingSpinner } from "@react-fabric/core";
+ *
+ * // Basic spinner
+ * <LoadingSpinner />
+ *
+ * // Custom color and size
+ * <LoadingSpinner color="primary-500" size="2rem" />
+ *
+ * // With backdrop blur
+ * <LoadingSpinner maskBlur="sm" />
+ * ```
+ */
+export function LoadingSpinner(props: LoadingSpinnerProps) {
+  // Delegate to AnimationLoader with a pre-configured eclipse spinner icon
+  return <AnimationLoader icon="icon-[svg-spinners--eclipse]" {...props} />;
+}

package/src/components/animations/Skeleton.tsx

@@ -0,0 +1,100 @@
+/**
+ * React Fabric
+ * @version 1.0.0
+ * @license MIT
+ * @copyright 2024 Adarsh Pastakia
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import { cn } from "@react-fabric/utilities";
+import type { ColorTints, CssPropWithMap, CustomColors } from "../../types";
+import { getColor } from "../../utils";
+
+type SkeletonSlotNames = {
+  root?: string;
+  iconPlaceholder?: string;
+  titlePlaceholder?: string;
+  linePlaceholder?: string;
+};
+
+export interface SkeletonProps extends CssPropWithMap<SkeletonSlotNames> {
+  /**
+   * Background color for all skeleton slots. Accepts palette tokens or any CSS color.
+   * Defaults to `"tint-100"`.
+   */
+  color?: CustomColors<ColorTints>;
+}
+
+/**
+ * Content placeholder that renders a grayed-out card mockup with icon, title, and line slots.
+ *
+ * Displays a pre-styled skeleton card layout (icon area + title + two rows of text lines)
+ * to occupy space while real content loads. Useful for list items, cards, panels, and
+ * virtualized lists.
+ *
+ * @example
+ * ```tsx
+ * import { Skeleton } from "@react-fabric/core";
+ *
+ * // Basic skeleton placeholder
+ * <Skeleton />
+ *
+ * // Custom color
+ * <Skeleton color="primary-100" />
+ *
+ * // Custom slot styling
+ * <Skeleton classNames={{ titlePlaceholder: "w-2/3" }} />
+ * ```
+ */
+export function Skeleton({ className, classNames, color = "tint-200", ...rest }: SkeletonProps) {
+  const bgColor = getColor(color);
+  return (
+    <div
+      className={cn("fabric-skeleton", "p-2 animate-fade flex gap-2 max-w-lg", className, classNames?.root)}
+      data-ref="skeleton"
+      {...rest}
+    >
+      <div className={cn("rounded aspect-square h-12", classNames?.iconPlaceholder)} style={{ backgroundColor: bgColor }} />
+      <div className="flex-1 flex flex-col gap-2">
+        <div className={cn("h-3 rounded-full", classNames?.titlePlaceholder)} style={{ backgroundColor: bgColor }} />
+        <div className="flex gap-2">
+          <div
+            className={cn("h-2 rounded-full basis-[30%]", classNames?.linePlaceholder)}
+            style={{ backgroundColor: bgColor }}
+          />
+          <div
+            className={cn("h-2 rounded-full basis-[60%]", classNames?.linePlaceholder)}
+            style={{ backgroundColor: bgColor }}
+          />
+        </div>
+        <div className="flex gap-2">
+          <div
+            className={cn("h-2 rounded-full basis-[30%]", classNames?.linePlaceholder)}
+            style={{ backgroundColor: bgColor }}
+          />
+          <div
+            className={cn("h-2 rounded-full basis-[60%]", classNames?.linePlaceholder)}
+            style={{ backgroundColor: bgColor }}
+          />
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/components/avatar/Avatar.tsx

@@ -1,82 +1,88 @@
-/*
+/**
  * React Fabric
- * @version: 1.0.0
- *
- *
- * The MIT License (MIT)
- * Copyright (c) 2024 Adarsh Pastakia
+ * @version 1.0.0
+ * @license MIT
+ * @copyright 2024 Adarsh Pastakia
  *
- * Permission is hereby granted, free of charge, to any person obtaining a copy of this software
- * and associated documentation files (the "Software"), to deal in the Software without restriction,
- * including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense,
- * and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so,
- * subject to the following conditions:
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
  *
- * The above copyright notice and this permission notice shall be included in all copies or substantial
- * portions of the Software.
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
  *
- * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
- * TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
- * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
- * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
  */
 
-import { isSvgPath } from "@react-fabric/utilities";
+import { cn, isSvgPath } from "@react-fabric/utilities";
 import BoringAvatar from "boring-avatars";
-import classNames from "classnames";
 import { useMemo, useState } from "react";
-import {
-  type AriaProps,
-  type ColorType,
-  type CssProp,
-  type RefProp,
-  type SizeType,
-  type TestProps,
-} from "../../types";
-import { getBgClass, getColor, getColorClass } from "../../utils";
-import classes from "./Avatar.module.css";
+import type { CssProp, CustomColors, HtmlEvents, RefProp, SizeType, TestProps } from "../../types";
+import { getColor } from "../../utils";
 
-export interface AvatarProps extends CssProp, AriaProps, TestProps, RefProp {
+export interface AvatarProps extends CssProp, TestProps, RefProp, HtmlEvents {
   /**
-   * avatar name for generated fallback
+   * Display name used for generating the fallback avatar (required).
+   * When no `avatar` image is provided, this name is used to generate
+   * a Boring Avatar pattern or extract text initials as a placeholder.
    */
   name: string;
   /**
-   * svg path
+   * SVG path string or CSS class name for a custom fallback icon.
+   * Used when no `avatar` image is provided and the variant is not `"text"`.
    */
   fallbackIcon?: string;
   /**
-   * avatar image url
+   * URL of the avatar image to display.
+   * Falls back to a Boring Avatar, text initials, or custom icon when
+   * the image fails to load or is not provided.
    */
   avatar?: string;
   /**
-   * avatar variant
+   * Fallback avatar style applied when no `avatar` image is provided.
+   * Defaults to `"beam"`. Options: `"text"` (text initials), `"beam"`,
+   * `"pixel"`, `"bauhaus"` (Boring Avatar variants).
    */
   variant?: "text" | "beam" | "pixel" | "bauhaus";
   /**
-   * background color (CSS color / tailwind color)
+   * Background color applied to the avatar container.
+   * Accepts Tailwind palette tokens or any CSS color.
    */
-  bg?: ColorType | string;
+  bg?: CustomColors;
   /**
-   * icon color (CSS color / tailwind color)
+   * Text/icon color applied to the avatar.
+   * Accepts Tailwind palette tokens or any CSS color.
    */
-  color?: ColorType | string;
+  color?: CustomColors;
   /**
-   * icon size
+   * Avatar size. Accepts predefined tokens `"xs"`–`"xl"` or a custom CSS size value.
    */
-  size?: SizeType | number | string;
+  size?: SizeType | number | (string & {});
   /**
-   * viewbox for svg path (default 24)
+   * SVG viewBox attribute for `fallbackIcon` when it is an SVG path.
+   * Defaults to `"0 0 24 24"`.
    */
   viewBox?: string;
   /**
-   * rounded icon
+   * When true, applies a fully rounded (circular) shape to the avatar.
+   * Otherwise, a standard rounded rectangle is used.
    */
   rounded?: boolean;
   /**
-   * click handler
+   * When true, prevents the default click action on the avatar.
+   * Useful when the avatar is nested inside an `<a>` element to avoid
+   * navigating away from the page.
    */
-  onClick?: React.MouseEventHandler;
+  preventDefault?: boolean;
 }
 
 const SizeMap: KeyValue<string> = {
@@ -88,9 +94,24 @@ const SizeMap: KeyValue<string> = {
 };
 
 /**
- * An avatar is a graphical representation of a user's identity.
+ * User avatar that renders an image with a Boring Avatar fallback.
+ *
+ * Displays a user image, falling back to a Boring Avatar (or text initials)
+ * when no image is provided or the image fails to load. Supports four
+ * Boring Avatar variants (beam, text, pixel, bauhaus) and custom SVG/icon fallbacks.
+ *
+ * @see {@link https://boringavatars.com/}
+ *
+ *  @example
+ * ```tsx
+ * import { Avatar } from "@react-fabric/core";
+ *
+ * <Avatar name="Ada Lovelace" avatar="/ada.jpg" />
+ * <Avatar name="John Doe" variant="pixel" size="lg" />
+ * <Avatar name="Jane" fallbackIcon="icon-[mdi--user]" variant="text" />
+ * ```
  */
-export const Avatar = ({
+export function Avatar({
   ref,
   name,
   avatar,
@@ -102,12 +123,13 @@ export const Avatar = ({
   variant = "beam",
   className,
   viewBox = "0 0 24 24",
+  preventDefault,
   onClick,
-  ...aria
-}: AvatarProps) => {
+  ...props
+}: AvatarProps) {
   const [fallback, setFallback] = useState(true);
 
-  /** ***************** style map *******************/
+  // Compute inline styles from props (memoized to prevent re-renders)
   const styles = useMemo(() => {
     const s: KeyValue = {};
     if (bg) {
@@ -125,18 +147,13 @@ export const Avatar = ({
     return s;
   }, [bg, color, size]);
 
-  /** ***************** render icon *******************/
+  // Render avatar image with a fade-in placeholder behind it
   const avatarImage = useMemo(() => {
     setFallback(!avatar);
     return (
       avatar && (
         <div className="contents">
-          <div
-            className={classNames(
-              classes.imgPlaceholder,
-              "absolute inset-0 bg-gray animate-pulse",
-            )}
-          />
+          <div className="fabric-imgPlaceholder absolute inset-0 bg-gray animate-fade -z-1" />
           <img
             src={avatar}
             alt={avatar}
@@ -149,10 +166,11 @@ export const Avatar = ({
     );
   }, [avatar]);
 
+  // Render fallback: custom icon, text initials, or Boring Avatar
   const fallbackAvatar = useMemo(() => {
     if (fallbackIcon) {
       return isSvgPath(fallbackIcon) ? (
-        <svg viewBox={viewBox}>
+        <svg viewBox={viewBox} className="p-[0.125em]">
           <path fill="currentColor" d={fallbackIcon.toString()} />
         </svg>
       ) : (
@@ -160,8 +178,8 @@ export const Avatar = ({
       );
     }
     if (variant === "text") {
-      const [, first, second, group] =
-        name.match(/(?=(\w).* (\w).*)|(?=(\w\w).*)/) ?? [];
+      // Extract initials: "John Doe" -> "JD", "Jane" -> "JA"
+      const [, first, second, group] = name.match(/(?=(\w).* (\w).*)|(?=(\w\w).*)/) as string[];
       return (
         <svg role="img">
           <text
@@ -177,29 +195,30 @@ export const Avatar = ({
         </svg>
       );
     }
+    // Default: generate a Boring Avatar from the name
     return <BoringAvatar square size={64} variant={variant} name={name} />;
-  }, [name, variant, fallbackIcon]);
+  }, [fallbackIcon, variant, name, viewBox]);
 
   return (
     <dfn
       role="presentation"
-      className={classNames(
-        classes.avatar,
+      className={cn(
+        "fabric-avatar",
+        rounded ? "rounded-full" : "rounded",
+        "select-none relative overflow-hidden inline-block box-content leading-none not-italic text-center is-clickable:cursor-pointer",
         className,
-        "select-none relative overflow-hidden inline-block box-content leading-none not-italic text-center",
-        bg && getBgClass(bg),
-        color && getColorClass(color),
-        !rounded && "rounded",
-        rounded && "rounded-full",
       )}
-      onClick={onClick}
+      onClick={(e) => {
+        if (preventDefault) e.preventDefault();
+        onClick?.(e);
+      }}
       style={styles}
       data-clickable={!!onClick}
       ref={ref}
-      {...aria}
+      {...props}
     >
       {!fallback && avatarImage}
       {fallback && fallbackAvatar}
     </dfn>
   );
-};
+}

package/src/components/avatar/AvatarGroup.tsx

@@ -1,57 +1,48 @@
-/*
+/**
  * React Fabric
- * @version: 1.0.0
- *
- *
- * The MIT License (MIT)
- * Copyright (c) 2024 Adarsh Pastakia
+ * @version 1.0.0
+ * @license MIT
+ * @copyright 2024 Adarsh Pastakia
  *
- * Permission is hereby granted, free of charge, to any person obtaining a copy of this software
- * and associated documentation files (the "Software"), to deal in the Software without restriction,
- * including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense,
- * and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so,
- * subject to the following conditions:
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
  *
- * The above copyright notice and this permission notice shall be included in all copies or substantial
- * portions of the Software.
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
  *
- * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
- * TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
- * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
- * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
  */
 
-import classNames from "classnames";
-import { Children, useMemo, type ReactElement } from "react";
+import { cn } from "@react-fabric/utilities";
+import { Children, useMemo } from "react";
 import { useMemoDebugger } from "../../hooks/useEffectDebugger";
-import {
-  type AriaProps,
-  type CssProp,
-  type RefProp,
-  type SizeType,
-} from "../../types";
-import { type AvatarProps } from "./Avatar";
-import classes from "./Avatar.module.css";
+import type { ChildrenProp, CssProp, RefProp, SizeType } from "../../types";
+import type { AvatarProps } from "./Avatar";
 
-type AvatarChild =
-  | ReactElement<Omit<AvatarProps, "size" | "rounded">>
-  | false
-  | undefined;
-
-export interface AvatarGroupProps extends CssProp, RefProp, AriaProps {
-  children: AvatarChild | AvatarChild[];
+export interface AvatarGroupProps
+  extends CssProp, RefProp<HTMLDivElement>, ChildrenProp<Omit<AvatarProps, "size" | "rounded">> {
   /**
-   * rounded icon
+   * Whether to apply a fully rounded shape to all avatars and the group container.
    */
   rounded?: boolean;
   /**
-   * icon size
+   * Avatar size. Accepts `"xs"`–`"xl"` tokens or a custom CSS size value.
    */
-  size?: SizeType | number | string;
+  size?: SizeType | number | (string & {});
   /**
-   * max count
+   * Maximum number of avatars to display before showing a "+N" overflow badge.
    */
-  totalCount?: number;
+  max?: number;
 }
 
 const SizeMap: KeyValue<string> = {
@@ -63,18 +54,27 @@ const SizeMap: KeyValue<string> = {
 };
 
 /**
- * Group multiple avatars together
+ * Horizontal group of avatars with an overflow count badge.
+ *
+ * Renders its avatar children in a flex row, truncating to `max` visible
+ * avatars and appending a "+N" badge for the remainder. Each avatar is
+ * sized according to the `size` prop.
+ *
+ * @example
+ * ```tsx
+ * import { Avatar, AvatarGroup } from "@react-fabric/core";
+ *
+ * <AvatarGroup max={3} size="md">
+ *     <Avatar name="John Doe" avatar="/john.jpg" />
+ *     <Avatar name="Jane Smith" avatar="/jane.jpg" />
+ *     <Avatar name="Alice Johnson" avatar="/alice.jpg" />
+ *     <Avatar name="Bob Brown" avatar="/bob.jpg" />
+ * </AvatarGroup>
+ * // Renders 3 avatars + a "+1" badge
+ * ```
  */
-export const AvatarGroup = ({
-  ref,
-  children,
-  className,
-  totalCount,
-  rounded,
-  size,
-  ...aria
-}: AvatarGroupProps) => {
-  /** ***************** style map *******************/
+export function AvatarGroup({ ref, children, className, max, rounded, size, ...props }: AvatarGroupProps) {
+  // Compute inline styles from size prop (memoized to prevent re-renders)
   const styles = useMemoDebugger(
     () => {
       const s: KeyValue = {};
@@ -90,35 +90,26 @@ export const AvatarGroup = ({
     "Icon styles",
   );
 
-  const avatars = useMemo(
-    () => Children.toArray(children).filter(Boolean),
-    [children],
-  );
-  const diff = useMemo(
-    () =>
-      totalCount && totalCount > avatars.length && totalCount - avatars.length,
-    [avatars, totalCount],
-  );
+  // Normalize children to an array, filtering out falsy values
+  // eslint-disable-next-line @eslint-react/no-children-to-array
+  const avatars = useMemo(() => Children.toArray(children).filter(Boolean), [children]);
+  // Calculate how many avatars exceed the max (0 if none)
+  const diff = useMemo(() => max && avatars.length > max && avatars.length - max, [avatars, max]);
   return (
     <div
-      {...aria}
-      ref={ref as AnyObject}
-      className={classNames(
-        classes.avatarGroup,
-        className,
-        "inline-flex flex-nowrap",
-        !rounded && "rounded",
-        rounded && "rounded-full",
-      )}
+      {...props}
+      ref={ref}
+      className={cn("fabric-avatarGroup", "inline-flex flex-nowrap", className, rounded ? "rounded-full" : "rounded")}
       style={styles}
     >
-      {avatars}
+      {avatars.slice(0, max)}
       {!!diff && (
         <dfn
-          className={classNames(
-            classes.avatar,
-            "select-none relative overflow-hidden inline-block box-content leading-none not-italic text-center",
-            classes.extra,
+          data-ref="avatarCount"
+          className={cn(
+            "fabric-avatar",
+            "fabric-avatarGroup--extra",
+            "select-none relative overflow-hidden inline-block box-content bg-muted leading-none not-italic text-center",
           )}
         >
           <svg>
@@ -137,4 +128,4 @@ export const AvatarGroup = ({
       )}
     </div>
   );
-};
+}