@nifrajs/web-react 2.1.0 → 2.3.0

package/src/router.ts

@@ -1,16 +1,28 @@
 /**
- * `@nifrajs/web-react/router` — React routing bindings over the agnostic `@nifrajs/web` router:
+ * `@nifrajs/web-react/router` - React routing bindings over the agnostic `@nifrajs/web` router:
  * `<Link>`/`<NavLink>`, `useNavigate`, `useParams`, `useLocation`, `useSearchParams`, and `<Navigate>`.
  *
  * These read the current route from a {@link RouterContext} that `compose` provides on BOTH the SSR
  * render and the client mount (seeded from the request match / router state respectively), so the read
  * hooks (`useParams`/`useLocation`/`useSearchParams`) are SSR-correct and hydrate with no mismatch.
  * Navigation goes through `@nifrajs/web`'s DOM-free navigate bridge (`getBrowserNavigate`, populated by
- * `installHistory`) — so this module imports only `react` (never `react-dom/*`), and a route component
+ * `installHistory`) - so this module imports only `react` (never `react-dom/*`), and a route component
  * can use these on the server and the client without dragging a DOM build into the wrong bundle. No JSX
  * (the package builds with plain `tsc`), so everything is `createElement`.
  */
-import { getBrowserNavigate, type NavigateOptions } from "@nifrajs/web"
+
+import type { InferOutput, StandardSchemaV1 } from "@nifrajs/core/server"
+import {
+  type Blocker,
+  type BlockerFunction,
+  getBrowserNavigate,
+  IDLE_BLOCKER,
+  type NavigateFunction,
+  type NavigateOptions,
+  type NavigateTargetInput,
+  registerBlocker,
+  resolveNavigate,
+} from "@nifrajs/web"
 import {
   type AnchorHTMLAttributes,
   type CSSProperties,
@@ -23,15 +35,23 @@ import {
   useContext,
   useEffect,
   useMemo,
+  useRef,
+  useState,
 } from "react"
 
+export type { Blocker, BlockerFunction, BlockerState, NavigateFunction } from "@nifrajs/web"
+
 /** The current route the routing hooks read. Provided by `compose` on SSR + client mount alike. */
 export interface RouterContextValue {
   /** The matched route's decoded path params (`/users/:id` → `{ id: "7" }`). */
   readonly params: Readonly<Record<string, string>>
-  /** The current URL's `pathname + search` (no hash — the router never carries one). */
+  /** The current URL's `pathname + search` (no hash - the router never carries one). */
   readonly path: string
-  /** True while a client navigation (or revalidation) is in flight — the current route stays mounted
+  /** The route's typed, validated search params (the loader's `ctx.search`), derived from the URL via
+   * the shared `searchOf` on SSR + client alike, read by {@link useSearch}. `{}` when the route
+   * declares no `searchSchema` (then it is the raw parsed query) or outside a nifra route tree. */
+  readonly search: Record<string, unknown>
+  /** True while a client navigation (or revalidation) is in flight - the current route stays mounted
    * until the new one is ready. Always `false` on SSR (loaders block before render). Drives loading UI
    * via {@link useNavigation}. */
   readonly pending: boolean
@@ -40,14 +60,17 @@ export interface RouterContextValue {
   readonly pendingPath?: string | undefined
 }
 
-// Frozen empty params so the default context value has a stable reference (no needless re-renders).
+// Frozen empty params/search so the default context value has a stable reference (no needless re-renders).
 const EMPTY_PARAMS: Readonly<Record<string, string>> = Object.freeze({})
+const EMPTY_SEARCH: Readonly<Record<string, unknown>> = Object.freeze({})
 
-/** Router context. The default ({} params, "" path) is what a component sees when rendered outside a
- * nifra route tree — the hooks stay defined (no throw) so a stray `useParams` degrades gracefully. */
+/** Router context. The default ({} params, "" path, {} search) is what a component sees when rendered
+ * outside a nifra route tree (the hooks stay defined, no throw, so a stray `useParams` degrades
+ * gracefully). */
 export const RouterContext = createContext<RouterContextValue>({
   params: EMPTY_PARAMS,
   path: "",
+  search: EMPTY_SEARCH,
   pending: false,
 })
 
@@ -61,7 +84,7 @@ function splitPath(path: string): { readonly pathname: string; readonly search:
 }
 
 /**
- * The matched route's decoded path params — `/users/:id` on `/users/7` → `{ id: "7" }`. SSR-correct:
+ * The matched route's decoded path params - `/users/:id` on `/users/7` → `{ id: "7" }`. SSR-correct:
  * `compose` provides the same value server-side (from the request match) and client-side (from router
  * state), so a param rendered into markup doesn't flash on hydration.
  */
@@ -71,7 +94,30 @@ export function useParams<
   return useContext(RouterContext).params as Readonly<T>
 }
 
-/** The parsed current location. `hash` is always `""` — the fragment is client-only and never reaches
+/**
+ * The route's typed, validated search params: the SAME value the loader received as `ctx.search`.
+ * SSR-correct: `compose` provides it from `searchOf(searchSchema, url.search)` server-side and from the
+ * identical derivation on the client mount, so a value rendered from it doesn't flash on hydration.
+ * Hostile input already failed closed to the schema's defaults at match time, so a component never
+ * parses `window.location.search` or guards against a bad query.
+ *
+ * Pass the route's `searchSchema` as the type argument to get its output type; bare, it's the raw parsed
+ * query (`Record<string, unknown>`), which is also what a route without a `searchSchema` yields.
+ *
+ * ```tsx
+ * export const searchSchema = v.object({ page: v.optional(v.fallback(v.number(), 1), 1) })
+ * const { page } = useSearch<typeof searchSchema>() // page: number
+ * ```
+ */
+export function useSearch<
+  Schema extends StandardSchemaV1 | undefined = undefined,
+>(): Schema extends StandardSchemaV1 ? InferOutput<Schema> : Record<string, unknown> {
+  return useContext(RouterContext).search as Schema extends StandardSchemaV1
+    ? InferOutput<Schema>
+    : Record<string, unknown>
+}
+
+/** The parsed current location. `hash` is always `""` - the fragment is client-only and never reaches
  * the router state / server, so exposing a live hash would hydration-mismatch; read `window.location.hash`
  * directly (in an effect) if you truly need it. */
 export interface Location {
@@ -130,18 +176,62 @@ export function usePending(): boolean {
   return useContext(RouterContext).pending
 }
 
-/** A programmatic navigate: a string path (push, or replace via `{ replace: true }`) or a history delta
- * (`-1`/`1`). A no-op on the server / before hydration (a render-time navigate isn't valid — use
- * {@link Navigate}, which navigates in an effect). */
-export type NavigateFunction = (to: string | number, options?: NavigateOptions) => void
-
-/** Get the {@link NavigateFunction}. Stable across renders; resolves the browser navigate at call time
- * (so it works as soon as `installHistory` has run, and no-ops before then / on the server). */
+/** Get the {@link NavigateFunction} (a string path, a history delta, or a typed `{ to, search }` object;
+ * a render-time navigate isn't valid - use {@link Navigate}, which navigates in an effect). Stable across
+ * renders; resolves the browser navigate at call time (so it works as soon as `installHistory` has run,
+ * and no-ops before then / on the server). */
 export function useNavigate(): NavigateFunction {
-  return useCallback((to, options) => {
+  return useCallback((to: string | number | NavigateTargetInput, options?: NavigateOptions) => {
     const navigate = getBrowserNavigate()
-    if (navigate !== undefined) navigate(to, options)
-  }, [])
+    if (navigate === undefined) return
+    const resolved = resolveNavigate(to, options)
+    navigate(resolved.to, resolved.options)
+  }, []) as NavigateFunction
+}
+
+/**
+ * Guard navigation away from a page with unsaved work, confirming with your OWN async UI. Mirrors
+ * react-router's `useBlocker`: pass a boolean (`useBlocker(isDirty)`) or a predicate
+ * `({ currentLocation, nextLocation }) => boolean`, and get back a {@link Blocker}. When a navigation
+ * (a `<Link>`/anchor click, `useNavigate`, or a browser back/forward) is intercepted, `blocker.state`
+ * becomes `"blocked"` and `proceed`/`reset` go live - render a dialog and call `proceed()` to continue
+ * or `reset()` to stay put. It also arms the browser's native "Leave site?" prompt on tab close / reload.
+ * Idle (never blocks, `proceed`/`reset` are `undefined`) on the server and before hydration, so it's
+ * SSR-safe and hydration-stable.
+ *
+ * ```tsx
+ * const blocker = useBlocker(form.isDirty)
+ * return (
+ *   <>
+ *     <MyForm />
+ *     {blocker.state === "blocked" && (
+ *       <ConfirmDialog
+ *         onCancel={blocker.reset}
+ *         onConfirm={blocker.proceed}
+ *         message="Discard unsaved changes?"
+ *       />
+ *     )}
+ *   </>
+ * )
+ * ```
+ */
+export function useBlocker(shouldBlock: boolean | BlockerFunction): Blocker {
+  const [blocker, setBlocker] = useState<Blocker>(IDLE_BLOCKER)
+  // Track the latest predicate in a ref (updated every render) so the single registration always sees
+  // current component state (the dirty flag) WITHOUT re-registering - re-registering mid-prompt drops it.
+  const shouldBlockRef = useRef(shouldBlock)
+  shouldBlockRef.current = shouldBlock
+  // Register once on mount; the returned unregister is the effect cleanup. A boolean reads as itself, a
+  // function is called. A no-op before `installHistory` has run (blocker stays idle → native navigation).
+  useEffect(
+    () =>
+      registerBlocker((args) => {
+        const current = shouldBlockRef.current
+        return typeof current === "function" ? current(args) : current
+      }, setBlocker),
+    [],
+  )
+  return blocker
 }
 
 /** The value forms `setSearchParams` accepts. */
@@ -185,7 +275,7 @@ export function useSearchParams(): readonly [URLSearchParams, SetSearchParams] {
   return [searchParams, setSearchParams] as const
 }
 
-/** A left-click with no modifier and no new-tab target — the only click a client router should
+/** A left-click with no modifier and no new-tab target - the only click a client router should
  * intercept (Cmd/Ctrl/Shift/Alt or a `_blank` target means the user wants native behavior). */
 function isPlainLeftClick(event: MouseEvent, target: string | undefined): boolean {
   if (event.button !== 0) return false
@@ -205,7 +295,7 @@ export interface LinkProps extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>,
  * A client-navigating anchor. Renders a real `<a href={to}>` (so it's a working link before hydration
  * and for right-click / open-in-new-tab), and on a plain left-click navigates through the router
  * instead of a full reload. Calling `navigate` + `preventDefault` here means `installHistory`'s
- * document-level click handler sees `defaultPrevented` and stands down — exactly one navigation.
+ * document-level click handler sees `defaultPrevented` and stands down - exactly one navigation.
  */
 export const Link = forwardRef<HTMLAnchorElement, LinkProps>(function Link(
   { to, replace, onClick, target, ...rest },
@@ -232,7 +322,7 @@ export interface NavLinkRenderProps {
   readonly isPending: boolean
 }
 
-/** {@link NavLink} props — like {@link LinkProps}, but `className`/`style`/`children` may be functions
+/** {@link NavLink} props - like {@link LinkProps}, but `className`/`style`/`children` may be functions
  * of the active state, and `end`/`caseSensitive` tune matching. */
 export interface NavLinkProps extends Omit<LinkProps, "className" | "style" | "children"> {
   /** Match the full path exactly instead of as a prefix (use for `to="/"` so it isn't always active). */
@@ -309,7 +399,7 @@ export interface NavigateProps {
 }
 
 /**
- * Declaratively navigate on mount — the component analogue of `useNavigate` (e.g. a guard that renders
+ * Declaratively navigate on mount - the component analogue of `useNavigate` (e.g. a guard that renders
  * `<Navigate to="/login" replace />`). Navigates in an effect, so it's a safe no-op during SSR (renders
  * `null`); the redirect happens once on the client after hydration.
  */