@richie-router/react 0.1.2 → 0.1.4

package/dist/esm/router.test.mjs

@@ -0,0 +1,552 @@
+// packages/react/src/router.test.ts
+import { describe, expect, test } from "bun:test";
+import React from "react";
+import { renderToStaticMarkup } from "react-dom/server";
+import {
+  Link,
+  useMatchRoute,
+  RouterProvider,
+  createLink,
+  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
+  });
+}
+function createLinkTestRouteTree(component) {
+  const rootRoute = createRootRoute({
+    component
+  });
+  const postRoute = createFileRoute("/post")({
+    component: () => null
+  });
+  const postsRoute = createFileRoute("/posts")({
+    component: () => null
+  });
+  const postDetailRoute = createFileRoute("/posts/$postId")({
+    component: () => null
+  });
+  postsRoute._addFileChildren({
+    detail: postDetailRoute
+  });
+  return rootRoute._addFileChildren({
+    post: postRoute,
+    posts: postsRoute
+  });
+}
+function renderLinkMarkup(initialEntry, component) {
+  const history = createMemoryHistory({
+    initialEntries: [initialEntry]
+  });
+  const router = createRouter({
+    routeTree: createLinkTestRouteTree(component),
+    history
+  });
+  return renderToStaticMarkup(React.createElement(RouterProvider, { router }));
+}
+describe("createRouter basePath", () => {
+  test('treats "/" as the root basePath', () => {
+    const history = createMemoryHistory({
+      initialEntries: ["/about?tab=team#bio"]
+    });
+    const router = createRouter({
+      routeTree: createTestRouteTree(),
+      history,
+      basePath: "/"
+    });
+    expect(router.state.location.pathname).toBe("/about");
+    expect(router.state.location.href).toBe("/about?tab=team#bio");
+    expect(router.buildHref({ to: "/about" })).toBe("/about");
+  });
+  test("normalizes a trailing slash in the basePath", async () => {
+    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.buildHref({ to: "/about" })).toBe("/project/about");
+    await router.navigate({
+      to: "/about"
+    });
+    expect(history.location.href).toBe("/project/about");
+  });
+  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;
+    }
+  });
+});
+describe("Link active state", () => {
+  test("keeps parent links active on child routes by default", () => {
+    const TestLink = Link;
+    const markup = renderLinkMarkup("/posts/alpha", () => React.createElement(TestLink, { to: "/posts", activeProps: { className: "active" } }, "Posts"));
+    expect(markup).toContain('class="active"');
+  });
+  test("supports exact-only active matching", () => {
+    const TestLink = Link;
+    const markup = renderLinkMarkup("/posts/alpha", () => React.createElement(TestLink, {
+      to: "/posts",
+      activeOptions: { exact: true },
+      activeProps: { className: "active" }
+    }, "Posts"));
+    expect(markup).not.toContain('class="active"');
+  });
+  test("matches path segments instead of raw string prefixes", () => {
+    const TestLink = Link;
+    const markup = renderLinkMarkup("/posts/alpha", () => React.createElement(TestLink, { to: "/post", activeProps: { className: "active" } }, "Post"));
+    expect(markup).not.toContain('class="active"');
+  });
+  test("applies activeOptions in custom links created with createLink", () => {
+    const AppLink = createLink((props) => React.createElement("a", props));
+    const markup = renderLinkMarkup("/posts/alpha", () => React.createElement(AppLink, {
+      to: "/posts",
+      activeOptions: { exact: true },
+      activeProps: { className: "active" }
+    }, "Posts"));
+    expect(markup).not.toContain('class="active"');
+  });
+});
+describe("useMatchRoute", () => {
+  test("returns matched params for exact matches", () => {
+    const markup = renderLinkMarkup("/posts/alpha", () => {
+      const matchRoute = useMatchRoute();
+      const match = matchRoute({ to: "/posts/$postId" });
+      return React.createElement("pre", null, match === false ? "false" : JSON.stringify(match));
+    });
+    expect(markup).toContain("{"postId":"alpha"}");
+  });
+  test("supports fuzzy parent matching", () => {
+    const markup = renderLinkMarkup("/posts/alpha", () => {
+      const matchRoute = useMatchRoute();
+      const match = matchRoute({ to: "/posts", fuzzy: true });
+      return React.createElement("pre", null, match === false ? "false" : JSON.stringify(match));
+    });
+    expect(markup).toContain("{}");
+  });
+  test("supports partial param filters", () => {
+    const markup = renderLinkMarkup("/posts/alpha", () => {
+      const matchRoute = useMatchRoute();
+      const match = matchRoute({ to: "/posts/$postId", params: { postId: "beta" } });
+      return React.createElement("pre", null, match === false ? "false" : JSON.stringify(match));
+    });
+    expect(markup).toContain("false");
+  });
+  test("can include search params in the match", () => {
+    const markup = renderLinkMarkup("/posts/alpha?tab=details&count=2", () => {
+      const matchRoute = useMatchRoute();
+      const match = matchRoute({
+        to: "/posts/$postId",
+        includeSearch: true,
+        search: { tab: "details" }
+      });
+      return React.createElement("pre", null, match === false ? "false" : JSON.stringify(match));
+    });
+    expect(markup).toContain("{"postId":"alpha"}");
+  });
+});

package/dist/types/router.d.ts

@@ -67,6 +67,8 @@ type ParamsInput<TParams> = TParams | ((previous: TParams) => TParams);
 type SearchInput<TSearch> = TSearch | ((previous: TSearch) => TSearch) | true;
 type ParamsOption<TParams> = keyof TParams extends never ? {
     params?: never;
+} : string extends keyof TParams ? {
+    params?: ParamsInput<TParams>;
 } : {
     params: ParamsInput<TParams>;
 };
@@ -107,8 +109,22 @@ export type NavigateOptions<TTo extends RoutePaths = RoutePaths> = {
     search?: SearchInput<SearchForTo<TTo>>;
 } & NavigateBaseOptions & ParamsOption<ParamsForTo<TTo>>;
 export type NavigateFn = <TTo extends RoutePaths>(options: NavigateOptions<TTo>) => Promise<void>;
+export interface MatchRouteOptions {
+    fuzzy?: boolean;
+    includeSearch?: boolean;
+}
+export type UseMatchRouteOptions<TTo extends RoutePaths = RoutePaths> = {
+    to: TTo;
+    params?: Partial<ParamsForTo<TTo>>;
+    search?: Record<string, unknown>;
+} & MatchRouteOptions;
+export type MatchRouteFn = <TTo extends RoutePaths>(options: UseMatchRouteOptions<TTo>) => false | ParamsForTo<TTo>;
+export interface ActiveOptions {
+    exact?: boolean;
+}
 export type LinkOwnProps<TTo extends RoutePaths> = NavigateOptions<TTo> & {
     preload?: 'intent' | 'render' | false;
+    activeOptions?: ActiveOptions;
     activeProps?: React.AnchorHTMLAttributes<HTMLAnchorElement>;
     children?: React.ReactNode | ((ctx: {
         isActive: boolean;
@@ -125,6 +141,7 @@ export interface RouterState {
 export interface RouterOptions<TRouteTree extends AnyRoute> {
     routeTree: TRouteTree;
     history?: RouterHistory;
+    basePath?: string;
     defaultPreload?: 'intent' | 'render' | false;
     defaultPreloadDelay?: number;
     defaultPendingMs?: number;
@@ -170,6 +187,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>);
@@ -184,6 +203,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;
@@ -192,21 +213,28 @@ 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;
 }
 export declare function createRouter<TRouteTree extends AnyRoute>(options: RouterOptions<TRouteTree>): Router<TRouteTree>;
-export declare function RouterProvider({ router }: {
-    router: RegisteredRouter;
+export declare function RouterProvider<TRouteTree extends AnyRoute>({ router }: {
+    router: Router<TRouteTree>;
 }): React.ReactElement;
 export declare function Outlet(): React.ReactNode;
 export declare function useRouter(): RegisteredRouter;
@@ -221,6 +249,7 @@ export declare function useSearch<TFrom extends RoutePaths>(options?: {
     from?: TFrom;
 }): SearchOfRoute<RouteById<TFrom>>;
 export declare function useNavigate(): NavigateFn;
+export declare function useMatchRoute(): MatchRouteFn;
 export declare function useLocation(): ParsedLocation;
 export declare function useRouterState<TSelection>(options: {
     select: Selector<TSelection>;

package/package.json

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