@terpjs/react-core 0.7.0 → 0.9.0

package/src/router.test.tsx

@@ -5,7 +5,13 @@ import { useEffect, useState } from "react";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import type { ModuleManifest } from "@terpjs/contract";
 
-import { buildAppRouter, useRouteParam, useRouteParams, useTerpNavigate } from "./router";
+import {
+  buildAppRouter,
+  useRouteParam,
+  useRouteParams,
+  useRouteSearch,
+  useTerpNavigate,
+} from "./router";
 import { Page } from "./Page";
 import { TerpProvider, useAuth } from "./TerpProvider";
 
@@ -303,6 +309,190 @@ describe("buildAppRouter", () => {
     );
   });
 
+  it("useRouteSearch reads the route's declared query-string keys, absent ones as undefined", async () => {
+    // The hole this closes: a list screen's filters live in the query string, so before
+    // search was declarable EVERY filtered screen left the typed seam for the router's own
+    // useSearch — losing path and param checking too, on the majority of screens.
+    vi.stubGlobal("fetch", sessionFetch());
+
+    function ListView() {
+      const { status, page } = useRouteSearch("/records");
+      return (
+        <Page title="Records">
+          <p>{`status=${status ?? "-"} page=${page ?? "-"}`}</p>
+        </Page>
+      );
+    }
+    render(
+      <TerpProvider baseUrl="https://api.test">
+        <LogInOnMount />
+        <RouterProvider
+          router={buildAppRouter(
+            [
+              {
+                name: "records",
+                routes: [{ path: "/records", view: "List", search: ["status", "page"] }],
+              },
+            ],
+            {
+              views: { List: ListView },
+              title: "Terp",
+              history: createMemoryHistory({ initialEntries: ["/records?status=open"] }),
+            },
+          )}
+        />
+      </TerpProvider>,
+    );
+
+    // `status` came from the URL; `page` is declared but unset, which is `undefined` rather
+    // than a missing key a screen has to guard.
+    expect(await screen.findByText("status=open page=-")).toBeInTheDocument();
+  });
+
+  it("useRouteSearch returns only declared keys, so a stray URL key cannot reach a screen", async () => {
+    vi.stubGlobal("fetch", sessionFetch());
+
+    function ListView() {
+      const search = useRouteSearch("/records") as Record<string, string | undefined>;
+      return <Page title="Records">{`keys=${Object.keys(search).join(",") || "none"}`}</Page>;
+    }
+    render(
+      <TerpProvider baseUrl="https://api.test">
+        <LogInOnMount />
+        <RouterProvider
+          router={buildAppRouter(
+            [{ name: "records", routes: [{ path: "/records", view: "List", search: ["status"] }] }],
+            {
+              views: { List: ListView },
+              title: "Terp",
+              history: createMemoryHistory({
+                initialEntries: ["/records?status=open&smuggled=yes"],
+              }),
+            },
+          )}
+        />
+      </TerpProvider>,
+    );
+
+    expect(await screen.findByText("keys=status")).toBeInTheDocument();
+  });
+
+  it("useRouteSearch refuses a path the router never mounted, naming what is mounted", async () => {
+    vi.stubGlobal("fetch", sessionFetch());
+
+    function ListView() {
+      // A silently empty bag would hand the screen `undefined` for every key it asked
+      // for, which reads as "no filters applied" — the failure this refusal replaces.
+      let message = "no refusal";
+      try {
+        (useRouteSearch as (path: string) => unknown)("/typo");
+      } catch (error) {
+        message = (error as Error).message;
+      }
+      return <Page title="Records">{message}</Page>;
+    }
+    render(
+      <TerpProvider baseUrl="https://api.test">
+        <LogInOnMount />
+        <RouterProvider
+          router={buildAppRouter([{ name: "records", routes: [{ path: "/records", view: "List" }] }], {
+            views: { List: ListView },
+            title: "Terp",
+            history: createMemoryHistory({ initialEntries: ["/records"] }),
+          })}
+        />
+      </TerpProvider>,
+    );
+
+    expect(await screen.findByText(/is not a mounted route/)).toBeInTheDocument();
+    expect(screen.getByText(/mounted: \/records/)).toBeInTheDocument();
+  });
+
+  it("useTerpNavigate carries search onto the URL, and clearing a key removes it", async () => {
+    // Replace, not merge (ADR 0096): clearing a filter means sending the key as
+    // undefined, and a merge would keep the old value — so "clear" would not clear.
+    vi.stubGlobal("fetch", sessionFetch());
+
+    function ListView() {
+      const navigate = useTerpNavigate();
+      const { status } = useRouteSearch("/records");
+      return (
+        <Page title="Records">
+          <p>{`status=${status ?? "-"}`}</p>
+          <button
+            type="button"
+            onClick={() => void navigate({ to: "/records", search: { status: "open" } })}
+          >
+            filter open
+          </button>
+          <button
+            type="button"
+            onClick={() => void navigate({ to: "/records", search: { status: undefined } })}
+          >
+            clear
+          </button>
+        </Page>
+      );
+    }
+    render(
+      <TerpProvider baseUrl="https://api.test">
+        <LogInOnMount />
+        <RouterProvider
+          router={buildAppRouter(
+            [{ name: "records", routes: [{ path: "/records", view: "List", search: ["status"] }] }],
+            {
+              views: { List: ListView },
+              title: "Terp",
+              history: createMemoryHistory({ initialEntries: ["/records"] }),
+            },
+          )}
+        />
+      </TerpProvider>,
+    );
+
+    fireEvent.click(await screen.findByRole("button", { name: "filter open" }));
+    await waitFor(() => expect(screen.getByText("status=open")).toBeInTheDocument());
+
+    fireEvent.click(screen.getByRole("button", { name: "clear" }));
+    await waitFor(() => expect(screen.getByText("status=-")).toBeInTheDocument());
+  });
+
+  it("a second composed router does not inherit the first one's declared searches", async () => {
+    // The declarations are published per router through a context, not a module-level
+    // table: a shared table would let one app embedding another (or one test process
+    // composing two) read routes it never mounted.
+    vi.stubGlobal("fetch", sessionFetch());
+    buildAppRouter([{ name: "a", routes: [{ path: "/a", view: "V", search: ["x"] }] }], {
+      views: { V: () => <Page title="A">a</Page> },
+      title: "Terp",
+      history: createMemoryHistory({ initialEntries: ["/a"] }),
+    });
+
+    function BView() {
+      let message = "no refusal";
+      try {
+        (useRouteSearch as (path: string) => unknown)("/a");
+      } catch (error) {
+        message = (error as Error).message;
+      }
+      return <Page title="B">{message}</Page>;
+    }
+    render(
+      <TerpProvider baseUrl="https://api.test">
+        <LogInOnMount />
+        <RouterProvider
+          router={buildAppRouter([{ name: "b", routes: [{ path: "/b", view: "V" }] }], {
+            views: { V: BView },
+            title: "Terp",
+            history: createMemoryHistory({ initialEntries: ["/b"] }),
+          })}
+        />
+      </TerpProvider>,
+    );
+
+    expect(await screen.findByText(/"\/a" is not a mounted route/)).toBeInTheDocument();
+  });
+
   it("gives breadcrumbs and hub cards the router's link without being asked", async () => {
     // A crumb rendered without `renderLink` used to fall back to a raw <a href>: a full
     // page reload, silently, with nothing to catch it. Inside a Terp router the default

package/src/router.tsx

@@ -7,6 +7,7 @@ import {
   useNavigate,
   useParams,
   useRouter,
+  useSearch,
   type AnyRoute,
   type RouterHistory,
 } from "@tanstack/react-router";
@@ -21,11 +22,18 @@ import type {
   TerpRouteParamName,
   TerpRouteParams,
   TerpRoutePath,
+  TerpRouteSearch,
 } from "./routeTypes";
 import { LAYOUT_CONTRACTS, LayoutContractContext } from "./layoutContract";
 import { visibleNav } from "./nav";
 import { NavLinkContext } from "./navLink";
 import { PageMarkerContext } from "./pageMarker";
+import {
+  RouteSearchContext,
+  declaredSearchKeys,
+  indexSearchKeys,
+  useRouteSearchIndex,
+} from "./routeSearch";
 import { useAuth } from "./TerpProvider";
 import { UserMenu } from "./UserMenu";
 import { useStrings } from "./uiText";
@@ -169,9 +177,56 @@ export function useTerpNavigate(): (target: TerpNavigateTarget) => Promise<void>
       // runtime TanStack types `params` as a reducer (or `true`), and merging over the
       // previous params is also the honest semantic for an in-place param change.
       params: (previous: Record<string, unknown>) => ({ ...previous, ...(target.params ?? {}) }),
+      // Search is REPLACED, not merged (ADR 0096). Merging reads as convenient and is the
+      // wrong default for the case this exists to serve: clearing a filter means sending
+      // the key as undefined, and a merge would keep the old value instead — so "clear"
+      // would silently not clear. A screen that wants to keep other keys passes them,
+      // which is also the only form that stays checkable against the declared key set.
+      search: dropUndefined(target.search),
     });
 }
 
+/**
+ * Drop `undefined` values so a cleared filter leaves the URL instead of appearing as
+ * `?status=undefined`, and an all-cleared search yields a bare path.
+ */
+function dropUndefined(
+  search: Record<string, string | undefined> | undefined,
+): Record<string, string> {
+  const kept: Record<string, string> = {};
+  for (const [key, value] of Object.entries(search ?? {})) {
+    if (value !== undefined) {
+      kept[key] = value;
+    }
+  }
+  return kept;
+}
+
+/**
+ * Read the current route's declared query-string keys (ADR 0096).
+ *
+ * ```tsx
+ * const { status, page } = useRouteSearch("/records");
+ * ```
+ *
+ * Every key is `string | undefined`, because a query parameter is text and is absent
+ * until someone sets it — so a screen destructures with defaults rather than branching on
+ * a bag of `unknown`. Reading a key the route did not declare is a typecheck error once
+ * `terp routes` has generated; before that the shape is loose, exactly like the params
+ * helpers. Undeclared keys present in the URL are **not** returned: the declaration is the
+ * surface, so a stray key someone hand-typed cannot leak into a screen's logic.
+ */
+export function useRouteSearch<P extends TerpRoutePath>(path: P): TerpRouteSearch<P> {
+  const search = useSearch({ strict: false }) as Record<string, unknown>;
+  const declared = declaredSearchKeys(useRouteSearchIndex(), path);
+  const resolved: Record<string, string | undefined> = {};
+  for (const name of declared) {
+    const value = search[name];
+    resolved[name] = typeof value === "string" ? value : undefined;
+  }
+  return resolved as TerpRouteSearch<P>;
+}
+
 export interface BuildAppRouterOptions {
   /** Maps a manifest route's `view` id to the component that renders it. */
   views: Record<string, ComponentType>;
@@ -251,6 +306,15 @@ export function buildAppRouter(
     );
   }
 
+  // The runtime half of the search declaration (ADR 0096): the generated table is types
+  // only, so `useRouteSearch` reads the keys from the manifests this router was built from,
+  // published per router through a context (never a module-level table, which every router
+  // in the process would share).
+  const searchKeys = new Map(indexSearchKeys(manifests));
+  if (!searchKeys.has(PROFILE_PATH)) {
+    searchKeys.set(PROFILE_PATH, []);
+  }
+
   function Shell() {
     const router = useRouter();
     const rank = useAuth().currentUser()?.role_rank ?? null;
@@ -265,18 +329,15 @@ export function buildAppRouter(
         logo={options.logo}
         footer={options.footer}
         nav={nav}
-        renderBrandLink={({ to, children, style }) => (
-          <Link to={to} data-terp="appshell-brand" style={style}>
+        renderBrandLink={({ to, children }) => (
+          <Link to={to} data-terp="appshell-brand">
             {children}
           </Link>
         )}
-        renderLink={(item, children, context) => (
-          <Link
-            to={item.to}
-            style={context.style}
-            activeProps={{ style: { ...context.style, ...context.activeStyle } }}
-            activeOptions={{ exact: item.to === "/" }}
-          >
+        // No style objects and no activeProps: the shell's stylesheet owns the link
+        // geometry and keys the active route on aria-current="page", which Link sets.
+        renderLink={(item, children) => (
+          <Link to={item.to} activeOptions={{ exact: item.to === "/" }}>
             {children}
           </Link>
         )}
@@ -333,15 +394,17 @@ export function buildAppRouter(
         return <Unauthorized />;
       }
       return (
-        <LayoutContractContext.Provider value={layoutContract}>
-          <PageMarkerContext.Provider
-            value={() => {
-              marked.current = true;
-            }}
-          >
-            <View />
-          </PageMarkerContext.Provider>
-        </LayoutContractContext.Provider>
+        <RouteSearchContext.Provider value={searchKeys}>
+          <LayoutContractContext.Provider value={layoutContract}>
+            <PageMarkerContext.Provider
+              value={() => {
+                marked.current = true;
+              }}
+            >
+              <View />
+            </PageMarkerContext.Provider>
+          </LayoutContractContext.Provider>
+        </RouteSearchContext.Provider>
       );
     }
     return createRoute({

package/src/sso.test.tsx

@@ -120,9 +120,12 @@ describe("SSO login (ADR 0058)", () => {
       </TerpProvider>,
     );
 
-    await waitFor(() =>
-      expect(screen.getByText("Single sign-on failed. Try again.")).toBeInTheDocument(),
-    );
+    // Announced, not merely displayed. This is the one screen whose user is not signed in
+    // yet, so a failure they cannot see leaves them with no signal at all that the sign-in
+    // did not happen — the form simply sits there. ResourceList's error has carried
+    // role="alert" since it existed; this one carried nothing.
+    const failure = await screen.findByRole("alert");
+    expect(failure).toHaveTextContent("Single sign-on failed. Try again.");
     expect(window.location.pathname).toBe("/");
   });
 });

package/src/ssr.test.tsx

@@ -24,9 +24,7 @@ describe("server rendering", () => {
       <AppShell
         title="Terp"
         nav={[{ label: "Home", to: "/", icon: "home" }]}
-        renderLink={(item, children, context) => (
-          <a href={item.to} style={context.style}>{children}</a>
-        )}
+        renderLink={(item, children) => <a href={item.to}>{children}</a>}
       >
         <p>content</p>
       </AppShell>,