@terpjs/react-core 0.8.0 → 0.10.0

package/src/router.tsx

@@ -7,12 +7,14 @@ import {
   useNavigate,
   useParams,
   useRouter,
+  useRouterState,
+  useSearch,
   type AnyRoute,
   type RouterHistory,
 } from "@tanstack/react-router";
 import type { ComponentType, ReactNode } from "react";
-import { useEffect, useRef, useState } from "react";
-import type { ModuleManifest } from "@terpjs/contract";
+import { useCallback, useEffect, useRef, useState } from "react";
+import type { ModuleManifest, NavGroup } from "@terpjs/contract";
 
 import { AppShell } from "./AppShell";
 import { ProfileView } from "./ProfileView";
@@ -21,11 +23,24 @@ import type {
   TerpRouteParamName,
   TerpRouteParams,
   TerpRoutePath,
+  TerpRouteSearch,
 } from "./routeTypes";
 import { LAYOUT_CONTRACTS, LayoutContractContext } from "./layoutContract";
-import { visibleNav } from "./nav";
+import {
+  BRAND_FIELDS,
+  resolveLayoutDeclaration,
+  type LayoutDeclaration,
+} from "./layoutDeclaration";
+import { isDeclarationVisible, visibleNav } from "./nav";
 import { NavLinkContext } from "./navLink";
+import type { NavLinkRenderer } 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 +184,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>;
@@ -179,8 +241,51 @@ export interface BuildAppRouterOptions {
   title: string;
   /** Brand mark in the sidebar (any rendered node); default: the placeholder TerpMark. */
   logo?: ReactNode;
+  /**
+   * The dark-theme brand mark ({@link AppShell.logoDark}); the stylesheet picks per appearance.
+   *
+   * Forwarded because it was not, which made it the third slot to exist on the shell and be
+   * unreachable from the entry points every app uses — after `headerActions`, which this ADR's
+   * own Context complains about. This one was worse than unreachable: the project template
+   * instructs every new app to pass `logoDark` to `renderTerpApp`, so the documented example
+   * did not typecheck.
+   */
+  logoDark?: ReactNode;
+  /** Extra header content, rendered before the theme / language controls. */
+  headerActions?: ReactNode;
   /** Footer line under the content; default: a muted line with the app title. */
   footer?: ReactNode;
+  /**
+   * Cap routed content at the published measure, with each page's header on the full track
+   * ({@link AppShell.contentWidth}); default `"full"`, which changes nothing.
+   */
+  contentWidth?: "full" | "measured";
+  /**
+   * App-wide density ({@link AppShell.density}). **No default** — omitting it stamps nothing, so
+   * an app's own `data-density` on `<html>` still reaches the tree.
+   */
+  density?: "comfortable" | "compact";
+  /**
+   * Where the primary navigation lives on desktop ({@link AppShell.navPlacement}): the
+   * full-height `"sidebar"` (default, and what every shell renders today) or `"header"`, a
+   * horizontal row in the header with no sidebar at all. Below the mobile breakpoint both are
+   * the drawer.
+   */
+  navPlacement?: "sidebar" | "header";
+  /**
+   * The app's navigation groups ({@link AppShell.navGroups}), which manifest items reference by
+   * `NavItem.group`. Omit for the flat, unlabelled sidebar every app renders today.
+   *
+   * Prefer {@link BuildAppRouterOptions.layout}: `shell.navGroups` in the app's own
+   * `frontend/layout-contract.json` says the same thing in the one document a tool can read and
+   * rewrite. Declaring the groups in both places is refused rather than silently resolved.
+   *
+   * A duplicate id is refused here rather than tolerated: it is an authoring error with no
+   * legitimate transient form, and composition time is where it can be reported once instead of
+   * on every render. An item naming an *undeclared* group is the opposite case and is not an
+   * error at all — modules ship independently of the app, so `groupNav` lets it fall open.
+   */
+  navGroups?: readonly NavGroup[];
   /** Role-name -> minimum rank; an unknown role is denied (fail closed). */
   roleRanks?: Record<string, number>;
   /** Rendered when the current user may not access a route (default: a simple message). */
@@ -189,10 +294,32 @@ export interface BuildAppRouterOptions {
    * Opt into a slot-typed layout contract (ADR 0079), e.g. `"standard"`: every routed
    * archetype's body slot then accepts only the components the contract allows there,
    * verified at runtime (fail closed) with the same directive message the
-   * `terp/layout-contract` lint rule phrases. Keep it in sync with the app's checked-in
-   * `layout-contract.json` (the lint half). Omit for today's archetype-only behavior.
+   * `terp/layout-contract` lint rule phrases.
+   *
+   * Prefer {@link BuildAppRouterOptions.layout}. This option used to carry the instruction
+   * "keep it in sync with the app's checked-in `layout-contract.json`", which is a defect
+   * written as advice and, since this function began reading that file, worse than stale:
+   * doing what the sentence said is now refused as one fact declared twice, even when the two
+   * agree. Omit both for today's archetype-only behavior.
    */
   layoutContract?: string;
+  /**
+   * The app's checked-in layout declaration (`frontend/layout-contract.json`, imported).
+   *
+   * The file the `terp/layout-contract` lint rule already reads, now read by the runtime half
+   * too, so `contract` is declared once instead of once per half. It also carries the palette
+   * the app opens on and the shell's own shape — `density`, `navPlacement`, `contentWidth` and
+   * the `navGroups` a module's `NavItem.group` names by id — all of which shipped as options
+   * here and were therefore out of reach of anything that edits files rather than code.
+   *
+   * The authoritative list is `TOP_LEVEL_KEYS` and `SHELL_KEYS` in
+   * {@link ./layoutDeclaration}, and the published `layout.manifest.json` beside them. This
+   * sentence is a restatement and has already drifted once.
+   *
+   * Declaring a key here AND passing the matching option is refused — see
+   * {@link resolveLayoutDeclaration}.
+   */
+  layout?: LayoutDeclaration;
   /** Router history (e.g. `createMemoryHistory`); omit for the browser history. */
   history?: RouterHistory;
 }
@@ -226,13 +353,33 @@ function DefaultUnauthorized() {
  * built-in {@link ProfileView} mounts at {@link PROFILE_PATH} unless a manifest claims that
  * path. Wrap the returned router in `<TerpProvider><RouterProvider router={router}/></TerpProvider>`.
  */
+/**
+ * A declared path as the element the shell's slot takes.
+ *
+ * `alt=""` because the mark is decorative here: the shell renders the app's title beside it,
+ * so a name on the image would have a screen reader announce the app twice. That is also what
+ * the template's own commented example does, and what an app hand-writing the option should do.
+ */
+function brandMark(path: string | undefined) {
+  return path === undefined ? undefined : <img src={path} alt="" />;
+}
+
 export function buildAppRouter(
   manifests: readonly ModuleManifest[],
   options: BuildAppRouterOptions,
 ) {
   const roleRanks = options.roleRanks ?? DEFAULT_ROLE_RANKS;
   const Unauthorized = options.unauthorized ?? DefaultUnauthorized;
-  const layoutContract = options.layoutContract ?? null;
+  // The declaration and the options collapse into one set before anything reads them, so
+  // every consumer below sees a single answer per key and cannot pick a different precedence.
+  const layout = resolveLayoutDeclaration(options.layout, {
+    contract: options.layoutContract,
+    density: options.density,
+    navPlacement: options.navPlacement,
+    contentWidth: options.contentWidth,
+    navGroups: options.navGroups,
+  });
+  const layoutContract = layout.contract ?? null;
   if (layoutContract !== null && LAYOUT_CONTRACTS[layoutContract] === undefined) {
     throw new Error(
       `Unknown layout contract "${layoutContract}"; known contracts: ` +
@@ -240,6 +387,40 @@ export function buildAppRouter(
         ".",
     );
   }
+  // An authoring error with no legitimate transient form, so it is refused here rather than
+  // absorbed. `groupNav` itself stays total — first declaration wins — because it runs on every
+  // render and a render must not be able to throw; this runs once, when the app is composed.
+  // Deliberately NOT symmetrical with an item naming an undeclared group, which is not an error
+  // at all: a module ships on its own schedule, so that is the normal state of an app mid-adoption
+  // and it falls open.
+  // Over the RESOLVED list, so one refusal covers a group declared in the file and a group
+  // passed as an option alike — which is also why `resolveLayoutDeclaration` does not restate it.
+  // The brand's two slots, each declarable as a checked-in PATH or passed as a rendered
+  // element. Refused together for the reason every other doubly-declared key is, and refused
+  // HERE rather than in the resolver because a path and an element are not comparable values:
+  // the resolver's message names both, and there is nothing to name on the code side but the
+  // fact that something was passed.
+  const brandConflicts = BRAND_FIELDS.filter(
+    (slot) => layout.brand?.[slot] !== undefined && options[slot] !== undefined,
+  );
+  if (brandConflicts.length > 0) {
+    throw new Error(
+      `frontend/layout-contract.json declares shell.brand.${brandConflicts.join(" and shell.brand.")}` +
+        ` and the bootstrap options pass ${brandConflicts.join(" and ")}. Declare each mark in ` +
+        "one place: the file is what a tool can read and rewrite, so prefer it and drop the option.",
+    );
+  }
+
+  const duplicateGroups = (layout.navGroups ?? [])
+    .map((group) => group.id)
+    .filter((id, index, ids) => ids.indexOf(id) !== index);
+  if (duplicateGroups.length > 0) {
+    throw new Error(
+      "Terp navGroups declare duplicate id(s): " +
+        [...new Set(duplicateGroups)].join(", ") +
+        ". Each group id is referenced by NavItem.group and must be declared once.",
+    );
+  }
   const missingViews = manifests.flatMap((manifest) =>
     manifest.routes
       .filter((route) => options.views[route.view] === undefined)
@@ -251,29 +432,86 @@ 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;
-    const nav = visibleNav(manifests, (role) => allows(roleRanks, rank, role));
+    const user = useAuth().currentUser();
+    const rank = user?.role_rank ?? null;
+    const nav = visibleNav(manifests, {
+      canSeeRole: (role) => allows(roleRanks, rank, role),
+      permissions: user?.permissions ?? [],
+    });
+    // The shell decides which nav item is current and needs the path to do it. Selected, so the
+    // subscription re-renders only when the pathname itself changes — the same mechanism
+    // ModuleNav already uses.
+    const pathname = useRouterState({ select: (state) => state.location.pathname });
+    // Memoised, and this is a fix for a regression the line above introduces rather than
+    // tidying. `Shell` used to re-render only when `useAuth()` changed; it now re-renders on
+    // every navigation. `Outlet` is memoised with no props, so a re-render alone bails out at
+    // that boundary and the routed subtree is untouched — but a CONTEXT VALUE punches straight
+    // through a memo bailout, and this value is used as a component (Breadcrumbs and HubCard
+    // render it through useNavLink), so an unstable identity is worse than a re-render: it
+    // remounts every in-app link in the tree on each navigation.
+    const renderNavLink = useCallback<NavLinkRenderer>(
+      ({ to, children, attributes }) => (
+        <Link to={to} {...attributes}>
+          {children}
+        </Link>
+      ),
+      [],
+    );
     return (
       // Publish the router's Link so every layout component that renders an in-app link
       // (Breadcrumbs, HubCard) navigates client-side by default. Forgetting `renderLink`
       // used to degrade the app silently: a raw anchor, a full page reload, no error.
-      <NavLinkContext.Provider value={({ to, children }) => <Link to={to}>{children}</Link>}>
+      <NavLinkContext.Provider value={renderNavLink}>
       <AppShell
         title={options.title}
-        logo={options.logo}
+        logo={brandMark(layout.brand?.logo) ?? options.logo}
+        logoDark={brandMark(layout.brand?.logoDark) ?? options.logoDark}
+        headerActions={options.headerActions}
         footer={options.footer}
+        contentWidth={layout.contentWidth}
+        density={layout.density}
+        navPlacement={layout.navPlacement}
+        activePath={pathname}
         nav={nav}
+        navGroups={layout.navGroups}
         renderBrandLink={({ to, children }) => (
           <Link to={to} data-terp="appshell-brand">
             {children}
           </Link>
         )}
-        // 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 === "/" }}>
+        // No style objects and no activeProps: the shell's stylesheet owns the link geometry
+        // and keys the active route on aria-current="page".
+        //
+        // The shell supplies that attribute now, and `exact: true` is what makes the router
+        // agree instead of arguing. Two facts combine. `aria-current` is not among the props
+        // useLinkProps destructures, so a value passed here survives into the rendered anchor;
+        // and the router's own active props are spread LAST, but only when it considers the link
+        // active. With exact matching, "the router considers it active" implies the link's path
+        // equals the URL — which is the longest possible match, so it is always the same item
+        // the shell picked. The router can therefore only ever agree, never add a second
+        // current item.
+        //
+        // Prefix matching is what broke that: it marked every ancestor active, so `/settings`
+        // and `/settings/users` were both current at `/settings/users`. The old
+        // `exact: item.to === "/"` was a workaround for the same thing at the root, and it is
+        // gone because the shell's predicate matches on segments and `/` claims nothing else.
+        renderLink={(item, children, { active }) => (
+          <Link
+            to={item.to}
+            activeOptions={{ exact: true }}
+            aria-current={active ? "page" : undefined}
+          >
             {children}
           </Link>
         )}
@@ -295,12 +533,21 @@ export function buildAppRouter(
   function guardedRoute(
     path: string,
     View: ComponentType,
-    role: string | undefined,
+    declaration: { role?: string; permission?: string },
     viewName: string,
   ): AnyRoute {
     function RouteComponent() {
-      const rank = useAuth().currentUser()?.role_rank ?? null;
-      const allowed = allows(roleRanks, rank, role);
+      const user = useAuth().currentUser();
+      const rank = user?.role_rank ?? null;
+      // The same resolution the sidebar uses, and using it here is what stops `permission` from
+      // becoming a cosmetic gate: hiding a link while leaving its route reachable by URL is not
+      // a weaker version of authorization, it is the appearance of it. `role` has never had that
+      // asymmetry — it is declared on both NavItem and ModuleRoute — so `permission` does not
+      // get to introduce one.
+      const allowed = isDeclarationVisible(declaration, {
+        canSeeRole: (role) => allows(roleRanks, rank, role),
+        permissions: user?.permissions ?? [],
+      });
       // The runtime half of the "every routed view is a page archetype" control: Page
       // (composed by OverviewPage / DetailPage / HubPage) marks the render; a routed view
       // that mounted without any archetype in its tree is refused, fail closed. The check
@@ -330,15 +577,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({
@@ -350,14 +599,14 @@ export function buildAppRouter(
 
   const childRoutes: AnyRoute[] = manifests.flatMap((manifest) =>
     manifest.routes.map((route) =>
-      guardedRoute(route.path, options.views[route.view]!, route.role, route.view),
+      guardedRoute(route.path, options.views[route.view]!, route, route.view),
     ),
   );
   const profileClaimed = manifests.some((manifest) =>
     manifest.routes.some((route) => route.path === PROFILE_PATH),
   );
   if (!profileClaimed) {
-    childRoutes.push(guardedRoute(PROFILE_PATH, ProfileView, undefined, "profile"));
+    childRoutes.push(guardedRoute(PROFILE_PATH, ProfileView, {}, "profile"));
   }
 
   const routeTree = rootRoute.addChildren(childRoutes);

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("/");
   });
 });