@nifrajs/web 1.8.0 → 1.9.1

package/src/client.ts

@@ -5,6 +5,7 @@
  * a full page load). DOM-only — never imported on the server, so the store stays SSR-safe.
  */
 import type { Meta } from "./manifest.ts"
+import { type BrowserNavigate, setBrowserNavigate } from "./navigation.ts"
 import type { ClientRouter } from "./router.ts"
 
 export interface InstallHistoryOptions {
@@ -80,9 +81,14 @@ export function installHistory(
     for (const p of [vt.ready, vt.finished, vt.updateCallbackDone]) p.catch(() => {})
   }
 
-  const go = (path: string, push: boolean): void => {
+  const go = (path: string, mode: "push" | "replace"): void => {
     const url = new URL(path, location.origin)
-    if (push) {
+    if (mode === "replace") {
+      // Replace the current entry with the new URL. The entry we're leaving is discarded, so its scroll
+      // isn't worth saving; the new route scrolls to its fragment target, else the top.
+      history.replaceState({}, "", path)
+      pendingScroll = url.hash !== "" ? { hash: hashId(url.hash) } : { pos: [0, 0] }
+    } else {
       // Save the leaving entry's scroll, push a fresh entry (URL incl. any #hash), then scroll the new
       // route: to the fragment target if one was given, else to the top.
       history.replaceState({ ...(history.state ?? {}), nifraScroll: [scrollX, scrollY] }, "")
@@ -93,6 +99,20 @@ export function installHistory(
     transition(() => router.navigate(url.pathname + url.search).catch(() => fallback(path)))
   }
 
+  // Programmatic navigation for adapter `useNavigate` bindings, published through the DOM-free bridge
+  // (`@nifrajs/web`'s `getBrowserNavigate`). A string path pushes (or replaces); a number is a history
+  // delta (`-1` back / `1` forward), matching `history.go`. An off-route / cross-origin push still goes
+  // through `go`, whose `router.navigate` no-ops an unmatched path and whose fetch-failure falls back to
+  // a full load — same graceful degradation as a link click.
+  const navigate: BrowserNavigate = (to, navOptions) => {
+    if (typeof to === "number") {
+      history.go(to)
+      return
+    }
+    go(to, navOptions?.replace === true ? "replace" : "push")
+  }
+  setBrowserNavigate(navigate)
+
   // Resolve an event target to an in-app route path, or null (cross-origin, unknown route, or an
   // anchor opting out via target/download/rel=external). Shared by click + hover/focus prefetch.
   const inAppHref = (target: EventTarget | null): string | null => {
@@ -121,7 +141,7 @@ export function installHistory(
     const href = inAppHref(event.target)
     if (href === null) return
     event.preventDefault()
-    go(href, true)
+    go(href, "push")
   }
 
   // Hover/focus an in-app link → warm its chunk + data (the store dedupes the spam).
@@ -165,6 +185,7 @@ export function installHistory(
   window.addEventListener("popstate", onPopState)
   return () => {
     unsubscribe()
+    setBrowserNavigate(undefined) // stop routing `useNavigate` to a torn-down router
     document.removeEventListener("click", onClick)
     document.removeEventListener("pointerover", onPrefetch)
     document.removeEventListener("focusin", onPrefetch)

package/src/index.ts

@@ -101,14 +101,32 @@ export {
   type StaticPaths,
   type StaticRoutes,
 } from "./manifest.ts"
+// Navigation bridge — a DOM-free seam the browser layer (`installHistory`) populates so an adapter's
+// `useNavigate` (a route component, importing only this agnostic entry) reaches history-aware nav.
+export {
+  type BrowserNavigate,
+  getBrowserNavigate,
+  type NavigateOptions,
+  setBrowserNavigate,
+} from "./navigation.ts"
 // Keyed query-cache (agnostic) — a `query(key, fn)` primitive (dedup + staleness + invalidation + GC)
 // consumed by the per-adapter `useQuery`/`createQuery` bindings.
 export {
+  createMutation,
   createQueryClient,
+  type DehydratedState,
   hashQueryKey,
+  type InfiniteData,
+  type InfiniteQueryHandle,
+  type InfiniteQueryOptions,
+  type MutationCallbacks,
+  type MutationHandle,
+  type MutationState,
+  type MutationStatus,
   type QueryClient,
   type QueryClientOptions,
   type QueryHandle,
+  type QueryOptions,
   type QueryState,
   type QueryStatus,
 } from "./query.ts"
@@ -180,6 +198,14 @@ export interface RenderProps {
   readonly pending?: boolean
   /** The in-flight client submit, for optimistic UI (client-only; absent on SSR + when idle). */
   readonly submission?: Submission
+  /** The matched route's decoded path params (`/users/:id` → `{ id: "7" }`). Threaded identically on
+   * SSR (from the request match) and on client navigation (from router state) so an adapter's
+   * `useParams` reads the same value on both, with no hydration mismatch. Absent ⇒ no params (`{}`). */
+  readonly params?: Readonly<Record<string, string>>
+  /** The current URL's `pathname + search` (no hash — the hash never reaches the server). Threaded on
+   * SSR and client alike so an adapter's `useLocation`/`useSearchParams` hydrate consistently. Absent
+   * on adapters/callers that don't supply it (treated as `""`). */
+  readonly path?: string
 }
 
 /**
@@ -316,6 +342,14 @@ export interface RenderPageOptions {
   readonly revalidate?: number
   /** Matched route id; written to `window.__NIFRA_ROUTE__` so the client hydrates this chain. */
   readonly routeId?: string
+  /** The matched route's decoded path params — surfaced to the page as `params` (via {@link RenderProps})
+   * so an adapter's `useParams` is SSR-correct. Omit ⇒ `{}` (a route with no dynamic segments, or an
+   * error/404 render). */
+  readonly params?: Readonly<Record<string, string>>
+  /** The request's `pathname + search` — surfaced as `path` (via {@link RenderProps}) so an adapter's
+   * `useLocation`/`useSearchParams` render the right URL server-side and hydrate without drift. Omit ⇒
+   * `""`. */
+  readonly path?: string
   /** HTTP status for the response (default 200; e.g. 404 for a not-found page). */
   readonly status?: number
   /** Document title (fallback when `head.title` is unset). */
@@ -455,7 +489,15 @@ export function renderPageResult(options: RenderPageOptions): MaybePromise<Rende
   // dedicated header (not the action-revalidation `x-nifra-revalidate`) so the TTL channel never aliases
   // the client's path-list channel.
   if (revalidate !== undefined) headers[ISR_REVALIDATE_HEADER] = String(revalidate)
-  const renderProps: RenderProps = { data: forComponent, actionData: actionSplit?.forComponent }
+  const renderProps: RenderProps = {
+    data: forComponent,
+    actionData: actionSplit?.forComponent,
+    // `params`/`path` thread the matched route + URL to the adapter's `useParams`/`useLocation` so they
+    // render SSR-correct. Spread only when supplied (exactOptionalPropertyTypes) — an adapter with no
+    // router bindings simply never reads them.
+    ...(options.params !== undefined ? { params: options.params } : {}),
+    ...(options.path !== undefined ? { path: options.path } : {}),
+  }
 
   // Fast path: nothing `defer()`s and the adapter can render synchronously to a string → buffer the
   // whole document in one pass. Progressive streaming only benefits pages with deferred boundaries
@@ -1126,6 +1168,19 @@ export function createWebApp<Env = unknown>(
     }
   }
 
+  // The request's `pathname + search` — threaded into `renderPage` so an adapter's `useLocation`/
+  // `useSearchParams` render the current URL server-side and hydrate against the client's initial state
+  // (which the client entry seeds from `location.pathname + location.search`). No hash: it never reaches
+  // the server. A malformed `req.url` degrades to "/" rather than throwing during render.
+  const pathOf = (req: Request): string => {
+    try {
+      const u = new URL(req.url)
+      return u.pathname + u.search
+    } catch {
+      return "/"
+    }
+  }
+
   /**
    * Render the **nearest `_error` boundary** when a route's loader throws (the agnostic, server-side
    * half of error UI — works on every adapter, no client takeover). The boundary renders in place of
@@ -1166,7 +1221,7 @@ export function createWebApp<Env = unknown>(
   // The 404 response — the `_404` page (status 404) or a plain-text fallback. Shared by the wildcard
   // catch-all (unmatched paths) and the `fallback: "404"` enforcement (unlisted paths under a route
   // that opted out of on-demand SSR).
-  const renderNotFound = async (): Promise<Response | RenderedPage> => {
+  const renderNotFound = async (path?: string): Promise<Response | RenderedPage> => {
     if (manifest.notFound === undefined) {
       return new Response("Not Found", {
         status: 404,
@@ -1180,6 +1235,9 @@ export function createWebApp<Env = unknown>(
       data: null,
       clientEntry,
       routeId: "_404",
+      // `_404` hydrates, so its SSR `path` must equal the client's initial `location.pathname+search`
+      // (an unmatched path yields no params → `{}`), or a `useLocation` on the 404 page would drift.
+      ...(path !== undefined ? { path } : {}),
       status: 404,
       ...preloadOf("_404"),
       ...stylesOf("_404"),
@@ -1197,7 +1255,7 @@ export function createWebApp<Env = unknown>(
       // Covers hard navigation directly; a client soft-nav's data fetch gets the 404, throws, and the
       // history layer falls back to a full-page navigation (which lands here again, as a document).
       if (is404Fallback && !prerenderedSet.has(new URL(c.req.url).pathname)) {
-        return renderNotFound()
+        return renderNotFound(pathOf(c.req))
       }
       const mod = await route.load()
       const draft = await draftFlag(c.req)
@@ -1266,6 +1324,8 @@ export function createWebApp<Env = unknown>(
           head,
           clientEntry,
           routeId: route.id,
+          params: c.params,
+          path: pathOf(c.req),
           hydrate: hydrateRoute,
           ...preloadOf(route.id),
           ...stylesOf(route.id),
@@ -1360,6 +1420,8 @@ export function createWebApp<Env = unknown>(
         head,
         clientEntry,
         routeId: route.id,
+        params: c.params,
+        path: pathOf(c.req),
         hydrate: hydrateRoute,
         ...preloadOf(route.id),
         ...stylesOf(route.id),
@@ -1385,7 +1447,7 @@ export function createWebApp<Env = unknown>(
   })
 
   // Wildcard catch-all: unmatched paths render `_404` (404), or a plain text 404 if absent.
-  app.register("GET", "/*", undefined, () => renderNotFound())
+  app.register("GET", "/*", undefined, (c: RouteContext) => renderNotFound(pathOf(c.req)))
 
   return app
 }
@@ -1498,7 +1560,10 @@ export function generateClientEntry(
     "const initial = {",
     `  routeId: matched ? matched.routeId : (window.${ROUTE_GLOBAL} ?? ""),`,
     "  params: matched ? matched.params : {},",
-    "  path: location.pathname,",
+    // pathname + search (NOT just pathname): the SSR render threads `pathname+search` into
+    // `useLocation`/`useSearchParams`, so the hydrating initial state must carry the query too or a
+    // page reading the search string would hydrate-mismatch. The #hash is client-only (never SSR'd).
+    "  path: location.pathname + location.search,",
     `  data: mapDeferred(window.${DATA_GLOBAL}),`,
     // actionData (only set after a form POST) is in the initial state so the binding hydrates
     // consistently with the server-rendered markup; mapped through `mapDeferred` too so a deferred

package/src/navigation.ts

@@ -0,0 +1,42 @@
+/**
+ * `@nifrajs/web` navigation bridge — a tiny, DOM-free seam that lets an adapter's `useNavigate`
+ * (a route component, which must import only from the agnostic `@nifrajs/web` main entry — never the
+ * DOM-only `/client`) reach the browser's history-aware navigate, WITHOUT the route component pulling
+ * `@nifrajs/web/client` (and its `document`/`history` access) into a bundle that also renders on the
+ * server.
+ *
+ * The browser layer (`installHistory`, in `./client.ts`) populates this on setup and clears it on
+ * teardown; a framework binding reads it via {@link getBrowserNavigate}. Module-level singleton — the
+ * browser mounts exactly one app per page (the same convention the adapters' `setMountedRouter` uses).
+ * On the server (and before hydration) the getter returns `undefined`, so a binding degrades to the
+ * native `<a href>` full-page navigation — progressive enhancement, no throw.
+ */
+
+/** Options for a programmatic navigation. */
+export interface NavigateOptions {
+  /** Replace the current history entry instead of pushing a new one (like `history.replaceState`). */
+  readonly replace?: boolean
+}
+
+/**
+ * A history-aware navigate. A **string** `to` is a same-origin path (`/users/7?tab=a`) navigated to
+ * (push, or replace with `{ replace: true }`); a **number** is a history delta (`-1` back, `1`
+ * forward), matching the browser's `history.go`. Registered by `installHistory`.
+ */
+export type BrowserNavigate = (to: string | number, options?: NavigateOptions) => void
+
+// The active browser navigate (set by `installHistory`, cleared on teardown). Module-scoped: one app
+// per page; absent on the server and before hydration.
+let browserNavigate: BrowserNavigate | undefined
+
+/** Register (or clear, with `undefined`) the browser navigate — called by `installHistory`. Not for
+ * app use. */
+export function setBrowserNavigate(navigate: BrowserNavigate | undefined): void {
+  browserNavigate = navigate
+}
+
+/** The active browser navigate, or `undefined` on the server / before `installHistory` has run. A
+ * binding calls it when present and falls back to native navigation otherwise. */
+export function getBrowserNavigate(): BrowserNavigate | undefined {
+  return browserNavigate
+}