@boxcustodia/library 2.0.0-alpha.2 → 2.0.0-alpha.21

package/src/components/avatar/avatar.test.tsx

@@ -0,0 +1,336 @@
+import { render, screen } from "@testing-library/react";
+import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
+import {
+  Avatar,
+  AvatarBadge,
+  AvatarFallback,
+  AvatarGroup,
+  AvatarGroupCount,
+  AvatarImage,
+  AvatarPrimitive,
+  AvatarRoot,
+} from "../../components";
+import { extractInitials } from "../../utils";
+
+// Base UI's Avatar uses `new window.Image()` to detect loading state, which
+// never resolves in jsdom. Mock it so a non-empty src completes synchronously
+// and Base UI's fast path (`image.complete && naturalWidth > 0`) renders the
+// underlying `<img>` immediately.
+const OriginalImage = globalThis.Image;
+beforeAll(() => {
+  class MockImage {
+    onload: (() => void) | null = null;
+    onerror: (() => void) | null = null;
+    referrerPolicy = "";
+    crossOrigin: string | null = null;
+    naturalWidth = 0;
+    complete = false;
+    set src(value: string) {
+      if (value) {
+        this.naturalWidth = 1;
+        this.complete = true;
+      }
+    }
+  }
+  vi.stubGlobal("Image", MockImage);
+});
+afterAll(() => {
+  vi.stubGlobal("Image", OriginalImage);
+});
+
+describe("Avatar composite", () => {
+  const personName = "lorem ipsum";
+  const imageSrc = "https://i.pravatar.cc/300";
+
+  it("renders the image with src and alt", () => {
+    render(<Avatar alt={personName} src={imageSrc} />);
+
+    const image = screen.getByRole("img");
+    expect(image).toHaveAttribute("alt", personName);
+    expect(image).toHaveAttribute("src", imageSrc);
+    expect(image).toHaveAttribute("data-slot", "avatar-image");
+  });
+
+  it("falls back to the alt initials when no src is provided", () => {
+    render(<Avatar alt={personName} src="" />);
+
+    expect(screen.queryByRole("img")).not.toBeInTheDocument();
+    expect(screen.getByText(extractInitials(personName))).toBeInTheDocument();
+  });
+
+  it("falls back to the alt initials when src is omitted", () => {
+    render(<Avatar alt={personName} />);
+
+    expect(screen.queryByRole("img")).not.toBeInTheDocument();
+    expect(screen.getByText(extractInitials(personName))).toBeInTheDocument();
+  });
+
+  it("renders a custom fallback node when provided", () => {
+    render(<Avatar alt={personName} src="" fallback={<span>Custom</span>} />);
+
+    expect(screen.getByText("Custom")).toBeInTheDocument();
+    expect(
+      screen.queryByText(extractInitials(personName)),
+    ).not.toBeInTheDocument();
+  });
+
+  it("renders a badge when provided", () => {
+    render(<Avatar alt={personName} src={imageSrc} badge={<span>3</span>} />);
+
+    const badge = document.querySelector('[data-slot="avatar-badge"]');
+    expect(badge).not.toBeNull();
+    expect(badge).toHaveTextContent("3");
+  });
+
+  it("omits the badge slot when no badge is provided", () => {
+    render(<Avatar alt={personName} src={imageSrc} />);
+
+    expect(document.querySelector('[data-slot="avatar-badge"]')).toBeNull();
+  });
+
+  it.each([
+    ["xs", "size-6", "text-[10px]"],
+    ["sm", "size-8", "text-xs"],
+    ["md", "size-10", "text-sm"],
+    ["lg", "size-14", "text-base"],
+    ["xl", "size-20", "text-xl"],
+  ] as const)("applies size '%s' classes and data-size attribute", (size, sizeClass, textClass) => {
+    render(<Avatar alt={personName} src={imageSrc} size={size} />);
+
+    const root = document.querySelector('[data-slot="avatar"]');
+    expect(root).toHaveAttribute("data-size", size);
+    expect(root).toHaveClass(sizeClass, textClass);
+  });
+
+  it("defaults size to md when omitted", () => {
+    render(<Avatar alt={personName} src={imageSrc} />);
+
+    const root = document.querySelector('[data-slot="avatar"]');
+    expect(root).toHaveAttribute("data-size", "md");
+    expect(root).toHaveClass("size-10");
+  });
+
+  it("applies className to the root and classNames to each slot", () => {
+    render(
+      <Avatar
+        alt={personName}
+        src={imageSrc}
+        badge={<span>!</span>}
+        className="root-class"
+        classNames={{
+          image: "image-class",
+          fallback: "fallback-class",
+          badge: "badge-class",
+        }}
+      />,
+    );
+
+    expect(document.querySelector('[data-slot="avatar"]')).toHaveClass(
+      "root-class",
+    );
+    expect(document.querySelector('[data-slot="avatar-image"]')).toHaveClass(
+      "image-class",
+    );
+    expect(document.querySelector('[data-slot="avatar-badge"]')).toHaveClass(
+      "badge-class",
+    );
+  });
+
+  it("applies classNames.fallback when the image is absent", () => {
+    render(
+      <Avatar
+        alt={personName}
+        src=""
+        classNames={{ fallback: "fallback-class" }}
+      />,
+    );
+
+    expect(document.querySelector('[data-slot="avatar-fallback"]')).toHaveClass(
+      "fallback-class",
+    );
+  });
+
+  it("forwards the delay prop to the underlying Fallback", () => {
+    // With a delay, Base UI defers rendering the fallback. Asserting that the
+    // fallback is absent right after mount proves the prop is being honored.
+    render(<Avatar alt={personName} src="" delay={500} />);
+
+    expect(document.querySelector('[data-slot="avatar-fallback"]')).toBeNull();
+  });
+
+  it("spreads extra props onto the AvatarRoot element", () => {
+    render(
+      <Avatar
+        alt={personName}
+        src={imageSrc}
+        data-testid="composite-root"
+        aria-label="user avatar"
+      />,
+    );
+
+    const root = screen.getByTestId("composite-root");
+    expect(root).toHaveAttribute("data-slot", "avatar");
+    expect(root).toHaveAttribute("aria-label", "user avatar");
+  });
+});
+
+describe("Avatar primitives", () => {
+  it("composes Root, Image, and Fallback directly", () => {
+    render(
+      <AvatarRoot>
+        <AvatarImage src="https://i.pravatar.cc/300" alt="user" />
+        <AvatarFallback>U</AvatarFallback>
+      </AvatarRoot>,
+    );
+
+    expect(screen.getByRole("img")).toHaveAttribute("alt", "user");
+  });
+
+  it("renders the Fallback when no Image is provided", () => {
+    render(
+      <AvatarRoot>
+        <AvatarFallback>FB</AvatarFallback>
+      </AvatarRoot>,
+    );
+
+    expect(screen.getByText("FB")).toBeInTheDocument();
+  });
+
+  it("merges custom className onto AvatarRoot alongside variant classes", () => {
+    render(
+      <AvatarRoot size="lg" className="ring-custom">
+        <AvatarFallback>L</AvatarFallback>
+      </AvatarRoot>,
+    );
+
+    const root = document.querySelector('[data-slot="avatar"]');
+    expect(root).toHaveClass("ring-custom", "size-14");
+    expect(root).toHaveAttribute("data-size", "lg");
+  });
+
+  it("applies the base image classes to AvatarImage", () => {
+    render(
+      <AvatarRoot>
+        <AvatarImage src="https://i.pravatar.cc/300" alt="user" />
+        <AvatarFallback>U</AvatarFallback>
+      </AvatarRoot>,
+    );
+
+    const image = screen.getByRole("img");
+    expect(image).toHaveClass("size-full", "rounded-full", "object-cover");
+  });
+
+  it("merges custom className onto AvatarFallback alongside base classes", () => {
+    render(
+      <AvatarRoot>
+        <AvatarFallback className="text-emerald-500">U</AvatarFallback>
+      </AvatarRoot>,
+    );
+
+    const fallback = document.querySelector('[data-slot="avatar-fallback"]');
+    expect(fallback).toHaveClass("text-emerald-500", "rounded-full");
+  });
+
+  it("renders AvatarBadge as an absolutely positioned slot", () => {
+    render(
+      <AvatarRoot>
+        <AvatarFallback>U</AvatarFallback>
+        <AvatarBadge>1</AvatarBadge>
+      </AvatarRoot>,
+    );
+
+    const badge = document.querySelector('[data-slot="avatar-badge"]');
+    expect(badge).toHaveTextContent("1");
+    expect(badge).toHaveClass("absolute");
+  });
+
+  it("applies size-scoped badge classes for every avatar size", () => {
+    render(
+      <AvatarRoot size="xl">
+        <AvatarFallback>X</AvatarFallback>
+        <AvatarBadge>!</AvatarBadge>
+      </AvatarRoot>,
+    );
+
+    const badge = document.querySelector('[data-slot="avatar-badge"]');
+    expect(badge).toHaveClass(
+      "group-data-[size=xl]/avatar:size-4",
+      "group-data-[size=xl]/avatar:[&>svg]:size-3",
+    );
+  });
+
+  it("merges custom className onto AvatarBadge", () => {
+    render(
+      <AvatarRoot>
+        <AvatarFallback>U</AvatarFallback>
+        <AvatarBadge className="bg-red-500">!</AvatarBadge>
+      </AvatarRoot>,
+    );
+
+    const badge = document.querySelector('[data-slot="avatar-badge"]');
+    expect(badge).toHaveClass("bg-red-500", "absolute");
+  });
+
+  it("renders AvatarGroup wrapping multiple avatars", () => {
+    render(
+      <AvatarGroup data-testid="group">
+        <AvatarRoot>
+          <AvatarFallback>A</AvatarFallback>
+        </AvatarRoot>
+        <AvatarRoot>
+          <AvatarFallback>B</AvatarFallback>
+        </AvatarRoot>
+      </AvatarGroup>,
+    );
+
+    const group = screen.getByTestId("group");
+    expect(group).toHaveAttribute("data-slot", "avatar-group");
+    expect(group.querySelectorAll('[data-slot="avatar"]')).toHaveLength(2);
+  });
+
+  it("merges custom className onto AvatarGroup alongside base classes", () => {
+    render(
+      <AvatarGroup data-testid="group" className="gap-4">
+        <AvatarRoot>
+          <AvatarFallback>A</AvatarFallback>
+        </AvatarRoot>
+      </AvatarGroup>,
+    );
+
+    const group = screen.getByTestId("group");
+    expect(group).toHaveClass("gap-4", "flex");
+  });
+
+  it("renders AvatarGroupCount with the chosen size", () => {
+    render(<AvatarGroupCount size="lg">+3</AvatarGroupCount>);
+
+    const count = document.querySelector('[data-slot="avatar-group-count"]');
+    expect(count).toHaveTextContent("+3");
+    expect(count).toHaveClass("size-14");
+  });
+
+  it("defaults AvatarGroupCount size to md when omitted", () => {
+    render(<AvatarGroupCount>+9</AvatarGroupCount>);
+
+    const count = document.querySelector('[data-slot="avatar-group-count"]');
+    expect(count).toHaveClass("size-10", "text-sm");
+  });
+
+  it("merges custom className onto AvatarGroupCount alongside variant classes", () => {
+    render(
+      <AvatarGroupCount size="sm" className="bg-blue-500">
+        +1
+      </AvatarGroupCount>,
+    );
+
+    const count = document.querySelector('[data-slot="avatar-group-count"]');
+    expect(count).toHaveClass("bg-blue-500", "size-8");
+  });
+
+  it("exposes the Base UI namespace via AvatarPrimitive", () => {
+    expect(AvatarPrimitive).toBeDefined();
+    expect(AvatarPrimitive.Root).toBeDefined();
+    expect(AvatarPrimitive.Image).toBeDefined();
+    expect(AvatarPrimitive.Fallback).toBeDefined();
+  });
+});

package/src/components/avatar/avatar.tsx

@@ -0,0 +1,165 @@
+"use client";
+
+import { Avatar as AvatarPrimitive } from "@base-ui/react/avatar";
+import { cva, type VariantProps } from "class-variance-authority";
+import { type ComponentProps, type ReactNode } from "react";
+import { cn } from "../../lib";
+import { extractInitials } from "../../utils";
+
+const avatarVariants = cva(
+  "group/avatar relative flex aspect-square shrink-0 select-none rounded-full bg-muted items-center justify-center font-medium",
+  {
+    variants: {
+      size: {
+        xs: "size-6 text-[10px]",
+        sm: "size-8 text-xs",
+        md: "size-10 text-sm",
+        lg: "size-14 text-base",
+        xl: "size-20 text-xl",
+      },
+    },
+    defaultVariants: {
+      size: "md",
+    },
+  },
+);
+
+export function AvatarRoot({
+  className,
+  size,
+  ...props
+}: AvatarPrimitive.Root.Props & VariantProps<typeof avatarVariants>) {
+  return (
+    <AvatarPrimitive.Root
+      className={cn(avatarVariants({ size }), className)}
+      data-slot="avatar"
+      data-size={size ?? "md"}
+      {...props}
+    />
+  );
+}
+
+export function AvatarImage({
+  className,
+  ...props
+}: AvatarPrimitive.Image.Props) {
+  return (
+    <AvatarPrimitive.Image
+      className={cn(
+        "aspect-square size-full rounded-full object-cover",
+        className,
+      )}
+      data-slot="avatar-image"
+      {...props}
+    />
+  );
+}
+
+export function AvatarFallback({
+  className,
+  ...props
+}: AvatarPrimitive.Fallback.Props) {
+  return (
+    <AvatarPrimitive.Fallback
+      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"];
+  size?: VariantProps<typeof avatarVariants>["size"];
+  /** 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,
+  size,
+  className,
+  classNames,
+  ...props
+}: AvatarProps) {
+  return (
+    <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>
+  );
+}
+
+export { AvatarPrimitive };

package/src/components/avatar/index.ts

@@ -0,0 +1 @@
+export * from "./avatar";