@terpjs/react-core 0.1.0

package/src/Page.tsx

@@ -0,0 +1,158 @@
+import type { CSSProperties, ReactNode } from "react";
+import { useContext, useEffect, useRef, useState } from "react";
+
+import { Breadcrumbs } from "./Breadcrumbs";
+import type { BreadcrumbItem, RenderBreadcrumbLink } from "./Breadcrumbs";
+import { ErrorState } from "./ErrorState";
+import {
+  LayoutSlotContext,
+  useLayoutContract,
+  verifySlotChildren,
+} from "./layoutContract";
+import { LoadingState } from "./LoadingState";
+import { usePageMarker } from "./pageMarker";
+import { useUiText } from "./uiText";
+import type { UiText } from "./uiText";
+
+export interface PageProps {
+  /** The page heading (rendered as the single `h1`). */
+  title: UiText;
+  /** Ancestor breadcrumb trail, outermost first; the current page's crumb is appended automatically. */
+  breadcrumbs?: readonly BreadcrumbItem[];
+  /** Link renderer for ancestor crumbs; pass the stack's `Link` (see {@link Breadcrumbs}). */
+  renderLink?: RenderBreadcrumbLink;
+  /** Optional page-level actions, rendered on the heading row (e.g. a primary `Button`). */
+  actions?: ReactNode;
+  /** Show the loading state instead of the body (the header stays for orientation). */
+  isLoading?: boolean;
+  /** Loading slot; defaults to the standard {@link LoadingState} spinner block. */
+  loadingState?: ReactNode;
+  /**
+   * The failure to surface instead of the body (e.g. the record 404'd or access was revoked).
+   * Accepts the caught error itself (`ApiError`, `Error`, raw envelope) or a plain message;
+   * pass `useResource`'s `cause ?? error` so the stable `code` reaches the code→copy map.
+   * Takes precedence over `isLoading`, so a failed query never gets stuck on a spinner.
+   */
+  error?: unknown;
+  /** Error slot; defaults to {@link ErrorState} rendering `error` through the error-code map. */
+  errorState?: ReactNode;
+  /** The page body. */
+  children: ReactNode;
+}
+
+const pageStyle: CSSProperties = {
+  display: "grid",
+  gridTemplateColumns: "minmax(0, 1fr)",
+  gap: "var(--space-4)",
+  alignContent: "start",
+  minWidth: 0,
+};
+
+const headerStyle: CSSProperties = { display: "grid", gap: "var(--space-2)" };
+
+const breadcrumbRowStyle: CSSProperties = {
+  display: "flex",
+  alignItems: "center",
+  minHeight: "2rem",
+};
+
+const titleRowStyle: CSSProperties = {
+  display: "flex",
+  alignItems: "center",
+  justifyContent: "space-between",
+  gap: "var(--space-3)",
+  flexWrap: "wrap",
+};
+
+const titleStyle: CSSProperties = {
+  margin: 0,
+  fontSize: "var(--font-size-lg)",
+  fontWeight: "var(--font-weight-semibold)" as CSSProperties["fontWeight"],
+  letterSpacing: 0,
+  color: "var(--color-neutral-900)",
+  lineHeight: 1.3,
+};
+
+/**
+ * The base content-page frame: every routed view is constructed the same way — one
+ * header holding the breadcrumb trail (when there is a path back up through the
+ * layers), then one row with the single `h1` title on the left and the page's
+ * `actions` slot on the right, then the body. A root page omits the redundant
+ * current-page-only crumb. Title-first DOM order keeps narrow layouts natural.
+ * `OverviewPage` and `DetailPage` specialise it for the standard overview -> detail
+ * layering; a bespoke screen composes `Page` directly.
+ *
+ * The frame also owns the async body states: `error` (which wins, so a failed
+ * query never hides behind a spinner) then `isLoading` replace the body while the
+ * header stays put, so the user keeps their place in the layers.
+ */
+export function Page({
+  title,
+  breadcrumbs,
+  renderLink,
+  actions,
+  isLoading,
+  loadingState,
+  error,
+  errorState,
+  children,
+}: PageProps) {
+  const resolve = useUiText();
+  // Mark the routed view as archetype-framed (the runtime half of the page-archetype control).
+  usePageMarker()?.();
+  // The runtime half of the slot-typed layout contract control (ADR 0079): when the app
+  // opted into a contract and the enclosing archetype declared a governed body slot
+  // (OverviewPage / DetailPage), the rendered body's DOM children must each carry an
+  // allowed component's data-terp marker — verified one macrotask after mount (like the
+  // page-archetype check) and refused fail closed with the lint rule's directive message.
+  const contract = useLayoutContract();
+  const slotOwner = useContext(LayoutSlotContext);
+  const articleRef = useRef<HTMLElement>(null);
+  const [slotViolation, setSlotViolation] = useState<string | null>(null);
+  const showsBody = (error === null || error === undefined) && !isLoading;
+  useEffect(() => {
+    if (contract === null || slotOwner === null || !showsBody) {
+      return;
+    }
+    const timer = setTimeout(() => {
+      const article = articleRef.current;
+      if (article === null) {
+        return;
+      }
+      const body = [...article.children].filter((child) => child.tagName !== "HEADER");
+      setSlotViolation(verifySlotChildren(contract, slotOwner, body));
+    }, 0);
+    return () => clearTimeout(timer);
+  });
+  if (slotViolation !== null) {
+    throw new Error(slotViolation);
+  }
+  const hasAncestors = breadcrumbs !== undefined && breadcrumbs.length > 0;
+  const trail: BreadcrumbItem[] = hasAncestors ? [...breadcrumbs, { label: title }] : [];
+  const body =
+    error !== null && error !== undefined ? (
+      (errorState ?? <ErrorState error={error} />)
+    ) : isLoading ? (
+      (loadingState ?? <LoadingState />)
+    ) : (
+      children
+    );
+  return (
+    <article ref={articleRef} style={pageStyle}>
+      <header style={headerStyle}>
+        {hasAncestors && (
+          <div style={breadcrumbRowStyle}>
+            <Breadcrumbs items={trail} renderLink={renderLink} />
+          </div>
+        )}
+        <div style={titleRowStyle}>
+          <h1 style={titleStyle}>{resolve(title)}</h1>
+          {actions}
+        </div>
+      </header>
+      {/* Reset the slot for the body's own subtree, so nested content is never judged
+          by an ancestor archetype's slot. */}
+      <LayoutSlotContext.Provider value={null}>{body}</LayoutSlotContext.Provider>
+    </article>
+  );
+}

package/src/PageActions.test.tsx

@@ -0,0 +1,104 @@
+// @vitest-environment jsdom
+import { cleanup, fireEvent, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { PageActions } from "./PageActions";
+import { Button } from "./ui/Button";
+import { UiTextProvider } from "./uiText";
+
+afterEach(cleanup);
+
+describe("PageActions", () => {
+  it("returns no wrapper when no actions are supplied", () => {
+    const { container } = render(<PageActions />);
+
+    expect(container).toBeEmptyDOMElement();
+  });
+
+  it("orders overflow, secondary, then primary actions", () => {
+    render(
+      <PageActions
+        overflow={[{ label: "Archive", onSelect: () => {} }]}
+        secondary={<Button variant="secondary">Filter</Button>}
+        primary={<Button>Save</Button>}
+      />,
+    );
+
+    expect(screen.getAllByRole("button").map((button) => button.textContent)).toEqual([
+      "⋯",
+      "Filter",
+      "Save",
+    ]);
+  });
+
+  it("opens overflow actions and closes after selecting one, restoring trigger focus", () => {
+    const onSelect = vi.fn();
+    render(<PageActions overflow={[{ label: "Delete", variant: "destructive", onSelect }]} />);
+
+    fireEvent.click(screen.getByRole("button", { name: "More actions" }));
+    fireEvent.click(screen.getByRole("menuitem", { name: "Delete" }));
+
+    expect(onSelect).toHaveBeenCalledOnce();
+    expect(screen.queryByRole("menu")).not.toBeInTheDocument();
+    expect(screen.getByRole("button", { name: "More actions" })).toHaveFocus();
+  });
+
+  it("moves focus into the menu on open and roams items with arrow keys", () => {
+    render(
+      <PageActions
+        overflow={[
+          { label: "Archive", onSelect: () => {} },
+          { label: "Duplicate", onSelect: () => {}, disabled: true },
+          { label: "Delete", onSelect: () => {} },
+        ]}
+      />,
+    );
+
+    fireEvent.click(screen.getByRole("button", { name: "More actions" }));
+    const menu = screen.getByRole("menu");
+    expect(screen.getByRole("menuitem", { name: "Archive" })).toHaveFocus();
+
+    fireEvent.keyDown(menu, { key: "ArrowDown" });
+    expect(screen.getByRole("menuitem", { name: "Delete" })).toHaveFocus();
+    fireEvent.keyDown(menu, { key: "ArrowDown" });
+    expect(screen.getByRole("menuitem", { name: "Archive" })).toHaveFocus();
+    fireEvent.keyDown(menu, { key: "ArrowUp" });
+    expect(screen.getByRole("menuitem", { name: "Delete" })).toHaveFocus();
+    fireEvent.keyDown(menu, { key: "Home" });
+    expect(screen.getByRole("menuitem", { name: "Archive" })).toHaveFocus();
+    fireEvent.keyDown(menu, { key: "End" });
+    expect(screen.getByRole("menuitem", { name: "Delete" })).toHaveFocus();
+  });
+
+  it("closes on Escape (restoring trigger focus) and on outside click", () => {
+    render(<PageActions overflow={[{ label: "Archive", onSelect: () => {} }]} />);
+
+    fireEvent.click(screen.getByRole("button", { name: "More actions" }));
+    fireEvent.keyDown(screen.getByRole("menu"), { key: "Escape" });
+    expect(screen.queryByRole("menu")).not.toBeInTheDocument();
+    expect(screen.getByRole("button", { name: "More actions" })).toHaveFocus();
+
+    fireEvent.click(screen.getByRole("button", { name: "More actions" }));
+    expect(screen.getByRole("menu")).toBeInTheDocument();
+    fireEvent.pointerDown(document.body);
+    expect(screen.queryByRole("menu")).not.toBeInTheDocument();
+  });
+
+  it("closes when tabbing away from the menu", () => {
+    render(<PageActions overflow={[{ label: "Archive", onSelect: () => {} }]} />);
+
+    fireEvent.click(screen.getByRole("button", { name: "More actions" }));
+    fireEvent.keyDown(screen.getByRole("menu"), { key: "Tab" });
+    expect(screen.queryByRole("menu")).not.toBeInTheDocument();
+  });
+
+  it("localises the overflow trigger label", () => {
+    render(
+      <UiTextProvider strings={{ moreActions: "Meer acties" }}>
+        <PageActions overflow={[{ label: "Archiveren", onSelect: () => {} }]} />
+      </UiTextProvider>,
+    );
+
+    expect(screen.getByRole("button", { name: "Meer acties" })).toBeInTheDocument();
+  });
+});

package/src/PageActions.tsx

@@ -0,0 +1,72 @@
+import type { CSSProperties, ReactNode } from "react";
+
+import { Menu, MenuItem } from "./ui/Menu";
+import { useStrings } from "./uiText";
+import type { UiText } from "./uiText";
+
+export interface OverflowAction {
+  /** Display label for the menu item. */
+  label: UiText;
+  /** Optional leading icon or glyph. */
+  icon?: ReactNode;
+  onSelect: () => void;
+  /** Destructive actions are shown in the danger colour inside the overflow menu. */
+  variant?: "default" | "destructive";
+  disabled?: boolean;
+}
+
+export interface PageActionsProps {
+  /** The single most important call-to-action, supplied by the page as a styled element. */
+  primary?: ReactNode;
+  /** Supporting action(s), supplied by the page as styled element(s). */
+  secondary?: ReactNode;
+  /** Rare or destructive actions, kept out of the primary click path. */
+  overflow?: readonly OverflowAction[];
+  className?: string;
+}
+
+const clusterStyle: CSSProperties = {
+  display: "flex",
+  flexWrap: "wrap",
+  alignItems: "center",
+  justifyContent: "flex-end",
+  gap: "var(--space-2)",
+};
+
+/** Standard right-aligned action cluster for page headers. */
+export function PageActions({ primary, secondary, overflow, className }: PageActionsProps) {
+  const strings = useStrings();
+  const hasOverflow = overflow !== undefined && overflow.length > 0;
+
+  if (primary === undefined && secondary === undefined && !hasOverflow) {
+    return null;
+  }
+
+  return (
+    <div className={className} style={clusterStyle}>
+      {hasOverflow && (
+        <Menu trigger="⋯" triggerLabel={strings.moreActions}>
+          {({ close }) => (
+            <>
+              {overflow.map((action) => (
+                <MenuItem
+                  key={typeof action.label === "string" ? action.label : action.label.id}
+                  label={action.label}
+                  icon={action.icon}
+                  destructive={action.variant === "destructive"}
+                  disabled={action.disabled}
+                  onSelect={() => {
+                    action.onSelect();
+                    close(true);
+                  }}
+                />
+              ))}
+            </>
+          )}
+        </Menu>
+      )}
+      {secondary}
+      {primary}
+    </div>
+  );
+}

package/src/ProfileView.test.tsx

@@ -0,0 +1,112 @@
+// @vitest-environment jsdom
+import { cleanup, fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { useEffect } from "react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { ProfileView } from "./ProfileView";
+import { TerpProvider, useAuth } from "./TerpProvider";
+import { LOCALE_EN, LOCALE_NL, LocaleProvider } from "./locale";
+import { ThemeProvider } from "./theme";
+
+function jsonResponse(body: unknown): Response {
+  return new Response(JSON.stringify(body), {
+    status: 200,
+    headers: { "content-type": "application/json" },
+  });
+}
+
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+  window.localStorage.clear();
+  document.documentElement.removeAttribute("data-theme");
+});
+
+function LogInOnMount() {
+  const auth = useAuth();
+  useEffect(() => {
+    void auth.login({ email: "jane.doe@example.com", password: "pw" });
+  }, []);
+  return null;
+}
+
+function stubAuthFetch() {
+  const fetchMock = vi.fn<typeof fetch>(async (input) => {
+    const url = (input as Request).url;
+    if (url.endsWith("/api/v1/auth/login")) {
+      return jsonResponse({ access_token: "token", token_type: "bearer" });
+    }
+    if (url.endsWith("/api/v1/auth/logout")) {
+      return new Response(null, { status: 204 });
+    }
+    return jsonResponse({
+      id: "u1",
+      email: "jane.doe@example.com",
+      role_rank: 20,
+      role_name: "editor",
+    });
+  });
+  vi.stubGlobal("fetch", fetchMock);
+  return fetchMock;
+}
+
+describe("ProfileView", () => {
+  it("shows the identity, the preference controls and sign-out, framed by a Page", async () => {
+    const fetchMock = stubAuthFetch();
+    render(
+      <ThemeProvider>
+        <LocaleProvider locales={{ en: LOCALE_EN, nl: LOCALE_NL }}>
+          <TerpProvider baseUrl="https://api.test">
+            <LogInOnMount />
+            <ProfileView />
+          </TerpProvider>
+        </LocaleProvider>
+      </ThemeProvider>,
+    );
+
+    await waitFor(() =>
+      expect(screen.getByRole("heading", { level: 1, name: "Profile" })).toBeInTheDocument(),
+    );
+    expect(screen.getAllByText("jane.doe@example.com").length).toBeGreaterThanOrEqual(1);
+    expect(screen.getByText("editor (20)")).toBeInTheDocument();
+    // The stacked preference controls live here (settings surface).
+    expect(screen.getByLabelText("Theme")).toBeInTheDocument();
+    expect(screen.getByLabelText("Language")).toBeInTheDocument();
+
+    fireEvent.click(screen.getByRole("button", { name: "Sign out" }));
+    await waitFor(() =>
+      expect(
+        fetchMock.mock.calls.some(([input]) =>
+          (input as Request).url.endsWith("/api/v1/auth/logout"),
+        ),
+      ).toBe(true),
+    );
+  });
+
+  it("renders nothing while signed out", () => {
+    stubAuthFetch();
+    render(
+      <TerpProvider baseUrl="https://api.test">
+        <ProfileView />
+      </TerpProvider>,
+    );
+    expect(screen.queryByRole("heading", { name: "Profile" })).not.toBeInTheDocument();
+  });
+
+  it("follows the active locale (Dutch out of the box)", async () => {
+    stubAuthFetch();
+    window.localStorage.setItem("terp.locale", "nl");
+    render(
+      <LocaleProvider locales={{ en: LOCALE_EN, nl: LOCALE_NL }}>
+        <TerpProvider baseUrl="https://api.test">
+          <LogInOnMount />
+          <ProfileView />
+        </TerpProvider>
+      </LocaleProvider>,
+    );
+    await waitFor(() =>
+      expect(screen.getByRole("heading", { level: 1, name: "Profiel" })).toBeInTheDocument(),
+    );
+    expect(screen.getByRole("button", { name: "Uitloggen" })).toBeInTheDocument();
+  });
+});

package/src/ProfileView.tsx

@@ -0,0 +1,84 @@
+import type { CSSProperties } from "react";
+
+import { Page } from "./Page";
+import { useAuth } from "./TerpProvider";
+import { LanguageSwitcher } from "./locale";
+import { Stack, DetailList } from "./layout";
+import { ThemeToggle } from "./theme";
+import { userInitials } from "./UserMenu";
+import { Button } from "./ui/Button";
+import { useStrings } from "./uiText";
+
+const avatarStyle: CSSProperties = {
+  display: "inline-flex",
+  alignItems: "center",
+  justifyContent: "center",
+  width: "3.5rem",
+  height: "3.5rem",
+  flexShrink: 0,
+  borderRadius: "var(--radius-full)",
+  background: "var(--color-brand-primary)",
+  color: "var(--color-brand-primary-contrast)",
+  fontSize: "var(--font-size-lg)",
+  fontWeight: "var(--font-weight-medium)" as CSSProperties["fontWeight"],
+};
+
+const mutedStyle: CSSProperties = { margin: 0, color: "var(--color-neutral-600)" };
+
+const cardStyle: CSSProperties = {
+  display: "grid",
+  gap: "var(--space-4)",
+  padding: "var(--space-4)",
+  maxWidth: "32rem",
+  background: "var(--color-neutral-0)",
+  border: "1px solid var(--color-neutral-200)",
+  borderRadius: "var(--radius-lg)",
+};
+
+/**
+ * The built-in profile / settings page the {@link UserMenu}'s Settings item opens.
+ * `buildAppRouter` mounts it at `/profile` in every app (an app manifest claiming
+ * that path wins): the signed-in identity (avatar, email, role — the server-validated
+ * `/me` session, not token claims), the standard theme + language preferences, and
+ * sign-out. A `Page` archetype, so it satisfies the routed-view frame control.
+ */
+export function ProfileView() {
+  const auth = useAuth();
+  const strings = useStrings();
+  const user = auth.currentUser();
+  if (user === null) {
+    return null; // RequireAuth gates the shell; this is unreachable when signed out.
+  }
+  return (
+    <Page title={strings.profile}>
+      <Stack gap={4}>
+        <div style={cardStyle}>
+          <Stack direction="row" gap={3} align="center">
+            <span aria-hidden="true" style={avatarStyle}>
+              {userInitials(user.email)}
+            </span>
+            <Stack gap={0}>
+              <strong style={{ overflowWrap: "anywhere" }}>{user.email}</strong>
+              <p style={mutedStyle}>{user.role_name}</p>
+            </Stack>
+          </Stack>
+          <DetailList
+            items={[
+              { label: strings.email, value: user.email },
+              { label: strings.role, value: `${user.role_name} (${user.role_rank})` },
+            ]}
+          />
+        </div>
+        <div style={cardStyle}>
+          <ThemeToggle />
+          <LanguageSwitcher />
+          <div>
+            <Button variant="secondary" onClick={() => void auth.logout()}>
+              {strings.signOut}
+            </Button>
+          </div>
+        </div>
+      </Stack>
+    </Page>
+  );
+}

package/src/RequireAuth.test.tsx

@@ -0,0 +1,89 @@
+// @vitest-environment jsdom
+import { cleanup, render, screen, waitFor } from "@testing-library/react";
+import { useEffect } from "react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { RequireAuth } from "./RequireAuth";
+import { TerpProvider, useAuth } from "./TerpProvider";
+
+function jsonResponse(body: unknown): Response {
+  return new Response(JSON.stringify(body), {
+    status: 200,
+    headers: { "content-type": "application/json" },
+  });
+}
+
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+});
+
+function LogInOnMount() {
+  const auth = useAuth();
+  useEffect(() => {
+    void auth.login({ email: "user@example.com", password: "pw" });
+  }, []);
+  return null;
+}
+
+describe("RequireAuth", () => {
+  it("shows the fallback while signed out", async () => {
+    render(
+      <TerpProvider baseUrl="https://api.test">
+        <RequireAuth fallback={<span>please-sign-in</span>}>
+          <span>app</span>
+        </RequireAuth>
+      </TerpProvider>,
+    );
+    await waitFor(() => expect(screen.getByText("please-sign-in")).toBeInTheDocument());
+    expect(screen.queryByText("app")).not.toBeInTheDocument();
+  });
+
+  it("shows the pending view while boot refresh is in flight", async () => {
+    let finishRefresh!: () => void;
+    vi.stubGlobal(
+      "fetch",
+      vi.fn<typeof fetch>(
+        async () => new Promise<Response>((resolve) => {
+          finishRefresh = () => resolve(new Response("{}", { status: 401 }));
+        }),
+      ),
+    );
+
+    render(
+      <TerpProvider baseUrl="https://api.test">
+        <RequireAuth fallback={<span>please-sign-in</span>} pending={<span>checking</span>}>
+          <span>app</span>
+        </RequireAuth>
+      </TerpProvider>,
+    );
+    expect(screen.getByText("checking")).toBeInTheDocument();
+    expect(screen.queryByText("please-sign-in")).not.toBeInTheDocument();
+
+    finishRefresh();
+    await waitFor(() => expect(screen.getByText("please-sign-in")).toBeInTheDocument());
+  });
+
+  it("shows children once a user signs in", async () => {
+    const fetchMock = vi.fn<typeof fetch>(async (input) => {
+      const url = (input as Request).url;
+      if (url.endsWith("/api/v1/auth/login")) {
+        return jsonResponse({ access_token: "t", token_type: "bearer" });
+      }
+      return jsonResponse({ id: "1", email: "user@example.com", role_rank: 10, role_name: "viewer" });
+    });
+    vi.stubGlobal("fetch", fetchMock);
+
+    render(
+      <TerpProvider baseUrl="https://api.test">
+        <LogInOnMount />
+        <RequireAuth fallback={<span>please-sign-in</span>}>
+          <span>app</span>
+        </RequireAuth>
+      </TerpProvider>,
+    );
+
+    await waitFor(() => expect(screen.getByText("app")).toBeInTheDocument());
+    expect(screen.queryByText("please-sign-in")).not.toBeInTheDocument();
+  });
+});

package/src/RequireAuth.tsx

@@ -0,0 +1,22 @@
+import type { ReactNode } from "react";
+
+import { useAuth } from "./TerpProvider";
+
+export interface RequireAuthProps {
+  /** Rendered while no user is signed in (e.g. a login view). */
+  fallback: ReactNode;
+  /** Rendered while the provider is checking a persisted session (default: nothing). */
+  pending?: ReactNode;
+  children: ReactNode;
+}
+
+/**
+ * Render `children` only when a user is signed in, otherwise `fallback` (typically a login
+ * view). Pair with the router so the authenticated app mounts only once there is a session;
+ * the backend still enforces authorization on every request.
+ */
+export function RequireAuth({ fallback, pending = null, children }: RequireAuthProps) {
+  const auth = useAuth();
+  if (auth.loading()) return <>{pending}</>;
+  return <>{auth.currentUser() !== null ? children : fallback}</>;
+}