@exegia/corpora-ui 0.6.0 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exegia/corpora-ui",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "shadcn-ready React UI library for the corpora manuscript-research apps.",
   "license": "MIT",
   "repository": {
@@ -54,7 +54,11 @@
     "@eslint/js": "^10",
     "@fontsource-variable/figtree": "^5.3.0",
     "@fontsource-variable/inter": "^5.3.0",
+    "@happy-dom/global-registrator": "^20.11.1",
     "@tailwindcss/vite": "^4",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/react": "^16.3.2",
+    "@testing-library/user-event": "^14.6.1",
     "@types/bun": "^1.3.14",
     "@types/node": "^24",
     "@types/react": "^19",

package/src/components/blocks/auth/__tests__/linked-accounts-block.test.tsx

@@ -0,0 +1,110 @@
+import { describe, expect, mock, test } from "bun:test";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+
+import {
+  LinkedAccountsBlock,
+  type LinkedIdentity,
+} from "../linked-accounts-block";
+
+const IDENTITIES: LinkedIdentity[] = [
+  { id: "id-1", provider: "google", email: "reader@example.com" },
+  { id: "id-2", provider: "github" },
+];
+
+describe("LinkedAccountsBlock", () => {
+  test("shows the loading row", () => {
+    render(<LinkedAccountsBlock loading />);
+    expect(screen.getByText("Loading connected accounts…")).toBeDefined();
+  });
+
+  test("shows the empty state when nothing is connected", () => {
+    render(<LinkedAccountsBlock identities={[]} />);
+    expect(screen.getByText("No sign-in methods connected yet.")).toBeDefined();
+  });
+
+  test("lists connected identities with their addresses", () => {
+    render(<LinkedAccountsBlock identities={IDENTITIES} />);
+
+    const list = screen.getByRole("list", { name: "Connected accounts" });
+    expect(list.querySelectorAll("li")).toHaveLength(2);
+    expect(screen.getByText("reader@example.com")).toBeDefined();
+  });
+
+  test("offers only the providers that are not connected yet", () => {
+    render(
+      <LinkedAccountsBlock
+        identities={IDENTITIES}
+        providers={["google", "apple", "github"]}
+      />,
+    );
+
+    expect(screen.getByRole("button", { name: "Connect Apple" })).toBeDefined();
+    expect(screen.queryByRole("button", { name: "Connect Google" })).toBeNull();
+    expect(screen.queryByRole("button", { name: "Connect GitHub" })).toBeNull();
+  });
+
+  test("connects a provider through onLink", async () => {
+    const user = userEvent.setup();
+    const onLink = mock(async () => {});
+    render(
+      <LinkedAccountsBlock
+        identities={IDENTITIES}
+        providers={["apple"]}
+        onLink={onLink}
+      />,
+    );
+
+    await user.click(screen.getByRole("button", { name: "Connect Apple" }));
+
+    expect(onLink).toHaveBeenCalledWith("apple");
+  });
+
+  test("disconnects an identity through onUnlink", async () => {
+    const user = userEvent.setup();
+    const onUnlink = mock(async () => {});
+    render(<LinkedAccountsBlock identities={IDENTITIES} onUnlink={onUnlink} />);
+
+    await user.click(screen.getByRole("button", { name: "Disconnect Google" }));
+
+    expect(onUnlink).toHaveBeenCalledWith("id-1");
+  });
+
+  test("guards the last remaining sign-in method", async () => {
+    const user = userEvent.setup();
+    const onUnlink = mock(async () => {});
+    render(
+      <LinkedAccountsBlock identities={[IDENTITIES[0]!]} onUnlink={onUnlink} />,
+    );
+
+    const button = screen.getByRole("button", { name: "Disconnect Google" });
+    expect(button.hasAttribute("disabled")).toBe(true);
+
+    const note = screen.getByText(
+      "This is your only way to sign in, so it can't be disconnected.",
+    );
+    expect(button.getAttribute("aria-describedby")).toBe(note.id);
+
+    await user.click(button);
+    expect(onUnlink).not.toHaveBeenCalled();
+  });
+
+  test("surfaces a failing link as an error", async () => {
+    const user = userEvent.setup();
+    render(
+      <LinkedAccountsBlock
+        identities={IDENTITIES}
+        providers={["apple"]}
+        onLink={async () => {
+          throw new Error("That account is already linked elsewhere.");
+        }}
+      />,
+    );
+
+    await user.click(screen.getByRole("button", { name: "Connect Apple" }));
+
+    expect((await screen.findByRole("alert")).textContent).toBe(
+      "That account is already linked elsewhere.",
+    );
+  });
+});

package/src/components/blocks/auth/__tests__/onboarding-block.test.tsx

@@ -0,0 +1,156 @@
+import { describe, expect, mock, test } from "bun:test";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+
+import {
+  OnboardingBlock,
+  type OnboardingBlockProps,
+  type OnboardingStepConfig,
+} from "../onboarding-block";
+
+const STEPS: OnboardingStepConfig[] = [
+  {
+    id: "profile",
+    title: "Your profile",
+    fields: [
+      { kind: "text", name: "display_name", label: "Display name", required: true },
+    ],
+  },
+  {
+    id: "links",
+    title: "Your links",
+    fields: [
+      { kind: "url", name: "website", label: "Website" },
+      { kind: "checkbox", name: "newsletter", label: "Send me the newsletter" },
+    ],
+  },
+];
+
+describe("OnboardingBlock", () => {
+  test("renders the declared steps as progress", () => {
+    render(<OnboardingBlock steps={STEPS} />);
+
+    const items = screen
+      .getByRole("navigation", { name: "Onboarding progress" })
+      .querySelectorAll("li");
+    expect(items).toHaveLength(2);
+    expect(items[0]?.getAttribute("aria-current")).toBe("step");
+  });
+
+  test("blocks advance on a missing required field", async () => {
+    const user = userEvent.setup();
+    const onStepSubmit = mock(async () => {});
+    render(<OnboardingBlock steps={STEPS} onStepSubmit={onStepSubmit} />);
+
+    await user.click(screen.getByRole("button", { name: "Continue" }));
+
+    expect(await screen.findByText("Display name is required")).toBeDefined();
+    expect(onStepSubmit).not.toHaveBeenCalled();
+  });
+
+  test("rejects a malformed URL", async () => {
+    const user = userEvent.setup();
+    render(<OnboardingBlock steps={STEPS} />);
+
+    await user.type(screen.getByLabelText("Display name"), "Ada");
+    await user.click(screen.getByRole("button", { name: "Continue" }));
+
+    await user.type(await screen.findByLabelText("Website"), "not-a-url");
+    await user.click(screen.getByRole("button", { name: "Finish" }));
+
+    expect(await screen.findByText("Enter a valid URL")).toBeDefined();
+  });
+
+  test("walks the steps and reports the merged profile once", async () => {
+    const user = userEvent.setup();
+    const onStepSubmit =
+      mock<NonNullable<OnboardingBlockProps["onStepSubmit"]>>(async () => {});
+    const onComplete =
+      mock<NonNullable<OnboardingBlockProps["onComplete"]>>(async () => {});
+    render(
+      <OnboardingBlock
+        steps={STEPS}
+        onStepSubmit={onStepSubmit}
+        onComplete={onComplete}
+      />,
+    );
+
+    await user.type(screen.getByLabelText("Display name"), "Ada");
+    await user.click(screen.getByRole("button", { name: "Continue" }));
+
+    await user.type(
+      await screen.findByLabelText("Website"),
+      "https://example.com",
+    );
+    await user.click(
+      screen.getByRole("checkbox", { name: "Send me the newsletter" }),
+    );
+    await user.click(screen.getByRole("button", { name: "Finish" }));
+
+    expect(onStepSubmit).toHaveBeenCalledTimes(2);
+    expect(onStepSubmit.mock.calls[0]).toEqual([
+      "profile",
+      { display_name: "Ada" },
+    ]);
+    expect(onComplete).toHaveBeenCalledTimes(1);
+    expect(onComplete.mock.calls[0]?.[0]).toEqual({
+      display_name: "Ada",
+      website: "https://example.com",
+      newsletter: true,
+    });
+    expect(await screen.findByText("You're all set")).toBeDefined();
+  });
+
+  test("restores drafts when navigating back", async () => {
+    const user = userEvent.setup();
+    render(<OnboardingBlock steps={STEPS} />);
+
+    await user.type(screen.getByLabelText("Display name"), "Ada");
+    await user.click(screen.getByRole("button", { name: "Continue" }));
+
+    const website = await screen.findByLabelText("Website");
+    await user.type(website, "https://example.com");
+    await user.click(screen.getByRole("button", { name: "Back" }));
+
+    expect(
+      ((await screen.findByLabelText("Display name")) as HTMLInputElement).value,
+    ).toBe("Ada");
+
+    await user.click(screen.getByRole("button", { name: "Continue" }));
+    expect(
+      ((await screen.findByLabelText("Website")) as HTMLInputElement).value,
+    ).toBe("https://example.com");
+  });
+
+  test("keeps the user on the step when onStepSubmit rejects", async () => {
+    const user = userEvent.setup();
+    render(
+      <OnboardingBlock
+        steps={STEPS}
+        onStepSubmit={async () => {
+          throw new Error("Saving your profile was rejected.");
+        }}
+      />,
+    );
+
+    await user.type(screen.getByLabelText("Display name"), "Ada");
+    await user.click(screen.getByRole("button", { name: "Continue" }));
+
+    expect((await screen.findByRole("alert")).textContent).toBe(
+      "Saving your profile was rejected.",
+    );
+    expect(screen.getByLabelText("Display name")).toBeDefined();
+  });
+
+  test("renders nothing after completion when the success screen is off", async () => {
+    const user = userEvent.setup();
+    const { container } = render(
+      <OnboardingBlock steps={[STEPS[0]!]} showCompleteScreen={false} />,
+    );
+
+    await user.type(screen.getByLabelText("Display name"), "Ada");
+    await user.click(screen.getByRole("button", { name: "Finish" }));
+
+    expect(container.innerHTML).toBe("");
+  });
+});

package/src/components/blocks/auth/__tests__/passkey-manager-block.test.tsx

@@ -0,0 +1,131 @@
+import { describe, expect, mock, test } from "bun:test";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+
+import {
+  PasskeyManagerBlock,
+  type PasskeyRecord,
+} from "../passkey-manager-block";
+
+const PASSKEYS: PasskeyRecord[] = [
+  { id: "pk-1", name: "MacBook", createdAt: "2026-01-05T00:00:00.000Z" },
+  { id: "pk-2", name: "iPhone", lastUsedAt: "2026-02-01T00:00:00.000Z" },
+];
+
+describe("PasskeyManagerBlock", () => {
+  test("explains itself when the device cannot use passkeys", () => {
+    render(<PasskeyManagerBlock available={false} passkeys={PASSKEYS} />);
+
+    expect(screen.getByText(/aren't available on this device/i)).toBeDefined();
+    expect(screen.queryByRole("list", { name: "Passkeys" })).toBeNull();
+  });
+
+  test("shows the loading row", () => {
+    render(<PasskeyManagerBlock loading />);
+    expect(screen.getByText("Loading passkeys…")).toBeDefined();
+  });
+
+  test("shows the empty state when nothing is registered", () => {
+    render(<PasskeyManagerBlock />);
+    expect(screen.getByText(/No passkeys registered yet/i)).toBeDefined();
+  });
+
+  test("lists every passkey", () => {
+    render(<PasskeyManagerBlock passkeys={PASSKEYS} />);
+
+    const list = screen.getByRole("list", { name: "Passkeys" });
+    expect(list.querySelectorAll("li")).toHaveLength(2);
+    expect(screen.getByText("MacBook")).toBeDefined();
+    expect(screen.getByText("iPhone")).toBeDefined();
+  });
+
+  test("registers a passkey through onRegister", async () => {
+    const user = userEvent.setup();
+    const onRegister = mock(async () => {});
+    render(<PasskeyManagerBlock onRegister={onRegister} />);
+
+    await user.click(screen.getByRole("button", { name: "Add a passkey" }));
+
+    expect(onRegister).toHaveBeenCalledTimes(1);
+  });
+
+  test("rejects a rename outside 1-120 characters without calling onRename", async () => {
+    const user = userEvent.setup();
+    const onRename = mock(async () => {});
+    render(<PasskeyManagerBlock passkeys={PASSKEYS} onRename={onRename} />);
+
+    await user.click(screen.getByRole("button", { name: "Rename MacBook" }));
+    const input = await screen.findByLabelText("Passkey name");
+    await user.clear(input);
+    await user.click(screen.getByRole("button", { name: "Save" }));
+
+    expect(
+      await screen.findByText("Name must be between 1 and 120 characters."),
+    ).toBeDefined();
+    expect(onRename).not.toHaveBeenCalled();
+  });
+
+  test("submits a trimmed rename", async () => {
+    const user = userEvent.setup();
+    const onRename = mock(async () => {});
+    render(<PasskeyManagerBlock passkeys={PASSKEYS} onRename={onRename} />);
+
+    await user.click(screen.getByRole("button", { name: "Rename MacBook" }));
+    const input = await screen.findByLabelText("Passkey name");
+    await user.clear(input);
+    await user.type(input, "  Work laptop  ");
+    await user.click(screen.getByRole("button", { name: "Save" }));
+
+    expect(onRename).toHaveBeenCalledWith("pk-1", "Work laptop");
+  });
+
+  test("deletes only after confirmation", async () => {
+    const user = userEvent.setup();
+    const onDelete = mock(async () => {});
+    render(<PasskeyManagerBlock passkeys={PASSKEYS} onDelete={onDelete} />);
+
+    await user.click(screen.getByRole("button", { name: "Delete MacBook" }));
+    expect(onDelete).not.toHaveBeenCalled();
+
+    await user.click(
+      await screen.findByRole("button", { name: "Delete passkey" }),
+    );
+    expect(onDelete).toHaveBeenCalledWith("pk-1");
+  });
+
+  test("warns before deleting the last remaining passkey", async () => {
+    const user = userEvent.setup();
+    render(<PasskeyManagerBlock passkeys={[PASSKEYS[0]!]} />);
+
+    await user.click(screen.getByRole("button", { name: "Delete MacBook" }));
+
+    expect(await screen.findByText(/This is your last passkey/i)).toBeDefined();
+  });
+
+  test("does not warn while other passkeys remain", async () => {
+    const user = userEvent.setup();
+    render(<PasskeyManagerBlock passkeys={PASSKEYS} />);
+
+    await user.click(screen.getByRole("button", { name: "Delete MacBook" }));
+    await screen.findByRole("button", { name: "Delete passkey" });
+
+    expect(screen.queryByText(/This is your last passkey/i)).toBeNull();
+  });
+
+  test("surfaces a failing action as an error", async () => {
+    const user = userEvent.setup();
+    render(
+      <PasskeyManagerBlock
+        onRegister={async () => {
+          throw new Error("Passkey registration is disabled.");
+        }}
+      />,
+    );
+
+    await user.click(screen.getByRole("button", { name: "Add a passkey" }));
+
+    expect((await screen.findByRole("alert")).textContent).toBe(
+      "Passkey registration is disabled.",
+    );
+  });
+});

package/src/components/blocks/auth/__tests__/passkey-sign-in-block.test.tsx

@@ -0,0 +1,59 @@
+import { describe, expect, mock, test } from "bun:test";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+
+import { PasskeySignInBlock } from "../passkey-sign-in-block";
+
+describe("PasskeySignInBlock", () => {
+  test("renders nothing when passkeys are unavailable", () => {
+    const { container } = render(<PasskeySignInBlock available={false} />);
+    expect(container.innerHTML).toBe("");
+  });
+
+  test("signs in through onSignIn", async () => {
+    const user = userEvent.setup();
+    const onSignIn = mock(async () => {});
+    render(<PasskeySignInBlock onSignIn={onSignIn} />);
+
+    await user.click(screen.getByRole("button", { name: /passkey/i }));
+
+    expect(onSignIn).toHaveBeenCalledTimes(1);
+    expect(screen.queryByRole("alert")).toBeNull();
+  });
+
+  test("treats a cancelled prompt as a silent return to idle", async () => {
+    const user = userEvent.setup();
+    render(<PasskeySignInBlock onSignIn={async () => ({ cancelled: true })} />);
+
+    await user.click(screen.getByRole("button", { name: /passkey/i }));
+
+    expect(screen.queryByRole("alert")).toBeNull();
+  });
+
+  test("shows the error and the fallback hint on failure", async () => {
+    const user = userEvent.setup();
+    render(
+      <PasskeySignInBlock
+        onSignIn={async () => {
+          throw new Error("No passkey found for this account.");
+        }}
+      />,
+    );
+
+    await user.click(screen.getByRole("button", { name: /passkey/i }));
+
+    expect((await screen.findByRole("alert")).textContent).toBe(
+      "No passkey found for this account.",
+    );
+    expect(
+      await screen.findByText(
+        "You can still sign in with your other methods below.",
+      ),
+    ).toBeDefined();
+  });
+
+  test("uses a custom label", () => {
+    render(<PasskeySignInBlock label="Use Face ID" />);
+    expect(screen.getByRole("button", { name: "Use Face ID" })).toBeDefined();
+  });
+});

package/src/components/blocks/auth/__tests__/signup-block.test.tsx

@@ -0,0 +1,176 @@
+import { describe, expect, mock, test } from "bun:test";
+import { render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import * as React from "react";
+
+import { SignupBlock } from "../signup-block";
+
+const STRONG = "Str0ngPassword";
+
+/** Fills every field, so only the terms checkbox stands between us and submit. */
+async function fillForm(user: ReturnType<typeof userEvent.setup>) {
+  await user.type(screen.getByLabelText("Name"), "Ada Researcher");
+  await user.type(screen.getByLabelText("Email"), "ada@corpora.local");
+  await user.type(await screen.findByLabelText("Password"), STRONG);
+}
+
+// Base UI renders a hidden native input beside the Checkbox root, so the box is
+// queried by role and read from aria-checked (see CLAUDE.md).
+const checkbox = () => screen.getByRole("checkbox");
+
+describe("SignupBlock terms checkbox", () => {
+  test("owns the box when uncontrolled", async () => {
+    const user = userEvent.setup();
+    render(<SignupBlock />);
+
+    expect(checkbox().getAttribute("aria-checked")).toBe("false");
+
+    await user.click(checkbox());
+    await waitFor(() =>
+      expect(checkbox().getAttribute("aria-checked")).toBe("true"),
+    );
+  });
+
+  test("starts from defaultTermsChecked", () => {
+    render(<SignupBlock defaultTermsChecked />);
+    expect(checkbox().getAttribute("aria-checked")).toBe("true");
+  });
+
+  test("reports changes through onTermsCheckedChange while uncontrolled", async () => {
+    const user = userEvent.setup();
+    const onChange = mock((checked: boolean) => checked);
+    render(<SignupBlock onTermsCheckedChange={onChange} />);
+
+    await user.click(checkbox());
+    expect(onChange).toHaveBeenCalledWith(true);
+  });
+
+  test("defers to the owner when controlled", async () => {
+    const user = userEvent.setup();
+    const onChange = mock((checked: boolean) => checked);
+    render(<SignupBlock termsChecked={false} onTermsCheckedChange={onChange} />);
+
+    await user.click(checkbox());
+
+    // The click is reported, but the box only moves if the owner says so.
+    expect(onChange).toHaveBeenCalledWith(true);
+    expect(checkbox().getAttribute("aria-checked")).toBe("false");
+  });
+
+  test("lets an outside action tick the box and unblock submit", async () => {
+    const user = userEvent.setup();
+    const onSubmit = mock(async () => {});
+
+    // Stands in for a consumer's terms dialog: an "I agree" action that ticks
+    // the block's checkbox from outside it.
+    function Host() {
+      const [accepted, setAccepted] = React.useState(false);
+      return (
+        <>
+          <button type="button" onClick={() => setAccepted(true)}>
+            I agree
+          </button>
+          <SignupBlock
+            termsChecked={accepted}
+            onTermsCheckedChange={setAccepted}
+            onSubmit={onSubmit}
+          />
+        </>
+      );
+    }
+    render(<Host />);
+
+    await fillForm(user);
+    await user.click(await screen.findByRole("button", { name: "I agree" }));
+    await waitFor(() =>
+      expect(checkbox().getAttribute("aria-checked")).toBe("true"),
+    );
+
+    await user.click(screen.getByRole("button", { name: "Create account" }));
+    await waitFor(() => expect(onSubmit).toHaveBeenCalled());
+  });
+
+  test("still blocks submission while the controlled box is unticked", async () => {
+    const user = userEvent.setup();
+    const onSubmit = mock(async () => {});
+    render(<SignupBlock termsChecked={false} onSubmit={onSubmit} />);
+
+    await fillForm(user);
+    await user.click(screen.getByRole("button", { name: "Create account" }));
+
+    expect(await screen.findByRole("alert")).toHaveProperty(
+      "textContent",
+      "Please accept the terms to continue.",
+    );
+    expect(onSubmit).not.toHaveBeenCalled();
+  });
+});
+
+describe("SignupBlock field labelling", () => {
+  test("names every field, including the revealed password", async () => {
+    const user = userEvent.setup();
+    render(<SignupBlock />);
+
+    expect(screen.getByLabelText("Name")).toBeDefined();
+    expect(screen.getByLabelText("Email")).toBeDefined();
+
+    // The password field only appears once the email validates.
+    await user.type(screen.getByLabelText("Email"), "ada@corpora.local");
+    expect(await screen.findByLabelText("Password")).toBeDefined();
+  });
+
+  test("gives each instance its own password id", async () => {
+    const user = userEvent.setup();
+    render(
+      <>
+        <SignupBlock showNameField={false} />
+        <SignupBlock showNameField={false} />
+      </>,
+    );
+
+    const emails = screen.getAllByLabelText("Email");
+    await user.type(emails[0], "ada@corpora.local");
+    await user.type(emails[1], "ben@corpora.local");
+
+    // Two blocks on one page must not collide on a hard-coded id, or the
+    // second label would point at the first block's input.
+    const passwords = await screen.findAllByLabelText("Password");
+    expect(passwords).toHaveLength(2);
+    expect(passwords[0].id).not.toBe(passwords[1].id);
+  });
+});
+
+// The terms link sits inside the consent <label>, and under happy-dom that
+// nesting computes an empty accessible name — so it is queried by text rather
+// than by role + name. It resolves normally in a browser.
+const termsLink = () => screen.getByText("terms");
+
+describe("SignupBlock termsComponent", () => {
+  test("renders the built-in terms link by default", async () => {
+    const user = userEvent.setup();
+    const onTerms = mock(() => {});
+    render(<SignupBlock onTerms={onTerms} />);
+
+    expect(termsLink().tagName).toBe("BUTTON");
+    await user.click(termsLink());
+    expect(onTerms).toHaveBeenCalled();
+  });
+
+  test("swaps the link for the consumer's own node", () => {
+    render(
+      <SignupBlock
+        termsComponent={<button type="button">read the terms</button>}
+      />,
+    );
+
+    expect(screen.getByText("read the terms")).toBeDefined();
+    expect(screen.queryByText("terms")).toBeNull();
+  });
+
+  test("keeps the consent label around the replacement", () => {
+    render(<SignupBlock termsComponent={<span>our terms of use</span>} />);
+
+    expect(screen.getByText(/I agree to the/)).toBeDefined();
+    expect(screen.getByRole("checkbox")).toBeDefined();
+  });
+});