@terpjs/react-core 0.1.0

package/src/LoginView.tsx

@@ -0,0 +1,203 @@
+import { useState } from "react";
+import type { CSSProperties, FormEvent } from "react";
+
+import { TerpMark } from "./icons";
+import { useAuth, useSso } from "./TerpProvider";
+import { useStrings } from "./uiText";
+import { Button } from "./ui/Button";
+import { Input } from "./ui/Input";
+import type { SsoProvider } from "./sso";
+
+const pageStyle: CSSProperties = {
+  minHeight: "100vh",
+  display: "grid",
+  placeItems: "center",
+  padding: "var(--space-6)",
+  background: "var(--color-neutral-50)",
+  fontFamily: "var(--font-family-sans)",
+  color: "var(--color-neutral-900)",
+};
+
+const cardStyle: CSSProperties = {
+  width: "100%",
+  maxWidth: "24rem",
+  display: "grid",
+  gap: "var(--space-4)",
+  padding: "var(--space-6)",
+  background: "var(--color-neutral-0)",
+  border: "1px solid var(--color-neutral-200)",
+  borderRadius: "var(--radius-lg)",
+  boxShadow: "var(--shadow-md)",
+};
+
+const brandStyle: CSSProperties = {
+  display: "flex",
+  alignItems: "center",
+  gap: "var(--space-2)",
+  color: "var(--color-neutral-900)",
+};
+
+const brandTitleStyle: CSSProperties = {
+  margin: 0,
+  fontSize: "var(--font-size-xl)",
+  fontWeight: "var(--font-weight-bold)" as CSSProperties["fontWeight"],
+  letterSpacing: 0,
+};
+
+const formStyle: CSSProperties = { display: "grid", gap: "var(--space-3)" };
+
+const fullWidthStyle: CSSProperties = { width: "100%" };
+
+const separatorStyle: CSSProperties = {
+  display: "flex",
+  alignItems: "center",
+  gap: "var(--space-2)",
+  color: "var(--color-neutral-500)",
+  fontSize: "var(--font-size-xs)",
+  textTransform: "uppercase",
+  letterSpacing: "0.06em",
+};
+
+const separatorRuleStyle: CSSProperties = {
+  flex: 1,
+  borderTop: "1px solid var(--color-neutral-200)",
+};
+
+const errorStyle: CSSProperties = {
+  margin: 0,
+  color: "var(--color-status-danger)",
+  fontSize: "var(--font-size-sm)",
+};
+
+export interface LoginViewProps {
+  /**
+   * SSO providers to offer alongside the credentials form (ADR 0058). Each renders a
+   * "Continue with {label}" button that opens the provider flow through the session's
+   * SSO seam; the redirect/callback completion is handled by `TerpProvider`.
+   */
+  ssoProviders?: readonly SsoProvider[];
+  /**
+   * Development-only convenience: when set, the form offers a button that fills these
+   * credentials (typically the seeded dev admin). Gate it on the build, e.g.
+   * `import.meta.env.DEV ? { email, password } : undefined`, so the credentials are
+   * statically stripped from production bundles — never pass real secrets.
+   */
+  devCredentials?: DevCredentials;
+}
+
+/** The credentials the dev-only fill button enters — see {@link LoginViewProps.devCredentials}. */
+export interface DevCredentials {
+  email: string;
+  password: string;
+}
+
+/**
+ * The default signed-out screen: collects credentials and calls the auth session. Used by
+ * {@link renderTerpApp}/`RequireAuth` unless an app supplies its own login view. Pass
+ * {@link LoginViewProps.ssoProviders} to add SSO provider buttons under the form.
+ */
+export function LoginView({ ssoProviders = [], devCredentials }: LoginViewProps = {}) {
+  const auth = useAuth();
+  const sso = useSso();
+  const strings = useStrings();
+  const [email, setEmail] = useState("");
+  const [password, setPassword] = useState("");
+  const [error, setError] = useState<string | null>(null);
+  const [busy, setBusy] = useState(false);
+
+  async function onSubmit(event: FormEvent) {
+    event.preventDefault();
+    setError(null);
+    setBusy(true);
+    try {
+      await auth.login({ email, password });
+    } catch {
+      setError(strings.signInFailed);
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  async function onSso(provider: SsoProvider) {
+    setError(null);
+    setBusy(true);
+    try {
+      // Navigates away on success; only a failed authorize fetch reaches the catch.
+      await sso.begin(provider.name);
+    } catch {
+      setError(strings.ssoFailed);
+      setBusy(false);
+    }
+  }
+
+  const ssoError = sso.error !== null && sso.error !== undefined ? strings.ssoFailed : null;
+
+  return (
+    <main style={pageStyle}>
+      <div style={cardStyle}>
+        <div style={brandStyle}>
+          <TerpMark />
+          <h1 style={brandTitleStyle}>{strings.signIn}</h1>
+        </div>
+        <form style={formStyle} onSubmit={onSubmit}>
+          <Input
+            type="email"
+            placeholder={strings.email}
+            value={email}
+            onChange={(event) => setEmail(event.target.value)}
+            required
+          />
+          <Input
+            type="password"
+            placeholder={strings.password}
+            value={password}
+            onChange={(event) => setPassword(event.target.value)}
+            required
+          />
+          <Button type="submit" disabled={busy} style={fullWidthStyle}>
+            {busy ? strings.signingIn : strings.signIn}
+          </Button>
+          {devCredentials ? (
+            <Button
+              type="button"
+              variant="secondary"
+              disabled={busy}
+              style={fullWidthStyle}
+              onClick={() => {
+                setEmail(devCredentials.email);
+                setPassword(devCredentials.password);
+                setError(null);
+              }}
+            >
+              {strings.fillDevCredentials}
+            </Button>
+          ) : null}
+        </form>
+        {ssoProviders.length > 0 ? (
+          <>
+            <div style={separatorStyle} aria-hidden="true">
+              <span style={separatorRuleStyle} />
+              <span>{strings.orSeparator}</span>
+              <span style={separatorRuleStyle} />
+            </div>
+            <div style={formStyle}>
+              {ssoProviders.map((provider) => (
+                <Button
+                  key={provider.name}
+                  type="button"
+                  variant="secondary"
+                  disabled={busy}
+                  style={fullWidthStyle}
+                  onClick={() => void onSso(provider)}
+                >
+                  {`${strings.continueWith} ${provider.label ?? provider.name}`}
+                </Button>
+              ))}
+            </div>
+          </>
+        ) : null}
+        {error ?? ssoError ? <p style={errorStyle}>{error ?? ssoError}</p> : null}
+      </div>
+    </main>
+  );
+}

package/src/ModuleNav.test.tsx

@@ -0,0 +1,96 @@
+// @vitest-environment jsdom
+import {
+  Outlet,
+  RouterProvider,
+  createMemoryHistory,
+  createRootRoute,
+  createRoute,
+  createRouter,
+} from "@tanstack/react-router";
+import { cleanup, render, screen, waitFor } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+
+import { ModuleNav } from "./ModuleNav";
+import { UiTextProvider } from "./uiText";
+
+afterEach(cleanup);
+
+function renderWithRouter(initialPath: string) {
+  const rootRoute = createRootRoute({
+    component: () => (
+      <>
+        <ModuleNav
+          items={[
+            { label: "Overview", to: "/tickets" },
+            { label: "Projects", to: "/tickets/projects" },
+          ]}
+        />
+        <Outlet />
+      </>
+    ),
+  });
+  const overviewRoute = createRoute({
+    getParentRoute: () => rootRoute,
+    path: "/tickets",
+    component: () => <p>Overview page</p>,
+  });
+  const projectsRoute = createRoute({
+    getParentRoute: () => rootRoute,
+    path: "/tickets/projects",
+    component: () => <p>Projects page</p>,
+  });
+  const router = createRouter({
+    routeTree: rootRoute.addChildren([overviewRoute, projectsRoute]),
+    history: createMemoryHistory({ initialEntries: [initialPath] }),
+  });
+
+  render(<RouterProvider router={router} />);
+}
+
+describe("ModuleNav", () => {
+  it("renders exact-route links and marks the active route", async () => {
+    renderWithRouter("/tickets/projects");
+
+    await waitFor(() =>
+      expect(screen.getByRole("navigation", { name: "Module navigation" })).toBeInTheDocument(),
+    );
+    expect(screen.getByRole("link", { name: "Overview" })).toHaveAttribute("href", "/tickets");
+    expect(screen.getByRole("link", { name: "Projects" })).toHaveAttribute(
+      "aria-current",
+      "page",
+    );
+    expect(screen.getByRole("link", { name: "Overview" })).not.toHaveAttribute("aria-current");
+  });
+
+  it("returns nothing for an empty tab list", () => {
+    const rootRoute = createRootRoute({ component: () => <ModuleNav items={[]} /> });
+    const router = createRouter({
+      routeTree: rootRoute,
+      history: createMemoryHistory({ initialEntries: ["/"] }),
+    });
+
+    const { container } = render(<RouterProvider router={router} />);
+
+    expect(container).toBeEmptyDOMElement();
+  });
+
+  it("localises the navigation landmark label", async () => {
+    const rootRoute = createRootRoute({
+      component: () => (
+        <UiTextProvider strings={{ moduleNavigationLabel: "Module navigatie" }}>
+          <ModuleNav items={[{ label: "Overzicht", to: "/" }]} />
+        </UiTextProvider>
+      ),
+    });
+    const router = createRouter({
+      routeTree: rootRoute,
+      history: createMemoryHistory({ initialEntries: ["/"] }),
+    });
+
+    render(<RouterProvider router={router} />);
+
+    await waitFor(() =>
+      expect(screen.getByRole("navigation", { name: "Module navigatie" })).toBeInTheDocument(),
+    );
+  });
+});

package/src/ModuleNav.tsx

@@ -0,0 +1,88 @@
+import { Link, useRouterState } from "@tanstack/react-router";
+import type { CSSProperties } from "react";
+
+import { useStrings, useUiText } from "./uiText";
+import type { UiText } from "./uiText";
+
+export interface ModuleNavTab {
+  /** Display label. */
+  label: UiText;
+  /** Router path for an exact sub-page route. */
+  to: string;
+}
+
+export interface ModuleNavProps {
+  items: readonly ModuleNavTab[];
+  /** Accessible label for the secondary navigation landmark. */
+  ariaLabel?: UiText;
+}
+
+const navStyle: CSSProperties = {
+  borderBottom: "1px solid var(--color-neutral-200)",
+};
+
+const listStyle: CSSProperties = {
+  listStyle: "none",
+  margin: 0,
+  padding: 0,
+  display: "flex",
+  flexWrap: "wrap",
+  gap: "var(--space-3)",
+};
+
+const linkStyle: CSSProperties = {
+  display: "inline-flex",
+  alignItems: "center",
+  padding: "var(--space-2) 0",
+  color: "var(--color-neutral-600)",
+  textDecoration: "none",
+  borderBottom: "2px solid transparent",
+};
+
+const activeLinkStyle: CSSProperties = {
+  color: "var(--color-neutral-900)",
+  borderBottomColor: "var(--color-brand-primary)",
+};
+
+/**
+ * Secondary horizontal navigation for intra-module sub-pages.
+ *
+ * Each tab links to a real TanStack Router route so sub-pages keep their own URL,
+ * lazy loading, and back-button behavior. The active tab is matched exactly.
+ */
+export function ModuleNav({ items, ariaLabel }: ModuleNavProps) {
+  const strings = useStrings();
+  const resolve = useUiText();
+  const pathname = useRouterState({ select: (state) => state.location.pathname });
+
+  if (items.length === 0) {
+    return null;
+  }
+
+  return (
+    <nav
+      aria-label={resolve(ariaLabel ?? strings.moduleNavigationLabel)}
+      data-terp="module-nav"
+      style={navStyle}
+    >
+      <ul style={listStyle}>
+        {items.map((item) => {
+          const label = resolve(item.label);
+          const isActive = pathname === item.to;
+          return (
+            <li key={item.to}>
+              <Link
+                to={item.to}
+                activeOptions={{ exact: true }}
+                aria-current={isActive ? "page" : undefined}
+                style={{ ...linkStyle, ...(isActive ? activeLinkStyle : undefined) }}
+              >
+                {label}
+              </Link>
+            </li>
+          );
+        })}
+      </ul>
+    </nav>
+  );
+}

package/src/OverviewPage.tsx

@@ -0,0 +1,26 @@
+import type { ReactNode } from "react";
+
+import type { BreadcrumbItem } from "./Breadcrumbs";
+import { Page } from "./Page";
+import type { PageProps } from "./Page";
+import { LayoutSlotContext } from "./layoutContract";
+
+export interface OverviewPageProps extends Omit<PageProps, "breadcrumbs"> {
+  /** Optional parent layers for an overview nested below a hub or another overview. */
+  parents?: readonly (BreadcrumbItem & { to: string })[];
+}
+
+/**
+ * The overview (level-2) page archetype: a module's top-level listing screen. It is a `Page`
+ * without a redundant current-page-only crumb; detail pages under it link back here — so every
+ * module's overview is constructed the same. Compose the body from `ResourceList` (or any listing UI).
+ * With a layout contract active (ADR 0079), the body slot accepts only the contract's
+ * listing components (e.g. `DataView` / `ResourceList`) — refused fail closed otherwise.
+ */
+export function OverviewPage({ parents, ...page }: OverviewPageProps): ReactNode {
+  return (
+    <LayoutSlotContext.Provider value="OverviewPage">
+      <Page breadcrumbs={parents} {...page} />
+    </LayoutSlotContext.Provider>
+  );
+}

package/src/Page.test.tsx

@@ -0,0 +1,147 @@
+// @vitest-environment jsdom
+import { cleanup, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+
+import { DetailPage } from "./DetailPage";
+import { OverviewPage } from "./OverviewPage";
+import { Page } from "./Page";
+import { ApiError } from "./unwrap";
+import { Button } from "./ui/Button";
+
+afterEach(cleanup);
+
+describe("Page", () => {
+  it("renders the h1 title, the actions slot, and the body", () => {
+    render(
+      <Page title="Tasks" actions={<Button>New</Button>}>
+        <p>body</p>
+      </Page>,
+    );
+
+    expect(screen.getByRole("heading", { level: 1, name: "Tasks" })).toBeInTheDocument();
+    expect(screen.getByRole("heading", { level: 1, name: "Tasks" })).toHaveStyle({
+      fontSize: "var(--font-size-lg)",
+      letterSpacing: "0",
+    });
+    expect(screen.getByRole("button", { name: "New" })).toBeInTheDocument();
+    const title = screen.getByRole("heading", { level: 1, name: "Tasks" });
+    const action = screen.getByRole("button", { name: "New" });
+    expect(title.compareDocumentPosition(action) & Node.DOCUMENT_POSITION_FOLLOWING).toBeTruthy();
+    expect(screen.getByText("body")).toBeInTheDocument();
+  });
+
+  it("does not repeat a root page title as a current-page-only breadcrumb", () => {
+    render(<Page title="Tasks">x</Page>);
+
+    expect(screen.queryByRole("navigation", { name: "Breadcrumb" })).not.toBeInTheDocument();
+    expect(screen.getAllByText("Tasks")).toHaveLength(1);
+  });
+
+  it("appends its own crumb to the supplied trail", () => {
+    render(
+      <Page title="Fix the door" breadcrumbs={[{ label: "Tasks", to: "/tasks" }]}>
+        x
+      </Page>,
+    );
+
+    expect(screen.getByRole("navigation", { name: "Breadcrumb" })).toBeInTheDocument();
+    expect(screen.getByRole("link", { name: "Tasks" })).toHaveAttribute("href", "/tasks");
+    expect(screen.getByText("Fix the door", { selector: "span" })).toHaveAttribute(
+      "aria-current",
+      "page",
+    );
+  });
+
+  it("replaces the body with the loading state while keeping the header", () => {
+    render(
+      <Page title="Tasks" isLoading>
+        <p>body</p>
+      </Page>,
+    );
+
+    expect(screen.getByRole("heading", { level: 1, name: "Tasks" })).toBeInTheDocument();
+    expect(screen.getByText("Loading...")).toBeInTheDocument();
+    expect(screen.queryByText("body")).not.toBeInTheDocument();
+  });
+
+  it("surfaces an error instead of the body, winning over isLoading", () => {
+    render(
+      <Page title="Tasks" isLoading error="Not found">
+        <p>body</p>
+      </Page>,
+    );
+
+    const alert = screen.getByRole("alert");
+    expect(alert).toHaveTextContent("Something went wrong.");
+    expect(alert).toHaveTextContent("Not found");
+    expect(screen.queryByText("Loading...")).not.toBeInTheDocument();
+    expect(screen.queryByText("body")).not.toBeInTheDocument();
+  });
+
+  it("maps a caught ApiError's stable code to the registered copy", () => {
+    render(
+      <Page
+        title="Tasks"
+        error={new ApiError("row was updated concurrently", { code: "stale_data", status: 409 })}
+      >
+        <p>body</p>
+      </Page>,
+    );
+
+    expect(screen.getByRole("alert")).toHaveTextContent(
+      "This item was changed by someone else. Refresh and try again.",
+    );
+    expect(screen.queryByText("row was updated concurrently")).not.toBeInTheDocument();
+  });
+
+  it("renders the custom loading and error slots when supplied", () => {
+    const { rerender } = render(
+      <Page title="Tasks" isLoading loadingState={<p>spinner</p>}>
+        body
+      </Page>,
+    );
+    expect(screen.getByText("spinner")).toBeInTheDocument();
+
+    rerender(
+      <Page title="Tasks" error="boom" errorState={<p>custom error</p>}>
+        body
+      </Page>,
+    );
+    expect(screen.getByText("custom error")).toBeInTheDocument();
+    expect(screen.queryByText("boom")).not.toBeInTheDocument();
+  });
+});
+
+describe("OverviewPage", () => {
+  it("is a root-level Page with one title and no redundant breadcrumb", () => {
+    render(<OverviewPage title="Tasks">list</OverviewPage>);
+
+    expect(screen.getByRole("heading", { level: 1, name: "Tasks" })).toBeInTheDocument();
+    expect(screen.queryByRole("navigation", { name: "Breadcrumb" })).not.toBeInTheDocument();
+    expect(screen.getAllByText("Tasks")).toHaveLength(1);
+    expect(screen.getByText("list")).toBeInTheDocument();
+  });
+});
+
+describe("DetailPage", () => {
+  it("always breadcrumbs back to its parents, ending on the record's crumb", () => {
+    render(
+      <DetailPage
+        title="Fix the door"
+        parents={[{ label: "Tasks", to: "/tasks" }]}
+        renderLink={(item) => <a href={item.to}>{item.label}</a>}
+      >
+        detail
+      </DetailPage>,
+    );
+
+    expect(screen.getByRole("navigation", { name: "Breadcrumb" })).toBeInTheDocument();
+    expect(screen.getByRole("link", { name: "Tasks" })).toHaveAttribute("href", "/tasks");
+    expect(screen.getByRole("heading", { level: 1, name: "Fix the door" })).toBeInTheDocument();
+    expect(screen.getByText("Fix the door", { selector: "span" })).toHaveAttribute(
+      "aria-current",
+      "page",
+    );
+    expect(screen.getByText("detail")).toBeInTheDocument();
+  });
+});