@richie-router/react 0.1.1 → 0.1.3

package/dist/esm/router.test.mjs

@@ -0,0 +1,418 @@
+// packages/react/src/router.test.ts
+import { describe, expect, test } from "bun:test";
+import {
+  createFileRoute,
+  createMemoryHistory,
+  createRootRoute,
+  createRouter
+} from "./router.mjs";
+function createTestRouteTree(options) {
+  const rootRoute = createRootRoute({
+    component: () => null
+  });
+  const indexRoute = createFileRoute("/")({
+    component: () => null
+  });
+  const aboutRoute = createFileRoute("/about")({
+    component: () => null
+  });
+  aboutRoute._setServerHead(options?.serverHead);
+  return rootRoute._addFileChildren({
+    index: indexRoute,
+    about: aboutRoute
+  });
+}
+function createNestedHeadRouteTree() {
+  const rootRoute = createRootRoute({
+    component: () => null
+  });
+  const postsRoute = createFileRoute("/posts")({
+    component: () => null,
+    head: [
+      { tag: "title", children: "Posts" }
+    ]
+  });
+  const postRoute = createFileRoute("/posts/$postId")({
+    component: () => null
+  });
+  rootRoute._setServerHead(true);
+  postRoute._setServerHead(true);
+  postsRoute._addFileChildren({
+    post: postRoute
+  });
+  return rootRoute._addFileChildren({
+    posts: postsRoute
+  });
+}
+function createRootServerHeadTree() {
+  const rootRoute = createRootRoute({
+    component: () => null
+  });
+  const indexRoute = createFileRoute("/")({
+    component: () => null
+  });
+  const aboutRoute = createFileRoute("/about")({
+    component: () => null
+  });
+  rootRoute._setServerHead(true);
+  return rootRoute._addFileChildren({
+    index: indexRoute,
+    about: aboutRoute
+  });
+}
+function createNestedServerHeadTree() {
+  const rootRoute = createRootRoute({
+    component: () => null
+  });
+  const postsRoute = createFileRoute("/posts")({
+    component: () => null
+  });
+  const postRoute = createFileRoute("/posts/$postId")({
+    component: () => null
+  });
+  rootRoute._setServerHead(true);
+  postsRoute._setServerHead(true);
+  postRoute._setServerHead(true);
+  postsRoute._addFileChildren({
+    post: postRoute
+  });
+  return rootRoute._addFileChildren({
+    posts: postsRoute
+  });
+}
+describe("createRouter basePath", () => {
+  test("strips the basePath from the current history location", () => {
+    const history = createMemoryHistory({
+      initialEntries: ["/project/about?tab=team#bio"]
+    });
+    const router = createRouter({
+      routeTree: createTestRouteTree(),
+      history,
+      basePath: "/project"
+    });
+    expect(router.state.location.pathname).toBe("/about");
+    expect(router.state.location.href).toBe("/about?tab=team#bio");
+    expect(router.state.matches.at(-1)?.route.fullPath).toBe("/about");
+  });
+  test("prefixes generated hrefs and history writes with the basePath", async () => {
+    const history = createMemoryHistory({
+      initialEntries: ["/project"]
+    });
+    const router = createRouter({
+      routeTree: createTestRouteTree(),
+      history,
+      basePath: "/project"
+    });
+    expect(router.buildHref({ to: "/about" })).toBe("/project/about");
+    await router.navigate({
+      to: "/about",
+      search: {
+        tab: "team"
+      }
+    });
+    expect(history.location.href).toBe("/project/about?tab=team");
+    expect(router.state.location.href).toBe("/about?tab=team");
+  });
+  test("uses the basePath for the default head API endpoint", async () => {
+    const history = createMemoryHistory({
+      initialEntries: ["/project/about"]
+    });
+    const fetchCalls = [];
+    const originalFetch = globalThis.fetch;
+    globalThis.fetch = async (input) => {
+      fetchCalls.push(typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url);
+      return new Response(JSON.stringify({
+        head: [],
+        routeHeads: [
+          { routeId: "/about", head: [] }
+        ]
+      }), {
+        status: 200,
+        headers: {
+          "content-type": "application/json"
+        }
+      });
+    };
+    try {
+      const router = createRouter({
+        routeTree: createTestRouteTree({ serverHead: true }),
+        history,
+        basePath: "/project"
+      });
+      await router.load();
+      expect(fetchCalls).toHaveLength(1);
+      expect(fetchCalls[0]).toBe("/project/head-api?href=%2Fproject%2Fabout");
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+  test("uses one document head request and preserves inline head precedence", async () => {
+    const history = createMemoryHistory({
+      initialEntries: ["/posts/alpha"]
+    });
+    const fetchCalls = [];
+    const originalFetch = globalThis.fetch;
+    globalThis.fetch = async (input) => {
+      const url = typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url;
+      fetchCalls.push(url);
+      return new Response(JSON.stringify({
+        head: [
+          { tag: "title", children: "Site" },
+          { tag: "title", children: "Alpha" }
+        ],
+        routeHeads: [
+          {
+            routeId: "__root__",
+            head: [{ tag: "title", children: "Site" }],
+            staleTime: 60000
+          },
+          {
+            routeId: "/posts/$postId",
+            head: [{ tag: "title", children: "Alpha" }],
+            staleTime: 1e4
+          }
+        ],
+        staleTime: 1e4
+      }), {
+        status: 200,
+        headers: {
+          "content-type": "application/json"
+        }
+      });
+    };
+    try {
+      const router = createRouter({
+        routeTree: createNestedHeadRouteTree(),
+        history
+      });
+      await router.load();
+      expect(fetchCalls).toEqual(["/head-api?href=%2Fposts%2Falpha"]);
+      expect(router.state.head).toEqual([
+        { tag: "title", children: "Alpha" }
+      ]);
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+  test("reuses a fresh root server head across navigations without refetching", async () => {
+    const history = createMemoryHistory({
+      initialEntries: ["/"]
+    });
+    const fetchCalls = [];
+    const originalFetch = globalThis.fetch;
+    globalThis.fetch = async (input) => {
+      fetchCalls.push(typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url);
+      return new Response(JSON.stringify({
+        head: [
+          { tag: "title", children: "Site" }
+        ],
+        routeHeads: [
+          {
+            routeId: "__root__",
+            head: [{ tag: "title", children: "Site" }],
+            staleTime: 60000
+          }
+        ],
+        staleTime: 60000
+      }), {
+        status: 200,
+        headers: {
+          "content-type": "application/json"
+        }
+      });
+    };
+    try {
+      const router = createRouter({
+        routeTree: createRootServerHeadTree(),
+        history
+      });
+      await router.load();
+      await router.navigate({
+        to: "/about"
+      });
+      expect(fetchCalls).toEqual(["/head-api?href=%2F"]);
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+  test("seeds the route head cache from the dehydrated snapshot", async () => {
+    const history = createMemoryHistory({
+      initialEntries: ["/about"]
+    });
+    const fetchCalls = [];
+    const originalFetch = globalThis.fetch;
+    const globalWithWindow = globalThis;
+    const originalWindow = globalWithWindow.window;
+    globalThis.fetch = async (input) => {
+      fetchCalls.push(typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url);
+      return new Response(JSON.stringify({
+        head: [
+          { tag: "title", children: "Site" }
+        ],
+        routeHeads: [
+          {
+            routeId: "__root__",
+            head: [{ tag: "title", children: "Site" }],
+            staleTime: 60000
+          }
+        ],
+        staleTime: 60000
+      }), {
+        status: 200,
+        headers: {
+          "content-type": "application/json"
+        }
+      });
+    };
+    globalWithWindow.window = {
+      __RICHIE_ROUTER_HEAD__: {
+        href: "/about",
+        head: [
+          { tag: "title", children: "Site" }
+        ],
+        routeHeads: [
+          {
+            routeId: "__root__",
+            head: [{ tag: "title", children: "Site" }],
+            staleTime: 60000
+          }
+        ]
+      }
+    };
+    try {
+      const router = createRouter({
+        routeTree: createRootServerHeadTree(),
+        history
+      });
+      await router.load();
+      expect(fetchCalls).toHaveLength(0);
+      expect(router.state.head).toEqual([
+        { tag: "title", children: "Site" }
+      ]);
+    } finally {
+      globalThis.fetch = originalFetch;
+      if (originalWindow === undefined) {
+        Reflect.deleteProperty(globalWithWindow, "window");
+      } else {
+        originalWindow.__RICHIE_ROUTER_HEAD__ = undefined;
+        globalWithWindow.window = originalWindow;
+      }
+    }
+  });
+  test("reuses the initial merged head snapshot without fetching when the branch has no inline head", async () => {
+    const history = createMemoryHistory({
+      initialEntries: ["/about"]
+    });
+    const fetchCalls = [];
+    const originalFetch = globalThis.fetch;
+    const globalWithWindow = globalThis;
+    const originalWindow = globalWithWindow.window;
+    globalThis.fetch = async (input) => {
+      fetchCalls.push(typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url);
+      return new Response("{}", {
+        status: 500
+      });
+    };
+    globalWithWindow.window = {
+      __RICHIE_ROUTER_HEAD__: {
+        href: "/about",
+        head: [
+          { tag: "title", children: "About from SSR" }
+        ]
+      }
+    };
+    try {
+      const router = createRouter({
+        routeTree: createTestRouteTree({ serverHead: true }),
+        history
+      });
+      await router.load();
+      expect(fetchCalls).toHaveLength(0);
+      expect(router.state.head).toEqual([
+        { tag: "title", children: "About from SSR" }
+      ]);
+    } finally {
+      globalThis.fetch = originalFetch;
+      if (originalWindow === undefined) {
+        Reflect.deleteProperty(globalWithWindow, "window");
+      } else {
+        originalWindow.__RICHIE_ROUTER_HEAD__ = undefined;
+        globalWithWindow.window = originalWindow;
+      }
+    }
+  });
+  test("uses the merged document head without route fallback requests when the branch has no inline head", async () => {
+    const history = createMemoryHistory({
+      initialEntries: ["/posts/alpha"]
+    });
+    const fetchCalls = [];
+    const originalFetch = globalThis.fetch;
+    globalThis.fetch = async (input) => {
+      const url = typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url;
+      fetchCalls.push(url);
+      return new Response(JSON.stringify({
+        head: [
+          { tag: "meta", name: "description", content: "Nested server head" },
+          { tag: "title", children: "Alpha" }
+        ],
+        staleTime: 1e4
+      }), {
+        status: 200,
+        headers: {
+          "content-type": "application/json"
+        }
+      });
+    };
+    try {
+      const router = createRouter({
+        routeTree: createNestedServerHeadTree(),
+        history
+      });
+      await router.load();
+      expect(fetchCalls).toEqual(["/head-api?href=%2Fposts%2Falpha"]);
+      expect(router.state.head).toEqual([
+        { tag: "meta", name: "description", content: "Nested server head" },
+        { tag: "title", children: "Alpha" }
+      ]);
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+  test("keeps loadRouteHead as the route-scoped override path", async () => {
+    const history = createMemoryHistory({
+      initialEntries: ["/about"]
+    });
+    const fetchCalls = [];
+    const loadRouteHeadCalls = [];
+    const originalFetch = globalThis.fetch;
+    globalThis.fetch = async (input) => {
+      fetchCalls.push(typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url);
+      return new Response("{}", {
+        status: 500
+      });
+    };
+    try {
+      const router = createRouter({
+        routeTree: createTestRouteTree({ serverHead: true }),
+        history,
+        loadRouteHead: async ({ routeId }) => {
+          loadRouteHeadCalls.push(routeId);
+          return {
+            head: [
+              { tag: "title", children: "About override" }
+            ],
+            staleTime: 1000
+          };
+        }
+      });
+      await router.load();
+      expect(loadRouteHeadCalls).toEqual(["/about"]);
+      expect(fetchCalls).toHaveLength(0);
+      expect(router.state.head).toEqual([
+        { tag: "title", children: "About override" }
+      ]);
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+});

package/dist/types/router.d.ts

@@ -1,6 +1,6 @@
 import React from 'react';
 import { RouteNode, isNotFound, isRedirect, notFound, redirect } from '@richie-router/core';
-import type { AnyComponent, AnyRoute, DehydratedHeadState, HeadConfig, NormalizeRouteId, ParsedLocation, ResolveAllParams, RouteMatch, RouteOptions as CoreRouteOptions, Simplify } from '@richie-router/core';
+import type { AnyComponent, AnyRoute, DehydratedHeadState, HeadConfig, NormalizeRouteId, ParsedLocation, ResolveAllParams, RouteMatch, RouteOptions as CoreRouteOptions } from '@richie-router/core';
 import { createBrowserHistory, createHashHistory, createMemoryHistory } from './history';
 import type { MemoryHistoryOptions, RouterHistory } from './history';
 declare global {
@@ -10,12 +10,9 @@ declare global {
 }
 export interface Register {
 }
-type RegisteredHeadTagMap = Register extends {
-    headTagMap: infer THeadTagMap;
-} ? THeadTagMap : Record<string, string>;
-type RegisteredHeadTagSearchSchema = Register extends {
-    headTagSearchSchema: infer THeadTagSearchSchema;
-} ? THeadTagSearchSchema : Record<string, {}>;
+type RegisteredRouteSearchSchema = Register extends {
+    routeSearchSchema: infer TRouteSearchSchema;
+} ? TRouteSearchSchema : Record<string, {}>;
 type RegisteredRouteTree = Register extends {
     routeTree: infer TRouteTree;
 } ? TRouteTree : AnyRoute;
@@ -65,8 +62,7 @@ type MatchOfRoute<TRoute> = {
 type SafeRouteByTo<TTo extends string> = [RouteById<TTo>] extends [never] ? AnyRoute : RouteById<TTo>;
 type ParamsForTo<TTo extends string> = ParamsOfRoute<SafeRouteByTo<TTo>>;
 type SearchForTo<TTo extends string> = SearchOfRoute<SafeRouteByTo<TTo>>;
-type SearchForFullPath<TPath extends string> = TPath extends keyof RegisteredHeadTagSearchSchema ? RegisteredHeadTagSearchSchema[TPath] : {};
-type HeadTagNameForFullPath<TPath extends string> = TPath extends keyof RegisteredHeadTagMap ? RegisteredHeadTagMap[TPath] : string;
+type SearchForRouteId<TPath extends string> = TPath extends keyof RegisteredRouteSearchSchema ? RegisteredRouteSearchSchema[TPath] : {};
 type ParamsInput<TParams> = TParams | ((previous: TParams) => TParams);
 type SearchInput<TSearch> = TSearch | ((previous: TSearch) => TSearch) | true;
 type ParamsOption<TParams> = keyof TParams extends never ? {
@@ -79,11 +75,12 @@ type ClientHeadOption<TPath extends string, TSearch> = HeadConfig | ((ctx: {
     search: TSearch;
     matches: RouteMatch[];
 }) => HeadConfig);
-type RouteHeadOption<TPath extends string, TSearch> = ClientHeadOption<TPath, TSearch> | (HeadTagNameForFullPath<TPath> extends never ? never : HeadTagNameForFullPath<TPath>);
 type RouteOptionsInput<TPath extends string, TSearch> = Omit<CoreRouteOptions<TPath, TSearch>, 'head'> & {
-    head?: RouteHeadOption<TPath, TSearch>;
+    head?: ClientHeadOption<TPath, TSearch>;
+};
+type FileRouteInstance<TPath extends string, TSearch, TFileTypes = unknown, THasInlineHead extends boolean = boolean> = RouteNode<TPath, NormalizeRouteId<TPath>, ResolveAllParams<TPath>, TSearch, TFileTypes> & RouteApiMethods<RouteNode<TPath, NormalizeRouteId<TPath>, ResolveAllParams<TPath>, TSearch, TFileTypes>> & {
+    __hasInlineHead: THasInlineHead;
 };
-type FileRouteInstance<TPath extends string, TSearch, TFileTypes = unknown> = RouteNode<TPath, NormalizeRouteId<TPath>, ResolveAllParams<TPath>, TSearch, TFileTypes> & RouteApiMethods<RouteNode<TPath, NormalizeRouteId<TPath>, ResolveAllParams<TPath>, TSearch, TFileTypes>>;
 export interface TypedRouteMatch<TPath extends string, TSearch, TRoute extends AnyRoute = AnyRoute> extends Omit<RouteMatch<TRoute>, 'params' | 'search'> {
     params: ResolveAllParams<TPath>;
     search: TSearch;
@@ -128,6 +125,7 @@ export interface RouterState {
 export interface RouterOptions<TRouteTree extends AnyRoute> {
     routeTree: TRouteTree;
     history?: RouterHistory;
+    basePath?: string;
     defaultPreload?: 'intent' | 'render' | false;
     defaultPreloadDelay?: number;
     defaultPendingMs?: number;
@@ -142,7 +140,7 @@ export interface RouterOptions<TRouteTree extends AnyRoute> {
     stringifySearch?: (search: Record<string, unknown>) => string;
     loadRouteHead?: (ctx: {
         route: AnyRoute;
-        headTagName: string;
+        routeId: string;
         params: Record<string, string>;
         search: unknown;
         location: ParsedLocation;
@@ -156,12 +154,12 @@ type InternalRouteMatch = RouteMatch & {
     id: string;
 };
 type Selector<TSelection> = (state: RouterState) => TSelection;
-export declare function createFileRoute<TPath extends string>(path: TPath): <TCustomSearch = {}>(options: RouteOptionsInput<TPath, Simplify<SearchForFullPath<TPath> & TCustomSearch>> & {
-    validateSearch?: (raw: Record<string, unknown>) => TCustomSearch;
-}) => FileRouteInstance<TPath, Simplify<SearchForFullPath<TPath> & TCustomSearch>>;
-export declare function createRootRoute<TCustomSearch = {}>(options: CoreRouteOptions<'__root__', TCustomSearch> & {
-    validateSearch?: (raw: Record<string, unknown>) => TCustomSearch;
-}): FileRouteInstance<'__root__', TCustomSearch>;
+export declare function createFileRoute<TPath extends string>(path: TPath): <TOptions extends RouteOptionsInput<TPath, SearchForRouteId<TPath>>>(options: TOptions) => FileRouteInstance<TPath, SearchForRouteId<TPath>, unknown, TOptions extends {
+    head: any;
+} ? true : false>;
+export declare function createRootRoute<TOptions extends RouteOptionsInput<'__root__', SearchForRouteId<'__root__'>>>(options: TOptions): FileRouteInstance<'__root__', SearchForRouteId<'__root__'>, unknown, TOptions extends {
+    head: any;
+} ? true : false>;
 export declare class Router<TRouteTree extends AnyRoute> {
     readonly routeTree: TRouteTree;
     readonly history: RouterHistory;
@@ -173,6 +171,8 @@ export declare class Router<TRouteTree extends AnyRoute> {
     private readonly headCache;
     private readonly parseSearch;
     private readonly stringifySearch;
+    private readonly basePath;
+    private initialHeadSnapshot?;
     private started;
     private unsubscribeHistory?;
     constructor(options: RouterOptions<TRouteTree>);
@@ -187,6 +187,8 @@ export declare class Router<TRouteTree extends AnyRoute> {
     preloadRoute<TTo extends RoutePaths>(options: NavigateOptions<TTo>): Promise<void>;
     invalidate(): Promise<void>;
     buildHref<TTo extends RoutePaths>(options: NavigateOptions<TTo>): string;
+    private buildLocation;
+    private buildLocationHref;
     private readLocation;
     private applyTrailingSlash;
     private notify;
@@ -195,14 +197,21 @@ export declare class Router<TRouteTree extends AnyRoute> {
     private resolveSearch;
     resolveLocation(location: ParsedLocation, options?: {
         request?: Request;
+        initialHeadSnapshot?: DehydratedHeadState;
     }): Promise<{
         matches: InternalRouteMatch[];
         head: HeadConfig;
         error: unknown;
     }>;
     private resolveLocationHead;
+    private getRouteHeadCacheKey;
+    private getCachedRouteHead;
+    private setRouteHeadCache;
+    private seedHeadCacheFromRouteHeads;
+    private cacheRouteHeadsFromDocument;
     private loadRouteHead;
     private fetchRouteHead;
+    private fetchDocumentHead;
     private commitLocation;
     private restoreScroll;
     private handleHistoryChange;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@richie-router/react",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "React runtime, components, and hooks for Richie Router",
   "sideEffects": false,
   "exports": {
@@ -13,7 +13,7 @@
     }
   },
   "dependencies": {
-    "@richie-router/core": "^0.1.1"
+    "@richie-router/core": "^0.1.3"
   },
   "peerDependencies": {
     "react": "^19"