@terpjs/react-core 0.1.0

package/src/files.test.tsx

@@ -0,0 +1,142 @@
+// @vitest-environment jsdom
+import { cleanup, fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { FileUpload, useFileDownload, type FileMeta } from "./files";
+import { TerpProvider } from "./TerpProvider";
+
+function json(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "content-type": "application/json" },
+  });
+}
+
+const STORED: FileMeta = {
+  id: "f-1",
+  filename: "report.txt",
+  content_type: "text/plain",
+  size: 5,
+  sha256: "abc",
+  owner_id: null,
+  version: 1,
+  created_at: "2026-01-01T00:00:00Z",
+  updated_at: "2026-01-01T00:00:00Z",
+};
+
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+});
+
+function stubFetch(handler: (request: Request) => Promise<Response | null>) {
+  vi.stubGlobal(
+    "fetch",
+    vi.fn<typeof fetch>(async (input) => {
+      const request = input as Request;
+      if (request.url.endsWith("/api/v1/auth/refresh")) return json({}, 401);
+      return (await handler(request)) ?? json({}, 404);
+    }),
+  );
+}
+
+describe("FileUpload", () => {
+  it("uploads the picked file as multipart/form-data and reports the metadata", async () => {
+    stubFetch(async (request) => {
+      if (request.url.endsWith("/api/v1/files/") && request.method === "POST") {
+        // The client must send multipart/form-data with the browser-set boundary,
+        // carrying the picked file under the backend's `file` field.
+        expect(request.headers.get("content-type")).toMatch(/^multipart\/form-data/);
+        const form = await request.clone().formData();
+        expect(form.get("file")).not.toBeNull();
+        return json(STORED, 201);
+      }
+      return null;
+    });
+    const onUploaded = vi.fn();
+
+    const { container } = render(
+      <TerpProvider baseUrl="https://api.test">
+        <FileUpload onUploaded={onUploaded} />
+      </TerpProvider>,
+    );
+
+    expect(screen.getByRole("button", { name: "Upload file" })).toBeInTheDocument();
+    const input = container.querySelector('input[type="file"]');
+    expect(input).not.toBeNull();
+    fireEvent.change(input as HTMLInputElement, {
+      target: { files: [new File(["hello"], "report.txt", { type: "text/plain" })] },
+    });
+
+    await waitFor(() => expect(onUploaded).toHaveBeenCalledWith(STORED));
+  });
+
+  it("reports a failed upload through onError", async () => {
+    stubFetch(async (request) => {
+      if (request.url.endsWith("/api/v1/files/") && request.method === "POST") {
+        return json({ detail: "File too large", code: "file_too_large" }, 413);
+      }
+      return null;
+    });
+    const onUploaded = vi.fn();
+    const onError = vi.fn();
+
+    const { container } = render(
+      <TerpProvider baseUrl="https://api.test">
+        <FileUpload onUploaded={onUploaded} onError={onError} />
+      </TerpProvider>,
+    );
+
+    fireEvent.change(container.querySelector('input[type="file"]') as HTMLInputElement, {
+      target: { files: [new File(["x"], "big.bin")] },
+    });
+
+    await waitFor(() => expect(onError).toHaveBeenCalled());
+    expect(onUploaded).not.toHaveBeenCalled();
+  });
+});
+
+describe("useFileDownload", () => {
+  it("fetches the content through the client and saves it as a named download", async () => {
+    stubFetch(async (request) => {
+      if (request.url.endsWith("/api/v1/files/f-1/content")) {
+        return new Response("hello", {
+          status: 200,
+          headers: { "content-type": "application/octet-stream" },
+        });
+      }
+      return null;
+    });
+    const objectUrls: Blob[] = [];
+    const urlWithObjectUrls = URL as typeof URL & {
+      createObjectURL?: (blob: Blob) => string;
+      revokeObjectURL?: (url: string) => void;
+    };
+    urlWithObjectUrls.createObjectURL = (blob: Blob) => {
+      objectUrls.push(blob);
+      return "blob:mock";
+    };
+    urlWithObjectUrls.revokeObjectURL = () => {};
+    const clicked = vi.fn();
+    vi.spyOn(HTMLAnchorElement.prototype, "click").mockImplementation(clicked);
+
+    function Download() {
+      const download = useFileDownload();
+      return (
+        <button type="button" onClick={() => void download({ id: "f-1", filename: "report.txt" })}>
+          Download
+        </button>
+      );
+    }
+
+    render(
+      <TerpProvider baseUrl="https://api.test">
+        <Download />
+      </TerpProvider>,
+    );
+
+    fireEvent.click(screen.getByRole("button", { name: "Download" }));
+    await waitFor(() => expect(clicked).toHaveBeenCalled());
+    expect(await objectUrls[0]?.text()).toBe("hello");
+  });
+});

package/src/files.tsx

@@ -0,0 +1,174 @@
+import { useCallback, useRef, useState } from "react";
+import type { ChangeEvent, CSSProperties } from "react";
+
+import { useTerpClient } from "./TerpProvider";
+import { Button } from "./ui/Button";
+import { useStrings, useUiText, type UiText } from "./uiText";
+import { unwrap } from "./unwrap";
+import type { TerpClient, TerpClientFor } from "@terpjs/contract";
+
+/**
+ * The frontend surface of the files capability (ADR 0056/0057): a token-styled
+ * upload control ({@link FileUpload}) and an authenticated download helper
+ * ({@link useFileDownload}). The endpoints are app-mounted (the capability is
+ * opt-in), so they are not part of the baked base-profile contract; the wire
+ * shapes below mirror the capability's DTOs, which the shipped capability keeps
+ * stable.
+ */
+
+/** A stored file's metadata — the files capability's `FileRead` DTO. */
+export interface FileMeta {
+  id: string;
+  filename: string;
+  content_type: string;
+  size: number;
+  sha256: string;
+  owner_id: string | null;
+  version: number;
+  created_at: string;
+  updated_at: string;
+}
+
+/** The files capability endpoints the helpers call, typed for the shared client. */
+interface FilesPaths {
+  "/api/v1/files/": {
+    post: {
+      parameters: { query?: never; header?: never; path?: never; cookie?: never };
+      requestBody: { content: { "multipart/form-data": { file: string } } };
+      responses: {
+        201: { headers: { [name: string]: unknown }; content: { "application/json": FileMeta } };
+      };
+    };
+  };
+  "/api/v1/files/{file_id}/content": {
+    get: {
+      parameters: { path: { file_id: string }; query?: never; header?: never; cookie?: never };
+      requestBody?: never;
+      responses: {
+        200: {
+          headers: { [name: string]: unknown };
+          content: { "application/octet-stream": string };
+        };
+      };
+    };
+  };
+}
+
+function filesClient(client: TerpClient): TerpClientFor<FilesPaths> {
+  return client as unknown as TerpClientFor<FilesPaths>;
+}
+
+/** Upload one file through the typed client; resolves to the stored metadata. */
+export async function uploadFile(client: TerpClient, file: File): Promise<FileMeta> {
+  return unwrap(
+    await filesClient(client).POST("/api/v1/files/", {
+      body: { file: "" },
+      bodySerializer: () => {
+        const form = new FormData();
+        form.append("file", file, file.name);
+        return form;
+      },
+    }),
+  );
+}
+
+/** Fetch a stored file's bytes through the typed client (bearer + cookies attached). */
+export async function fetchFileContent(client: TerpClient, fileId: string): Promise<Blob> {
+  const { data, error, response } = await filesClient(client).GET(
+    "/api/v1/files/{file_id}/content",
+    { params: { path: { file_id: fileId } }, parseAs: "blob" },
+  );
+  return unwrap({ data: data as Blob | undefined, error, response });
+}
+
+/**
+ * An authenticated file download: fetches `/files/{id}/content` through the session
+ * client (a raw `<a href>` would carry no bearer token) and hands the bytes to the
+ * browser as a named download.
+ */
+export function useFileDownload(): (file: Pick<FileMeta, "id" | "filename">) => Promise<void> {
+  const client = useTerpClient();
+  return useCallback(
+    async (file: Pick<FileMeta, "id" | "filename">) => {
+      const blob = await fetchFileContent(client as unknown as TerpClient, file.id);
+      const url = URL.createObjectURL(blob);
+      try {
+        const anchor = document.createElement("a");
+        anchor.href = url;
+        anchor.download = file.filename;
+        document.body.appendChild(anchor);
+        anchor.click();
+        anchor.remove();
+      } finally {
+        URL.revokeObjectURL(url);
+      }
+    },
+    [client],
+  );
+}
+
+const hiddenInputStyle: CSSProperties = { display: "none" };
+
+export interface FileUploadProps {
+  /** Called with the stored metadata after a successful upload. */
+  onUploaded?: (file: FileMeta) => void;
+  /** Called when an upload fails (surface it via a toast or an inline error). */
+  onError?: (error: unknown) => void;
+  /** Button label; defaults to the `uploadFile` string. */
+  label?: UiText;
+  /** Native file-picker filter, e.g. `"image/*"` or `".pdf"`. */
+  accept?: string;
+  /** Disable the control (e.g. while the surrounding view is busy). */
+  disabled?: boolean;
+}
+
+/**
+ * The attachment picker for the files capability: a token-styled button that opens the
+ * native file dialog and uploads the choice as `multipart/form-data` through the typed
+ * session client, reporting the stored {@link FileMeta} to `onUploaded`.
+ */
+export function FileUpload({ onUploaded, onError, label, accept, disabled }: FileUploadProps) {
+  const client = useTerpClient();
+  const strings = useStrings();
+  const resolve = useUiText();
+  const inputRef = useRef<HTMLInputElement>(null);
+  const [busy, setBusy] = useState(false);
+
+  async function onChange(event: ChangeEvent<HTMLInputElement>) {
+    const file = event.target.files?.[0];
+    // Allow re-selecting the same file to upload it again.
+    event.target.value = "";
+    if (!file) return;
+    setBusy(true);
+    try {
+      const meta = await uploadFile(client as unknown as TerpClient, file);
+      onUploaded?.(meta);
+    } catch (error) {
+      onError?.(error);
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  return (
+    <>
+      <input
+        ref={inputRef}
+        type="file"
+        accept={accept}
+        style={hiddenInputStyle}
+        onChange={(event) => void onChange(event)}
+        aria-hidden="true"
+        tabIndex={-1}
+      />
+      <Button
+        type="button"
+        variant="secondary"
+        disabled={disabled || busy}
+        onClick={() => inputRef.current?.click()}
+      >
+        {busy ? strings.uploading : resolve(label ?? strings.uploadFile)}
+      </Button>
+    </>
+  );
+}

package/src/icons.test.tsx

@@ -0,0 +1,46 @@
+// @vitest-environment jsdom
+import { cleanup, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+
+import { ICON_GLYPHS, NavIcon, TerpMark } from "./icons";
+
+afterEach(cleanup);
+
+describe("NavIcon", () => {
+  it("renders the named glyph as decorative svg", () => {
+    const { container } = render(<NavIcon name="users" label="Users" />);
+    const slot = container.querySelector('[data-terp="nav-icon"]');
+    const svg = container.querySelector("svg");
+    expect(slot).toHaveStyle({ width: "1.25rem", height: "1.25rem", flex: "0 0 1.25rem" });
+    expect(svg).not.toBeNull();
+    expect(svg).toHaveAttribute("aria-hidden", "true");
+  });
+
+  it("falls back to the label's initial for an unknown or missing name", () => {
+    const { container } = render(<NavIcon name="no-such-glyph" label="widgets" />);
+    expect(screen.getByText("W")).toBeInTheDocument();
+    expect(container.querySelector('[data-terp="nav-icon"]')).toHaveStyle({
+      width: "1.25rem",
+      height: "1.25rem",
+      flex: "0 0 1.25rem",
+    });
+    render(<NavIcon label="records" />);
+    expect(screen.getByText("R")).toBeInTheDocument();
+  });
+
+  it("ships a stable set of named glyphs", () => {
+    for (const name of ["home", "list", "users", "shield", "settings", "audit", "hub"]) {
+      expect(ICON_GLYPHS[name], name).toBeDefined();
+    }
+  });
+});
+
+describe("TerpMark", () => {
+  it("is a decorative, token-coloured placeholder mark", () => {
+    const { container } = render(<TerpMark />);
+    const svg = container.querySelector("svg");
+    expect(svg).not.toBeNull();
+    expect(svg).toHaveAttribute("aria-hidden", "true");
+    expect(container.innerHTML).toContain("var(--color-brand-primary)");
+  });
+});