@native-router/react 1.1.1 → 1.2.0

package/dist/ssr-C17nRDBM.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ssr-C17nRDBM.js","names":[],"sources":["../src/context.tsx","../src/resolve-view.tsx","../src/components/Router.tsx","../src/ssr.tsx"],"sourcesContent":["import {createContext, ReactNode, useContext, useMemo} from 'react';\nimport type {Context, LoadStatus, Route} from './types';\n\nconst ViewContext = createContext<ReactNode>(null);\n\nexport function ViewProvider(props: {children: ReactNode; value: ReactNode}) {\n  return <ViewContext.Provider {...props} />;\n}\n\n/**\n * @group Hooks\n * @see {@link View View Component}\n */\nexport function useView() {\n  return useContext(ViewContext);\n}\n\n/**\n * Used for route component to render child route component.\n * It just render the return of {@link useView}\n * @group Components\n */\nexport function View() {\n  return useView();\n}\n\nconst DataContext = createContext<[any, Record<string, any>]>([undefined, {}]);\n\nfunction useDataContext() {\n  return useContext(DataContext);\n}\n\n/**\n * Get the named data map of the resolved route levels: an object keyed by\n * each ancestor's `name`, holding its resolved `data`. The current level\n * is included only when it declares a `name`.\n *\n * Give the generic the expected map shape to read values type-safely:\n * `useNamedData<{user: User}>()`.\n * @group Hooks\n */\nexport function useNamedData<T = Record<string, unknown>>() {\n  return useDataContext()[1] as T;\n}\n\nexport function DataProvider({\n  children,\n  name,\n  data\n}: {\n  children: ReactNode;\n  data: any;\n  name?: string;\n}) {\n  const namedData = useNamedData();\n  const value = useMemo(\n    () => [data, name ? {...namedData, [name]: data} : namedData] as [any, any],\n    [data, name, namedData]\n  );\n  return <DataContext.Provider value={value}>{children}</DataContext.Provider>;\n}\n\nexport const MatchedContext = createContext<Context<Route> | undefined>(\n  undefined\n);\n\n/**\n * @group Hooks\n */\nexport function useMatched() {\n  return useContext(MatchedContext)!;\n}\n\n/**\n * Get the resolved `data` of the current route level, or the named data\n * of an ancestor level when `name` is given.\n *\n * Give the generic the expected data type to read it type-safely without\n * a cast: `useData<Article>()` → `Article | undefined`.\n * @group Hooks\n */\nexport function useData<T = unknown>(name?: string): T | undefined {\n  const [data, namedData] = useDataContext();\n  return (name ? namedData[name] : data) as T | undefined;\n}\n\nexport const LoadingContext = createContext<LoadStatus | undefined>(undefined);\n\n/**\n * @group Hooks\n */\nexport function useLoading() {\n  return useContext(LoadingContext);\n}\n","import type {ComponentType, ReactElement} from 'react';\nimport type {Context, ResolveViewContext, Route} from '@@/types';\nimport {\n  mergeMatchedParams,\n  parseSearch,\n  parseSearchInput\n} from '@native-router/core';\nimport type {Matched} from '@native-router/core';\nimport {DataProvider, MatchedContext, View, ViewProvider} from './context';\n\n/**\n * The default implementation of resolve view\n * @param matched the matched result\n * @param viewContext resolved view context\n * @returns the resolve view\n * @see {@link create router->create}\n */\nexport default function resolveView(\n  matched: Matched<Route>[],\n  ctx: ResolveViewContext<Route>\n) {\n  return resolveViewBase(matched, ctx, (data, dataCtx) => data?.(dataCtx));\n}\n\nconst viewDataMap = new WeakMap<ReactElement, any[]>();\n\nexport function resolveViewServer(\n  matched: Matched<Route>[],\n  ctx: ResolveViewContext<Route>\n) {\n  const dataResults = new Array(matched.length);\n  return resolveViewBase(matched, ctx, (data, dataCtx) =>\n    Promise.resolve(data?.(dataCtx)).then(\n      (result) => (dataResults[dataCtx.index] = result)\n    )\n  ).then((view) => {\n    viewDataMap.set(view, dataResults);\n    return view;\n  });\n}\n\nexport function createHydrateResolveView(data: any[]) {\n  return (matched: Matched<Route>[], ctx: ResolveViewContext<Route>) =>\n    resolveViewBase(matched, ctx, (_, dataCtx) => data[dataCtx.index]);\n}\n\nexport function getViewData(view: ReactElement) {\n  return viewDataMap.get(view);\n}\n\nfunction resolveViewBase(\n  matched: Matched<Route>[],\n  {router, location}: ResolveViewContext<Route>,\n  resolveData: (\n    dataFetcher: ((ctx: Context<Route>) => any) | undefined,\n    ctx: Context<Route>\n  ) => any\n) {\n  return Promise.all(\n    matched.map(({route}, index) => {\n      // `search` starts as the degraded input and is upgraded to the\n      // schema output before the data fetcher runs below; schema outputs\n      // are user-typed(`Route<P, S>`), so the property stays `any` here.\n      const ctx: Context<Route, Record<string, string>, any> = {\n        matched: matched!,\n        params: mergeMatchedParams(matched, index),\n        index,\n        router,\n        location,\n        search: parseSearchInput(location.search)\n      };\n      function resolveComponent(): ComponentType | Promise<ComponentType> {\n        if (!route.component) return View;\n        const r = route.component(ctx);\n        return Promise.resolve(r).then((m) => ('default' in m ? m.default : m));\n      }\n\n      // The level's search schema runs before its data fetcher: the parsed\n      // output replaces the degraded input in `ctx.search`, and a rejected\n      // validation fails the level exactly like a data error.\n      const resolveDataWithSearch = () =>\n        route.search\n          ? parseSearch(route.search, location.search).then((search) => {\n              ctx.search = search;\n              return resolveData(route.data, ctx);\n            })\n          : resolveData(route.data, ctx);\n\n      // A level that fails to resolve (search, data or component) is\n      // replaced by its route-level errorComponent when configured;\n      // otherwise the error bubbles up to the global errorHandler as before.\n      return Promise.all([resolveDataWithSearch(), resolveComponent()]).then(\n        ([data, C]) => (\n          <DataProvider data={data} name={route.name}>\n            <MatchedContext.Provider value={ctx}>\n              <C />\n            </MatchedContext.Provider>\n          </DataProvider>\n        ),\n        (error: Error) => {\n          if (!route.errorComponent) throw error;\n          return (\n            <DataProvider data={undefined} name={route.name}>\n              <MatchedContext.Provider value={ctx}>\n                <route.errorComponent error={error} ctx={ctx} />\n              </MatchedContext.Provider>\n            </DataProvider>\n          );\n        }\n      );\n    })\n  ).then((views) =>\n    views\n      .reverse()\n      .reduce((acc, view) => <ViewProvider value={acc}>{view}</ViewProvider>)\n  );\n}\n","import {\n  ReactNode,\n  createContext,\n  useCallback,\n  useContext,\n  useEffect,\n  useMemo,\n  useRef,\n  useState\n} from 'react';\nimport {\n  History,\n  createBrowserHistory,\n  createHashHistory,\n  createMemoryHistory,\n  MemoryHistoryOptions\n} from 'history';\nimport type {LoadStatus, Route} from '@@/types';\nimport {LoadingContext, ViewProvider} from '@@/context';\nimport {create, getCurrentView, listen, setOptions} from '@native-router/core';\nimport type {Options, ResolveView, RouterInstance} from '@native-router/core';\nimport {splitProps, uniqId} from '@native-router/core/util';\nimport {useSyncExternalStore} from 'use-sync-external-store/shim';\nimport defaultResolve from '@@/resolve-view';\n\nconst RouterContext = createContext<RouterInstance<Route, ReactNode> | null>(\n  null\n);\n\ntype Props = {\n  children?: ReactNode;\n  routes: Route[] | Route;\n  resolveView?: typeof defaultResolve;\n} & Omit<Options<ReactNode>, 'onLoadingChange'>;\n\n/**\n * Base Router Component.\n * @group Components\n */\nexport function Router({\n  router,\n  children\n}: {\n  children?: ReactNode;\n  router: RouterInstance<Route, ReactNode>;\n}) {\n  const viewRef = useRef<ReactNode>(getCurrentView(router));\n  const subscribe = useCallback(\n    (onStoreChange: () => void) =>\n      listen(router, (view) => {\n        viewRef.current = view;\n        onStoreChange();\n      }),\n    [router]\n  );\n  const getSnapshot = useCallback(() => viewRef.current, []);\n  // `getServerSnapshot` is required by the native implementation when the\n  // Router is rendered inside server-rendered content(e.g. resolveServerView).\n  const getServerSnapshot = useCallback(() => getCurrentView(router), [router]);\n  const view = useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);\n\n  return (\n    <RouterContext.Provider value={router}>\n      {children === undefined ? (\n        view\n      ) : (\n        <ViewProvider value={view}>{children}</ViewProvider>\n      )}\n    </RouterContext.Provider>\n  );\n}\n\nexport function createRouter(\n  routes: Route | Route[],\n  history: History,\n  {\n    resolveView = defaultResolve,\n    ...options\n  }: Options<ReactNode> & {resolveView?: ResolveView<Route, ReactNode>} = {}\n): RouterInstance<Route, ReactNode> {\n  return create(routes, history, resolveView, options);\n}\n\nfunction useNewRouter(\n  {routes, children, ...options}: Props,\n  createHistory: () => History\n) {\n  const [tracked, rest] = splitProps(options, ['baseUrl', 'currentView']);\n  const {baseUrl, currentView} = tracked;\n  const router = useMemo(\n    () => createRouter(routes, createHistory(), tracked),\n    [routes, createHistory, baseUrl, currentView]\n  );\n\n  const [loading, setLoading] = useState<LoadStatus>();\n  // Options are applied in an effect(never during render) and refreshed on\n  // every commit, so `onLoadingChange` always sees the latest closure.\n  useEffect(() => {\n    setOptions(router, {\n      ...rest,\n      onLoadingChange(status) {\n        setLoading(status && {key: uniqId(), status});\n      }\n    });\n  }, [router, rest]);\n\n  const r = useMemo(\n    () => <Router router={router}>{children}</Router>,\n    [router, children]\n  );\n\n  return <LoadingContext.Provider value={loading}>{r}</LoadingContext.Provider>;\n}\n\n/**\n * History mode Router Component.\n * @group Components\n */\nexport function HistoryRouter(props: Props) {\n  return useNewRouter(props, createBrowserHistory);\n}\n\n/**\n * Hash mode Router Component.\n * @group Components\n */\nexport function HashRouter(props: Props) {\n  return useNewRouter(props, createHashHistory);\n}\n\n/**\n * Memory mode Router Component.\n * @group Components\n */\nexport function MemoryRouter({\n  initialEntries,\n  initialIndex,\n  ...props\n}: Props & MemoryHistoryOptions) {\n  const createHistory = useMemo(\n    () => () => createMemoryHistory({initialEntries, initialIndex}),\n    [initialEntries, initialIndex]\n  );\n  return useNewRouter(props, createHistory);\n}\n\n/**\n * Get Router instance.\n * @group Hooks\n * @returns Router Instance\n */\nexport function useRouter() {\n  const router = useContext(RouterContext);\n  if (!router) {\n    throw new Error('useRouter() must be used within a <Router> component');\n  }\n  return router;\n}\n","import {createBrowserHistory, createMemoryHistory, createPath} from 'history';\nimport {ReactElement, ReactNode} from 'react';\nimport {create, resolve, toLocation} from '@native-router/core';\nimport type {\n  HistoryState,\n  Location,\n  Options,\n  RouterInstance\n} from '@native-router/core';\nimport {isString} from '@native-router/core/util';\nimport {Router} from './components/Router';\nimport {\n  createHydrateResolveView,\n  getViewData,\n  resolveViewServer\n} from './resolve-view';\nimport type {Route} from './types';\n\nconst defaultHydrateKey = '_nativeRouterReactSSRData';\n\n/**\n * Serialize the SSR payload for embedding in a script element.\n * `JSON.stringify` does not escape `<`, U+2028 and U+2029,\n * so route data like `</script>` would break out of the script element.\n * @param payload the payload to serialize\n * @returns the escaped JSON string\n */\nfunction serializePayload(payload: {\n  data?: any[];\n  location: Location;\n  index: number;\n}) {\n  return JSON.stringify(payload)\n    .replace(/</g, '\\\\u003c')\n    .replace(/\\u2028/g, '\\\\u2028')\n    .replace(/\\u2029/g, '\\\\u2029');\n}\n\nexport function resolveServerViewBase(\n  router: RouterInstance<Route, ReactNode>,\n  location: Location,\n  options?: {\n    scriptAttributes?: Record<string, string>;\n    hydrateKey?: string;\n  }\n) {\n  return resolve<Route, ReactNode>(router, location).then((view) => {\n    const data = getViewData(view as ReactElement);\n    const index =\n      (router.history.location.state as HistoryState | undefined)?.index || 0;\n    return (\n      <>\n        <Router router={router}>{view}</Router>\n        <script\n          {...options?.scriptAttributes}\n          suppressHydrationWarning\n          // eslint-disable-next-line @eslint-react/dom-no-dangerously-set-innerhtml -- serialized state for hydration\n          dangerouslySetInnerHTML={{\n            __html: `window.${\n              options?.hydrateKey || defaultHydrateKey\n            } = ${serializePayload({data, location, index})};`\n          }}\n        />\n      </>\n    );\n  });\n}\n\nexport function resolveServerView(\n  routes: Route | Route[],\n  location: Location | string,\n  {\n    scriptAttributes,\n    hydrateKey,\n    ...options\n  }: Options<ReactElement> & {\n    scriptAttributes?: Record<string, string>;\n    hydrateKey?: string;\n  } = {}\n) {\n  const router = create(\n    routes,\n    createMemoryHistory({initialEntries: [location]}),\n    resolveViewServer,\n    options\n  );\n\n  return resolveServerViewBase(\n    router,\n    isString(location) ? toLocation(router, location) : location,\n    {\n      scriptAttributes,\n      hydrateKey\n    }\n  );\n}\n\n/**\n * Hydrate the SSR result of {@link resolveServerView} on the client.\n * The router is bound to the browser history(aligned with the index\n * in the SSR payload), so navigation after hydration updates the address bar.\n * @param routes routes config, must match the server side\n * @param options options, `hydrateKey` must match the server side\n * @returns the resolved view and the router instance, for example:\n * `const {view, router} = await hydrate(routes);`\n * `hydrateRoot(root, <Router router={router}>{view}</Router>)`\n * @group Methods\n */\nexport function hydrate(\n  routes: Route | Route[],\n  options?: Options<ReactElement> & {\n    hydrateKey?: string;\n  }\n): Promise<{view: ReactNode; router: RouterInstance<Route, ReactNode>}> {\n  const {\n    data,\n    location,\n    index = 0\n  } = (window as any)[options?.hydrateKey || defaultHydrateKey] as {\n    data: any[];\n    location: Location;\n    index?: number;\n  };\n  const history = createBrowserHistory();\n  history.replace(createPath(history.location), {index});\n  const router = create(\n    routes,\n    history,\n    createHydrateResolveView(data),\n    options\n  );\n  return resolve<Route, ReactNode>(router, location).then((view) => ({\n    view,\n    router\n  }));\n}\n"],"mappings":"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"}

package/dist/types/components/Link.d.ts

@@ -4,4 +4,4 @@ import type { LinkProps } from '../types';
  * @param props
  * @group Components
  */
-export default function Link({ to, ...rest }: LinkProps): import("react/jsx-runtime").JSX.Element;
+export default function Link({ to, ...rest }: LinkProps): import("react").JSX.Element;

package/dist/types/components/NavLink.d.ts

@@ -0,0 +1,22 @@
+import type { NavLinkProps } from '../types';
+/**
+ * Link that knows whether its target matches the current location.
+ *
+ * Active rules(aligned with react-router's `NavLink`):
+ *
+ * - `target` is the pathname of `toLocation(router, to)`(baseUrl prepended),
+ *   `current` is `router.history.location.pathname`; both are lowercased
+ *   unless `caseSensitive` is set.
+ * - `isExactActive`: `current === target`.
+ * - `isActive`: `isExactActive` when `end` is set, otherwise `current` equals
+ *   `target` or starts with `target` plus a trailing `/`(so `to="/"` is active
+ *   for every path).
+ *
+ * While active the anchor renders `aria-current={ariaCurrent ?? 'page'}` and
+ * `className`/`style`/`children` receive the active state when given as
+ * functions. Click behavior is delegated to {@link Link}, inheriting the
+ * modified-click guard and the double-click lock.
+ * @param props
+ * @group Components
+ */
+export default function NavLink({ to, end, caseSensitive, className, style, ariaCurrent, children, ...rest }: NavLinkProps): import("react").JSX.Element;

package/dist/types/components/PrefetchLink.d.ts

@@ -11,9 +11,16 @@ type PrefetchLinkContext = {
  */
 export declare function usePrefetch(): PrefetchLinkContext;
 /**
- * Link support hover prefetch.
+ * Link with prefetch support.
+ *
+ * The `prefetch` prop controls when the target view is resolved:
+ * - `'intent'` (default): prefetch on hover or focus.
+ * - `'render'`: prefetch as soon as the link mounts.
+ * - `'viewport'`: prefetch when the link scrolls into the viewport.
+ * - `'none'`: never prefetch; the target is resolved on click.
+ *
  * @param props
  * @group Components
  */
-export default function PrefetchLink({ to, children, ...rest }: LinkProps): import("react/jsx-runtime").JSX.Element;
+export default function PrefetchLink({ to, prefetch, children, ...rest }: LinkProps): import("react").JSX.Element;
 export {};

package/dist/types/components/Router.d.ts

@@ -4,7 +4,7 @@ import type { Route } from '../types';
 import type { Options, ResolveView, RouterInstance } from '@native-router/core';
 import defaultResolve from '../resolve-view';
 type Props = {
-    children: ReactNode;
+    children?: ReactNode;
     routes: Route[] | Route;
     resolveView?: typeof defaultResolve;
 } & Omit<Options<ReactNode>, 'onLoadingChange'>;
@@ -13,9 +13,9 @@ type Props = {
  * @group Components
  */
 export declare function Router({ router, children }: {
-    children: ReactNode;
+    children?: ReactNode;
     router: RouterInstance<Route, ReactNode>;
-}): import("react/jsx-runtime").JSX.Element;
+}): import("react").JSX.Element;
 export declare function createRouter(routes: Route | Route[], history: History, { resolveView, ...options }?: Options<ReactNode> & {
     resolveView?: ResolveView<Route, ReactNode>;
 }): RouterInstance<Route, ReactNode>;
@@ -23,17 +23,17 @@ export declare function createRouter(routes: Route | Route[], history: History,
  * History mode Router Component.
  * @group Components
  */
-export declare function HistoryRouter(props: Props): import("react/jsx-runtime").JSX.Element;
+export declare function HistoryRouter(props: Props): import("react").JSX.Element;
 /**
  * Hash mode Router Component.
  * @group Components
  */
-export declare function HashRouter(props: Props): import("react/jsx-runtime").JSX.Element;
+export declare function HashRouter(props: Props): import("react").JSX.Element;
 /**
  * Memory mode Router Component.
  * @group Components
  */
-export declare function MemoryRouter({ initialEntries, initialIndex, ...props }: Props & MemoryHistoryOptions): import("react/jsx-runtime").JSX.Element;
+export declare function MemoryRouter({ initialEntries, initialIndex, ...props }: Props & MemoryHistoryOptions): import("react").JSX.Element;
 /**
  * Get Router instance.
  * @group Hooks

package/dist/types/components/ScrollRestoration.d.ts

@@ -0,0 +1,43 @@
+type ScrollRestorationProps = {
+    /**
+     * Scroll a freshly pushed(or replaced) entry back to the top, like a full
+     * page load. Set to false to keep the current offset across forward
+     * navigations(e.g. feed-style "load more" pages). POP always restores the
+     * saved offset, regardless of this flag.
+     * @default true
+     */
+    resetOnPush?: boolean;
+};
+/**
+ * Restore the window scroll position across history navigations.
+ *
+ * The router restores views from the in-memory `viewStack`: on back/forward
+ * the view is reused without re-fetching its data, but the browser has
+ * already left the old document position and a remounted DOM starts at the
+ * top by default. Mount `<ScrollRestoration />` anywhere inside
+ * {@link Router}(typically in the root layout) to fill that gap:
+ *
+ * - the scroll offset of every visited entry is remembered, keyed by the
+ *   absolute history index(`history.location.state.index` — the same key
+ *   `viewStack` is keyed by). Like `viewStack`, the map is in-memory and
+ *   session scoped: after a page reload there is nothing to restore and the
+ *   browser's own restoration takes over.
+ * - `history.scrollRestoration` is taken over as `manual`(the browser's
+ *   own `auto` restoration would race the restore and pre-scroll while the
+ *   left entry's offset is still being read), making the component solely
+ *   responsible for restoration; the takeover is session scoped and not
+ *   reverted on unmount, like `viewStack`.
+ * - POP restores the saved offset of the landed entry(`0,0` when none was
+ *   saved, e.g. forward-past-the-end or post-reload entries).
+ * - PUSH and REPLACE scroll a fresh entry back to the top when
+ *   `resetOnPush` is set(default). Internal re-commits of the very same
+ *   entry(the core listener's POP sync, `refresh`, listen bootstrap) never
+ *   touch the scroll.
+ *
+ * Renders nothing. SSR safe: it only subscribes in an effect and only when
+ * `window` exists.
+ * @param props
+ * @group Components
+ */
+export default function ScrollRestoration({ resetOnPush }: ScrollRestorationProps): null;
+export {};

package/dist/types/components/link-behavior.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Checks whether a click on an anchor should be intercepted and handled as an
+ * in-app navigation, following the standard link interception semantics of
+ * react-router/wouter: plain left clicks only.
+ *
+ * The browser keeps the default behavior whenever this returns `false`, so
+ * modified clicks, middle clicks and links to other browsing contexts open in
+ * a new tab/window as the user expects.
+ *
+ * @param e The click event to inspect.
+ * @param target The anchor's `target` attribute, if any.
+ * @param rel The anchor's `rel` attribute, if any.
+ * @group Components
+ */
+export declare function shouldNavigate(e: {
+    button: number;
+    defaultPrevented: boolean;
+    metaKey: boolean;
+    ctrlKey: boolean;
+    shiftKey: boolean;
+    altKey: boolean;
+}, target?: string, rel?: string): boolean;

package/dist/types/context.d.ts

@@ -3,7 +3,7 @@ import type { Context, LoadStatus, Route } from './types';
 export declare function ViewProvider(props: {
     children: ReactNode;
     value: ReactNode;
-}): import("react/jsx-runtime").JSX.Element;
+}): import("react").JSX.Element;
 /**
  * @group Hooks
  * @see {@link View View Component}
@@ -16,23 +16,34 @@ export declare function useView(): ReactNode;
  */
 export declare function View(): ReactNode;
 /**
+ * Get the named data map of the resolved route levels: an object keyed by
+ * each ancestor's `name`, holding its resolved `data`. The current level
+ * is included only when it declares a `name`.
+ *
+ * Give the generic the expected map shape to read values type-safely:
+ * `useNamedData<{user: User}>()`.
  * @group Hooks
  */
-export declare function useNamedData(): Record<string, any>;
+export declare function useNamedData<T = Record<string, unknown>>(): T;
 export declare function DataProvider({ children, name, data }: {
     children: ReactNode;
     data: any;
     name?: string;
-}): import("react/jsx-runtime").JSX.Element;
+}): import("react").JSX.Element;
 export declare const MatchedContext: import("react").Context<Context<Route> | undefined>;
 /**
  * @group Hooks
  */
 export declare function useMatched(): Context<Route>;
 /**
+ * Get the resolved `data` of the current route level, or the named data
+ * of an ancestor level when `name` is given.
+ *
+ * Give the generic the expected data type to read it type-safely without
+ * a cast: `useData<Article>()` → `Article | undefined`.
  * @group Hooks
  */
-export declare function useData(name?: string): any;
+export declare function useData<T = unknown>(name?: string): T | undefined;
 export declare const LoadingContext: import("react").Context<LoadStatus | undefined>;
 /**
  * @group Hooks

package/dist/types/index.d.ts

@@ -1,7 +1,10 @@
 export * from './components/Router';
 export { default as Link } from './components/Link';
+export { default as NavLink } from './components/NavLink';
 export { default as PrefetchLink, usePrefetch } from './components/PrefetchLink';
-export { useView, View, useData, useLoading, useMatched } from './context';
+export { default as ScrollRestoration } from './components/ScrollRestoration';
+export { useView, View, useData, useNamedData, useLoading, useMatched } from './context';
+export { useSearchParams, useSearch } from './use-search-params';
 export { default as defaultResolveView } from './resolve-view';
 export * from './types';
-export { resolveClientView } from './ssr';
+export { hydrate } from './ssr';

package/dist/types/resolve-view.d.ts

@@ -8,7 +8,7 @@ import type { Matched } from '@native-router/core';
  * @returns the resolve view
  * @see {@link create router->create}
  */
-export default function resolveView(matched: Matched<Route>[], ctx: ResolveViewContext<Route>): Promise<import("react/jsx-runtime").JSX.Element>;
-export declare function resolveViewServer(matched: Matched<Route>[], ctx: ResolveViewContext<Route>): Promise<import("react/jsx-runtime").JSX.Element>;
-export declare function createHydrateResolveView(data: any[]): (matched: Matched<Route>[], ctx: ResolveViewContext<Route>) => Promise<import("react/jsx-runtime").JSX.Element>;
+export default function resolveView(matched: Matched<Route>[], ctx: ResolveViewContext<Route>): Promise<import("react").JSX.Element>;
+export declare function resolveViewServer(matched: Matched<Route>[], ctx: ResolveViewContext<Route>): Promise<import("react").JSX.Element>;
+export declare function createHydrateResolveView(data: any[]): (matched: Matched<Route>[], ctx: ResolveViewContext<Route>) => Promise<import("react").JSX.Element>;
 export declare function getViewData(view: ReactElement): any[] | undefined;

package/dist/types/ssr.d.ts

@@ -4,11 +4,25 @@ import type { Route } from './types';
 export declare function resolveServerViewBase(router: RouterInstance<Route, ReactNode>, location: Location, options?: {
     scriptAttributes?: Record<string, string>;
     hydrateKey?: string;
-}): Promise<import("react/jsx-runtime").JSX.Element>;
+}): Promise<import("react").JSX.Element>;
 export declare function resolveServerView(routes: Route | Route[], location: Location | string, { scriptAttributes, hydrateKey, ...options }?: Options<ReactElement> & {
     scriptAttributes?: Record<string, string>;
     hydrateKey?: string;
-}): Promise<import("react/jsx-runtime").JSX.Element>;
-export declare function resolveClientView(routes: Route | Route[], options?: Options<ReactElement> & {
+}): Promise<import("react").JSX.Element>;
+/**
+ * Hydrate the SSR result of {@link resolveServerView} on the client.
+ * The router is bound to the browser history(aligned with the index
+ * in the SSR payload), so navigation after hydration updates the address bar.
+ * @param routes routes config, must match the server side
+ * @param options options, `hydrateKey` must match the server side
+ * @returns the resolved view and the router instance, for example:
+ * `const {view, router} = await hydrate(routes);`
+ * `hydrateRoot(root, <Router router={router}>{view}</Router>)`
+ * @group Methods
+ */
+export declare function hydrate(routes: Route | Route[], options?: Options<ReactElement> & {
     hydrateKey?: string;
-}): Promise<import("react/jsx-runtime").JSX.Element>;
+}): Promise<{
+    view: ReactNode;
+    router: RouterInstance<Route, ReactNode>;
+}>;

package/dist/types/types.d.ts

@@ -1,28 +1,112 @@
-import type { AnchorHTMLAttributes, ComponentType, DetailedHTMLProps, ReactNode } from 'react';
-import type { BaseRoute, Matched, Location, RouterInstance } from '@native-router/core';
+import type { AnchorHTMLAttributes, ComponentType, CSSProperties, DetailedHTMLProps, ReactNode } from 'react';
+import type { BaseRoute, ExtractPathParams, Matched, Location, RouterInstance, SearchInput } from '@native-router/core';
 export type ResolveViewContext<R extends BaseRoute> = {
     router: RouterInstance<R>;
     location: Location;
 };
-export type Context<T extends BaseRoute> = {
+export type Context<T extends BaseRoute, P = Record<string, string>, S = SearchInput> = {
     matched: Matched<T>[];
     index: number;
-    router: RouterInstance<BaseRoute>;
+    router: RouterInstance<T>;
     location: Location;
-    params: Record<string, string>;
+    params: P;
+    /**
+     * The parsed search of the current location: with a route
+     * {@link Route.search search schema} the schema output, otherwise the
+     * raw input object of `parseSearchInput`(strings, arrays for repeated
+     * keys).
+     */
+    search: S;
 };
-export type Route = BaseRoute<{
+/**
+ * Params shape of a route path. Literal patterns get a precise shape via
+ * {@link ExtractPathParams}; the default `string`(and `any`) degrade to
+ * the legacy `Record<string, string>` so untyped routes keep working.
+ * @group Types
+ * @category Route
+ */
+export type RouteParams<P extends string> = string extends P ? Record<string, string> : ExtractPathParams<P>;
+/**
+ * Route with optional path-pattern and search generics. Give `path` a
+ * string literal type and the `data`/`component`/`errorComponent`
+ * contexts receive precisely-typed `params`, e.g.
+ * `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}`.
+ *
+ * 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.
+ * `children` accepts `Route<any, any>` so levels with different patterns
+ * and search shapes nest without variance conflicts.
+ * @group Types
+ * @category Route
+ */
+export type Route<P extends string = string, S = any> = Omit<BaseRoute<{
     name?: string;
-    data?(ctx: Context<Route>): any | Promise<any>;
-    component?(ctx: Context<Route>): ComponentType | Promise<ComponentType | {
+    data?(ctx: Context<Route, RouteParams<P>, S>): any | Promise<any>;
+    component?(ctx: Context<Route, RouteParams<P>, S>): ComponentType | Promise<ComponentType | {
         default: ComponentType;
     }>;
-}>;
+    /**
+     * Not parametrized by `P`: props are strictly contravariant, so a
+     * precise params type here would break assignability between
+     * `Route<'/a/:id'>` and plain `Route`.
+     */
+    errorComponent?: ComponentType<{
+        error: Error;
+        ctx: Context<Route>;
+    }>;
+}>, 'path' | 'children'> & {
+    /** Path pattern; params of the contexts above are inferred from it. */
+    path?: P;
+    /**
+     * `Route<any, any>` accepts levels with any path pattern and search
+     * shape, so typed levels nest without variance conflicts. The
+     * `search` field is inherited from `BaseRoute`, loosely typed — see
+     * the Route doc above.
+     */
+    children?: Route<any, any>[];
+};
 export type LoadStatus = {
     key: number;
     status: 'pending' | 'resolved' | 'rejected';
 };
 export type LinkProps = {
     to: string;
+    /**
+     * 预取策略：'intent'（默认，hover/focus 触发）、'render'（挂载即预取）、
+     * 'viewport'（进入视口）、'none'（不预取）
+     */
+    prefetch?: 'intent' | 'render' | 'viewport' | 'none';
     children?: ReactNode;
 } & DetailedHTMLProps<AnchorHTMLAttributes<HTMLAnchorElement>, HTMLAnchorElement>;
+export type { SearchInput, SearchOutputOf, StandardSchemaV1 } from '@native-router/core';
+/**
+ * Active state passed to the render-prop / callback flavors of
+ * {@link NavLinkProps.className}, {@link NavLinkProps.style} and
+ * {@link NavLinkProps.children}.
+ */
+export type NavLinkState = {
+    /** Matches the target pathname, partially or exactly. */
+    isActive: boolean;
+    /** Matches the target pathname exactly. */
+    isExactActive: boolean;
+};
+export type NavLinkProps = {
+    /** Target path, same as {@link LinkProps.to}. */
+    to: string;
+    /** Only the exact pathname counts as active. @default false */
+    end?: boolean;
+    /** Compare pathnames case-sensitively. @default false */
+    caseSensitive?: boolean;
+    className?: string | ((state: NavLinkState) => string);
+    style?: CSSProperties | ((state: NavLinkState) => CSSProperties);
+    /** `aria-current` value rendered while active. @default 'page' */
+    ariaCurrent?: 'page' | 'step' | 'location' | 'date' | 'time';
+    children?: ReactNode | ((state: NavLinkState) => ReactNode);
+} & Omit<DetailedHTMLProps<AnchorHTMLAttributes<HTMLAnchorElement>, HTMLAnchorElement>, 'className' | 'style' | 'children' | 'onClick'>;

package/dist/types/use-search-params.d.ts

@@ -0,0 +1,56 @@
+import type { SearchInput, SearchOutputOf, StandardSchemaV1 } from '@native-router/core';
+type SetSearchParams = (next: URLSearchParams | ((prev: URLSearchParams) => URLSearchParams), opts?: {
+    replace?: boolean;
+}) => Promise<void> | void;
+/**
+ * Read and write the search params of the current location.
+ *
+ * The raw `location.search` string is subscribed via
+ * `useSyncExternalStore`(same source as the Router Component), so every
+ * location change(push, replace or pop) re-renders the component with the
+ * latest params; a fresh `URLSearchParams` view is derived from that string
+ * on each render.
+ *
+ * The setter navigates like any other route change: by default the new
+ * search is pushed onto the history stack(mainstream react-router
+ * semantics), pass `{replace: true}` to rewrite the current entry instead.
+ * Since the search is part of the location, every write re-resolves the
+ * matched route, so route `data` fetchers(see {@link useData}) observe the
+ * new search on the next {@link useData} read.
+ *
+ * @group Hooks
+ * @returns [searchParams, setSearchParams] - the current search params and
+ * the setter(functional updates receive the live previous params); the
+ * setter returns a `Promise<void>` that resolves once the navigation
+ * commits, so callers may optionally `await` it
+ */
+export declare function useSearchParams(): [URLSearchParams, SetSearchParams];
+/**
+ * Read the parsed search params of the current location.
+ *
+ * The raw `location.search` string is subscribed via
+ * `useSyncExternalStore`(same source as {@link useSearchParams}), so every
+ * location change(push, replace or pop) re-renders the component with the
+ * latest params; the parse itself runs on each render.
+ *
+ * Without a schema the hook degrades to the raw input object of
+ * `parseSearchInput` — strings, arrays for repeated keys
+ * (`{page: '2', tag: ['a', 'b']}`). With a schema — any zod/valibot/
+ * arktype schema, see the route {@link Route.search search field} — the
+ * returned object is the schema's parsed output, so coercion and defaults
+ * apply, e.g. `useSearch(pageSchema).page` is a number.
+ *
+ * Prefer declaring the schema once on the route: its `data` loader then
+ * receives a parsed `ctx.search` during resolve, and an invalid search
+ * fails the navigation through the existing error channels instead of
+ * throwing during render.
+ *
+ * @group Hooks
+ * @param schema an optional Standard Schema validator of the search; it
+ * must validate synchronously
+ * @returns the parsed search params of the current location
+ * @throws {SearchError} when `schema` rejects the current search
+ */
+export declare function useSearch<S extends StandardSchemaV1>(schema: S): SearchOutputOf<S>;
+export declare function useSearch(): SearchInput;
+export {};