@exegia/corpora-ui 0.8.0 → 0.9.0

package/dist-lib/lib/ease.d.ts

@@ -0,0 +1,46 @@
+export declare const EASE_OUT: readonly [0.16, 1, 0.3, 1];
+export declare const EASE_IN_OUT: readonly [0.77, 0, 0.175, 1];
+export declare const EASE_DRAWER: readonly [0.32, 0.72, 0, 1];
+/** CSS string form of EASE_OUT for inline style transitions. */
+export declare const EASE_OUT_CSS = "cubic-bezier(0.16, 1, 0.3, 1)";
+/** Press feedback on buttons and other tappable surfaces. */
+export declare const SPRING_PRESS: {
+    readonly type: "spring";
+    readonly stiffness: 500;
+    readonly damping: 30;
+    readonly mass: 0.6;
+};
+/** Content swaps — label/icon slots trading places inside a control. */
+export declare const SPRING_SWAP: {
+    readonly type: "spring";
+    readonly stiffness: 460;
+    readonly damping: 30;
+    readonly mass: 0.55;
+};
+/** Overlay panel entrances — modals and sheets summoned by pointer. */
+export declare const SPRING_PANEL: {
+    readonly type: "spring";
+    readonly stiffness: 420;
+    readonly damping: 40;
+    readonly mass: 0.5;
+};
+/** Shared-layout glides — pills, indicators and panels morphing between positions. */
+export declare const SPRING_LAYOUT: {
+    readonly type: "spring";
+    readonly stiffness: 360;
+    readonly damping: 32;
+    readonly mass: 0.6;
+};
+/** Cursor-follow physics for decorative mouse tracking (magnetic, tilt, dock). */
+export declare const SPRING_MOUSE: {
+    readonly stiffness: 200;
+    readonly damping: 15;
+    readonly mass: 0.3;
+};
+/** Dragged handles and fills (sliders) — critically damped `useSpring` config,
+ * so the value follows the pointer butterily and never rebounds off an end. */
+export declare const SPRING_GLIDE: {
+    readonly stiffness: 700;
+    readonly damping: 50;
+    readonly mass: 0.5;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exegia/corpora-ui",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "shadcn-ready React UI library for the corpora manuscript-research apps.",
   "license": "MIT",
   "repository": {

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

@@ -0,0 +1,125 @@
+import { describe, expect, mock, test } from "bun:test"
+import { render, screen } from "@testing-library/react"
+import userEvent from "@testing-library/user-event"
+
+import { SidebarBlock, type SidebarNavSection } from "../sidebar-block"
+
+const SECTIONS: SidebarNavSection[] = [
+  {
+    id: "work",
+    label: "Research",
+    items: [
+      { id: "search", label: "Search" },
+      {
+        id: "library",
+        label: "Library",
+        items: [
+          { id: "manuscripts", label: "Manuscripts" },
+          { id: "codices", label: "Codices" },
+        ],
+      },
+    ],
+  },
+  { id: "workspace", items: [{ id: "settings", label: "Settings" }] },
+]
+
+describe("SidebarBlock", () => {
+  test("renders the sections and their entries", () => {
+    render(<SidebarBlock ariaLabel="Main" sections={SECTIONS} />)
+
+    expect(screen.getByRole("navigation", { name: "Main" })).toBeDefined()
+    expect(screen.getByText("Research")).toBeDefined()
+    expect(screen.getByRole("button", { name: "Search" })).toBeDefined()
+    expect(screen.getByRole("button", { name: "Settings" })).toBeDefined()
+  })
+
+  test("marks the active entry", () => {
+    render(<SidebarBlock activeId="search" sections={SECTIONS} />)
+
+    expect(
+      screen
+        .getByRole("button", { name: "Search" })
+        .getAttribute("aria-current")
+    ).toBe("page")
+    expect(
+      screen
+        .getByRole("button", { name: "Settings" })
+        .getAttribute("aria-current")
+    ).toBeNull()
+  })
+
+  test("reports selections through onNavigate, after the entry's onSelect", async () => {
+    const user = userEvent.setup()
+    const calls: string[] = []
+    render(
+      <SidebarBlock
+        onNavigate={(item) => calls.push(`navigate:${item.id}`)}
+        sections={[
+          {
+            id: "work",
+            items: [
+              {
+                id: "search",
+                label: "Search",
+                onSelect: () => calls.push("select:search"),
+              },
+            ],
+          },
+        ]}
+      />
+    )
+
+    await user.click(screen.getByRole("button", { name: "Search" }))
+
+    expect(calls).toEqual(["select:search", "navigate:search"])
+  })
+
+  test("an entry with children expands instead of navigating", async () => {
+    const user = userEvent.setup()
+    const onNavigate = mock(() => {})
+    render(<SidebarBlock onNavigate={onNavigate} sections={SECTIONS} />)
+
+    const parent = screen.getByRole("button", { name: "Library" })
+    expect(parent.getAttribute("aria-expanded")).toBe("false")
+    expect(screen.queryByRole("button", { name: "Manuscripts" })).toBeNull()
+
+    await user.click(parent)
+
+    expect(
+      await screen.findByRole("button", { name: "Manuscripts" })
+    ).toBeDefined()
+    expect(parent.getAttribute("aria-expanded")).toBe("true")
+    expect(onNavigate).not.toHaveBeenCalled()
+  })
+
+  test("starts expanded when one of its children is active", async () => {
+    render(<SidebarBlock activeId="codices" sections={SECTIONS} />)
+
+    const child = await screen.findByRole("button", { name: "Codices" })
+    expect(child.getAttribute("aria-current")).toBe("page")
+    expect(
+      screen
+        .getByRole("button", { name: "Library" })
+        .getAttribute("aria-expanded")
+    ).toBe("true")
+  })
+
+  test("renders href entries as links", () => {
+    render(
+      <SidebarBlock
+        sections={[
+          {
+            id: "work",
+            items: [
+              { id: "docs", label: "Docs", href: "/docs", target: "_blank" },
+            ],
+          },
+        ]}
+      />
+    )
+
+    const link = screen.getByRole("link", { name: "Docs" })
+    expect(link.getAttribute("href")).toBe("/docs")
+    expect(link.getAttribute("rel")).toBe("noreferrer noopener")
+  })
+})

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