@exegia/corpora-ui 0.8.0 → 0.9.0

package/src/components/blocks/profile/profile-card-block.tsx

@@ -0,0 +1,281 @@
+"use client"
+
+import {
+  ChevronsUpDownIcon,
+  LogOutIcon,
+  SettingsIcon,
+  UserIcon,
+  UserPlusIcon,
+  UsersIcon,
+} from "lucide-react"
+import * as React from "react"
+
+import { UserAvatar } from "@/components/composed/user-avatar"
+import { Button } from "@/components/ui/button"
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuGroup,
+  DropdownMenuItem,
+  DropdownMenuLabel,
+  DropdownMenuSeparator,
+  DropdownMenuShortcut,
+  DropdownMenuTrigger,
+  type MenuPrimitive,
+} from "@/components/ui/menu"
+import { playCue } from "@/lib/sound"
+import { cn } from "@/lib/utils"
+
+/** The identity shown on the card. */
+export interface ProfileCardUser {
+  name: string
+  /** Secondary line under the name — a handle, an email, a role. */
+  username?: string
+  /** Avatar image URL. Falls back to the initials when absent or broken. */
+  avatar?: string
+  /** Fallback initials. Derived from `name` when omitted. */
+  initials?: string
+}
+
+/** An actionable row of the menu. */
+export interface ProfileCardAction {
+  type?: "item"
+  id: string
+  label: string
+  icon?: React.ReactNode
+  /** Right-aligned hint, e.g. "⌘K". Purely decorative — bind the key yourself. */
+  shortcut?: string
+  disabled?: boolean
+  variant?: "default" | "destructive"
+  /** Returning a promise puts the card in its loading state until it settles. */
+  onSelect?: () => void | Promise<void>
+}
+
+/** A heading over the rows that follow it, up to the next separator. */
+export interface ProfileCardLabel {
+  type: "label"
+  label: string
+}
+
+/** A rule between two sections. */
+export interface ProfileCardSeparator {
+  type: "separator"
+}
+
+/**
+ * One entry of `items`. Authored flat; the block renders each run between
+ * separators as its own menu group so a label actually names its section.
+ */
+export type ProfileCardItem =
+  ProfileCardAction | ProfileCardLabel | ProfileCardSeparator
+
+/**
+ * The menu the card ships with. Spread it to keep the shape and attach your
+ * own handlers, or ignore it and pass `items` of your own.
+ */
+export const defaultProfileCardItems: ProfileCardItem[] = [
+  { type: "label", label: "Management" },
+  { id: "profile", label: "Profile", icon: <UserIcon aria-hidden="true" /> },
+  {
+    id: "settings",
+    label: "Settings",
+    icon: <SettingsIcon aria-hidden="true" />,
+  },
+  { type: "separator" },
+  { id: "teams", label: "Teams", icon: <UsersIcon aria-hidden="true" /> },
+  { id: "invite", label: "Invite", icon: <UserPlusIcon aria-hidden="true" /> },
+  { type: "separator" },
+  {
+    id: "sign-out",
+    label: "Log out",
+    icon: <LogOutIcon aria-hidden="true" />,
+    variant: "destructive",
+  },
+]
+
+type PopupProps = React.ComponentProps<typeof DropdownMenuContent>
+
+export interface ProfileCardBlockProps {
+  user: ProfileCardUser
+  /**
+   * The menu, flat: actions plus `{ type: "separator" }` / `{ type: "label" }`
+   * entries. Defaults to `defaultProfileCardItems` (no handlers attached).
+   */
+  items?: ProfileCardItem[]
+  /** Menu placement relative to the card. */
+  align?: PopupProps["align"]
+  side?: PopupProps["side"]
+  sideOffset?: PopupProps["sideOffset"]
+  open?: boolean
+  defaultOpen?: boolean
+  onOpenChange?: MenuPrimitive.Root.Props["onOpenChange"]
+  /**
+   * Emit cuelume press/release on the card and play the open/close cues.
+   * Inert unless the app opts into interaction sound via `bindSounds()`.
+   */
+  sound?: boolean
+  /** Called when an action's promise rejects — the card leaves its loading state either way. */
+  onError?: (error: unknown) => void
+  className?: string
+}
+
+/** Split a flat item list into the groups the menu renders. */
+function toGroups(
+  items: ProfileCardItem[]
+): { label?: string; actions: ProfileCardAction[] }[] {
+  const groups: { label?: string; actions: ProfileCardAction[] }[] = []
+  let current: { label?: string; actions: ProfileCardAction[] } = {
+    actions: [],
+  }
+
+  for (const item of items) {
+    if (item.type === "separator") {
+      groups.push(current)
+      current = { actions: [] }
+    } else if (item.type === "label") {
+      current.label = item.label
+    } else {
+      current.actions.push(item)
+    }
+  }
+  groups.push(current)
+
+  return groups.filter(
+    (group) => group.actions.length > 0 || group.label !== undefined
+  )
+}
+
+/**
+ * Avatar card that opens an account menu.
+ *
+ * The trigger is the rich identity chip (avatar + name over handle) and the
+ * popup is a plain action menu. `items` is the whole menu — a flat list of
+ * actions, separators and labels — defaulting to `defaultProfileCardItems`.
+ */
+export function ProfileCardBlock({
+  user,
+  items = defaultProfileCardItems,
+  align = "center",
+  side = "bottom",
+  sideOffset = 8,
+  open,
+  defaultOpen,
+  onOpenChange,
+  sound = true,
+  onError,
+  className,
+}: ProfileCardBlockProps): React.ReactElement {
+  const [pending, setPending] = React.useState<string | null>(null)
+  // Actions can outlive the card (sign-out unmounts it, typically).
+  const mounted = React.useRef(true)
+  React.useEffect(() => {
+    mounted.current = true
+    return () => {
+      mounted.current = false
+    }
+  }, [])
+
+  const groups = React.useMemo(() => toGroups(items), [items])
+
+  function select(action: ProfileCardAction) {
+    const result = action.onSelect?.()
+    if (!(result instanceof Promise)) return
+    setPending(action.id)
+    result
+      .catch((cause: unknown) => onError?.(cause))
+      .finally(() => {
+        if (mounted.current) setPending(null)
+      })
+  }
+
+  const busy = pending !== null
+
+  const handleOpenChange: MenuPrimitive.Root.Props["onOpenChange"] = (
+    nextOpen,
+    details
+  ) => {
+    if (sound) playCue(nextOpen ? "bloom" : "droplet")
+    onOpenChange?.(nextOpen, details)
+  }
+
+  return (
+    <DropdownMenu
+      defaultOpen={defaultOpen}
+      onOpenChange={handleOpenChange}
+      open={open}
+    >
+      <DropdownMenuTrigger
+        disabled={busy}
+        render={
+          <Button
+            // Spelled out rather than left to the name-from-contents rule: the
+            // avatar sits inside the button and the handle is a second line.
+            aria-label={`${user.name}${user.username ? ` ${user.username}` : ""}, account menu`}
+            className={cn(
+              "h-auto w-full justify-between py-1.5 pl-1.5 sm:h-auto",
+              className
+            )}
+            data-slot="profile-card"
+            loading={busy}
+            sound={sound}
+            variant="outline"
+          >
+            <span className="flex w-full min-w-0 items-center justify-start gap-2">
+              <UserAvatar
+                // Decorative: the name beside it already labels the card.
+                alt=""
+                initials={user.initials}
+                name={user.name}
+                src={user.avatar}
+              />
+              <span className="flex min-w-0 flex-col text-left">
+                <span className="truncate font-medium">{user.name}</span>
+                {user.username ? (
+                  <span className="truncate text-xs font-normal text-muted-foreground">
+                    {user.username}
+                  </span>
+                ) : null}
+              </span>
+            </span>
+            <ChevronsUpDownIcon aria-hidden="true" className="size-3.5" />
+          </Button>
+        }
+      />
+      <DropdownMenuContent
+        align={align}
+        // Content-width menu (not the card's width) so `align` reads: a popup
+        // locked to `--anchor-width` lands in the same place for every value.
+        // `!` because the popup's own `not-[class*='w-']:min-w-32` compiles to
+        // a higher-specificity `:not(:is())` that would otherwise win.
+        className="min-w-44! origin-(--transform-origin) transition-[opacity,scale,translate] duration-150 ease-smooth-out data-ending-style:scale-98 data-ending-style:opacity-0 data-ending-style:duration-100 data-starting-style:scale-98 data-starting-style:opacity-0 data-[side=bottom]:data-ending-style:-translate-y-1 data-[side=bottom]:data-starting-style:-translate-y-1 data-[side=top]:data-ending-style:translate-y-1 data-[side=top]:data-starting-style:translate-y-1 motion-reduce:transition-none"
+        side={side}
+        sideOffset={sideOffset}
+      >
+        {groups.map((group, index) => (
+          <React.Fragment key={group.label ?? `group-${group.actions[0]?.id}`}>
+            {index > 0 ? <DropdownMenuSeparator /> : null}
+            <DropdownMenuGroup>
+              {group.label ? (
+                <DropdownMenuLabel>{group.label}</DropdownMenuLabel>
+              ) : null}
+              {group.actions.map((item) => (
+                <DropdownMenuItem
+                  disabled={item.disabled}
+                  key={item.id}
+                  onClick={() => select(item)}
+                  variant={item.variant}
+                >
+                  {item.icon}
+                  <span>{item.label}</span>
+                  {item.shortcut ? (
+                    <DropdownMenuShortcut>{item.shortcut}</DropdownMenuShortcut>
+                  ) : null}
+                </DropdownMenuItem>
+              ))}
+            </DropdownMenuGroup>
+          </React.Fragment>
+        ))}
+      </DropdownMenuContent>
+    </DropdownMenu>
+  )
+}

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>
+  )
+}