@cntyclub/ui-react 0.13.0 → 0.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cntyclub/ui-react",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "React component library for the Country Club UI Kit — Base UI primitives styled with the Country Club design system (Tailwind CSS v4)",
   "type": "module",
   "sideEffects": [

package/src/components/ui/avatar-group.tsx

@@ -5,6 +5,12 @@ import type * as React from "react";
 
 import { cn } from "../../lib/utils/css";
 import { Avatar, avatarVariants } from "./avatar";
+import {
+  Tooltip,
+  TooltipPopup,
+  TooltipProvider,
+  TooltipTrigger,
+} from "./tooltip";
 
 type AvatarSize = NonNullable<VariantProps<typeof avatarVariants>["size"]>;
 
@@ -29,6 +35,11 @@ interface AvatarGroupItem {
   /** Initials shown when there is no image. */
   initials?: React.ReactNode;
   alt?: string;
+  /**
+   * Label revealed on hover when `showNameOnHover` is set (e.g. the person's
+   * name). Falls back to `alt` when omitted.
+   */
+  name?: React.ReactNode;
 }
 
 interface AvatarGroupProps
@@ -39,11 +50,19 @@ interface AvatarGroupProps
   /** Cap the visible avatars; the rest collapse into a "+N" chip. */
   max?: number;
   size?: AvatarSize;
+  /**
+   * Reveal each avatar's `name` (or `alt`) in a tooltip above it on hover /
+   * focus. Only applies to the data-driven `items` path.
+   */
+  showNameOnHover?: boolean;
 }
 
 /**
  * A row of overlapping avatars with an overflow "+N" chip. Pass `items` for the
  * data-driven path, or compose `<Avatar>` children directly for full control.
+ *
+ * With `showNameOnHover`, hovering (or focusing) an avatar reveals its `name`
+ * in a tooltip — e.g. hovering Amir's photo shows "Amir".
  */
 function AvatarGroup({
   className,
@@ -51,13 +70,14 @@ function AvatarGroup({
   max,
   size = "sm",
   overlap,
+  showNameOnHover = false,
   children,
   ...props
 }: AvatarGroupProps) {
   const shown = items && max ? items.slice(0, max) : items;
   const overflow = items && max ? items.length - max : 0;
 
-  return (
+  const group = (
     <div
       className={cn(avatarGroupVariants({ overlap }), className)}
       data-slot="avatar-group"
@@ -65,16 +85,36 @@ function AvatarGroup({
       {...props}
     >
       {items
-        ? shown?.map((item, i) => (
-            <Avatar
-              alt={item.alt}
+        ? shown?.map((item, i) => {
+            const label = item.name ?? item.alt;
+            const avatar = (
+              <Avatar
+                alt={item.alt}
+                initials={item.initials}
+                size={size}
+                src={item.src}
+              />
+            );
+            if (!(showNameOnHover && label)) {
               // biome-ignore lint/suspicious/noArrayIndexKey: order is stable
-              key={i}
-              initials={item.initials}
-              size={size}
-              src={item.src}
-            />
-          ))
+              return <Avatar alt={item.alt} initials={item.initials} key={i} size={size} src={item.src} />;
+            }
+            return (
+              // The span wrapper is the group's direct child, so it carries the
+              // ring/overlap styling; the tooltip anchors to it (Base UI needs a
+              // ref-able host, which the Avatar fn component doesn't forward).
+              // biome-ignore lint/suspicious/noArrayIndexKey: order is stable
+              <Tooltip key={i}>
+                <TooltipTrigger
+                  className="inline-flex cursor-default"
+                  render={<span />}
+                >
+                  {avatar}
+                </TooltipTrigger>
+                <TooltipPopup>{label}</TooltipPopup>
+              </Tooltip>
+            );
+          })
         : children}
       {overflow > 0 ? (
         <span
@@ -92,6 +132,19 @@ function AvatarGroup({
       ) : null}
     </div>
   );
+
+  // Self-contained: provide a tooltip context so the hover mode works without
+  // the consumer having to mount a TooltipProvider. A short delay keeps names
+  // from flickering as the pointer sweeps across the row.
+  if (showNameOnHover) {
+    return (
+      <TooltipProvider delay={150} closeDelay={0}>
+        {group}
+      </TooltipProvider>
+    );
+  }
+
+  return group;
 }
 
 export { AvatarGroup, avatarGroupVariants };