@terpjs/react-core 0.8.0 → 0.9.0

package/src/ResourceList.tsx

@@ -1,5 +1,5 @@
 import { useState } from "react";
-import type { CSSProperties, FormEvent, ReactNode } from "react";
+import type { FormEvent, ReactNode } from "react";
 
 import { Authorized } from "./Authorized";
 import { useErrorMessage } from "./errorMessages";
@@ -9,19 +9,6 @@ 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;
@@ -52,6 +39,10 @@ export interface ResourceListProps<T extends { id: string }> {
  *
  * It is a composable component, not a hidden CRUD DSL: a screen that needs more just renders its own
  * React and ignores this.
+ *
+ * It renders no inline styles: the section, the create row, both messages, the list and the
+ * rows take their geometry and ink from the injected react-core sheet, matched on the
+ * `data-terp` markers stamped below (ADR 0094).
  */
 export function ResourceList<T extends { id: string }>({
   title,
@@ -81,37 +72,35 @@ export function ResourceList<T extends { id: string }>({
   }
 
   return (
-    <section
-      data-terp="resource-list"
-      style={{ display: "grid", gap: "var(--space-4)", maxWidth: "40rem" }}
-    >
+    <section data-terp="resource-list">
       {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)" }}>
+          <form onSubmit={onCreate} data-terp="resource-list-create">
             <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)" }}>
+        <p role="alert" data-terp="resource-list-error">
           {messageForCode(resource.cause) ?? resource.error}
         </p>
       )}
       {resource.items.length === 0 ? (
-        <p style={mutedStyle}>{resource.loading ? strings.loading : resolve(emptyMessage ?? strings.emptyList)}</p>
+        <p data-terp="resource-list-empty">
+          {resource.loading ? strings.loading : resolve(emptyMessage ?? strings.emptyList)}
+        </p>
       ) : (
-        <ul style={{ listStyle: "none", margin: 0, padding: 0, display: "grid", gap: "var(--space-2)" }}>
+        <ul data-terp="resource-list-items">
           {resource.items.map((item) => (
-            <li key={item.id} style={rowStyle}>
+            <li key={item.id} data-terp="resource-list-row">
               <div>{renderItem(item)}</div>
               {renderActions && <Authorized action="write">{renderActions(item)}</Authorized>}
             </li>

package/src/admin/AuditLogAdmin.tsx

@@ -46,15 +46,6 @@ function buildColumns(strings: TerpStrings): DataViewColumn<AuditEventRead>[] {
   ];
 }
 
-const payloadStyle = {
-  margin: 0,
-  padding: "var(--space-3)",
-  background: "var(--color-neutral-100)",
-  borderRadius: "var(--radius-md)",
-  fontSize: "var(--font-size-sm, 0.875rem)",
-  overflowX: "auto" as const,
-};
-
 /**
  * The packaged audit-log screen (`/admin/audit`): the append-only trail every
  * mutation lands in (ADR 0007), newest first as served, read-only by design.
@@ -106,7 +97,7 @@ export function AuditLogAdmin() {
               ]}
             />
             {event.payload !== null && (
-              <pre style={payloadStyle}>{JSON.stringify(event.payload, null, 2)}</pre>
+              <pre data-terp="admin-payload">{JSON.stringify(event.payload, null, 2)}</pre>
             )}
           </div>
         )}

package/src/admin/GroupCreate.tsx

@@ -75,7 +75,7 @@ export function GroupCreate() {
         />
       }
     >
-      <div style={{ maxWidth: "32rem" }}>
+      <div data-terp="admin-form">
         <Stack id={FORM_ID} as="form" gap={4} onSubmit={onSubmit}>
           <Field label={strings.groupName}>
             <Input value={name} onChange={(event) => setName(event.target.value)} required />

package/src/admin/GroupDetail.tsx

@@ -339,7 +339,7 @@ export function GroupDetail() {
           />
         )}
         <Stack gap={3}>
-          <h2 style={{ margin: 0, fontSize: "var(--font-size-base)" }}>
+          <h2 data-terp="admin-section-title">
             {strings.members}
           </h2>
           <Stack as="form" direction="row" gap={2} align="end" wrap onSubmit={onAddMember}>
@@ -376,7 +376,7 @@ export function GroupDetail() {
           />
         </Stack>
         <Stack gap={3}>
-          <h2 style={{ margin: 0, fontSize: "var(--font-size-base)" }}>
+          <h2 data-terp="admin-section-title">
             {strings.permissions}
           </h2>
           <Stack as="form" direction="row" gap={2} align="end" wrap onSubmit={onGrant}>

package/src/admin/UserCreate.tsx

@@ -81,7 +81,7 @@ export function UserCreate() {
         />
       }
     >
-      <div style={{ maxWidth: "32rem" }}>
+      <div data-terp="admin-form">
         <Stack id={FORM_ID} as="form" gap={4} onSubmit={onSubmit}>
           <Field label={strings.email}>
             <Input

package/src/admin/admin.test.tsx

@@ -418,6 +418,15 @@ describe("the packaged admin area", () => {
     fireEvent.click(screen.getByRole("button", { name: "Provision user" }));
     await screen.findByRole("heading", { level: 1, name: "Provision user" });
 
+    // The form's measure is a sheet rule now (ADR 0094), and this is the only gate on it:
+    // no admin screen has a specimen, so nothing pictures these three surfaces. What a test
+    // can hold is that the marked element is there and styles nothing itself; that the rule
+    // exists is held by styles.test.ts, and its values are a verbatim copy of the object
+    // this replaced.
+    const form = document.querySelector('[data-terp="admin-form"]');
+    expect(form).not.toBeNull();
+    expect(form?.getAttribute("style")).toBeNull();
+
     fireEvent.change(screen.getByLabelText("Email"), {
       target: { value: "new.account@example.com" },
     });
@@ -510,6 +519,28 @@ describe("the packaged admin area", () => {
     );
   });
 
+  it("marks the detail sections it no longer styles inline", async () => {
+    // The second of the three surfaces the admin views used to style at the call site. Same
+    // reasoning as the create form above: markers plus the absence of a style attribute,
+    // because no admin screen has a specimen.
+    //
+    // The third, the audit payload, has no assertion here and it is worth saying why rather
+    // than quietly having none: the audit fixture serves an empty page, so no row exists to
+    // expand and the <pre> never renders in any test. Giving it one means adding rows to a
+    // fixture several tests share, which is not a change a styling migration should make.
+    // It is held by styles.test.ts (the rule exists) and by the values being a verbatim copy.
+    renderAdminApp("/admin/groups/g1");
+    const headings = await waitFor(() => {
+      const found = document.querySelectorAll('[data-terp="admin-section-title"]');
+      expect(found.length).toBe(2);
+      return found;
+    });
+    for (const heading of headings) {
+      expect(heading.tagName).toBe("H2");
+      expect(heading.getAttribute("style")).toBeNull();
+    }
+  });
+
   it("clears group destructive state when navigating between detail records in place", async () => {
     const { router } = renderAdminApp("/admin/groups/g1");
     await screen.findByRole("heading", { level: 1, name: "Finance" });

package/src/download.test.tsx

@@ -0,0 +1,153 @@
+// @vitest-environment jsdom
+import { cleanup, fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { downloadUrl, saveBlob, useEndpointDownload } from "./download";
+import { TerpProvider } from "./TerpProvider";
+
+// Downloading a *generated* artifact (ADR 0096). The two things a hand-rolled version
+// gets wrong are what these tests pin: a raw `<a href>` carries no bearer token (so it
+// saves an error page under the intended filename), and a raw fetch leaks the object URL.
+
+afterEach(() => {
+  cleanup();
+  vi.unstubAllGlobals();
+  vi.restoreAllMocks();
+  restoreObjectUrl();
+});
+
+// jsdom ships no object-URL implementation, so it is installed per test rather than
+// stubbed over the global `URL` — replacing that breaks the client's own URL building,
+// which is exactly the machinery these tests are here to exercise.
+type ObjectUrlHost = { createObjectURL?: (blob: Blob) => string; revokeObjectURL?: (url: string) => void };
+const objectUrlHost = URL as unknown as ObjectUrlHost;
+const originalCreate = objectUrlHost.createObjectURL;
+const originalRevoke = objectUrlHost.revokeObjectURL;
+
+function installObjectUrl(): { revoked: string[] } {
+  const revoked: string[] = [];
+  objectUrlHost.createObjectURL = () => "blob:x";
+  objectUrlHost.revokeObjectURL = (url: string) => void revoked.push(url);
+  return { revoked };
+}
+
+function restoreObjectUrl(): void {
+  objectUrlHost.createObjectURL = originalCreate;
+  objectUrlHost.revokeObjectURL = originalRevoke;
+}
+
+describe("downloadUrl", () => {
+  it("fills path placeholders and appends only the set query keys", () => {
+    expect(
+      downloadUrl({
+        path: "/api/v1/revisions/{revisionId}/evidence",
+        filename: "x.json",
+        params: { revisionId: "r-1" },
+        query: { format: "json", locale: undefined },
+      }),
+    ).toBe("/api/v1/revisions/r-1/evidence?format=json");
+  });
+
+  it("encodes a param rather than splicing it into the path raw", () => {
+    expect(downloadUrl({ path: "/api/v1/x/{id}", filename: "f", params: { id: "a/b" } })).toBe(
+      "/api/v1/x/a%2Fb",
+    );
+  });
+
+  it("refuses an unfilled placeholder instead of requesting a literal {id}", () => {
+    // Requesting `/revisions/{revisionId}/evidence` would 404 — or, on a permissive
+    // route, hand back somebody else's bytes.
+    expect(() =>
+      downloadUrl({ path: "/api/v1/revisions/{revisionId}/evidence", filename: "x" }),
+    ).toThrow(/still contains the placeholder "\{revisionId\}"/);
+  });
+});
+
+describe("saveBlob", () => {
+  it("offers the bytes under the given filename and revokes the object URL", () => {
+    const { revoked } = installObjectUrl();
+    const clicked: string[] = [];
+    const click = vi
+      .spyOn(HTMLAnchorElement.prototype, "click")
+      .mockImplementation(function (this: HTMLAnchorElement) {
+        clicked.push(this.download);
+      });
+
+    saveBlob(new Blob(["body"]), "evidence.json");
+
+    expect(clicked).toEqual(["evidence.json"]);
+    // Revoked in a `finally`, which is the leak every hand-rolled copy forgets.
+    expect(revoked).toEqual(["blob:x"]);
+    // ...and nothing is left in the document.
+    expect(document.querySelector("a")).toBeNull();
+    click.mockRestore();
+  });
+});
+
+describe("useEndpointDownload", () => {
+  function DownloadButton() {
+    const download = useEndpointDownload();
+    return (
+      <button
+        type="button"
+        onClick={() =>
+          void download({
+            path: "/api/v1/revisions/{revisionId}/evidence",
+            params: { revisionId: "r-1" },
+            filename: "evidence.json",
+          }).catch((error: unknown) => {
+            document.title = (error as Error).message;
+          })
+        }
+      >
+        download
+      </button>
+    );
+  }
+
+  it("fetches through the session client, so the request carries the session", async () => {
+    const fetchMock = vi.fn<typeof fetch>(
+      async () => new Response("bytes", { status: 200, headers: { "content-type": "application/octet-stream" } }),
+    );
+    vi.stubGlobal("fetch", fetchMock);
+    installObjectUrl();
+    const click = vi.spyOn(HTMLAnchorElement.prototype, "click").mockImplementation(() => {});
+
+    render(
+      <TerpProvider baseUrl="https://api.test">
+        <DownloadButton />
+      </TerpProvider>,
+    );
+    fireEvent.click(screen.getByRole("button", { name: "download" }));
+
+    // The provider's own boot session-probe is also on this mock, so match the download
+    // rather than assuming it is the first request.
+    await waitFor(() =>
+      expect(
+        fetchMock.mock.calls.map((call) => (call[0] as Request).url),
+        // Resolved against the client's base URL — the thing a raw <a href> could not do.
+      ).toContain("https://api.test/api/v1/revisions/r-1/evidence"),
+    );
+    click.mockRestore();
+  });
+
+  it("rejects on a non-2xx instead of saving the error body under the filename", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn<typeof fetch>(async () => new Response("nope", { status: 403 })),
+    );
+    const click = vi.spyOn(HTMLAnchorElement.prototype, "click").mockImplementation(() => {});
+
+    render(
+      <TerpProvider baseUrl="https://api.test">
+        <DownloadButton />
+      </TerpProvider>,
+    );
+    fireEvent.click(screen.getByRole("button", { name: "download" }));
+
+    await waitFor(() => expect(document.title).toMatch(/failed with HTTP 403/));
+    // Nothing was handed to the browser: the failure surfaces instead of downloading.
+    expect(click).not.toHaveBeenCalled();
+    click.mockRestore();
+  });
+});

package/src/download.tsx

@@ -0,0 +1,132 @@
+/**
+ * Handing bytes to the browser as a named download (ADR 0096).
+ *
+ * `useFileDownload` covers the stored-file case: a `FileMeta` id, fetched from the files
+ * capability's content endpoint. What it does not cover is the other half of the same
+ * need — **an artifact the backend generates on demand** ("download this revision as
+ * proof", a CSV export, a signed evidence bundle). Those have no stored file id, and the
+ * only ways to reach them were a raw `fetch` (refused: one typed egress path) or a raw
+ * `<a href>` (which carries no bearer token, so it 401s or, worse, silently downloads an
+ * error page). The observed outcome was the feature being dropped rather than built.
+ *
+ * So the blob-to-anchor dance lives here once, and `useEndpointDownload` reaches any
+ * authorized GET through the session client. `path` is a plain string, deliberately and
+ * unusually: the generated client is keyed by the app's own schema, which this package
+ * cannot see, and a byte-stream route is app-specific by nature. Everything else that
+ * matters — the base URL, the bearer token, cookie credentials, the refusal on a non-2xx —
+ * still comes from the client, which is what the raw alternatives threw away.
+ */
+
+import { useCallback } from "react";
+
+import { useTerpClient } from "./TerpProvider";
+import type { TerpClient } from "@terpjs/contract";
+
+/** What to download: where the bytes come from, and what the file should be called. */
+export interface DownloadTarget {
+  /** API path, e.g. `/api/v1/revisions/{id}/evidence` with `params` filling `{id}`. */
+  path: string;
+  /** Filename offered to the browser (extension included). */
+  filename: string;
+  /** Path placeholders to substitute, e.g. `{ id: revision.id }`. */
+  params?: Record<string, string>;
+  /** Query string to append; `undefined` values are omitted. */
+  query?: Record<string, string | undefined>;
+}
+
+/**
+ * Save *blob* as a named download.
+ *
+ * Exported because it is the one piece a screen cannot avoid re-implementing when it
+ * already holds the bytes (a client-side CSV, a canvas export) — and every hand-rolled
+ * copy leaks the object URL, which is why the revoke is in a `finally` here.
+ */
+export function saveBlob(blob: Blob, filename: string): void {
+  const url = URL.createObjectURL(blob);
+  try {
+    const anchor = document.createElement("a");
+    anchor.href = url;
+    anchor.download = filename;
+    document.body.appendChild(anchor);
+    anchor.click();
+    anchor.remove();
+  } finally {
+    URL.revokeObjectURL(url);
+  }
+}
+
+/** Fill `{placeholder}` segments and append the query string, dropping unset values. */
+export function downloadUrl(target: DownloadTarget): string {
+  let path = target.path;
+  for (const [name, value] of Object.entries(target.params ?? {})) {
+    path = path.replaceAll(`{${name}}`, encodeURIComponent(value));
+  }
+  const unfilled = /\{([A-Za-z_][A-Za-z0-9_]*)\}/.exec(path);
+  if (unfilled !== null) {
+    // Fail closed rather than requesting a literal `{id}`: the server would 404 or, on a
+    // permissive route, hand back somebody else's bytes.
+    throw new Error(
+      `Download path "${target.path}" still contains the placeholder "${unfilled[0]}" — ` +
+        `pass it in \`params\` (e.g. params: { ${unfilled[1]}: row.id }).`,
+    );
+  }
+  const query = new URLSearchParams();
+  for (const [name, value] of Object.entries(target.query ?? {})) {
+    if (value !== undefined) {
+      query.append(name, value);
+    }
+  }
+  const suffix = query.toString();
+  return suffix.length > 0 ? `${path}?${suffix}` : path;
+}
+
+/**
+ * Download a generated artifact from an authorized endpoint (ADR 0096).
+ *
+ * ```tsx
+ * const download = useEndpointDownload();
+ * void download({
+ *   path: "/api/v1/revisions/{revisionId}/evidence",
+ *   params: { revisionId: revision.id },
+ *   filename: `revision-${revision.number}.json`,
+ * });
+ * ```
+ *
+ * Rejects on a non-2xx response, so a caller can surface the failure — a raw anchor would
+ * have saved the error body under the intended filename instead.
+ */
+export function useEndpointDownload(): (target: DownloadTarget) => Promise<void> {
+  const client = useTerpClient();
+  return useCallback(
+    async (target: DownloadTarget) => {
+      const blob = await fetchDownload(client as unknown as TerpClient, target);
+      saveBlob(blob, target.filename);
+    },
+    [client],
+  );
+}
+
+/**
+ * Fetch a download target's bytes through the session client.
+ *
+ * Separate from the hook so a caller that wants the blob for something *other* than
+ * saving it (a preview, a checksum) does not have to save it first.
+ */
+export async function fetchDownload(client: TerpClient, target: DownloadTarget): Promise<Blob> {
+  const url = downloadUrl(target);
+  const { data, error, response } = await (
+    client as unknown as {
+      GET: (
+        path: string,
+        init: { parseAs: "blob" },
+      ) => Promise<{ data?: unknown; error?: unknown; response: Response }>;
+    }
+  ).GET(url, { parseAs: "blob" });
+  if (error !== undefined || !response.ok) {
+    throw new Error(
+      `Download of ${url} failed with HTTP ${response.status}. The endpoint must be a GET ` +
+        "the current session is authorized for.",
+    );
+  }
+  return data as Blob;
+}

package/src/files.tsx

@@ -1,6 +1,7 @@
 import { useCallback, useRef, useState } from "react";
 import type { ChangeEvent } from "react";
 
+import { saveBlob } from "./download";
 import { useTerpClient } from "./TerpProvider";
 import { Button } from "./ui/Button";
 import { useStrings, useUiText, type UiText } from "./uiText";
@@ -91,17 +92,7 @@ export function useFileDownload(): (file: Pick<FileMeta, "id" | "filename">) =>
   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);
-      }
+      saveBlob(blob, file.filename);
     },
     [client],
   );

package/src/index.ts

@@ -8,7 +8,7 @@ export { canPerform, DEFAULT_RANK_THRESHOLDS } from "./capabilities";
 export type { RankThresholds } from "./capabilities";
 export { createAuthClient } from "./createAuthClient";
 export type { AuthClientOptions, TokenGetter } from "./createAuthClient";
-export { Authorized, useCan } from "./Authorized";
+export { Authorized, useCan, useHasPermission, usePermissions } from "./Authorized";
 export type { AuthorizedProps } from "./Authorized";
 export { useResource } from "./useResource";
 export type { Resource, ResourceSource } from "./useResource";
@@ -109,6 +109,8 @@ export { Alert } from "./ui/Alert";
 export type { AlertProps, AlertTone } from "./ui/Alert";
 export { Markdown } from "./ui/Markdown";
 export type { MarkdownProps } from "./ui/Markdown";
+export { saveBlob, useEndpointDownload, fetchDownload, downloadUrl } from "./download";
+export type { DownloadTarget } from "./download";
 export { Field } from "./Field";
 export type { FieldProps } from "./Field";
 export { Stack, DetailList } from "./layout";
@@ -119,6 +121,7 @@ export {
   PROFILE_PATH,
   useRouteParam,
   useRouteParams,
+  useRouteSearch,
   useTerpNavigate,
 } from "./router";
 export type { BuildAppRouterOptions } from "./router";
@@ -129,6 +132,9 @@ export type {
   TerpRouteParamName,
   TerpRouteParams,
   TerpRoutePath,
+  TerpRouteSearch,
+  TerpRouteSearchKey,
+  TerpRouteSearchTable,
   TerpRouteTable,
 } from "./routeTypes";
 export { LoginView } from "./LoginView";