@terpjs/react-core 0.5.3 → 0.5.4

package/README.md

@@ -70,7 +70,7 @@ runtime, fail closed (ADR 0059), so every screen keeps the breadcrumb/title/erro
 | `HubPage`, `HubCard` | Responsive `auto-fit` landing grid. Cards share equal outer and internal tracks even when descriptions/stats differ; nested hubs use the ordinary breadcrumb contract via `parents`. |
 | `OverviewPage` | A module's top-level listing screen (level 2); detail pages crumb back to it. |
 | `DetailPage` | One record's screen (level 3); breadcrumb trail = ancestors + record title. |
-| `Breadcrumbs` | The trail itself (used by the archetypes; rarely composed directly). |
+| `Breadcrumbs` | The trail itself (used by the archetypes; rarely composed directly). Ancestor crumbs use the router's `Link` by default — `renderLink` is only for rendering outside a Terp router. |
 | `ModuleNav` | Secondary horizontal tabs for intra-module sub-pages (real routes, not state). |
 | `PageActions` | Primary action + overflow menu for a page header. |
 
@@ -131,7 +131,7 @@ marker, counted by the escape-hatch budget.
 | `Radio`, `RadioGroup` | Labelled radio and accessible grouped radio options with controlled or uncontrolled value. |
 | `Switch` | Labelled boolean toggle (`role="switch"`) with `checked` / `defaultChecked` and boolean `onChange`. |
 | `Tabs` | In-page (non-routed) tab set with `tablist` / `tab` / `tabpanel` roles, arrow-key navigation, and controlled or uncontrolled value. |
-| `Badge` | Small status pill (`tone`: neutral / info / success / warning / danger). |
+| `Badge` | Small status pill: `<Badge tone="success">Synced</Badge>` (or `label="Synced"`); `tone`: neutral / info / success / warning / danger. |
 | `Tooltip` | Accessible focus/hover tooltip that describes its trigger with `aria-describedby`. |
 | `Popover`, `Menu`, `MenuItem` | Shared anchored overlay and dropdown-menu primitives: body-portaled, viewport-aware panels that escape scroll/table clipping, with outside-click/Escape close, focus return, selected-item semantics, and roving keyboard navigation. |
 | `Alert` | Inline banner for persistent feedback (`tone`: neutral / info / success / warning / danger); warnings and danger announce as `alert`, others as `status`. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@terpjs/react-core",
-  "version": "0.5.3",
+  "version": "0.5.4",
   "type": "module",
   "description": "Terp React stack core — typed @terpjs/contract client provider, auth session, capability gates, TanStack Router adapter, app shell, page archetypes, DataView and token-styled UI primitives. First frontend stack; see README.md for the component catalog.",
   "exports": {
@@ -13,7 +13,7 @@
   },
   "dependencies": {
     "@tanstack/react-router": "^1.170.16",
-    "@terpjs/contract": "^0.5.3"
+    "@terpjs/contract": "^0.5.4"
   },
   "peerDependencies": {
     "react": "^18.3.0 || ^19.0.0",

package/src/Breadcrumbs.tsx

@@ -1,6 +1,7 @@
 import type { CSSProperties, ReactNode } from "react";
 
 import { injectTerpStyles } from "./styles";
+import { useNavLink } from "./navLink";
 import { useStrings, useUiText } from "./uiText";
 import type { UiText } from "./uiText";
 
@@ -20,7 +21,11 @@ export type RenderBreadcrumbLink = (item: { label: string; to: string }) => Reac
 export interface BreadcrumbsProps {
   /** The trail, outermost first; the last item is the current page. */
   items: readonly BreadcrumbItem[];
-  /** Link renderer for ancestor crumbs (default: a plain `<a href>`); pass the stack's `Link`. */
+  /**
+   * Link renderer for ancestor crumbs. Defaults to the surrounding router's `Link`
+   * (published by `buildAppRouter`), falling back to a plain `<a href>` only outside a
+   * Terp router — a crumb inside an app must never full-page-reload.
+   */
   renderLink?: RenderBreadcrumbLink;
 }
 
@@ -69,7 +74,7 @@ function ChevronSeparator() {
   );
 }
 
-const defaultRenderLink: RenderBreadcrumbLink = (item) => <a href={item.to}>{item.label}</a>;
+const anchorRenderLink: RenderBreadcrumbLink = (item) => <a href={item.to}>{item.label}</a>;
 
 /**
  * The breadcrumb trail every page shows through the remaining layers (shell -> overview ->
@@ -77,7 +82,13 @@ const defaultRenderLink: RenderBreadcrumbLink = (item) => <a href={item.to}>{ite
  * list, and `aria-current="page"` on the final crumb. Router-agnostic — `renderLink` turns
  * an ancestor crumb into the active stack's link, exactly like `AppShell`'s `renderLink`.
  */
-export function Breadcrumbs({ items, renderLink = defaultRenderLink }: BreadcrumbsProps) {
+export function Breadcrumbs({ items, renderLink }: BreadcrumbsProps) {
+  const navLink = useNavLink();
+  const renderCrumbLink =
+    renderLink ??
+    (navLink === null
+      ? anchorRenderLink
+      : (item: { label: string; to: string }) => navLink({ to: item.to, children: item.label }));
   const strings = useStrings();
   const resolve = useUiText();
   return (
@@ -89,7 +100,7 @@ export function Breadcrumbs({ items, renderLink = defaultRenderLink }: Breadcrum
           return (
             <li key={`${index}-${label}`} style={listStyle}>
               {!isLast && item.to !== undefined ? (
-                renderLink({ label, to: item.to })
+                renderCrumbLink({ label, to: item.to })
               ) : (
                 <span aria-current={isLast ? "page" : undefined} style={isLast ? currentStyle : undefined}>
                   {label}

package/src/HubPage.tsx

@@ -4,6 +4,7 @@ import { useEffect, useRef, useState } from "react";
 import { Page } from "./Page";
 import type { PageProps } from "./Page";
 import { useLayoutContract, verifySlotChildren } from "./layoutContract";
+import { useNavLink } from "./navLink";
 import { injectTerpStyles } from "./styles";
 import { useUiText } from "./uiText";
 import type { UiText } from "./uiText";
@@ -157,7 +158,7 @@ const linkStyle: CSSProperties = {
   minHeight: 0,
 };
 
-const defaultRenderLink: RenderHubCardLink = ({ to, children }) => (
+const anchorRenderLink: RenderHubCardLink = ({ to, children }) => (
   <a href={to} data-terp="hubcard-link" style={linkStyle}>
     {children}
   </a>
@@ -166,7 +167,8 @@ const defaultRenderLink: RenderHubCardLink = ({ to, children }) => (
 /**
  * A single navigable card inside a {@link HubPage}: icon + title, a short description of
  * the area, and an optional live `stat`. The whole card is one link, rendered through
- * `renderLink` so the hub stays router-agnostic.
+ * `renderLink` so the hub stays router-agnostic — defaulting to the surrounding router's
+ * `Link`, and to a plain anchor only outside a Terp router.
  */
 export function HubCard({
   to,
@@ -174,12 +176,22 @@ export function HubCard({
   description,
   icon,
   stat,
-  renderLink = defaultRenderLink,
+  renderLink,
 }: HubCardProps) {
+  const navLink = useNavLink();
+  const renderCardLink =
+    renderLink ??
+    (navLink === null
+      ? anchorRenderLink
+      : ({ to: href, children }: { to: string; children: ReactNode }) => (
+          <span data-terp="hubcard-link" style={linkStyle}>
+            {navLink({ to: href, children })}
+          </span>
+        ));
   const resolve = useUiText();
   return (
     <li data-terp="hubcard" style={cardStyle}>
-      {renderLink({
+      {renderCardLink({
         to,
         children: (
           <span data-terp="hubcard-body" style={cardBodyStyle}>

package/src/Page.tsx

@@ -19,7 +19,7 @@ export interface PageProps {
   title: UiText;
   /** Ancestor breadcrumb trail, outermost first; the current page's crumb is appended automatically. */
   breadcrumbs?: readonly BreadcrumbItem[];
-  /** Link renderer for ancestor crumbs; pass the stack's `Link` (see {@link Breadcrumbs}). */
+  /** Link renderer for ancestor crumbs; defaults to the surrounding router's `Link` (see {@link Breadcrumbs}). */
   renderLink?: RenderBreadcrumbLink;
   /** Optional page-level actions, rendered on the heading row (e.g. a primary `Button`). */
   actions?: ReactNode;

package/src/guide/guideSnippets.tsx

@@ -0,0 +1,41 @@
+// Typechecked guide snippets.
+//
+// `terp guide <topic>` is the first thing the golden rules point an author at, so a
+// snippet in it that does not compile is worse than no snippet at all — this file
+// shipped three lines of a DataView API that never existed. The blocks below are the
+// real code the guide prints, compiled by the workspace typecheck and pinned to the
+// guide text by tests/architecture/test_guide_snippets.py: change one and the other
+// fails. Keep the block bodies byte-identical to the guide (modulo indentation).
+import { useMemo } from "react";
+
+import { DataView, InMemoryDataViewRepository } from "../dataview";
+import type { DataViewColumn } from "../dataview";
+
+interface Row {
+  id: string;
+  title: string;
+  status: string;
+}
+
+export function GuideDataViewSnippet({ rows }: { rows: Row[] }) {
+  const columns: DataViewColumn<Row>[] = [
+    { id: "title", header: "Title", accessor: (r) => r.title },
+    { id: "status", header: "Status", accessor: (r) => r.status },
+  ];
+  // terp-guide-snippet: dataview
+  const repo = useMemo(
+    () =>
+      new InMemoryDataViewRepository(rows, {
+        getRowId: (r) => r.id,
+        getValue: (r, col) => r[col as keyof Row],
+        searchFields: ["title", "status"],
+      }),
+    [rows],
+  );
+  // terp-guide-snippet-end
+  return (
+    // terp-guide-snippet: dataview
+    <DataView repository={repo} columns={columns} viewId="notes.list" />
+    // terp-guide-snippet-end
+  );
+}

package/src/navLink.tsx

@@ -0,0 +1,28 @@
+import { createContext, useContext } from "react";
+import type { ReactNode } from "react";
+
+/**
+ * How the surrounding router renders an in-app link.
+ *
+ * The layout components (`Breadcrumbs`, `HubCard`) are deliberately router-agnostic and
+ * take a `renderLink` prop — but their *default* used to be a raw `<a href>`, which is
+ * the one construct the boundary lint refuses in app code, and which does a full page
+ * reload instead of a client-side navigation. Forgetting the prop therefore produced a
+ * silently degraded app: no error, no lint hit (the anchor lives inside react-core), just
+ * a white flash on every crumb click.
+ *
+ * So `buildAppRouter` publishes the router's own `Link` here, and the components default
+ * to it. The anchor remains only for a component rendered outside any Terp router (a
+ * standalone story or unit test), where there is no router to navigate with.
+ */
+export type NavLinkRenderer = (props: { to: string; children: ReactNode }) => ReactNode;
+
+export const NavLinkContext = createContext<NavLinkRenderer | null>(null);
+
+/**
+ * The ambient link renderer, or `null` outside a Terp router. Callers fall back to a
+ * plain anchor — never silently, always as the documented last resort.
+ */
+export function useNavLink(): NavLinkRenderer | null {
+  return useContext(NavLinkContext);
+}

package/src/router.test.tsx

@@ -85,6 +85,100 @@ describe("buildAppRouter", () => {
     expect(screen.queryByRole("link", { name: "Users" })).not.toBeInTheDocument();
   });
 
+  it("mounts a parameterised route in BOTH spellings the contract documents", async () => {
+    // The manifest is stack-agnostic and documents `:id`; TanStack wants `$id`. Passing
+    // the documented spelling through untranslated built a route that never matched —
+    // and nothing caught it: not the lint, not typecheck, not the build. Pin both.
+    for (const [path, entry] of [
+      ["/things/:thingId", "/things/abc"],
+      ["/legacy/$thingId", "/legacy/abc"],
+    ] as const) {
+      vi.stubGlobal(
+        "fetch",
+        vi.fn<typeof fetch>(async (input) => {
+          const url = (input as Request).url;
+          if (url.endsWith("/api/v1/auth/login")) {
+            return jsonResponse({ access_token: "t", token_type: "bearer" });
+          }
+          return jsonResponse({
+            id: "1",
+            email: "editor@example.com",
+            role_rank: 20,
+            role_name: "editor",
+          });
+        }),
+      );
+      const router = buildAppRouter([{ name: "things", routes: [{ path, view: "Thing" }] }], {
+        views: { Thing: () => <Page title="Thing view">thing body</Page> },
+        title: "Terp",
+        history: createMemoryHistory({ initialEntries: [entry] }),
+      });
+      render(
+        <TerpProvider baseUrl="https://api.test">
+          <LogInOnMount />
+          <RouterProvider router={router} />
+        </TerpProvider>,
+      );
+      await waitFor(() =>
+        expect(screen.getByRole("heading", { name: "Thing view" })).toBeInTheDocument(),
+      );
+      cleanup();
+    }
+  });
+
+  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
+    // is the router's own Link, so the trail navigates client-side.
+    vi.stubGlobal(
+      "fetch",
+      vi.fn<typeof fetch>(async (input) => {
+        const url = (input as Request).url;
+        if (url.endsWith("/api/v1/auth/login")) {
+          return jsonResponse({ access_token: "t", token_type: "bearer" });
+        }
+        return jsonResponse({ id: "1", email: "editor@example.com", role_rank: 20, role_name: "editor" });
+      }),
+    );
+    const router = buildAppRouter(
+      [
+        {
+          name: "notes",
+          routes: [
+            { path: "/notes", view: "NotesList" },
+            { path: "/notes/:noteId", view: "NoteDetail" },
+          ],
+          nav: [],
+        },
+      ],
+      {
+        views: {
+          NotesList: () => <Page title="Notes view">notes body</Page>,
+          NoteDetail: () => (
+            <Page title="Note view" breadcrumbs={[{ label: "Notes", to: "/notes" }]}>
+              note body
+            </Page>
+          ),
+        },
+        title: "Terp",
+        history: createMemoryHistory({ initialEntries: ["/notes/1"] }),
+      },
+    );
+
+    render(
+      <TerpProvider baseUrl="https://api.test">
+        <LogInOnMount />
+        <RouterProvider router={router} />
+      </TerpProvider>,
+    );
+
+    const crumb = await screen.findByRole("link", { name: "Notes" });
+    fireEvent.click(crumb);
+    await waitFor(() =>
+      expect(screen.getByRole("heading", { name: "Notes view" })).toBeInTheDocument(),
+    );
+  });
+
   it("navigates home through the product brand", async () => {
     const fetchMock = vi.fn<typeof fetch>(async (input) => {
       const url = (input as Request).url;

package/src/router.tsx

@@ -16,6 +16,7 @@ import { AppShell } from "./AppShell";
 import { ProfileView } from "./ProfileView";
 import { LAYOUT_CONTRACTS, LayoutContractContext } from "./layoutContract";
 import { visibleNav } from "./nav";
+import { NavLinkContext } from "./navLink";
 import { PageMarkerContext } from "./pageMarker";
 import { useAuth } from "./TerpProvider";
 import { UserMenu } from "./UserMenu";
@@ -31,6 +32,21 @@ export const DEFAULT_ROLE_RANKS: Record<string, number> = {
 /** The built-in profile / settings route (an app manifest claiming the path wins). */
 export const PROFILE_PATH = "/profile";
 
+/**
+ * Translate a manifest path into TanStack Router's dialect.
+ *
+ * `ModuleManifest` is stack-agnostic (the same manifest is meant to drive a SvelteKit
+ * adapter, where a param is `[id]`), so it spells a parameter the neutral way: `:id`.
+ * TanStack wants `$id`. Passing the manifest path through untranslated produced the
+ * worst possible failure — a route that simply never matches, caught by nothing: not
+ * the boundary lint, not typecheck, not the build, just a 404 at runtime for anyone who
+ * followed the documented example. Both spellings are accepted (`$id` is what shipped
+ * before this translation existed and what existing apps wrote); `:id` is canonical.
+ */
+export function routerPath(path: string): string {
+  return path.replace(/(^|\/):([A-Za-z_][A-Za-z0-9_]*)/g, "$1$$$2");
+}
+
 export interface BuildAppRouterOptions {
   /** Maps a manifest route's `view` id to the component that renders it. */
   views: Record<string, ComponentType>;
@@ -115,6 +131,10 @@ export function buildAppRouter(
     const rank = useAuth().currentUser()?.role_rank ?? null;
     const nav = visibleNav(manifests, (role) => allows(roleRanks, rank, role));
     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>}>
       <AppShell
         title={options.title}
         logo={options.logo}
@@ -144,6 +164,7 @@ export function buildAppRouter(
       >
         <Outlet />
       </AppShell>
+      </NavLinkContext.Provider>
     );
   }
 
@@ -200,7 +221,7 @@ export function buildAppRouter(
     }
     return createRoute({
       getParentRoute: () => rootRoute,
-      path,
+      path: routerPath(path),
       component: RouteComponent,
     });
   }

package/src/ui/Badge.test.tsx

@@ -11,4 +11,9 @@ describe("Badge", () => {
     render(<Badge label="Active" tone="success" />);
     expect(screen.getByText("Active").style.color).toContain("var(--color-status-success)");
   });
+
+  it("takes its text as children too, the way every other component does", () => {
+    render(<Badge tone="danger">No drift</Badge>);
+    expect(screen.getByText("No drift").style.color).toContain("var(--color-status-danger)");
+  });
 });

package/src/ui/Badge.tsx

@@ -5,10 +5,18 @@ import type { UiText } from "../uiText";
 
 export type BadgeTone = "neutral" | "info" | "success" | "warning" | "danger";
 
-export interface BadgeProps {
-  label: UiText;
-  tone?: BadgeTone;
-}
+/**
+ * The pill's content, either way round.
+ *
+ * Every other component in the catalog takes children, so `<Badge tone="success">No
+ * drift</Badge>` is the obvious first guess — it used to be a typecheck error, for no
+ * reason a caller could see. Both spellings work; `label` stays for call sites that
+ * already use it, and either accepts a `UiText` so the string still translates.
+ */
+export type BadgeProps = { tone?: BadgeTone } & (
+  | { label: UiText; children?: never }
+  | { children: UiText; label?: never }
+);
 
 const toneColor: Record<BadgeTone, string> = {
   neutral: "var(--color-neutral-600)",
@@ -41,8 +49,8 @@ const badgeStyle = (tone: BadgeTone): CSSProperties => ({
 });
 
 /** Small token-styled status pill — flat soft tint with a matching text colour. */
-export function Badge({ label, tone = "neutral" }: BadgeProps) {
+export function Badge({ label, children, tone = "neutral" }: BadgeProps) {
   const resolve = useUiText();
-  return <span style={badgeStyle(tone)}>{resolve(label)}</span>;
+  return <span style={badgeStyle(tone)}>{resolve((label ?? children) as UiText)}</span>;
 }