@terpjs/react-core 0.1.0

package/src/ResourceList.test.tsx

@@ -0,0 +1,176 @@
+// @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 { ResourceList } from "./ResourceList";
+import { ApiError } from "./unwrap";
+import { TerpProvider, useAuth } from "./TerpProvider";
+import type { Resource } from "./useResource";
+
+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: "editor@example.com", password: "pw" });
+  }, []);
+  return null;
+}
+
+function editorFetch() {
+  return 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: "editor@example.com", role_rank: 20, role_name: "editor" });
+  });
+}
+
+type Row = { id: string; label: string };
+
+function fakeResource(overrides: Partial<Resource<Row, string>> = {}): Resource<Row, string> {
+  return {
+    items: [],
+    loading: false,
+    error: null,
+    cause: null,
+    reload: async () => {},
+    create: async () => {},
+    mutate: async (operation) => {
+      await operation();
+    },
+    ...overrides,
+  };
+}
+
+describe("ResourceList", () => {
+  it("renders rows and a write-gated create form for a writer, and creates on submit", async () => {
+    vi.stubGlobal("fetch", editorFetch());
+    const create = vi.fn(async () => {});
+    const resource = fakeResource({ items: [{ id: "a", label: "Alpha" }], create });
+
+    render(
+      <TerpProvider baseUrl="https://api.test">
+        <LogInOnMount />
+        <ResourceList
+          title="Things"
+          resource={resource}
+          createPlaceholder="New thing"
+          renderItem={(row) => <strong>{row.label}</strong>}
+        />
+      </TerpProvider>,
+    );
+
+    expect(screen.getByRole("heading", { name: "Things" })).toBeInTheDocument();
+    expect(screen.getByText("Alpha")).toBeInTheDocument();
+    // The create form appears once the editor session loads (it is write-gated by ResourceList).
+    await waitFor(() => expect(screen.getByPlaceholderText("New thing")).toBeInTheDocument());
+
+    fireEvent.change(screen.getByPlaceholderText("New thing"), { target: { value: "Beta" } });
+    fireEvent.click(screen.getByRole("button", { name: "Add" }));
+    await waitFor(() => expect(create).toHaveBeenCalledWith("Beta"));
+  });
+
+  it("hides the create form when the resource is read-only (no createPlaceholder)", () => {
+    const resource = fakeResource({ items: [], loading: false });
+    render(
+      <TerpProvider baseUrl="https://api.test">
+        <ResourceList title="Empty" resource={resource} renderItem={(row) => <span>{row.label}</span>} />
+      </TerpProvider>,
+    );
+    expect(screen.getByText("Nothing here yet.")).toBeInTheDocument();
+    expect(screen.queryByRole("button", { name: "Add" })).not.toBeInTheDocument();
+  });
+
+  it("surfaces the resource error as an alert", () => {
+    const resource = fakeResource({ error: "boom" });
+    render(
+      <TerpProvider baseUrl="https://api.test">
+        <ResourceList title="Errored" resource={resource} renderItem={(row) => <span>{row.label}</span>} />
+      </TerpProvider>,
+    );
+    expect(screen.getByRole("alert")).toHaveTextContent("boom");
+  });
+
+  it("prefers the mapped copy for the failure's stable code over the raw message", () => {
+    const resource = fakeResource({
+      error: "permission denied for tenant",
+      cause: new ApiError("permission denied for tenant", {
+        code: "permission_denied",
+        status: 403,
+      }),
+    });
+    render(
+      <TerpProvider baseUrl="https://api.test">
+        <ResourceList title="Errored" resource={resource} renderItem={(row) => <span>{row.label}</span>} />
+      </TerpProvider>,
+    );
+    expect(screen.getByRole("alert")).toHaveTextContent(
+      "You do not have permission to do this.",
+    );
+    expect(screen.queryByText("permission denied for tenant")).not.toBeInTheDocument();
+  });
+
+  it("keeps the typed draft when a create fails, so the user can retry", async () => {
+    vi.stubGlobal("fetch", editorFetch());
+    const create = vi.fn(async () => {
+      throw new Error("Nope.");
+    });
+    const resource = fakeResource({ error: "Nope.", create });
+
+    render(
+      <TerpProvider baseUrl="https://api.test">
+        <LogInOnMount />
+        <ResourceList
+          title="Things"
+          resource={resource}
+          createPlaceholder="New thing"
+          renderItem={(row) => <strong>{row.label}</strong>}
+        />
+      </TerpProvider>,
+    );
+
+    await waitFor(() => expect(screen.getByPlaceholderText("New thing")).toBeInTheDocument());
+    fireEvent.change(screen.getByPlaceholderText("New thing"), { target: { value: "Beta" } });
+    fireEvent.click(screen.getByRole("button", { name: "Add" }));
+    await waitFor(() => expect(create).toHaveBeenCalledWith("Beta"));
+
+    // A failed create is not swallowed: the error shows and the draft is kept for a retry.
+    expect(screen.getByText("Nope.")).toBeInTheDocument();
+    expect(screen.getByPlaceholderText("New thing")).toHaveValue("Beta");
+  });
+
+  it("renders a custom create form via renderCreate (write-gated), not the default single-field form", async () => {
+    vi.stubGlobal("fetch", editorFetch());
+    const resource = fakeResource({ items: [] });
+
+    render(
+      <TerpProvider baseUrl="https://api.test">
+        <LogInOnMount />
+        <ResourceList
+          title="Things"
+          resource={resource}
+          renderCreate={() => <span>custom-create-form</span>}
+          renderItem={(row) => <span>{row.label}</span>}
+        />
+      </TerpProvider>,
+    );
+
+    // The custom form appears once the writer session loads (ResourceList still applies the gate).
+    await waitFor(() => expect(screen.getByText("custom-create-form")).toBeInTheDocument());
+    // The default single-field "Add" form is not rendered when renderCreate is supplied.
+    expect(screen.queryByRole("button", { name: "Add" })).not.toBeInTheDocument();
+  });
+});

package/src/ResourceList.tsx

@@ -0,0 +1,123 @@
+import { useState } from "react";
+import type { CSSProperties, FormEvent, ReactNode } from "react";
+
+import { Authorized } from "./Authorized";
+import { useErrorMessage } from "./errorMessages";
+import { useStrings, useUiText } from "./uiText";
+import type { UiText } from "./uiText";
+import { Button } from "./ui/Button";
+import { Input } from "./ui/Input";
+import type { Resource } from "./useResource";
+
+const rowStyle: CSSProperties = {
+  display: "flex",
+  alignItems: "center",
+  justifyContent: "space-between",
+  gap: "var(--space-3)",
+  padding: "var(--space-3)",
+  border: "1px solid var(--color-neutral-200)",
+  borderRadius: "var(--radius-md)",
+  background: "var(--color-neutral-0)",
+};
+
+const mutedStyle: CSSProperties = { color: "var(--color-neutral-600)" };
+
+export interface ResourceListProps<T extends { id: string }> {
+  /** Section heading; omit when composed under a `Page` (whose title is the `h1`). */
+  title?: UiText;
+  /** The module's data hook result (items / loading / error / create — see {@link useResource}). */
+  resource: Resource<T, string>;
+  /** Render the content of one row. */
+  renderItem: (item: T) => ReactNode;
+  /** Placeholder for the single-field create input; omit to hide creating. */
+  createPlaceholder?: UiText;
+  /**
+   * A custom (e.g. multi-field) create form, for creates that need more than one field. Supply a
+   * component built from `Field` + the input primitives; ResourceList still applies the write-gate
+   * around it. Overrides `createPlaceholder`.
+   */
+  renderCreate?: () => ReactNode;
+  /** Optional per-row actions (e.g. a delete button); rendered only for writers. */
+  renderActions?: (item: T) => ReactNode;
+  /** Message shown when there are no rows (default: the `emptyList` string). */
+  emptyMessage?: UiText;
+}
+
+/**
+ * The standard list screen every CRUD module needs, centralized: a titled section, a write-gated
+ * single-field create form, loading / error / empty states, and a token-styled list. A module
+ * composes it with its typed data hook and a row renderer, so every module lists and creates the
+ * same way — and the {@link Authorized} write-gate (create form + row actions) is applied for you,
+ * not re-implemented per module.
+ *
+ * It is a composable component, not a hidden CRUD DSL: a screen that needs more just renders its own
+ * React and ignores this.
+ */
+export function ResourceList<T extends { id: string }>({
+  title,
+  resource,
+  renderItem,
+  createPlaceholder,
+  renderCreate,
+  renderActions,
+  emptyMessage,
+}: ResourceListProps<T>) {
+  const strings = useStrings();
+  const resolve = useUiText();
+  const messageForCode = useErrorMessage();
+  const [draft, setDraft] = useState("");
+
+  async function onCreate(event: FormEvent) {
+    event.preventDefault();
+    if (!draft.trim()) {
+      return;
+    }
+    try {
+      await resource.create(draft);
+      setDraft(""); // clear only on success; a failed create surfaces resource.error and keeps the draft
+    } catch {
+      // The failure is already surfaced via resource.error (rendered below); keep the draft to retry.
+    }
+  }
+
+  return (
+    <section
+      data-terp="resource-list"
+      style={{ display: "grid", gap: "var(--space-4)", maxWidth: "40rem" }}
+    >
+      {title !== undefined && <h1>{resolve(title)}</h1>}
+      {renderCreate !== undefined ? (
+        <Authorized action="write">{renderCreate()}</Authorized>
+      ) : createPlaceholder !== undefined ? (
+        <Authorized action="write">
+          <form onSubmit={onCreate} style={{ display: "flex", gap: "var(--space-2)" }}>
+            <Input
+              placeholder={resolve(createPlaceholder ?? "")}
+              value={draft}
+              onChange={(event) => setDraft(event.target.value)}
+              style={{ flex: 1 }}
+            />
+            <Button type="submit">{strings.add}</Button>
+          </form>
+        </Authorized>
+      ) : null}
+      {resource.error !== null && (
+        <p role="alert" style={{ color: "var(--color-status-danger)" }}>
+          {messageForCode(resource.cause) ?? resource.error}
+        </p>
+      )}
+      {resource.items.length === 0 ? (
+        <p style={mutedStyle}>{resource.loading ? strings.loading : resolve(emptyMessage ?? strings.emptyList)}</p>
+      ) : (
+        <ul style={{ listStyle: "none", margin: 0, padding: 0, display: "grid", gap: "var(--space-2)" }}>
+          {resource.items.map((item) => (
+            <li key={item.id} style={rowStyle}>
+              <div>{renderItem(item)}</div>
+              {renderActions && <Authorized action="write">{renderActions(item)}</Authorized>}
+            </li>
+          ))}
+        </ul>
+      )}
+    </section>
+  );
+}

package/src/TerpProvider.tsx

@@ -0,0 +1,320 @@
+import {
+  createContext,
+  useEffect,
+  useCallback,
+  useContext,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+import type { ReactNode } from "react";
+import type {
+  Action,
+  AuthSession,
+  Credentials,
+  CurrentUser,
+  paths as ContractPaths,
+  TerpClient,
+  TerpClientFor,
+} from "@terpjs/contract";
+import { createTerpClient } from "@terpjs/contract";
+
+import {
+  canPerform,
+  DEFAULT_RANK_THRESHOLDS,
+  type RankThresholds,
+} from "./capabilities";
+import { createAuthClient } from "./createAuthClient";
+import {
+  completeSsoCallback,
+  DEFAULT_SSO_CALLBACK_PATH,
+  fetchSsoAuthorizationUrl,
+  isSsoCallbackLocation,
+  parseSsoCallback,
+  type SsoCallbackParams,
+} from "./sso";
+
+/**
+ * The SSO login session (ADR 0058): `begin` opens a provider flow (navigates the
+ * browser to the IdP), and `error` carries a failed callback completion so the
+ * login screen can surface it. Only meaningful in apps that mount the OIDC
+ * capability; a password-only app simply never calls `begin`.
+ */
+export interface SsoSession {
+  /** Start an SSO login: fetch the IdP authorize URL and navigate to it. */
+  begin(provider: string): Promise<void>;
+  /** The failure of the last SSO attempt (callback completion), or null. */
+  error: unknown;
+}
+
+interface TerpContextValue {
+  baseUrl: string;
+  client: TerpClient;
+  auth: AuthSession;
+  sso: SsoSession;
+}
+
+const TerpContext = createContext<TerpContextValue | null>(null);
+
+export interface TerpProviderProps {
+  /** Backend API origin, e.g. "https://api.example.com". */
+  baseUrl: string;
+  /** Role-rank thresholds for {@link AuthSession.can}; defaults to the bundled ladder. */
+  thresholds?: RankThresholds;
+  /**
+   * SPA path prefix the IdP redirects back to after an SSO login (ADR 0058); the
+   * provider completes a `{ssoCallbackPath}/{provider}?code&state` landing on boot.
+   * Must match the `redirect_uri` configured on the backend's OIDC providers.
+   */
+  ssoCallbackPath?: string;
+  children: ReactNode;
+}
+
+async function loadCurrentUser(client: TerpClient): Promise<CurrentUser> {
+  const { data, error } = await client.GET("/api/v1/me/", {});
+  if (error || !data) {
+    throw new Error("failed to load the current user");
+  }
+  return data;
+}
+
+/**
+ * Provides a typed `@terpjs/contract` client and an {@link AuthSession} to the tree. The
+ * session implements the contract over the generated client: login exchanges credentials
+ * for a token and loads `/me`, logout revokes it (ADR 0031), and `can` gates the UI on
+ * the server-validated role rank. The bearer token lives in memory for the provider's
+ * lifetime.
+ */
+export function TerpProvider({
+  baseUrl,
+  thresholds = DEFAULT_RANK_THRESHOLDS,
+  ssoCallbackPath = DEFAULT_SSO_CALLBACK_PATH,
+  children,
+}: TerpProviderProps) {
+  const tokenRef = useRef<string | null>(null);
+  const [user, setUser] = useState<CurrentUser | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [ssoError, setSsoError] = useState<unknown>(null);
+
+  // Captured once per provider lifetime (before the URL is cleaned), so a StrictMode
+  // double boot effect cannot replay the single-use OIDC state against the backend.
+  const ssoPendingRef = useRef<
+    { params: SsoCallbackParams | null; atCallback: boolean } | undefined
+  >(undefined);
+  if (ssoPendingRef.current === undefined) {
+    ssoPendingRef.current =
+      typeof window === "undefined"
+        ? { params: null, atCallback: false }
+        : {
+            params: parseSsoCallback(window.location, ssoCallbackPath),
+            atCallback: isSsoCallbackLocation(window.location, ssoCallbackPath),
+          };
+  }
+
+  const clearSession = useCallback(() => {
+    tokenRef.current = null;
+    setUser(null);
+  }, []);
+
+  const refreshClient = useMemo(
+    () => createTerpClient({ baseUrl, credentials: "include" }),
+    [baseUrl],
+  );
+
+  // Single-flight: concurrent callers (a StrictMode double boot effect, the 401 middleware
+  // racing the boot refresh) share one /refresh round-trip instead of racing the rotation.
+  const refreshInFlightRef = useRef<Promise<string | null> | null>(null);
+
+  const refreshAccessToken = useCallback((): Promise<string | null> => {
+    const existing = refreshInFlightRef.current;
+    if (existing) return existing;
+    const attempt = refreshClient
+      .POST("/api/v1/auth/refresh", {})
+      .then(({ data, error }) => {
+        if (error || !data) {
+          return null;
+        }
+        tokenRef.current = data.access_token;
+        return data.access_token;
+      })
+      .catch(() => null)
+      .finally(() => {
+        refreshInFlightRef.current = null;
+      });
+    refreshInFlightRef.current = attempt;
+    return attempt;
+  }, [refreshClient]);
+
+  // One client per provider; its middleware reads the live token from the ref, sends refresh
+  // cookies, and on a 401 tries one refresh+replay before clearing the session (ADR 0054/0031).
+  const client = useMemo(
+    () =>
+      createAuthClient(baseUrl, () => tokenRef.current, {
+        refreshAccessToken,
+        onUnauthorized: clearSession,
+      }),
+    [baseUrl, clearSession, refreshAccessToken],
+  );
+
+  const login = useCallback(
+    async (credentials: Credentials): Promise<CurrentUser> => {
+      const { data, error } = await client.POST("/api/v1/auth/login", {
+        body: credentials,
+      });
+      if (error || !data) {
+        throw new Error("login failed");
+      }
+      tokenRef.current = data.access_token;
+      const me = await loadCurrentUser(client);
+      setUser(me);
+      return me;
+    },
+    [client],
+  );
+
+  const logout = useCallback(async (): Promise<void> => {
+    try {
+      await client.POST("/api/v1/auth/logout", {});
+    } finally {
+      clearSession();
+    }
+  }, [client, clearSession]);
+
+  const refresh = useCallback(async (): Promise<CurrentUser | null> => {
+    const startingToken = tokenRef.current;
+    const token = await refreshAccessToken();
+    if (!token) {
+      if (tokenRef.current === startingToken) clearSession();
+      return null;
+    }
+    const me = await loadCurrentUser(client).catch(() => null);
+    if (!me) {
+      if (tokenRef.current === token) clearSession();
+      return null;
+    }
+    setUser(me);
+    return me;
+  }, [client, clearSession, refreshAccessToken]);
+
+  // Finish an in-flight SSO redirect: clean the URL first (the code/state are single-use
+  // and must not survive a reload), then exchange them for a normal Terp session.
+  const completePendingSso = useCallback(
+    async (pending: SsoCallbackParams): Promise<void> => {
+      try {
+        const token = await completeSsoCallback(client, pending.provider, pending);
+        tokenRef.current = token;
+        const me = await loadCurrentUser(client);
+        setUser(me);
+      } catch (error) {
+        tokenRef.current = null;
+        setSsoError(error);
+      }
+    },
+    [client],
+  );
+
+  useEffect(() => {
+    let cancelled = false;
+    setLoading(true);
+    const boot = async (): Promise<void> => {
+      const landing = ssoPendingRef.current;
+      ssoPendingRef.current = { params: null, atCallback: false };
+      if (landing?.atCallback && typeof window !== "undefined") {
+        window.history.replaceState(window.history.state, "", "/");
+      }
+      if (landing?.params) {
+        await completePendingSso(landing.params);
+        return;
+      }
+      if (landing?.atCallback) {
+        // The IdP redirected back without a usable code (e.g. the user denied
+        // consent): a failed SSO attempt, not a normal boot.
+        setSsoError(new Error("SSO sign-in was not completed"));
+        return;
+      }
+      await refresh();
+    };
+    void boot().finally(() => {
+      if (!cancelled) setLoading(false);
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [completePendingSso, refresh]);
+
+  const auth = useMemo<AuthSession>(
+    () => ({
+      login,
+      logout,
+      refresh,
+      currentUser: () => user,
+      loading: () => loading,
+      can: (action: Action) =>
+        user ? canPerform(user.role_rank, action, thresholds) : false,
+    }),
+    [login, logout, refresh, user, loading, thresholds],
+  );
+
+  const beginSso = useCallback(
+    async (provider: string): Promise<void> => {
+      setSsoError(null);
+      const url = await fetchSsoAuthorizationUrl(client, provider);
+      window.location.assign(url);
+    },
+    [client],
+  );
+
+  const sso = useMemo<SsoSession>(
+    () => ({ begin: beginSso, error: ssoError }),
+    [beginSso, ssoError],
+  );
+
+  const value = useMemo<TerpContextValue>(
+    () => ({ baseUrl, client, auth, sso }),
+    [baseUrl, client, auth, sso],
+  );
+
+  return <TerpContext.Provider value={value}>{children}</TerpContext.Provider>;
+}
+
+function useTerp(): TerpContextValue {
+  const ctx = useContext(TerpContext);
+  if (!ctx) {
+    throw new Error("useTerpClient / useAuth must be used within a <TerpProvider>");
+  }
+  return ctx;
+}
+
+/**
+ * The typed API client, authenticated with the current session token.
+ *
+ * Pass your app's generated `paths` to type calls to your OWN endpoints. It is the one
+ * shared client (the base-profile login / me / logout calls in {@link TerpProvider} use the
+ * same instance), re-typed to your contract:
+ *
+ * ```ts
+ * import type { paths } from "./api/schema"; // openapi-typescript output of your backend
+ * const client = useTerpClient<paths>();
+ * const { data } = await client.GET("/api/v1/invoices/", {});
+ * ```
+ *
+ * The default types the base-profile endpoints bundled in `@terpjs/contract`.
+ */
+export function useTerpClient<AppPaths extends {} = ContractPaths>(): TerpClientFor<AppPaths> {
+  return useTerp().client as unknown as TerpClientFor<AppPaths>;
+}
+
+/** @internal The configured backend origin for sanctioned transport hooks. */
+export function useTerpBaseUrl(): string {
+  return useTerp().baseUrl;
+}
+
+/** The current {@link AuthSession}: login / logout / refresh / currentUser / can. */
+export function useAuth(): AuthSession {
+  return useTerp().auth;
+}
+
+/** The current {@link SsoSession}: begin an SSO login, or read the last SSO failure. */
+export function useSso(): SsoSession {
+  return useTerp().sso;
+}