@terpjs/react-core 0.1.0

package/src/uiText.tsx

@@ -0,0 +1,342 @@
+import { createContext, useCallback, useContext, useMemo } from "react";
+import type { ReactNode } from "react";
+
+/**
+ * A piece of user-facing text: either a plain string (used as-is) or a message
+ * descriptor — a stable `id` for a translation catalog plus the source-language
+ * `message` used as the fallback. Components accept `UiText` so an app can go
+ * from hardcoded strings to a full i18n runtime without changing call sites.
+ */
+export type UiText = string | { id: string; message: string };
+
+/** Resolves a {@link UiText} to the display string for the active locale. */
+export type ResolveUiText = (text: UiText) => string;
+
+/** The default resolver: plain strings as-is, descriptors via their fallback `message`. */
+export function resolveUiText(text: UiText): string {
+  return typeof text === "string" ? text : text.message;
+}
+
+/**
+ * Every user-facing string the framework renders itself. Each key can be
+ * overridden per app (or wholesale rerouted through {@link UiTextProvider}'s
+ * `resolveText`), so react-core stays locale-agnostic: it ships English
+ * defaults but never forces them.
+ */
+export interface TerpStrings {
+  /** Body placeholder while a page's data loads. */
+  loading: string;
+  /** Default empty-list message. */
+  emptyList: string;
+  /** Label of the default single-field create button. */
+  add: string;
+  /** Label of the header sign-out button. */
+  signOut: string;
+  /** Login view heading and submit label. */
+  signIn: string;
+  /** Login submit label while the request is in flight. */
+  signingIn: string;
+  /** Login email placeholder. */
+  email: string;
+  /** Login password placeholder. */
+  password: string;
+  /** Login failure message. */
+  signInFailed: string;
+  /** Label of the dev-only button that fills the seeded development credentials. */
+  fillDevCredentials: string;
+  /** Prefix of an SSO provider button label ("Continue with {provider}"). */
+  continueWith: string;
+  /** Separator between the credentials form and the SSO provider buttons. */
+  orSeparator: string;
+  /** Message when an SSO login attempt fails. */
+  ssoFailed: string;
+  /** Label of the {@link FileUpload} button. */
+  uploadFile: string;
+  /** {@link FileUpload} button label while an upload is in flight. */
+  uploading: string;
+  /** Default message when the user may not access a route. */
+  unauthorized: string;
+  /** Accessible name of the breadcrumb `nav` landmark. */
+  breadcrumbsLabel: string;
+  /** Accessible name of intra-module secondary navigation. */
+  moduleNavigationLabel: string;
+  /** Accessible label of the page-actions overflow trigger. */
+  moreActions: string;
+  /** Default {@link ErrorState} title. */
+  errorTitle: string;
+  /** Default confirm-button label of {@link ConfirmDialog}. */
+  confirm: string;
+  /** Default cancel-button label of {@link ConfirmDialog}. */
+  cancel: string;
+  /** Default success-toast title. */
+  successTitle: string;
+  /** Default warning-toast title. */
+  warningTitle: string;
+  /** Accessible label of a toast's dismiss button. */
+  dismiss: string;
+  /** Accessible label of the {@link UserMenu} avatar trigger. */
+  accountMenu: string;
+  /** Label of the {@link UserMenu} item that opens the profile / settings page. */
+  settings: string;
+  /** Title of the built-in profile page (and its breadcrumb). */
+  profile: string;
+  /** Label of the profile page's role detail. */
+  role: string;
+  /** Label of the application home/root page. */
+  home: string;
+  /** Accessible name of the sidebar `nav` landmark. */
+  primaryNavigationLabel: string;
+  /** Accessible label of the header toggle when it collapses the expanded sidebar. */
+  collapseSidebar: string;
+  /** Accessible label of the header toggle when it expands the collapsed sidebar. */
+  expandSidebar: string;
+  /** Accessible label of the header toggle when it opens the mobile navigation drawer. */
+  openNavigation: string;
+  /** Accessible label of the control that closes the mobile navigation drawer. */
+  closeNavigation: string;
+  /** Label of the {@link ThemeToggle} select. */
+  theme: string;
+  /** {@link ThemeToggle} option: the light theme. */
+  themeLight: string;
+  /** {@link ThemeToggle} option: the dark theme. */
+  themeDark: string;
+  /** {@link ThemeToggle} option: follow the OS preference. */
+  themeSystem: string;
+  /** Label of the {@link LanguageSwitcher} select. */
+  language: string;
+  /** The packaged admin area: nav label + hub title. */
+  admin: string;
+  /** Admin hub card / users overview title. */
+  adminUsers: string;
+  /** Admin hub: users card description. */
+  adminUsersDescription: string;
+  /** Admin hub card / groups overview title. */
+  adminGroups: string;
+  /** Admin hub: groups card description. */
+  adminGroupsDescription: string;
+  /** Admin hub card / audit overview title. */
+  adminAudit: string;
+  /** Admin hub: audit card description. */
+  adminAuditDescription: string;
+  /** Generic "Status" column header. */
+  statusColumn: string;
+  /** Generic "Created" column header. */
+  createdColumn: string;
+  /** Active-account status label. */
+  statusActive: string;
+  /** Deactivated-account status label. */
+  statusDeactivated: string;
+  /** Users admin: provision-form submit label. */
+  provisionUser: string;
+  /** Users admin: viewer role label. */
+  roleViewer: string;
+  /** Users admin: editor role label. */
+  roleEditor: string;
+  /** Users admin: administrator role label. */
+  roleAdmin: string;
+  /** Generic in-flight label for a pending mutation. */
+  working: string;
+  /** Users admin: change-role action; `{role}` is replaced by the role's name. */
+  makeRole: string;
+  /** Users admin: reset-password action + dialog confirm label. */
+  resetPassword: string;
+  /** Users admin: reset dialog's password field label. */
+  newPassword: string;
+  /** Users admin: deactivate action. */
+  deactivate: string;
+  /** Users admin: reactivate action. */
+  reactivate: string;
+  /** Users admin: confirmation before changing a role; `{role}` is replaced. */
+  changeRoleConfirm: string;
+  /** Users admin: confirmation before deactivation. */
+  deactivateUserConfirm: string;
+  /** Users admin: confirmation before reactivation. */
+  reactivateUserConfirm: string;
+  /** Groups admin: name field / column. */
+  groupName: string;
+  /** Groups admin: description field / column. */
+  description: string;
+  /** Groups admin: members column / detail section title. */
+  members: string;
+  /** Groups admin: create-form submit label. */
+  createGroup: string;
+  /** Groups admin: delete action. */
+  deleteGroup: string;
+  /** Groups admin: delete confirmation body. */
+  deleteGroupConfirm: string;
+  /** Group detail: add-member submit label. */
+  addMember: string;
+  /** Group detail: remove-member action. */
+  removeMember: string;
+  /** Group detail: confirmation before removing a member. */
+  removeMemberConfirm: string;
+  /** Group detail: the user field of the add-member form. */
+  userField: string;
+  /** Group detail: no account matched the typed email. */
+  userNotFound: string;
+  /** Group detail: permissions section title. */
+  permissions: string;
+  /** Group detail: grant-form submit label. */
+  grantPermission: string;
+  /** Group detail: permission field / column. */
+  permission: string;
+  /** Group detail: revoke-grant action. */
+  revoke: string;
+  /** Group detail: confirmation before revoking a permission. */
+  revokeConfirm: string;
+  /** Audit admin: action column. */
+  actionColumn: string;
+  /** Audit admin: actor column. */
+  actorColumn: string;
+  /** Audit admin: target column. */
+  targetColumn: string;
+  /** Audit admin: timestamp column. */
+  whenColumn: string;
+  /** Audit admin: expanded row's payload heading. */
+  details: string;
+  /** Generic success toast after a saved mutation. */
+  saved: string;
+  /** Generic failure toast when a request did not go through. */
+  requestFailed: string;
+}
+
+export const DEFAULT_STRINGS: TerpStrings = {
+  loading: "Loading...",
+  emptyList: "Nothing here yet.",
+  add: "Add",
+  signOut: "Sign out",
+  signIn: "Sign in",
+  signingIn: "Signing in…",
+  email: "Email",
+  password: "Password",
+  signInFailed: "Sign-in failed. Check your credentials.",
+  fillDevCredentials: "Fill dev credentials",
+  continueWith: "Continue with",
+  orSeparator: "or",
+  ssoFailed: "Single sign-on failed. Try again.",
+  uploadFile: "Upload file",
+  uploading: "Uploading…",
+  unauthorized: "You do not have access to this page.",
+  breadcrumbsLabel: "Breadcrumb",
+  moduleNavigationLabel: "Module navigation",
+  moreActions: "More actions",
+  errorTitle: "Something went wrong.",
+  confirm: "Confirm",
+  cancel: "Cancel",
+  successTitle: "Success",
+  warningTitle: "Heads up",
+  dismiss: "Dismiss",
+  accountMenu: "Account menu",
+  settings: "Settings",
+  profile: "Profile",
+  role: "Role",
+  home: "Home",
+  primaryNavigationLabel: "Primary",
+  collapseSidebar: "Collapse sidebar",
+  expandSidebar: "Expand sidebar",
+  openNavigation: "Open navigation",
+  closeNavigation: "Close navigation",
+  theme: "Theme",
+  themeLight: "Light",
+  themeDark: "Dark",
+  themeSystem: "System",
+  language: "Language",
+  admin: "Admin",
+  adminUsers: "Users",
+  adminUsersDescription: "Provision accounts, change roles, reset passwords",
+  adminGroups: "Groups",
+  adminGroupsDescription: "Bundle permissions; membership applies them",
+  adminAudit: "Audit log",
+  adminAuditDescription: "Every change: what, who, when",
+  statusColumn: "Status",
+  createdColumn: "Created",
+  statusActive: "Active",
+  statusDeactivated: "Deactivated",
+  provisionUser: "Provision user",
+  roleViewer: "Viewer",
+  roleEditor: "Editor",
+  roleAdmin: "Administrator",
+  working: "Working…",
+  makeRole: "Make {role}",
+  resetPassword: "Reset password",
+  newPassword: "New password",
+  deactivate: "Deactivate",
+  reactivate: "Reactivate",
+  changeRoleConfirm: "Change this user's role to {role}?",
+  deactivateUserConfirm: "Deactivate this account? Its active sessions will be revoked.",
+  reactivateUserConfirm: "Reactivate this account?",
+  groupName: "Name",
+  description: "Description",
+  members: "Members",
+  createGroup: "Create group",
+  deleteGroup: "Delete group",
+  deleteGroupConfirm: "Delete this group? Its memberships and permission grants go with it.",
+  addMember: "Add member",
+  removeMember: "Remove",
+  removeMemberConfirm: "Remove this member from the group?",
+  userField: "User",
+  userNotFound: "No account matches that email.",
+  permissions: "Permissions",
+  grantPermission: "Grant permission",
+  permission: "Permission",
+  revoke: "Revoke",
+  revokeConfirm: "Revoke this permission from the group?",
+  actionColumn: "Action",
+  actorColumn: "Actor",
+  targetColumn: "Target",
+  whenColumn: "When",
+  details: "Details",
+  saved: "Saved",
+  requestFailed: "The request failed. Try again.",
+};
+
+interface UiTextContextValue {
+  strings: TerpStrings;
+  resolveText: ResolveUiText;
+}
+
+const UiTextContext = createContext<UiTextContextValue>({
+  strings: DEFAULT_STRINGS,
+  resolveText: resolveUiText,
+});
+
+export interface UiTextProviderProps {
+  /** Per-key overrides of the framework's own strings (e.g. translations). */
+  strings?: Partial<TerpStrings>;
+  /**
+   * Custom {@link UiText} resolver — the hook for a real i18n runtime: pass a
+   * function that looks descriptors up in the active locale's catalog
+   * (falling back to `message`). Defaults to {@link resolveUiText}.
+   */
+  resolveText?: ResolveUiText;
+  children: ReactNode;
+}
+
+/**
+ * The locale seam. react-core components read all their own strings and
+ * resolve all `UiText` props through this context; without a provider they
+ * use the bundled English defaults. An app localises by wrapping its tree
+ * once — no per-component wiring, no i18n dependency inside react-core.
+ */
+export function UiTextProvider({ strings, resolveText, children }: UiTextProviderProps) {
+  const parent = useContext(UiTextContext);
+  const value = useMemo<UiTextContextValue>(
+    () => ({
+      strings: { ...parent.strings, ...strings },
+      resolveText: resolveText ?? parent.resolveText,
+    }),
+    [parent, strings, resolveText],
+  );
+  return <UiTextContext.Provider value={value}>{children}</UiTextContext.Provider>;
+}
+
+/** The framework strings for the active locale (defaults merged with any overrides). */
+export function useStrings(): TerpStrings {
+  return useContext(UiTextContext).strings;
+}
+
+/** The active {@link UiText} resolver — call it on any `UiText` prop before rendering. */
+export function useUiText(): ResolveUiText {
+  const { resolveText } = useContext(UiTextContext);
+  return useCallback((text: UiText) => resolveText(text), [resolveText]);
+}

package/src/unwrap.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, it } from "vitest";
+
+import { ApiError, unwrap } from "./unwrap";
+
+function response(status: number): Response {
+  return new Response(null, { status });
+}
+
+describe("unwrap", () => {
+  it("returns the data on a 2xx result", () => {
+    expect(unwrap({ data: { items: [1, 2] }, response: response(200) })).toEqual({
+      items: [1, 2],
+    });
+  });
+
+  it("returns undefined data on a 204 (no body) without throwing", () => {
+    expect(unwrap<undefined>({ response: response(204) })).toBeUndefined();
+  });
+
+  it("throws the backend error `detail` on an HTTP error", () => {
+    expect(() =>
+      unwrap({
+        error: { code: "permission_denied", detail: "You do not have permission." },
+        response: response(403),
+      }),
+    ).toThrow("You do not have permission.");
+  });
+
+  it("flattens structured validation detail into field messages", () => {
+    expect(() =>
+      unwrap({
+        error: {
+          detail: [
+            { loc: ["body", "title"], msg: "String should have at least 1 character" },
+            { loc: ["body", "owner", "email"], msg: "Input should be a valid email" },
+          ],
+        },
+        response: response(422),
+      }),
+    ).toThrow("title: String should have at least 1 character; owner.email: Input should be a valid email");
+  });
+
+  it("falls back to the error `code`, then the status, when there is no detail", () => {
+    expect(() => unwrap({ error: { code: "conflict" }, response: response(409) })).toThrow(
+      "conflict",
+    );
+    expect(() => unwrap({ response: response(500) })).toThrow("HTTP 500");
+  });
+
+  it("throws an ApiError carrying the stable code, status, and request id", () => {
+    let caught: unknown;
+    try {
+      unwrap({
+        error: { code: "stale_data", detail: "Row changed.", request_id: "req-1" },
+        response: response(409),
+      });
+    } catch (error) {
+      caught = error;
+    }
+    expect(caught).toBeInstanceOf(ApiError);
+    const apiError = caught as ApiError;
+    expect(apiError.code).toBe("stale_data");
+    expect(apiError.status).toBe(409);
+    expect(apiError.requestId).toBe("req-1");
+    expect(apiError.message).toBe("Row changed.");
+  });
+});

package/src/unwrap.ts

@@ -0,0 +1,101 @@
+/**
+ * Unwrap an `openapi-fetch` result, throwing on any non-2xx.
+ *
+ * `openapi-fetch` does **not** throw on an HTTP error status — it returns `{ data, error }`
+ * (error carrying the parsed response body). A data hook that reads `.data` alone therefore
+ * silently swallows 401 / 403 / 409 / 422 / 500: a failed read shows an empty list, a failed
+ * write no-ops. Passing the result through {@link unwrap} makes every failure surface — it
+ * throws an {@link ApiError} carrying the backend's error-envelope `detail` (falling back to
+ * `code`, then the HTTP status), so a module's `useResource` reports it instead of hiding it.
+ */
+export interface FetchResult<T> {
+  /** The parsed 2xx response body (absent on error / 204). */
+  data?: T;
+  /** The parsed error-response body (absent on success). */
+  error?: unknown;
+  /** The raw response, used to detect a non-ok status even when the body did not parse. */
+  response: Response;
+}
+
+/**
+ * A failed request, carrying the machine-readable parts of the platform error
+ * envelope alongside the human-readable `message`. The stable `code` lets UI code
+ * dispatch on the failure kind (and map it to client-owned copy) without
+ * pattern-matching prose; `message` is the backend `detail` fallback.
+ */
+export class ApiError extends Error {
+  /** Stable machine code from the envelope (e.g. `stale_data`), if present. */
+  readonly code?: string;
+  /** HTTP status of the failed response. */
+  readonly status: number;
+  /** Correlation id from the envelope, for support and log lookup. */
+  readonly requestId?: string;
+
+  constructor(message: string, options: { code?: string; status: number; requestId?: string }) {
+    super(message);
+    this.name = "ApiError";
+    this.code = options.code;
+    this.status = options.status;
+    this.requestId = options.requestId;
+  }
+}
+
+/** Return the result's `data` on success, or throw an {@link ApiError} describing the failure. */
+export function unwrap<T>(result: FetchResult<T>): T {
+  if (result.error !== undefined || !result.response.ok) {
+    const envelope =
+      result.error !== null && typeof result.error === "object"
+        ? (result.error as { code?: unknown; request_id?: unknown })
+        : {};
+    throw new ApiError(errorMessage(result.error, result.response), {
+      code: typeof envelope.code === "string" ? envelope.code : undefined,
+      status: result.response.status,
+      requestId: typeof envelope.request_id === "string" ? envelope.request_id : undefined,
+    });
+  }
+  return result.data as T;
+}
+
+/** Human-readable message for a failed request: envelope `detail`, else `code`, else the status. */
+function errorMessage(error: unknown, response: Response): string {
+  if (error !== null && typeof error === "object") {
+    const envelope = error as { detail?: unknown; code?: unknown };
+    if (typeof envelope.detail === "string" && envelope.detail.length > 0) {
+      return envelope.detail;
+    }
+    const structured = structuredDetail(envelope.detail);
+    if (structured !== null) {
+      return structured;
+    }
+    if (typeof envelope.code === "string" && envelope.code.length > 0) {
+      return envelope.code;
+    }
+  }
+  return `Request failed (HTTP ${response.status})`;
+}
+
+/** Flatten common FastAPI/Pydantic validation details into an agent/user-actionable message. */
+function structuredDetail(detail: unknown): string | null {
+  if (!Array.isArray(detail)) {
+    return null;
+  }
+  const messages = detail
+    .map((item) => {
+      if (item === null || typeof item !== "object") {
+        return null;
+      }
+      const field = item as { loc?: unknown; msg?: unknown };
+      if (typeof field.msg !== "string" || field.msg.length === 0) {
+        return null;
+      }
+      const loc = Array.isArray(field.loc)
+        ? field.loc.filter((part) => typeof part === "string" || typeof part === "number")
+        : [];
+      const path = loc
+        .filter((part) => part !== "body" && part !== "query" && part !== "path")
+        .join(".");
+      return path.length > 0 ? `${path}: ${field.msg}` : field.msg;
+    })
+    .filter((message): message is string => message !== null);
+  return messages.length > 0 ? messages.join("; ") : null;
+}

package/src/useResource.test.tsx

@@ -0,0 +1,118 @@
+// @vitest-environment jsdom
+import { act, cleanup, renderHook, waitFor } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { useResource } from "./useResource";
+
+afterEach(cleanup);
+
+describe("useResource", () => {
+  it("loads on mount and exposes the rows", async () => {
+    const { result } = renderHook(() =>
+      useResource<string, string>({ list: async () => ["a", "b"] }),
+    );
+    expect(result.current.loading).toBe(true);
+    await waitFor(() => expect(result.current.loading).toBe(false));
+    expect(result.current.items).toEqual(["a", "b"]);
+    expect(result.current.error).toBeNull();
+  });
+
+  it("reloads when a declared dependency changes (in-place route-param navigation)", async () => {
+    // A detail view keyed by a route param must refetch when the param changes
+    // without a remount — otherwise the previous record's data lingers.
+    const list = vi.fn(async () => ["row"]);
+    const { result, rerender } = renderHook(
+      ({ id }: { id: string }) =>
+        useResource<string>(
+          {
+            list: async () => {
+              await list();
+              return [id];
+            },
+          },
+          [id],
+        ),
+      { initialProps: { id: "g1" } },
+    );
+    await waitFor(() => expect(result.current.items).toEqual(["g1"]));
+
+    rerender({ id: "g2" });
+    await waitFor(() => expect(result.current.items).toEqual(["g2"]));
+    expect(list).toHaveBeenCalledTimes(2);
+
+    // A rerender with the same dependency does not refetch.
+    rerender({ id: "g2" });
+    await waitFor(() => expect(result.current.loading).toBe(false));
+    expect(list).toHaveBeenCalledTimes(2);
+  });
+
+  it("create runs the source create then reloads", async () => {
+    let rows = ["a"];
+    const create = vi.fn(async (value: string) => {
+      rows = [...rows, value];
+    });
+    const { result } = renderHook(() =>
+      useResource<string, string>({ list: async () => rows, create }),
+    );
+    await waitFor(() => expect(result.current.loading).toBe(false));
+
+    await act(async () => {
+      await result.current.create("b");
+    });
+
+    expect(create).toHaveBeenCalledWith("b");
+    expect(result.current.items).toEqual(["a", "b"]);
+  });
+
+  it("captures a list error as a message", async () => {
+    const { result } = renderHook(() =>
+      useResource<string>({
+        list: async () => {
+          throw new Error("boom");
+        },
+      }),
+    );
+    await waitFor(() => expect(result.current.error).toBe("boom"));
+    expect(result.current.cause).toBeInstanceOf(Error);
+    expect(result.current.items).toEqual([]);
+  });
+
+  it("rejects create on a read-only resource", async () => {
+    const { result } = renderHook(() => useResource<string, string>({ list: async () => [] }));
+    await waitFor(() => expect(result.current.loading).toBe(false));
+    await expect(result.current.create("x")).rejects.toThrow(/read-only/);
+  });
+
+  it("surfaces a failed create as an error and rejects (not a silent no-op)", async () => {
+    const create = vi.fn(async () => {
+      throw new Error("You do not have permission.");
+    });
+    const { result } = renderHook(() =>
+      useResource<string, string>({ list: async () => ["a"], create }),
+    );
+    await waitFor(() => expect(result.current.loading).toBe(false));
+
+    await act(async () => {
+      await expect(result.current.create("b")).rejects.toThrow("You do not have permission.");
+    });
+    expect(result.current.error).toBe("You do not have permission.");
+    expect(result.current.cause).toBeInstanceOf(Error);
+  });
+
+  it("mutate surfaces module-specific write failures and rejects", async () => {
+    const { result } = renderHook(() =>
+      useResource<string, string>({ list: async () => ["a"] }),
+    );
+    await waitFor(() => expect(result.current.loading).toBe(false));
+
+    await act(async () => {
+      await expect(
+        result.current.mutate(async () => {
+          throw new Error("Delete failed.");
+        }),
+      ).rejects.toThrow("Delete failed.");
+    });
+    expect(result.current.error).toBe("Delete failed.");
+    expect(result.current.items).toEqual(["a"]);
+  });
+});