@exegia/corpora-ui 0.7.0 → 0.9.0

package/src/components/blocks/nav/sidebar-block.tsx

@@ -0,0 +1,264 @@
+"use client"
+
+import { PanelLeftIcon } from "lucide-react"
+import * as React from "react"
+
+import {
+  AnimatedSidebar,
+  AnimatedSidebarContent,
+  AnimatedSidebarFooter,
+  AnimatedSidebarGroup,
+  AnimatedSidebarGroupContent,
+  AnimatedSidebarGroupLabel,
+  AnimatedSidebarHeader,
+  AnimatedSidebarMenu,
+  AnimatedSidebarMenuButton,
+  AnimatedSidebarMenuItem,
+  AnimatedSidebarMenuSub,
+  AnimatedSidebarMenuSubButton,
+  AnimatedSidebarMenuSubItem,
+  AnimatedSidebarProvider,
+  AnimatedSidebarTrigger,
+} from "@/components/motion/animated-sidebar"
+import { cn } from "@/lib/utils"
+
+/** A nested link, one level under a top-level entry. */
+export interface SidebarNavSubItem {
+  id: string
+  label: string
+  icon?: React.ReactNode
+  /** Renders an anchor. Without one the row is a button. */
+  href?: string
+  disabled?: boolean
+  target?: "_blank" | "_self" | "_parent" | "_top"
+  onSelect?: () => void
+}
+
+/** A top-level entry. With `items` it expands instead of navigating. */
+export interface SidebarNavItem extends SidebarNavSubItem {
+  /** Trailing hint — a count, a "New" pill. Hidden while collapsed. */
+  badge?: React.ReactNode
+  items?: SidebarNavSubItem[]
+  /** Start expanded. Defaults to expanded when one of its children is active. */
+  defaultOpen?: boolean
+}
+
+/** A titled run of entries. The title hides while the rail is collapsed. */
+export interface SidebarNavSection {
+  id: string
+  label?: string
+  items: SidebarNavItem[]
+}
+
+export interface SidebarBlockProps {
+  sections: SidebarNavSection[]
+  /** `id` of the current entry — matches top-level and nested ids alike. */
+  activeId?: string
+  /** Fires for every selection, after the entry's own `onSelect`. */
+  onNavigate?: (item: SidebarNavItem | SidebarNavSubItem) => void
+  /** Brand row above the navigation. */
+  header?: React.ReactNode
+  /** Pinned below the navigation — an account card, a version note. */
+  footer?: React.ReactNode
+  /** Collapse toggle in the header row. */
+  showTrigger?: boolean
+  side?: "left" | "right"
+  variant?: "sidebar" | "floating" | "inset"
+  /** How the rail collapses: to icons, off-canvas, or not at all. */
+  collapsible?: "offcanvas" | "icon" | "none"
+  open?: boolean
+  defaultOpen?: boolean
+  onOpenChange?: (open: boolean) => void
+  /** Under 768px the panel is a drawer — drive it from your own header. */
+  openMobile?: boolean
+  defaultOpenMobile?: boolean
+  onOpenMobileChange?: (open: boolean) => void
+  /** Rail widths. CSS lengths, e.g. "16rem". */
+  width?: string
+  iconWidth?: string
+  mobileWidth?: string
+  ariaLabel?: string
+  className?: string
+}
+
+function isActive(id: string, activeId?: string): boolean {
+  return activeId !== undefined && id === activeId
+}
+
+interface RowProps {
+  item: SidebarNavItem
+  activeId?: string
+  onNavigate?: (item: SidebarNavItem | SidebarNavSubItem) => void
+}
+
+function SidebarNavRow({ item, activeId, onNavigate }: RowProps) {
+  const children = item.items ?? []
+  const hasChildren = children.length > 0
+  const childActive = children.some((child) => isActive(child.id, activeId))
+  // null = follow the active child; a boolean = the reader has said otherwise.
+  const [toggled, setToggled] = React.useState<boolean | null>(null)
+  const [wasChildActive, setWasChildActive] = React.useState(childActive)
+
+  // Navigating into a nested route from elsewhere reveals its parent, even if
+  // the reader had collapsed it. Adjusted during render rather than in an
+  // effect, so the group never paints closed for a frame first.
+  if (childActive !== wasChildActive) {
+    setWasChildActive(childActive)
+    if (childActive) setToggled(null)
+  }
+
+  const open = toggled ?? item.defaultOpen ?? childActive
+
+  function select(entry: SidebarNavItem | SidebarNavSubItem) {
+    entry.onSelect?.()
+    onNavigate?.(entry)
+  }
+
+  return (
+    <AnimatedSidebarMenuItem>
+      <AnimatedSidebarMenuButton
+        ariaExpanded={hasChildren ? open : undefined}
+        badge={item.badge}
+        disabled={item.disabled}
+        href={hasChildren ? undefined : item.href}
+        icon={item.icon}
+        isActive={isActive(item.id, activeId)}
+        onSelect={() => {
+          if (hasChildren) {
+            setToggled(!open)
+            return
+          }
+          select(item)
+        }}
+        target={item.target}
+      >
+        {item.label}
+      </AnimatedSidebarMenuButton>
+      {hasChildren ? (
+        <AnimatedSidebarMenuSub open={open}>
+          {children.map((child) => (
+            <AnimatedSidebarMenuSubItem key={child.id}>
+              <AnimatedSidebarMenuSubButton
+                disabled={child.disabled}
+                href={child.href}
+                icon={child.icon}
+                isActive={isActive(child.id, activeId)}
+                onSelect={() => select(child)}
+                target={child.target}
+              >
+                {child.label}
+              </AnimatedSidebarMenuSubButton>
+            </AnimatedSidebarMenuSubItem>
+          ))}
+        </AnimatedSidebarMenuSub>
+      ) : null}
+    </AnimatedSidebarMenuItem>
+  )
+}
+
+/**
+ * Application sidebar navigation, driven by data rather than composition.
+ *
+ * This is the navigation panel only — it claims no page layout, so place it
+ * beside your own content. It owns its own sidebar context (⌘B toggles it);
+ * pass `open`/`onOpenChange` to drive the rail, and `openMobile`/
+ * `onOpenMobileChange` to open the drawer from a header button of your own.
+ * Compose the underlying `AnimatedSidebar*` parts directly when a screen
+ * needs something this API does not cover.
+ */
+export function SidebarBlock({
+  sections,
+  activeId,
+  onNavigate,
+  header,
+  footer,
+  showTrigger = true,
+  side = "left",
+  variant = "sidebar",
+  collapsible = "icon",
+  open,
+  defaultOpen,
+  onOpenChange,
+  openMobile,
+  defaultOpenMobile,
+  onOpenMobileChange,
+  width,
+  iconWidth,
+  mobileWidth,
+  ariaLabel = "Main",
+  className,
+}: SidebarBlockProps): React.ReactElement {
+  return (
+    <AnimatedSidebarProvider
+      // The provider ships a full-page flex shell; this block is just the
+      // panel, so the shell is flattened back to the panel's own box.
+      className="h-full min-h-0 w-auto"
+      defaultOpen={defaultOpen}
+      defaultOpenMobile={defaultOpenMobile}
+      onOpenChange={onOpenChange}
+      onOpenMobileChange={onOpenMobileChange}
+      open={open}
+      openMobile={openMobile}
+      style={{
+        ...(width ? { "--sidebar-width": width } : null),
+        ...(iconWidth ? { "--sidebar-width-icon": iconWidth } : null),
+        ...(mobileWidth ? { "--sidebar-width-mobile": mobileWidth } : null),
+      }}
+    >
+      <AnimatedSidebar
+        ariaLabel={ariaLabel}
+        // The panel is built for a full-page shell (`h-svh`, so its footer
+        // hangs below any shorter box). Fill the parent instead — in a
+        // full-height layout that comes to the same thing.
+        className={cn("h-full", className)}
+        collapsible={collapsible}
+        panelClassName="h-full"
+        // The panel is navigation and nothing else, so it names a navigation
+        // landmark rather than the complementary one <aside> implies. (The
+        // mobile drawer is a dialog and keeps that role.)
+        role="navigation"
+        side={side}
+        variant={variant}
+      >
+        {header || showTrigger ? (
+          <AnimatedSidebarHeader>
+            <div className="flex min-w-0 items-center justify-between gap-2">
+              {header ? <div className="min-w-0 flex-1">{header}</div> : null}
+              {showTrigger ? (
+                <AnimatedSidebarTrigger className="text-muted-foreground hover:text-foreground">
+                  <PanelLeftIcon className="size-4.5" />
+                </AnimatedSidebarTrigger>
+              ) : null}
+            </div>
+          </AnimatedSidebarHeader>
+        ) : null}
+        <AnimatedSidebarContent>
+          {sections.map((section) => (
+            <AnimatedSidebarGroup key={section.id}>
+              {section.label ? (
+                <AnimatedSidebarGroupLabel>
+                  {section.label}
+                </AnimatedSidebarGroupLabel>
+              ) : null}
+              <AnimatedSidebarGroupContent>
+                <AnimatedSidebarMenu>
+                  {section.items.map((item) => (
+                    <SidebarNavRow
+                      activeId={activeId}
+                      item={item}
+                      key={item.id}
+                      onNavigate={onNavigate}
+                    />
+                  ))}
+                </AnimatedSidebarMenu>
+              </AnimatedSidebarGroupContent>
+            </AnimatedSidebarGroup>
+          ))}
+        </AnimatedSidebarContent>
+        {footer ? (
+          <AnimatedSidebarFooter>{footer}</AnimatedSidebarFooter>
+        ) : null}
+      </AnimatedSidebar>
+    </AnimatedSidebarProvider>
+  )
+}

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

@@ -0,0 +1,134 @@
+import { describe, expect, mock, test } from "bun:test";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+
+import { ProfileCardBlock } from "../profile-card-block";
+
+const USER = { name: "Jenny Hamilton", username: "@jennycodes" };
+
+describe("ProfileCardBlock", () => {
+  test("names the trigger after the identity it shows", () => {
+    render(<ProfileCardBlock user={USER} />);
+
+    const trigger = screen.getByRole("button", {
+      name: "Jenny Hamilton @jennycodes, account menu",
+    });
+    expect(trigger.textContent).toContain("Jenny Hamilton");
+    expect(trigger.textContent).toContain("@jennycodes");
+  });
+
+  test("falls back to initials derived from the name", () => {
+    render(<ProfileCardBlock user={{ name: "Jenny Hamilton" }} />);
+    expect(screen.getByText("JH")).toBeDefined();
+  });
+
+  test("opens the default menu with a destructive sign-out", async () => {
+    const user = userEvent.setup();
+    render(<ProfileCardBlock user={USER} />);
+
+    await user.click(screen.getByRole("button"));
+
+    expect(await screen.findByRole("menuitem", { name: "Profile" })).toBeDefined();
+    expect(screen.getByRole("menuitem", { name: "Settings" })).toBeDefined();
+    expect(screen.getByRole("menuitem", { name: "Teams" })).toBeDefined();
+    expect(screen.getByRole("menuitem", { name: "Invite" })).toBeDefined();
+    expect(
+      screen
+        .getByRole("menuitem", { name: "Log out" })
+        .getAttribute("data-variant"),
+    ).toBe("destructive");
+  });
+
+  test("opens from the keyboard", async () => {
+    const user = userEvent.setup();
+    render(<ProfileCardBlock user={USER} />);
+
+    await user.tab();
+    await user.keyboard("{Enter}");
+
+    expect(await screen.findByRole("menuitem", { name: "Profile" })).toBeDefined();
+  });
+
+  test("fires the handler behind the selected item", async () => {
+    const user = userEvent.setup();
+    const onSelect = mock(() => {});
+    render(
+      <ProfileCardBlock
+        items={[{ id: "settings", label: "Settings", onSelect }]}
+        user={USER}
+      />,
+    );
+
+    await user.click(screen.getByRole("button"));
+    await user.click(await screen.findByRole("menuitem", { name: "Settings" }));
+
+    expect(onSelect).toHaveBeenCalled();
+  });
+
+  test("items replace the default menu", async () => {
+    const user = userEvent.setup();
+    render(
+      <ProfileCardBlock
+        items={[{ id: "switch", label: "Switch team" }]}
+        user={USER}
+      />,
+    );
+
+    await user.click(screen.getByRole("button"));
+
+    expect(
+      await screen.findByRole("menuitem", { name: "Switch team" }),
+    ).toBeDefined();
+    expect(screen.queryByRole("menuitem", { name: "Log out" })).toBeNull();
+  });
+
+  test("labels name the group they head, up to the next separator", async () => {
+    const user = userEvent.setup();
+    render(
+      <ProfileCardBlock
+        items={[
+          { type: "label", label: "Workspace" },
+          { id: "switch", label: "Switch team" },
+          { type: "separator" },
+          { id: "sign-out", label: "Log out", variant: "destructive" },
+        ]}
+        user={USER}
+      />,
+    );
+
+    await user.click(screen.getByRole("button"));
+
+    const named = await screen.findByRole("group", { name: "Workspace" });
+    expect(named.querySelectorAll('[data-slot="menu-item"]')).toHaveLength(1);
+    expect(screen.getAllByRole("group")).toHaveLength(2);
+    expect(
+      screen.getByRole("menuitem", { name: "Log out" }).getAttribute("data-variant"),
+    ).toBe("destructive");
+  });
+
+  test("reports a rejected action through onError", async () => {
+    const user = userEvent.setup();
+    const onError = mock(() => {});
+    render(
+      <ProfileCardBlock
+        items={[
+          {
+            id: "sign-out",
+            label: "Log out",
+            onSelect: async () => {
+              throw new Error("Session already ended.");
+            },
+          },
+        ]}
+        onError={onError}
+        user={USER}
+      />,
+    );
+
+    await user.click(screen.getByRole("button"));
+    await user.click(await screen.findByRole("menuitem", { name: "Log out" }));
+
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    expect(onError).toHaveBeenCalled();
+  });
+});

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