@native-router/react 1.5.0 → 1.6.1

package/README.md

@@ -74,7 +74,8 @@ function Preview({visible}: {visible: boolean}) {
 - `NavLink` with `isActive`/`isExactActive`, `end`, `caseSensitive` and `aria-current` (defaults to `"page"`); `className`/`style`/`children` accept `({isActive, isExactActive})` callbacks; `to="/"` is active for every path
 - Polymorphic links: every link component takes an `as` component — own props flattened and type-checked on the link, colliding props through the `asProps` escape hatch, `href`/`onClick`/`aria-current` injected, `ref` forwarded
 - `useSearchParams` reads and writes the query string; writes push by default or replace with `{replace: true}`; `useSetSearch(schema)` is the schema-aware setter twin of `useSearch(schema)` — the next value is validated by the same schema before any navigation, a rejection throws `SearchError` without touching the location, and the written query is the schema's own output(defaults applied)
-- Typed search: an optional Standard Schema validator (zod/valibot/arktype, no hard dependency) on any route `search` field, parsed at resolve time — loaders receive a typed `ctx.search` and an invalid search fails the level through the existing error layers; `useSearch(schema?)` reads it in components, degrading to the raw object without a schema
+- Typed search: an optional Standard Schema validator (zod/valibot/arktype, no hard dependency) on any route `search` field, parsed at resolve time — `data` loaders and `beforeLoad` guards receive a typed `ctx.search` and an invalid search fails the level through the existing error layers; `useSearch(schema?)` reads it in components, degrading to the raw object without a schema
+- Search type closure: `createRoutes(routes)` re-types the returned table so every level's `data`/`beforeLoad` `ctx.search` derives from the level's own schema — no `Route<P, S>` generics or callback annotations needed; an explicit `Route<P, S>` generic still wins wherever written
 - Type-safe links: `createRoutes(routes)` checks the table while keeping every `path` literal, `RoutePaths<typeof routes>` extracts the pattern union(through nesting and param segments), and `<TypedLink<RoutePaths<...>> to params>` narrows `to` to the table and checks `params` against the exact pattern's segments — compile errors for unknown paths and missing/wrong params, click-time interpolation with encoding as the runtime backstop
 - `ScrollRestoration` restores the scroll offset per history entry on back/forward and resets it on push (`resetOnPush` to opt out)
 - Router-level `preload(router, to)` shares resolved views across links with in-flight dedup and a 30s TTL; `PrefetchLink` prefetch through it
@@ -140,6 +141,15 @@ The navigation semantics stay owned by the link: `href` is always the computed t
 
 `PrefetchLink`'s strategies keep working through the `as` component; the `viewport` strategy observes the DOM node the component forwards its ref to, so a component that never forwards the ref down to a DOM element simply never triggers a viewport prefetch.
 
+## Why `useData` is typed manually
+
+`useData<T>()` annotations have no compile-time link to the route's `data` loader — the annotation *is* the contract. That is deliberate. Two closure schemes were evaluated (2026-08) and rejected:
+
+- **A from-argument** (`useData('/articles/:slug')`, indexing a route-table map by path literal — TanStack's `useLoaderData({from})` shape). Rejected: it makes every view aware of the path it happens to be mounted under. Matching data to a view is the route configuration's job; a view should know what it renders, not where it is mounted.
+- **A data-props protocol** — constrain `component` to `ComponentType<{data: D}>` and let `createRoutes` check the loader output against it at the config site. The check lands at the right layer, but deep children would then need prop drilling to reach the data.
+
+What stays: path-agnostic views, no prop drilling, one local annotation. Revisit only if TypeScript or the library later offers a channel that couples neither paths nor props.
+
 ## Install
 
 ```bash
@@ -259,11 +269,12 @@ import {ScrollRestoration} from '@native-router/react';
 
 On mount it also sets `history.scrollRestoration` to `manual`: the browser's own `auto` restoration would race the component's restore and pre-scroll while the left entry's offset is still being read, so the component owns scroll restoration for the session (the setting is not reverted on unmount).
 
-Validate and type the search with a schema — any zod/valibot/arktype schema works, the router only speaks [Standard Schema](https://standardschema.dev). Declare it once on the route and the search is parsed during resolve: the `data` loader receives a typed `ctx.search` (coerced numbers, defaults applied), and an invalid search fails the level through the existing error layers — the route `errorComponent`, else the global `errorHandler`.
+Validate and type the search with a schema — any zod/valibot/arktype schema works, the router only speaks [Standard Schema](https://standardschema.dev). Declare it once on the route and the search is parsed during resolve: the `data` loader and the `beforeLoad` guard receive a typed `ctx.search` (coerced numbers, defaults applied), and an invalid search fails the level through the existing error layers — the route `errorComponent`, else the global `errorHandler`.
+
+Build the table with `createRoutes` and the typing closes by itself: the returned table derives every level's `ctx.search` from the level's own schema, so neither the manual `Route<P, S>` generic nor callback annotations are needed. (Callbacks written inside the literal are checked loosely — `ctx.search: any` — since TypeScript cannot contextually type a member from sibling properties; the precise types hold on the returned table, and a callback annotation that contradicts the schema is rejected at the property.)
 
 ```tsx
-import {useData, useSearch} from '@native-router/react';
-import type {Route} from '@native-router/react';
+import {createRoutes, useData, useSearch} from '@native-router/react';
 import {z} from 'zod';
 
 const listSearch = z.object({
@@ -271,14 +282,19 @@ const listSearch = z.object({
   tag: z.string().optional()
 });
 
-const listRoute = {
-  path: '/articles',
-  search: listSearch,
-  component: () => import('./ArticleList'),
-  // ctx.search: {page: number; tag?: string} — parsed and typed
-  data: ({search}) => fetchArticles(search.page, search.tag),
-  errorComponent: ({error}) => <p>{error.message}</p>
-} as Route<'/articles', {page: number; tag?: string}>;
+const routes = createRoutes({
+  component: () => import('./Layout'),
+  children: [
+    {
+      path: '/articles',
+      search: listSearch,
+      component: () => import('./ArticleList'),
+      // typeof routes → this level's ctx.search: {page: number; tag?: string}
+      data: ({search}) => fetchArticles(search.page, search.tag),
+      errorComponent: ({error}) => <p>{error.message}</p>
+    }
+  ]
+});
 
 function ArticleList() {
   const articles = useData<Article[]>(); // typed, no casts
@@ -288,6 +304,16 @@ function ArticleList() {
 }
 ```
 
+Hand-annotated route objects keep the explicit generic — it wins wherever written:
+
+```tsx
+const listRoute = {
+  path: '/articles',
+  search: listSearch,
+  component: () => import('./ArticleList')
+} as Route<'/articles', {page: number; tag?: string}>;
+```
+
 `useSearch()` without a schema degrades to the raw input object of `parseSearchInput` (strings; repeated keys are arrays) and needs no schema on the route. Both flavors re-render on every location change, and the schema must validate synchronously.
 
 Write the search through the same schema — `useSetSearch(schema)` validates the next value before any navigation, throws `SearchError` (with the schema's issues) without touching the location when it rejects, and writes the schema's own output so defaults apply:

package/dist/types/create-routes.d.ts

@@ -1,4 +1,4 @@
-import type { Route } from './types';
+import type { Route, SearchRoutesOf } from './types';
 /**
  * Identity function with `satisfies` semantics: the table is checked
  * against `Route` while every `path` keeps its string-literal type, so
@@ -6,22 +6,37 @@ import type { Route } from './types';
  * `TypedLink`. An `as Route` assertion does the opposite — it widens
  * every `path` to `string` and gives up the literals.
  *
+ * The return type additionally closes the search loop(see
+ * {@link SearchRoutesOf}): every level's `data` loader and `beforeLoad`
+ * guard receive their `ctx.search` typed from the level's own
+ * {@link Route.search search schema} —
+ *
  * ```tsx
  * const routes = createRoutes({
  *   children: [
- *     {path: '/', component: () => import('./Home')},
- *     {path: '/users/:id', component: () => import('./UserProfile')}
+ *     {
+ *       path: '/list',
+ *       search: z.object({page: z.coerce.number()}),
+ *       // typeof routes → ctx.search: {page: number}, no annotations
+ *       data: ({search}) => fetchList(search.page)
+ *     }
  *   ]
  * });
- * // type AppPaths = '/' | '/users/:id'
- * type AppPaths = RoutePaths<typeof routes>;
  * ```
  *
+ * Callbacks written inside the literal are still checked loosely
+ * against `Route`(`ctx.search: any` — TypeScript cannot contextually
+ * type a member from sibling properties); the precise types hold on the
+ * returned table, and a callback whose annotation contradicts the
+ * schema is rejected at the property. An explicit `Route<P, S>` generic
+ * keeps priority wherever it is written.
+ *
  * Zero runtime cost: the function returns its argument unchanged and
  * tree-shakes away.
  * @group Methods
  * @category Route
  * @param routes the route table, a route object or an array of them
- * @returns the very same route table, literal types preserved
+ * @returns the very same route table, literal types preserved and the
+ * loader/guard search contexts re-typed from the schemas
  */
-export declare function createRoutes<const T>(routes: T & (Route | Route[])): T;
+export declare function createRoutes<const T>(routes: T & SearchRoutesOf<T> & (Route | Route[])): SearchRoutesOf<T>;

package/dist/types/types.d.ts

@@ -1,5 +1,5 @@
 import type { AnchorHTMLAttributes, ComponentPropsWithRef, ComponentPropsWithoutRef, ComponentType, CSSProperties, DetailedHTMLProps, ElementType, ReactNode } from 'react';
-import type { BaseRoute, ExtractPathParams, Matched, Location, RouterInstance, SearchInput } from '@native-router/core';
+import type { Awaitable, BaseRoute, ExtractPathParams, GuardContext, Matched, Location, RouterInstance, SearchInput, StandardSchemaV1 } from '@native-router/core';
 export type ResolveViewContext<R extends BaseRoute> = {
     router: RouterInstance<R>;
     location: Location;
@@ -55,14 +55,18 @@ export type RouteParams<P extends string> = string extends P ? Record<string, st
  * `Route<'/users/:id'>` → `params: {id: string}`. Give the second
  * generic the output type of the route `search` schema and `ctx.search`
  * is typed accordingly, e.g. `Route<'/list', {page: number}>` with
- * `search: z.object({page: z.coerce.number()})` → `search: {page: number}`.
+ * `search: z.object({page: z.coerce.number()})` → `search: {page: number}` —
+ * for the `data` loader and the `beforeLoad` guard alike.
  *
  * Without the search generic an untyped `ctx.search` stays `any` — the
  * default that keeps differently typed levels assignable to plain
  * `Route`: schema outputs are arbitrary(coerced numbers, defaults, ...),
  * so no single degraded shape is bivariant with all of them. At runtime
  * it holds the raw input object of `parseSearchInput`; see `useSearch`
- * for the typed degraded shape.
+ * for the typed degraded shape. Prefer {@link createRoutes}: its
+ * returned table derives every level's `ctx.search` from the level's own
+ * schema(see {@link SearchRoutesOf}), so the manual generic is only
+ * needed for hand-annotated route objects.
  * `children` accepts `Route<any, any>` so levels with different patterns
  * and search shapes nest without variance conflicts.
  * @group Types
@@ -99,7 +103,17 @@ export type Route<P extends string = string, S = any> = Omit<BaseRoute<{
      * Receives no props.
      */
     pendingComponent?: ComponentType;
-}>, 'path' | 'children'> & {
+}>, 'path' | 'children' | 'beforeLoad'> & {
+    /**
+     * Route guard inherited from `BaseRoute`, re-typed by the search
+     * generic: `ctx.search` is `S`(`any` by default — see the Route doc
+     * above). At runtime it holds the level's parsed search — the schema
+     * output, or the degraded input without a schema. The guard context
+     * types `router` as `RouterInstance<any>`: a precise
+     * `RouterInstance<Route>` here would recurse into `Route`'s own
+     * members and break `Route`'s assignability to plain `BaseRoute`.
+     */
+    beforeLoad?(ctx: GuardContext<any, S>): Awaitable<string | void>;
     /** Path pattern; params of the contexts above are inferred from it. */
     path?: P;
     /**
@@ -114,6 +128,59 @@ export type LoadStatus = {
     key: number;
     status: 'pending' | 'resolved' | 'rejected';
 };
+/**
+ * The search a route's `data`/`beforeLoad` contexts receive: the
+ * level's own {@link Route.search search schema} output, or the
+ * degraded {@link SearchInput} when the level declares no schema.
+ * Building block of {@link SearchRoutesOf}.
+ * @group Types
+ * @category Route
+ */
+export type RouteSearchOf<R> = R extends {
+    search: StandardSchemaV1<any, infer Output>;
+} ? Output : SearchInput;
+/**
+ * A context with only its `search` member replaced — everything the
+ * callback declared(`params` precision, `signal`, custom shapes)
+ * passes through untouched.
+ * @group Types
+ * @category Route
+ */
+export type WithSearch<C, S> = Omit<C, 'search'> & {
+    search: S;
+};
+/**
+ * Re-type a route table so every level's `data` loader and `beforeLoad`
+ * guard derive their `ctx.search` from the level's own
+ * {@link Route.search search schema}: the schema's parsed output(see
+ * {@link RouteSearchOf}) instead of the loose `any`. This is what
+ * {@link createRoutes} returns, closing the type loop — no manual
+ * `Route<P, S>` generics or callback annotations needed for the search
+ * typing.
+ *
+ * Everything else passes through unchanged: `path` literals(so
+ * `RoutePaths<typeof routes>` and `TypedLink` keep working), the
+ * loaders' return types, and the rest of every level's members. A
+ * callback that annotates its ctx with a search shape the schema
+ * contradicts is rejected at the `data`/`beforeLoad` property; an
+ * un-annotated callback written inside the literal is checked loosely
+ * against `Route`(`ctx.search: any` — TypeScript cannot contextually
+ * type a member from sibling properties) and precisely on the returned
+ * table.
+ * @group Types
+ * @category Route
+ */
+export type SearchRoutesOf<T> = T extends readonly unknown[] ? {
+    -readonly [K in keyof T]: SearchRoutesOf<T[K]>;
+} : T extends Route ? T extends {
+    data?: infer Data;
+    beforeLoad?: infer BeforeLoad;
+    children?: infer Children;
+} ? Omit<T, 'data' | 'beforeLoad' | 'children'> & {
+    data?: [unknown] extends [Data] ? undefined : Data extends (ctx: infer DataCtx) => infer R ? (ctx: WithSearch<DataCtx, RouteSearchOf<T>>) => R : Data;
+    beforeLoad?: [unknown] extends [BeforeLoad] ? undefined : BeforeLoad extends (ctx: infer GuardCtx) => infer R ? (ctx: WithSearch<GuardCtx, RouteSearchOf<T>>) => R : BeforeLoad;
+    children?: [unknown] extends [Children] ? undefined : SearchRoutesOf<Children>;
+} : T : T;
 /**
  * Union of every navigable path pattern of a route table, computed from
  * the table's type. Each level's `path` literal concatenates with its

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@native-router/react",
-  "version": "1.5.0",
+  "version": "1.6.1",
   "type": "module",
   "exports": {
     ".": {
@@ -62,7 +62,7 @@
     "react-dom": "^17.0.0 || ^18.0.0 || ^19.0.0"
   },
   "dependencies": {
-    "@native-router/core": "^1.7.0",
+    "@native-router/core": "^1.8.0",
     "history": "^5.3.0",
     "use-sync-external-store": "^1.6.0"
   },