@exegia/corpora-ui 0.7.0 → 0.9.0

package/src/components/composed/__tests__/user-avatar.test.tsx

@@ -0,0 +1,85 @@
+import { describe, expect, test } from "bun:test"
+import { render, screen } from "@testing-library/react"
+
+import { UserAvatar, initialsFrom } from "../user-avatar"
+
+describe("initialsFrom", () => {
+  test("takes the first and last word", () => {
+    expect(initialsFrom("Jenny Hamilton")).toBe("JH")
+    expect(initialsFrom("ada  b  lovelace")).toBe("AL")
+    expect(initialsFrom("luna")).toBe("L")
+    expect(initialsFrom("   ")).toBe("")
+  })
+})
+
+describe("UserAvatar", () => {
+  test("shows initials right away when there is no image", () => {
+    const { container } = render(<UserAvatar name="Luna Wyen" />)
+
+    expect(screen.getByText("LW")).toBeDefined()
+    expect(container.querySelector('[data-slot="avatar-skeleton"]')).toBeNull()
+    expect(container.querySelector("img")).toBeNull()
+  })
+
+  test("holds a skeleton while a passed image is still loading", () => {
+    // happy-dom resolves every Image synchronously (complete, naturalWidth 0),
+    // so stand in a request that never answers.
+    const RealImage = window.Image
+    window.Image = class {
+      complete = false
+      naturalWidth = 0
+      onload: (() => void) | null = null
+      onerror: (() => void) | null = null
+      src = ""
+    } as unknown as typeof window.Image
+
+    try {
+      const { container } = render(
+        <UserAvatar name="Jenny Hamilton" src="https://example.com/j.jpg" />
+      )
+
+      expect(
+        container.querySelector('[data-slot="avatar-skeleton"]')
+      ).not.toBeNull()
+      expect(screen.queryByText("JH")).toBeNull()
+      expect(
+        container
+          .querySelector('[data-slot="user-avatar"]')
+          ?.hasAttribute("data-loading")
+      ).toBe(true)
+    } finally {
+      window.Image = RealImage
+    }
+  })
+
+  test("settles on the initials when the image fails", () => {
+    // The stubbed DOM never fetches, so every src lands in the error branch.
+    const { container } = render(
+      <UserAvatar name="Jenny Hamilton" src="https://example.com/missing.jpg" />
+    )
+
+    expect(screen.getByText("JH")).toBeDefined()
+    expect(container.querySelector('[data-slot="avatar-skeleton"]')).toBeNull()
+  })
+
+  test("loading forces the skeleton over a resolvable image", () => {
+    const { container } = render(
+      <UserAvatar
+        loading
+        name="Jenny Hamilton"
+        src="https://example.com/j.jpg"
+      />
+    )
+
+    expect(
+      container.querySelector('[data-slot="avatar-skeleton"]')
+    ).not.toBeNull()
+    expect(container.querySelector("img")).toBeNull()
+    expect(screen.queryByText("JH")).toBeNull()
+  })
+
+  test("explicit initials win over the derived ones", () => {
+    render(<UserAvatar initials="EX" name="Jenny Hamilton" />)
+    expect(screen.getByText("EX")).toBeDefined()
+  })
+})

package/src/components/composed/user-avatar.tsx

@@ -0,0 +1,98 @@
+"use client"
+
+import * as React from "react"
+
+import {
+  Avatar,
+  AvatarFallback,
+  AvatarImage,
+  type AvatarPrimitive,
+} from "@/components/ui/avatar"
+import { Skeleton } from "@/components/ui/skeleton"
+import { cn } from "@/lib/utils"
+
+type ImageStatus = Parameters<
+  NonNullable<AvatarPrimitive.Image.Props["onLoadingStatusChange"]>
+>[0]
+
+export interface UserAvatarProps extends Omit<
+  AvatarPrimitive.Root.Props,
+  "children"
+> {
+  /** Image URL. Without one the initials show immediately — no skeleton. */
+  src?: string
+  /** Drives the initials, and the alt text unless `alt` overrides it. */
+  name?: string
+  /** Overrides the initials derived from `name`. */
+  initials?: string
+  /**
+   * Alt text for the image. Pass "" when adjacent text already names the
+   * person — the image is then decorative.
+   */
+  alt?: string
+  /**
+   * Force the skeleton, for when the identity itself is still being fetched.
+   * Omitted, it follows the image: a passed `src` skeletons until it resolves.
+   */
+  loading?: boolean
+}
+
+/** "Jenny Hamilton" → "JH", "luna" → "L". */
+export function initialsFrom(name: string): string {
+  const parts = name.trim().split(/\s+/).filter(Boolean)
+  if (parts.length === 0) return ""
+  const first = parts[0]?.[0] ?? ""
+  const last = parts.length > 1 ? (parts.at(-1)?.[0] ?? "") : ""
+  return (first + last).toUpperCase()
+}
+
+/**
+ * Identity avatar: an image when one is given, initials otherwise.
+ *
+ * A passed `src` is assumed to be remote, so the slot holds a skeleton until
+ * the image resolves rather than flashing initials that are about to be
+ * replaced. A failed load settles on the initials.
+ */
+export function UserAvatar({
+  src,
+  name = "",
+  initials,
+  alt,
+  loading: loadingProp,
+  className,
+  ...props
+}: UserAvatarProps): React.ReactElement {
+  const [status, setStatus] = React.useState<ImageStatus>("idle")
+  const loading =
+    loadingProp ??
+    (src !== undefined && (status === "idle" || status === "loading"))
+
+  return (
+    <Avatar
+      className={cn("size-8", className)}
+      data-loading={loading || undefined}
+      data-slot="user-avatar"
+      {...props}
+    >
+      {/* Held back while forced-loading: a loaded image would hide the
+          fallback the skeleton lives in. */}
+      {src === undefined || loadingProp === true ? null : (
+        <AvatarImage
+          alt={alt ?? name}
+          onLoadingStatusChange={setStatus}
+          src={src}
+        />
+      )}
+      <AvatarFallback>
+        {loading ? (
+          <Skeleton
+            className="size-full rounded-full"
+            data-slot="avatar-skeleton"
+          />
+        ) : (
+          (initials ?? initialsFrom(name))
+        )}
+      </AvatarFallback>
+    </Avatar>
+  )
+}