@boxcustodia/library 2.0.0-alpha.12 → 2.0.0-alpha.14

package/src/components/avatar/avatar.stories.tsx

@@ -1,26 +1,31 @@
-import { faker } from "@faker-js/faker";
 import type { Meta, StoryObj } from "@storybook/react-vite";
-import { User } from "lucide-react";
+import { Check, User } from "lucide-react";
 import { action } from "storybook/actions";
 import {
   Avatar,
+  AvatarBadge,
   AvatarFallback,
+  AvatarGroup,
+  AvatarGroupCount,
   AvatarImage,
   AvatarRoot,
 } from "../../components";
 
 /**
- * Displays a user's profile image with automatic fallback to text initials derived from `alt`.
+ * Circular user profile image with automatic fallback to text initials derived from `alt`.
  * Built on Base UI Avatar — image loading and fallback visibility are handled natively.
  * Use `delay` to defer the fallback appearance and avoid a flash during image load.
- * Exposes `AvatarRoot`, `AvatarImage`, `AvatarFallback` primitives for custom compositions.
+ * Pass `badge` to render a status/notification dot via `AvatarBadge`.
+ * Exposes `AvatarRoot`, `AvatarImage`, `AvatarFallback`, `AvatarBadge`,
+ * `AvatarGroup`, `AvatarGroupCount` primitives for custom compositions.
  */
 const meta: Meta<typeof Avatar> = {
   title: "components/Avatar",
   component: Avatar,
+  parameters: { layout: "centered" },
   args: {
-    alt: faker.person.fullName(),
-    src: faker.image.avatar(),
+    alt: "Sara Lane",
+    src: "https://i.pravatar.cc/150?img=47",
     delay: 1000,
   },
 } satisfies Meta<typeof Avatar>;
@@ -30,6 +35,22 @@ type Story = StoryObj<typeof meta>;
 
 export const Default: Story = {};
 
+/**
+ * `className` styles the avatar root. `classNames` exposes the `image`,
+ * `fallback`, and `badge` slots for fine-grained styling without dropping
+ * to primitives.
+ */
+export const WithClassNames: Story = {
+  args: {
+    badge: <Check />,
+    className: "ring-2 ring-ring",
+    classNames: {
+      fallback: "bg-primary text-primary-foreground",
+      badge: "bg-emerald-500",
+    },
+  },
+};
+
 /**
  * When `src` is empty or the image fails to load, initials are extracted from `alt` automatically.
  */
@@ -39,46 +60,166 @@ export const FallbackText: Story = {
   },
 };
 
+/**
+ * Pass any node to `fallback` to override the default initials — useful for generic
+ * placeholders, icons, or branded glyphs.
+ */
 export const CustomFallback: Story = {
   args: {
     src: "",
-    fallback: <User />,
+    fallback: <User className="size-1/2" />,
   },
 };
 
 export const Sizes: Story = {
   render: (args) => (
-    <div className="flex items-center gap-4">
-      <Avatar {...args} size="xs" />
-      <Avatar {...args} size="sm" />
-      <Avatar {...args} size="md" />
-      <Avatar {...args} size="lg" />
-      <Avatar {...args} size="xl" />
+    <div className="flex items-end gap-6">
+      {(["xs", "sm", "md", "lg", "xl"] as const).map((size) => (
+        <div key={size} className="flex flex-col items-center gap-2">
+          <Avatar {...args} size={size} />
+          <span className="text-xs text-muted-foreground font-mono">
+            {size}
+          </span>
+        </div>
+      ))}
     </div>
   ),
 };
 
-export const Shapes: Story = {
-  render: (args) => (
-    <div className="flex items-center gap-4">
-      <Avatar {...args} shape="circle" />
-      <Avatar {...args} shape="square" />
+/**
+ * `badge` mounts an `AvatarBadge` inside the root. The badge auto-scales with the
+ * avatar's `size` via `group-data-[size=*]/avatar` selectors and clips icons on
+ * the smallest sizes to keep the dot legible.
+ *
+ * For a plain status indicator, leave the badge empty (`<span />`) and override
+ * its color via `className`.
+ */
+export const Badge: Story = {
+  render: () => (
+    <div className="flex items-end gap-6">
+      {(["sm", "md", "lg", "xl"] as const).map((size) => (
+        <div key={size} className="flex flex-col items-center gap-2">
+          <Avatar
+            src="https://i.pravatar.cc/150?img=47"
+            alt="Sara Lane"
+            size={size}
+            badge={<Check />}
+          />
+          <span className="text-xs text-muted-foreground font-mono">
+            {size}
+          </span>
+        </div>
+      ))}
+    </div>
+  ),
+};
+
+/**
+ * Status pattern via `AvatarBadge` on the primitive. The badge's color comes
+ * from `className`, the position and ring from the primitive itself.
+ */
+export const Status: Story = {
+  render: () => (
+    <div className="flex items-center gap-6">
+      {(
+        [
+          { label: "online", color: "bg-emerald-500" },
+          { label: "away", color: "bg-amber-500" },
+          { label: "offline", color: "bg-zinc-400" },
+        ] as const
+      ).map(({ label, color }) => (
+        <div key={label} className="flex flex-col items-center gap-2">
+          <AvatarRoot size="lg">
+            <AvatarImage
+              src={`https://i.pravatar.cc/150?u=${label}`}
+              alt={label}
+            />
+            <AvatarFallback>{label.slice(0, 2).toUpperCase()}</AvatarFallback>
+            <AvatarBadge className={color} />
+          </AvatarRoot>
+          <span className="text-xs text-muted-foreground font-mono">
+            {label}
+          </span>
+        </div>
+      ))}
     </div>
   ),
 };
 
+/**
+ * `AvatarGroup` clusters avatars with negative spacing and applies a background
+ * ring to every direct `Avatar` child so they read as overlapping discs.
+ * Combine with `AvatarGroupCount` for the trailing `+N` slot. Match `size`
+ * across children and the count to scale the cluster.
+ */
+export const Group: Story = {
+  render: () => (
+    <AvatarGroup>
+      <Avatar src="https://i.pravatar.cc/150?img=47" alt="Sara Lane" />
+      <Avatar src="https://i.pravatar.cc/150?img=12" alt="John Doe" />
+      <Avatar src="https://i.pravatar.cc/150?img=32" alt="Alex Kim" />
+      <Avatar src="https://i.pravatar.cc/150?img=68" alt="Mia Chen" />
+      <AvatarGroupCount>+12</AvatarGroupCount>
+    </AvatarGroup>
+  ),
+};
+
+/**
+ * Direct composition with `AvatarRoot`, `AvatarImage`, `AvatarFallback`,
+ * `AvatarBadge` for full structural control. Use when the composite API
+ * doesn't expose what you need — custom children inside the fallback,
+ * layered overlays, etc.
+ *
+ * ```tsx
+ * <AvatarRoot size="lg">
+ *   <AvatarImage src={src} alt="John Doe" />
+ *   <AvatarFallback delay={1000}>JD</AvatarFallback>
+ *   <AvatarBadge className="bg-emerald-500" />
+ * </AvatarRoot>
+ * ```
+ */
 export const Primitive: Story = {
   render: () => (
-    <AvatarRoot shape="square" size="lg">
-      <AvatarImage src={faker.image.avatar()} alt="John Doe" />
+    <AvatarRoot size="lg">
+      <AvatarImage src="https://i.pravatar.cc/150?img=13" alt="John Doe" />
       <AvatarFallback delay={1000}>JD</AvatarFallback>
+      <AvatarBadge className="bg-emerald-500" />
     </AvatarRoot>
   ),
 };
 
+/**
+ * Avatars accept any `div` prop including `onClick`. Pair with `cursor-pointer`
+ * and a ring/hover style for interactive profile triggers.
+ */
 export const Clickable: Story = {
   args: {
     onClick: action("avatar:click"),
-    className: "cursor-pointer",
+    className:
+      "cursor-pointer ring-2 ring-transparent hover:ring-ring transition-shadow",
   },
 };
+
+/**
+ * Real-world usage: avatar paired with name, role, and an `AvatarBadge`
+ * showing online status — canonical card layout for user lists, mentions,
+ * and team rosters.
+ */
+export const UserCard: Story = {
+  render: () => (
+    <div className="flex items-center gap-3 rounded-lg border bg-background p-4 shadow-sm">
+      <AvatarRoot size="lg">
+        <AvatarImage src="https://i.pravatar.cc/150?img=47" alt="Sara Lane" />
+        <AvatarFallback>SL</AvatarFallback>
+        <AvatarBadge className="bg-emerald-500" />
+      </AvatarRoot>
+      <div className="flex flex-col">
+        <span className="font-semibold leading-tight">Sara Lane</span>
+        <span className="text-sm text-muted-foreground leading-tight">
+          Senior Product Designer
+        </span>
+        <span className="text-xs text-muted-foreground mt-1">Active now</span>
+      </div>
+    </div>
+  ),
+};

package/src/components/avatar/avatar.tsx

@@ -1,17 +1,13 @@
 import { Avatar as AvatarPrimitive } from "@base-ui/react/avatar";
 import { cva, type VariantProps } from "class-variance-authority";
-import { type ReactNode } from "react";
+import { type ComponentProps, type ReactNode } from "react";
 import { cn } from "../../lib";
 import { extractInitials } from "../../utils";
 
 const avatarVariants = cva(
-  "overflow-hidden aspect-square bg-muted grid place-items-center font-semibold shrink-0 select-none",
+  "group/avatar relative flex aspect-square shrink-0 select-none rounded-full bg-muted items-center justify-center font-medium",
   {
     variants: {
-      shape: {
-        circle: "rounded-full",
-        square: "rounded-xl",
-      },
       size: {
         xs: "size-6 text-[10px]",
         sm: "size-8 text-xs",
@@ -21,7 +17,6 @@ const avatarVariants = cva(
       },
     },
     defaultVariants: {
-      shape: "circle",
       size: "md",
     },
   },
@@ -29,14 +24,14 @@ const avatarVariants = cva(
 
 export function AvatarRoot({
   className,
-  shape,
   size,
   ...props
 }: AvatarPrimitive.Root.Props & VariantProps<typeof avatarVariants>) {
   return (
     <AvatarPrimitive.Root
-      className={cn(avatarVariants({ shape, size }), className)}
+      className={cn(avatarVariants({ size }), className)}
       data-slot="avatar"
+      data-size={size ?? "md"}
       {...props}
     />
   );
@@ -48,7 +43,10 @@ export function AvatarImage({
 }: AvatarPrimitive.Image.Props) {
   return (
     <AvatarPrimitive.Image
-      className={cn("size-full object-cover", className)}
+      className={cn(
+        "aspect-square size-full rounded-full object-cover",
+        className,
+      )}
       data-slot="avatar-image"
       {...props}
     />
@@ -61,42 +59,103 @@ export function AvatarFallback({
 }: AvatarPrimitive.Fallback.Props) {
   return (
     <AvatarPrimitive.Fallback
-      className={cn("flex size-full items-center justify-center", className)}
+      className={cn(
+        "flex size-full items-center justify-center rounded-full bg-muted text-muted-foreground",
+        className,
+      )}
       data-slot="avatar-fallback"
       {...props}
     />
   );
 }
 
+export function AvatarBadge({ className, ...props }: ComponentProps<"span">) {
+  return (
+    <span
+      data-slot="avatar-badge"
+      className={cn(
+        "absolute bottom-0 right-0 z-10 inline-flex items-center justify-center rounded-full bg-primary text-primary-foreground ring-2 ring-background select-none",
+        "group-data-[size=xs]/avatar:size-1.5 group-data-[size=xs]/avatar:[&>svg]:hidden",
+        "group-data-[size=sm]/avatar:size-2 group-data-[size=sm]/avatar:[&>svg]:hidden",
+        "group-data-[size=md]/avatar:size-2.5 group-data-[size=md]/avatar:[&>svg]:size-2",
+        "group-data-[size=lg]/avatar:size-3.5 group-data-[size=lg]/avatar:[&>svg]:size-2.5",
+        "group-data-[size=xl]/avatar:size-4 group-data-[size=xl]/avatar:[&>svg]:size-3",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+export function AvatarGroup({ className, ...props }: ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="avatar-group"
+      className={cn(
+        "group/avatar-group flex -space-x-2 *:data-[slot=avatar]:ring-2 *:data-[slot=avatar]:ring-background",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+export function AvatarGroupCount({
+  className,
+  size,
+  ...props
+}: ComponentProps<"div"> & VariantProps<typeof avatarVariants>) {
+  return (
+    <div
+      data-slot="avatar-group-count"
+      className={cn(
+        avatarVariants({ size }),
+        "ring-2 ring-background bg-muted text-muted-foreground",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
 interface AvatarProps extends Omit<AvatarPrimitive.Root.Props, "children"> {
   src?: string;
   alt: string;
   fallback?: ReactNode;
+  badge?: ReactNode;
   delay?: AvatarPrimitive.Fallback.Props["delay"];
-  shape?: VariantProps<typeof avatarVariants>["shape"];
   size?: VariantProps<typeof avatarVariants>["size"];
-  imageProps?: AvatarPrimitive.Image.Props;
-  fallbackProps?: AvatarPrimitive.Fallback.Props;
+  /** Styles applied to each internal slot. */
+  classNames?: {
+    /** Image element rendered when `src` loads successfully. */
+    image?: string;
+    /** Fallback rendered when no image is available. */
+    fallback?: string;
+    /** Status/notification badge rendered over the avatar. */
+    badge?: string;
+  };
 }
 
 export function Avatar({
   src,
   alt,
   fallback,
+  badge,
   delay,
-  shape,
   size,
   className,
-  imageProps,
-  fallbackProps,
+  classNames,
   ...props
 }: AvatarProps) {
   return (
-    <AvatarRoot shape={shape} size={size} className={className} {...props}>
-      <AvatarImage src={src} alt={alt} {...imageProps} />
-      <AvatarFallback delay={delay} {...fallbackProps}>
+    <AvatarRoot size={size} className={className} {...props}>
+      <AvatarImage src={src} alt={alt} className={classNames?.image} />
+      <AvatarFallback delay={delay} className={classNames?.fallback}>
         {fallback ?? extractInitials(alt)}
       </AvatarFallback>
+      {badge ? (
+        <AvatarBadge className={classNames?.badge}>{badge}</AvatarBadge>
+      ) : null}
     </AvatarRoot>
   );
 }