@terpjs/react-core 0.1.0

package/src/useResource.ts

@@ -0,0 +1,110 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+
+/** An async collection: the loaded rows plus loading/error state, a reload, and a create-then-reload. */
+export interface Resource<T, TCreate> {
+  /** The loaded rows (empty until the first load resolves). */
+  items: T[];
+  /** True while the initial load or a reload is in flight. */
+  loading: boolean;
+  /** The last error message, or `null` when the most recent load succeeded. */
+  error: string | null;
+  /**
+   * The last caught failure itself, or `null` — typically the `ApiError` thrown by
+   * `unwrap`, whose stable `code` lets `useErrorMessage` map it to client-owned copy.
+   * Optional so hand-built `Resource` objects (which predate this field) keep compiling;
+   * consumers treat an absent cause the same as `null` (no code-mapped copy).
+   */
+  cause?: unknown;
+  /** Re-run the list query. */
+  reload: () => Promise<void>;
+  /** Create a row via `source.create`, then reload. Rejects if the resource is read-only. */
+  create: (input: TCreate) => Promise<void>;
+  /** Run any module-specific mutation (delete, custom action), surface failures, then reload. */
+  mutate: (operation: () => Promise<void>) => Promise<void>;
+}
+
+/** How a module fetches (and optionally creates) its rows — typically typed contract-client calls. */
+export interface ResourceSource<T, TCreate> {
+  /** Fetch the current rows (e.g. `(await client.GET("/api/v1/notes/", {})).data?.items ?? []`). */
+  list: () => Promise<T[]>;
+  /** Optional create (e.g. a typed client POST); omit for a read-only resource. */
+  create?: (input: TCreate) => Promise<void>;
+}
+
+/**
+ * The list + create state machine every module's data hook needs, factored out of the view: it loads
+ * once on mount, tracks `loading`/`error`, and exposes `reload` plus a `create` that refreshes the
+ * list. Modules wrap it in a typed `useX()` hook (e.g. `useNotes`) that supplies `list`/`create` over
+ * the contract client, so views stay declarative and every module fetches the same way.
+ *
+ * `source` may be rebuilt each render (its callbacks are read through a ref), so a module can pass
+ * inline closures without triggering a reload loop. Pass `deps` (e.g. a route param the query
+ * closes over) to reload automatically when they change — a detail view keyed by `$id` refreshes
+ * on in-place navigation instead of showing the previous record.
+ */
+export function useResource<T, TCreate = void>(
+  source: ResourceSource<T, TCreate>,
+  deps: readonly unknown[] = [],
+): Resource<T, TCreate> {
+  const sourceRef = useRef(source);
+  sourceRef.current = source;
+
+  const [items, setItems] = useState<T[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+  const [cause, setCause] = useState<unknown>(null);
+
+  const fail = useCallback((caught: unknown) => {
+    setError(caught instanceof Error ? caught.message : String(caught));
+    setCause(caught);
+  }, []);
+
+  const reload = useCallback(async () => {
+    setLoading(true);
+    setError(null);
+    setCause(null);
+    try {
+      setItems(await sourceRef.current.list());
+    } catch (caught) {
+      fail(caught);
+    } finally {
+      setLoading(false);
+    }
+    // The spread keys the loader to caller-declared dependencies (route params etc.).
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [fail, ...deps]);
+
+  useEffect(() => {
+    void reload();
+  }, [reload]);
+
+  const mutate = useCallback(
+    async (operation: () => Promise<void>) => {
+      setError(null);
+      setCause(null);
+      try {
+        await operation();
+      } catch (caught) {
+        // Surface a failed write (e.g. 403 / 409 / 422) instead of silently no-op'ing, then
+        // rethrow so the caller can keep local UI state for a retry.
+        fail(caught);
+        throw caught;
+      }
+      await reload();
+    },
+    [reload, fail],
+  );
+
+  const create = useCallback(
+    async (input: TCreate) => {
+      const createFn = sourceRef.current.create;
+      if (!createFn) {
+        throw new Error("This resource is read-only (no create was provided).");
+      }
+      await mutate(() => createFn(input));
+    },
+    [mutate],
+  );
+
+  return { items, loading, error, cause, reload, create, mutate };
+}

package/src/useTerpClient.test.ts

@@ -0,0 +1,35 @@
+import type { Client } from "openapi-fetch";
+import { describe, expect, it } from "vitest";
+
+import { useTerpClient } from "./TerpProvider";
+
+// A synthetic app contract with an endpoint that is NOT in @terpjs/contract's base profile —
+// what an app's own openapi-typescript output looks like.
+interface AppPaths {
+  "/api/v1/invoices/": {
+    get: {
+      responses: {
+        200: { content: { "application/json": { items: { id: string }[] } } };
+      };
+    };
+  };
+}
+
+// Compile-time proofs, verified by `tsc --noEmit` (the typecheck CI step); never invoked at
+// runtime, so the hook is not called outside a provider. They fail to compile if the hook
+// stops threading the app's own paths through.
+function _returnsAClientForTheAppsPaths(): Client<AppPaths> {
+  return useTerpClient<AppPaths>();
+}
+
+function _typesTheAppsOwnEndpoint(client: Client<AppPaths>): unknown {
+  return client.GET("/api/v1/invoices/", {});
+}
+
+describe("useTerpClient", () => {
+  it("is generic over the app's own generated paths (typed at compile time)", () => {
+    expect(typeof useTerpClient).toBe("function");
+    expect(typeof _returnsAClientForTheAppsPaths).toBe("function");
+    expect(typeof _typesTheAppsOwnEndpoint).toBe("function");
+  });
+});

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "types": [],
+    "jsx": "react-jsx",
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "verbatimModuleSyntax": true
+  },
+  "include": ["src", "vitest.setup.ts"]
+}

package/vite.config.ts

@@ -0,0 +1,14 @@
+import react from "@vitejs/plugin-react";
+import { defineConfig } from "vitest/config";
+
+// Vite + Vitest config for @terpjs/react-core. The React plugin handles TSX. The default
+// environment is node (headless client/logic tests); component tests opt into jsdom with
+// a `// @vitest-environment jsdom` docblock so the node-based tests keep their fetch/Response.
+export default defineConfig({
+  plugins: [react()],
+  test: {
+    environment: "node",
+    setupFiles: ["./vitest.setup.ts"],
+    include: ["src/**/*.test.ts", "src/**/*.test.tsx"],
+  },
+});

package/vitest.setup.ts

@@ -0,0 +1,58 @@
+// Vitest setup: register @testing-library/jest-dom matchers (toBeInTheDocument, …).
+// Importing here is harmless for node-environment tests; the matchers are only used by
+// the jsdom component tests.
+import "@testing-library/jest-dom/vitest";
+
+// jsdom's File / Blob / FormData are structurally incompatible with Node's built-in
+// (undici) fetch: a jsdom File inside a FormData body serializes as an empty, nameless
+// part, and on Node >= 24 `Request.formData()` brand-checks reject jsdom instances
+// outright. The component tests exercise uploads through the real fetch pipeline, so in
+// the jsdom environment swap these globals for Node's own classes. The tsconfig compiles
+// with `types: []` (browser-only), so `node:buffer` is imported dynamically through a
+// variable specifier; Node's FormData class is not exported, so it is recovered from a
+// parsed urlencoded Response body.
+if (typeof window !== "undefined") {
+  const bufferModuleId = "node:buffer";
+  const { File: NativeFile, Blob: NativeBlob } = (await import(
+    /* @vite-ignore */ bufferModuleId
+  )) as { File: typeof File; Blob: typeof Blob };
+  globalThis.File = NativeFile;
+  globalThis.Blob = NativeBlob;
+  window.File = NativeFile;
+  window.Blob = NativeBlob;
+  const NativeFormData = (
+    await new Response("a=b", {
+      headers: { "content-type": "application/x-www-form-urlencoded" },
+    }).formData()
+  ).constructor as typeof FormData;
+  globalThis.FormData = NativeFormData;
+  window.FormData = NativeFormData;
+}
+
+// jsdom does not implement scrollTo, which TanStack Router calls on navigation; stub it so
+// the router render tests do not emit a noisy "Not implemented" warning. Guarded so the
+// node-environment tests (no window) are unaffected.
+if (typeof window !== "undefined") {
+  window.scrollTo = (() => {}) as typeof window.scrollTo;
+}
+
+
+// jsdom does not implement the native <dialog> modal API (showModal/close); polyfill just
+// enough for the ConfirmDialog tests: toggle the `open` property and fire the `close` event.
+if (typeof window !== "undefined" && typeof HTMLDialogElement !== "undefined") {
+  const proto = HTMLDialogElement.prototype as HTMLDialogElement & {
+    showModal?: () => void;
+    close?: () => void;
+  };
+  if (typeof proto.showModal !== "function") {
+    proto.showModal = function showModal(this: HTMLDialogElement) {
+      this.setAttribute("open", "");
+    };
+  }
+  if (typeof proto.close !== "function") {
+    proto.close = function close(this: HTMLDialogElement) {
+      this.removeAttribute("open");
+      this.dispatchEvent(new Event("close"));
+    };
+  }
+}