@pyreon/router 0.3.0 → 0.4.0

package/src/tests/router.test.ts

@@ -5,14 +5,18 @@ import {
   createRouter,
   hydrateLoaderData,
   lazy,
+  onBeforeRouteLeave,
+  onBeforeRouteUpdate,
   prefetchLoaderData,
   RouterLink,
   RouterProvider,
   RouterView,
   serializeLoaderData,
+  useBlocker,
   useLoaderData,
   useRoute,
   useRouter,
+  useSearchParams,
 } from "../index"
 import {
   buildNameIndex,
@@ -1457,9 +1461,9 @@ describe("RouterLink", () => {
     const router = createRouter({ routes, url: "/" })
     let replaceCalled = false
     const origReplace = router.replace.bind(router)
-    router.replace = async (path: string) => {
+    router.replace = async (location: string | { name: string }) => {
       replaceCalled = true
-      return origReplace(path)
+      return origReplace(location as string)
     }
     mount(
       h(RouterProvider, { router }, h(RouterLink, { to: "/about", replace: true }, "About")),
@@ -3292,3 +3296,626 @@ describe("loader rejection with aborted signal", () => {
     expect(router.currentRoute().path).toBe("/other")
   })
 })
+
+// ─── Feature 1: Base path support ─────────────────────────────────────────────
+
+describe("base path", () => {
+  const baseRoutes: RouteRecord[] = [
+    { path: "/", component: Home },
+    { path: "/about", component: About },
+    { path: "/user/:id", component: User },
+  ]
+
+  it("strips base from SSR url", () => {
+    const router = createRouter({
+      routes: baseRoutes,
+      mode: "history",
+      base: "/app",
+      url: "/app/about",
+    })
+    expect(router.currentRoute().path).toBe("/about")
+  })
+
+  it("resolves root when SSR url equals the base", () => {
+    const router = createRouter({ routes: baseRoutes, mode: "history", base: "/app", url: "/app" })
+    expect(router.currentRoute().path).toBe("/")
+  })
+
+  it("resolves root when SSR url is base with trailing slash", () => {
+    const router = createRouter({ routes: baseRoutes, mode: "history", base: "/app", url: "/app/" })
+    expect(router.currentRoute().path).toBe("/")
+  })
+
+  it("normalizes base without leading slash", () => {
+    const router = createRouter({
+      routes: baseRoutes,
+      mode: "history",
+      base: "app",
+      url: "/app/about",
+    })
+    expect(router.currentRoute().path).toBe("/about")
+  })
+
+  it("strips trailing slash from base", () => {
+    const router = createRouter({
+      routes: baseRoutes,
+      mode: "history",
+      base: "/app/",
+      url: "/app/about",
+    })
+    expect(router.currentRoute().path).toBe("/about")
+  })
+
+  it("ignores base in hash mode", () => {
+    const router = createRouter({ routes: baseRoutes, mode: "hash", base: "/app", url: "/about" })
+    expect(router.currentRoute().path).toBe("/about")
+  })
+
+  it("stores normalized base on RouterInstance", () => {
+    const router = createRouter({
+      routes: baseRoutes,
+      mode: "history",
+      base: "/app/",
+    }) as unknown as RouterInstance
+    expect(router._base).toBe("/app")
+  })
+
+  it("prepends base to browser URL in syncBrowserUrl via push", async () => {
+    const router = createRouter({
+      routes: baseRoutes,
+      mode: "history",
+      base: "/app",
+      url: "/app/",
+    })
+    await router.push("/about")
+    expect(router.currentRoute().path).toBe("/about")
+    expect(router.currentRoute().matched.length).toBeGreaterThan(0)
+    router.destroy()
+  })
+})
+
+// ─── Feature 2: Navigation blockers ──────────────────────────────────────────
+
+describe("navigation blockers (useBlocker)", () => {
+  const blockerRoutes: RouteRecord[] = [
+    { path: "/", component: Home },
+    { path: "/about", component: About },
+    { path: "/user/:id", component: User },
+  ]
+
+  beforeEach(() => {
+    // Reset browser state so stale hash values from prior tests don't trigger hashchange
+    window.location.hash = ""
+  })
+
+  afterEach(() => {
+    setActiveRouter(null)
+  })
+
+  it("blocks navigation when blocker returns true", async () => {
+    const router = createRouter({ routes: blockerRoutes, url: "/" }) as unknown as RouterInstance
+    router._blockers.add(() => true)
+    await router.push("/about")
+    expect(router.currentRoute().path).toBe("/")
+    router.destroy()
+  })
+
+  it("allows navigation when blocker returns false", async () => {
+    const router = createRouter({ routes: blockerRoutes, url: "/" }) as unknown as RouterInstance
+    router._blockers.add(() => false)
+    await router.push("/about")
+    expect(router.currentRoute().path).toBe("/about")
+    router.destroy()
+  })
+
+  it("supports async blockers", async () => {
+    const router = createRouter({ routes: blockerRoutes, url: "/" }) as unknown as RouterInstance
+    router._blockers.add(async () => {
+      await new Promise<void>((r) => setTimeout(r, 5))
+      return true
+    })
+    await router.push("/about")
+    expect(router.currentRoute().path).toBe("/")
+    router.destroy()
+  })
+
+  it("removing blocker allows navigation", async () => {
+    const router = createRouter({ routes: blockerRoutes, url: "/" }) as unknown as RouterInstance
+    const fn = () => true
+    router._blockers.add(fn)
+    router._blockers.delete(fn)
+    await router.push("/about")
+    expect(router.currentRoute().path).toBe("/about")
+    router.destroy()
+  })
+
+  it("blocker receives to and from routes", async () => {
+    const router = createRouter({ routes: blockerRoutes, url: "/" }) as unknown as RouterInstance
+    let receivedTo: ResolvedRoute | undefined
+    let receivedFrom: ResolvedRoute | undefined
+    router._blockers.add((to, from) => {
+      receivedTo = to
+      receivedFrom = from
+      return false
+    })
+    await router.push("/about")
+    expect(receivedTo!.path).toBe("/about")
+    expect(receivedFrom!.path).toBe("/")
+    router.destroy()
+  })
+
+  it("destroy() clears blockers", () => {
+    const router = createRouter({ routes: blockerRoutes, url: "/" }) as unknown as RouterInstance
+    router._blockers.add(() => true)
+    router.destroy()
+    expect(router._blockers.size).toBe(0)
+  })
+
+  it("useBlocker hook works via RouterProvider", () => {
+    const router = createRouter({ routes: blockerRoutes, url: "/" }) as unknown as RouterInstance
+    let blockerRef: { remove(): void } | undefined
+    const container = document.createElement("div")
+    const TestComp = () => {
+      blockerRef = useBlocker(() => true)
+      return null
+    }
+    mount(h(RouterProvider, { router }, h(TestComp, {})), container)
+    expect(router._blockers.size).toBe(1)
+    blockerRef!.remove()
+    expect(router._blockers.size).toBe(0)
+    router.destroy()
+  })
+
+  it("auto-removes blocker on component unmount via destroy()", () => {
+    const router = createRouter({ routes: blockerRoutes, url: "/" }) as unknown as RouterInstance
+    const container = document.createElement("div")
+    const TestComp = () => {
+      useBlocker(() => true)
+      return null
+    }
+    mount(h(RouterProvider, { router }, h(TestComp, {})), container)
+    expect(router._blockers.size).toBe(1)
+    // destroy() triggers onUnmount callbacks which should auto-remove the blocker
+    router.destroy()
+    expect(router._blockers.size).toBe(0)
+  })
+})
+
+// ─── Feature 3: Relative navigation ──────────────────────────────────────────
+
+describe("relative navigation", () => {
+  const relRoutes: RouteRecord[] = [
+    { path: "/", component: Home },
+    { path: "/admin/users", component: AdminUsers },
+    { path: "/admin/settings", component: AdminSettings },
+    { path: "/about", component: About },
+  ]
+
+  it("resolves ./sibling from a nested path", async () => {
+    const router = createRouter({ routes: relRoutes, url: "/admin/users" })
+    await router.push("./settings")
+    expect(router.currentRoute().path).toBe("/admin/settings")
+  })
+
+  it("resolves ../up from a nested path", async () => {
+    const router = createRouter({ routes: relRoutes, url: "/admin/users" })
+    await router.push("../about")
+    expect(router.currentRoute().path).toBe("/about")
+  })
+
+  it("resolves . to the parent directory", async () => {
+    const router = createRouter({ routes: relRoutes, url: "/admin/users" })
+    await router.push(".")
+    expect(router.currentRoute().path).toBe("/admin")
+  })
+
+  it("resolves .. to the grandparent directory", async () => {
+    const router = createRouter({ routes: relRoutes, url: "/admin/users" })
+    await router.push("..")
+    expect(router.currentRoute().path).toBe("/")
+  })
+
+  it("does not modify absolute paths", async () => {
+    const router = createRouter({ routes: relRoutes, url: "/admin/users" })
+    await router.push("/about")
+    expect(router.currentRoute().path).toBe("/about")
+  })
+
+  it("works with replace()", async () => {
+    const router = createRouter({ routes: relRoutes, url: "/admin/users" })
+    await router.replace("./settings")
+    expect(router.currentRoute().path).toBe("/admin/settings")
+  })
+})
+
+// ─── Feature 4: Trailing slash normalization ──────────────────────────────────
+
+describe("trailing slash normalization", () => {
+  const tsRoutes: RouteRecord[] = [
+    { path: "/", component: Home },
+    { path: "/about", component: About },
+    { path: "/user/:id", component: User },
+  ]
+
+  it("strips trailing slash by default", () => {
+    const router = createRouter({ routes: tsRoutes, url: "/about/" })
+    expect(router.currentRoute().path).toBe("/about")
+  })
+
+  it("strips trailing slash on navigation", async () => {
+    const router = createRouter({ routes: tsRoutes, url: "/" })
+    await router.push("/about/")
+    expect(router.currentRoute().path).toBe("/about")
+  })
+
+  it("adds trailing slash when trailingSlash=add", () => {
+    const router = createRouter({ routes: tsRoutes, url: "/about", trailingSlash: "add" })
+    expect(router.currentRoute().path).toBe("/about/")
+  })
+
+  it("does not modify when trailingSlash=ignore", () => {
+    const router = createRouter({ routes: tsRoutes, url: "/about/", trailingSlash: "ignore" })
+    expect(router.currentRoute().path).toBe("/about/")
+  })
+
+  it("does not strip slash from root path", () => {
+    const router = createRouter({ routes: tsRoutes, url: "/" })
+    expect(router.currentRoute().path).toBe("/")
+  })
+
+  it("preserves query string when stripping slash", async () => {
+    const router = createRouter({ routes: tsRoutes, url: "/" })
+    await router.push("/about/?foo=bar")
+    const route = router.currentRoute()
+    expect(route.path).toBe("/about")
+    expect(route.query.foo).toBe("bar")
+  })
+})
+
+// ─── Feature 5: Typed search params ──────────────────────────────────────────
+
+describe("useSearchParams", () => {
+  const spRoutes: RouteRecord[] = [
+    { path: "/", component: Home },
+    { path: "/search", component: About },
+  ]
+
+  it("returns current query params via RouterProvider", () => {
+    const router = createRouter({ routes: spRoutes, url: "/search?q=hello&page=2" })
+    const container = document.createElement("div")
+    let result: Record<string, string> | undefined
+    const TestComp = () => {
+      const [params] = useSearchParams()
+      result = params()
+      return null
+    }
+    mount(h(RouterProvider, { router }, h(TestComp, {})), container)
+    expect(result!.q).toBe("hello")
+    expect(result!.page).toBe("2")
+    router.destroy()
+  })
+
+  it("merges URL params over defaults for missing keys", () => {
+    const router = createRouter({ routes: spRoutes, url: "/search?q=hello" })
+    const container = document.createElement("div")
+    let result: Record<string, string> | undefined
+    const TestComp = () => {
+      const [params] = useSearchParams({ q: "", page: "1", sort: "name" })
+      result = params()
+      return null
+    }
+    mount(h(RouterProvider, { router }, h(TestComp, {})), container)
+    expect(result!.q).toBe("hello")
+    expect(result!.page).toBe("1")
+    expect(result!.sort).toBe("name")
+    router.destroy()
+  })
+
+  it("URL params take precedence over defaults", () => {
+    const router = createRouter({ routes: spRoutes, url: "/search?page=5" })
+    const container = document.createElement("div")
+    let result: Record<string, string> | undefined
+    const TestComp = () => {
+      const [params] = useSearchParams({ page: "1" })
+      result = params()
+      return null
+    }
+    mount(h(RouterProvider, { router }, h(TestComp, {})), container)
+    expect(result!.page).toBe("5")
+    router.destroy()
+  })
+
+  it("setSearchParams updates query and navigates", async () => {
+    const router = createRouter({ routes: spRoutes, url: "/search?page=1" })
+    const container = document.createElement("div")
+    let setter: ((updates: Partial<Record<string, string>>) => Promise<void>) | undefined
+    const TestComp = () => {
+      const [, setParams] = useSearchParams({ page: "1", sort: "name" })
+      setter = setParams
+      return null
+    }
+    mount(h(RouterProvider, { router }, h(TestComp, {})), container)
+    await setter!({ page: "3" })
+    expect(router.currentRoute().query.page).toBe("3")
+    expect(router.currentRoute().query.sort).toBe("name")
+    router.destroy()
+  })
+})
+
+// ─── Feature 6: Stale-while-revalidate loaders ───────────────────────────────
+
+describe("stale-while-revalidate loaders", () => {
+  const Comp = () => null
+
+  it("uses cached data and revalidates in background", async () => {
+    let callCount = 0
+    const swrRoutes: RouteRecord[] = [
+      { path: "/", component: Comp },
+      {
+        path: "/data",
+        component: Comp,
+        staleWhileRevalidate: true,
+        loader: async () => {
+          callCount++
+          return `result-${callCount}`
+        },
+      },
+    ]
+
+    const router = createRouter({ routes: swrRoutes, url: "/" })
+
+    // First navigation: no cached data, loader runs blocking
+    await router.push("/data")
+    expect(callCount).toBe(1)
+    const inst = router as unknown as RouterInstance
+    const record = swrRoutes[1] as RouteRecord
+    expect(inst._loaderData.get(record)).toBe("result-1")
+
+    // Navigate away then back — SWR should use cached data
+    await router.push("/")
+    await router.push("/data")
+    // callCount is now 2 because loader was called again (SWR revalidation)
+    // But navigation committed immediately with stale data
+    await new Promise<void>((r) => setTimeout(r, 50))
+    expect(callCount).toBe(2)
+    expect(inst._loaderData.get(record)).toBe("result-2")
+  })
+
+  it("non-SWR routes still block", async () => {
+    let loaded = false
+    const mixedRoutes: RouteRecord[] = [
+      { path: "/", component: Comp },
+      {
+        path: "/blocking",
+        component: Comp,
+        loader: async () => {
+          await new Promise<void>((r) => setTimeout(r, 10))
+          loaded = true
+          return "data"
+        },
+      },
+    ]
+
+    const router = createRouter({ routes: mixedRoutes, url: "/" })
+    await router.push("/blocking")
+    expect(loaded).toBe(true)
+  })
+})
+
+// ─── go(n), forward() ────────────────────────────────────────────────────────
+
+describe("go() and forward()", () => {
+  test("go() calls window.history.go", () => {
+    const spy = vi.spyOn(window.history, "go").mockImplementation(() => {})
+    const router = createRouter({ routes, url: "/" })
+    router.go(-2)
+    expect(spy).toHaveBeenCalledWith(-2)
+    router.go(3)
+    expect(spy).toHaveBeenCalledWith(3)
+    spy.mockRestore()
+    router.destroy()
+  })
+
+  test("forward() calls window.history.forward", () => {
+    const spy = vi.spyOn(window.history, "forward").mockImplementation(() => {})
+    const router = createRouter({ routes, url: "/" })
+    router.forward()
+    expect(spy).toHaveBeenCalled()
+    spy.mockRestore()
+    router.destroy()
+  })
+})
+
+// ─── Named replace() ──────────────────────────────────────────────────────────
+
+describe("named replace()", () => {
+  const namedRoutes: RouteRecord[] = [
+    { path: "/", component: Home },
+    { path: "/user/:id", component: User, name: "user" },
+    { path: "/about", component: About, name: "about" },
+  ]
+
+  test("replace with named route navigates correctly", async () => {
+    const router = createRouter({ routes: namedRoutes, url: "/" })
+    await router.replace({ name: "user", params: { id: "42" } })
+    expect(router.currentRoute().path).toBe("/user/42")
+    router.destroy()
+  })
+
+  test("replace with named route and query", async () => {
+    const router = createRouter({ routes: namedRoutes, url: "/" })
+    await router.replace({ name: "about", query: { ref: "home" } })
+    expect(router.currentRoute().path).toBe("/about")
+    expect(router.currentRoute().query.ref).toBe("home")
+    router.destroy()
+  })
+})
+
+// ─── Optional params ──────────────────────────────────────────────────────────
+
+describe("optional params", () => {
+  const optRoutes: RouteRecord[] = [
+    { path: "/", component: Home },
+    { path: "/lang/:locale?/about", component: About },
+    { path: "/user/:id/:tab?", component: User },
+  ]
+
+  test("matches with optional param present", () => {
+    const r = resolveOn(optRoutes, "/user/42/settings") as {
+      params: Record<string, string>
+    }
+    expect(r.params.id).toBe("42")
+    expect(r.params.tab).toBe("settings")
+  })
+
+  test("matches with optional param absent", () => {
+    const r = resolveOn(optRoutes, "/user/42") as {
+      params: Record<string, string>
+      matched: unknown[]
+    }
+    expect(r.params.id).toBe("42")
+    expect(r.params.tab).toBeUndefined()
+    expect(r.matched.length).toBeGreaterThan(0)
+  })
+
+  test("matches mid-path optional param present", () => {
+    const r = resolveOn(optRoutes, "/lang/en/about") as {
+      params: Record<string, string>
+    }
+    expect(r.params.locale).toBe("en")
+  })
+
+  test("matchPath supports optional params", () => {
+    expect(matchPath("/user/:id/:tab?", "/user/42")).toEqual({ id: "42" })
+    expect(matchPath("/user/:id/:tab?", "/user/42/settings")).toEqual({
+      id: "42",
+      tab: "settings",
+    })
+  })
+
+  test("buildPath omits optional segment when param is missing", () => {
+    expect(buildPath("/user/:id/:tab?", { id: "42" })).toBe("/user/42")
+    expect(buildPath("/user/:id/:tab?", { id: "42", tab: "settings" })).toBe("/user/42/settings")
+  })
+})
+
+// ─── isReady() ───────────────────────────────────────────────────────────────
+
+describe("isReady()", () => {
+  test("resolves after router is created", async () => {
+    const router = createRouter({ routes, url: "/" })
+    await router.isReady()
+    expect(router.currentRoute().path).toBe("/")
+    router.destroy()
+  })
+
+  test("calling isReady() multiple times returns the same promise", () => {
+    const router = createRouter({ routes, url: "/" })
+    const p1 = router.isReady()
+    const p2 = router.isReady()
+    expect(p1).toBe(p2)
+    router.destroy()
+  })
+})
+
+// ─── Route aliases ───────────────────────────────────────────────────────────
+
+describe("route aliases", () => {
+  const aliasRoutes: RouteRecord[] = [
+    { path: "/", component: Home },
+    { path: "/user/:id", alias: "/profile/:id", component: User, name: "user" },
+    {
+      path: "/about",
+      alias: ["/about-us", "/info"],
+      component: About,
+      meta: { title: "About" },
+    },
+  ]
+
+  test("alias path matches same component as primary", () => {
+    const r1 = resolveOn(aliasRoutes, "/user/42") as {
+      params: Record<string, string>
+      matched: { component: unknown }[]
+    }
+    const r2 = resolveOn(aliasRoutes, "/profile/42") as {
+      params: Record<string, string>
+      matched: { component: unknown }[]
+    }
+    expect(r1.matched[0]?.component).toBe(User)
+    expect(r2.matched[0]?.component).toBe(User)
+    expect(r2.params.id).toBe("42")
+  })
+
+  test("multiple aliases all match", () => {
+    const r1 = resolveOn(aliasRoutes, "/about") as { matched: { component: unknown }[] }
+    const r2 = resolveOn(aliasRoutes, "/about-us") as { matched: { component: unknown }[] }
+    const r3 = resolveOn(aliasRoutes, "/info") as { matched: { component: unknown }[] }
+    expect(r1.matched[0]?.component).toBe(About)
+    expect(r2.matched[0]?.component).toBe(About)
+    expect(r3.matched[0]?.component).toBe(About)
+  })
+
+  test("alias shares meta with primary route", () => {
+    const r = resolveOn(aliasRoutes, "/about-us") as { meta: { title?: string } }
+    expect(r.meta.title).toBe("About")
+  })
+})
+
+// ─── In-component guards ─────────────────────────────────────────────────────
+
+describe("onBeforeRouteLeave", () => {
+  test("blocks navigation when returning false", async () => {
+    const guardRoutes: RouteRecord[] = [
+      { path: "/", component: Home },
+      { path: "/about", component: About },
+    ]
+    const router = createRouter({ routes: guardRoutes, url: "/" })
+    const el = container()
+    let leaveCalled = false
+
+    const App = () => {
+      onBeforeRouteLeave(() => {
+        leaveCalled = true
+        return false
+      })
+      return h(RouterView, { router })
+    }
+
+    mount(h(RouterProvider, { router }, h(App, {})), el)
+    await router.push("/about")
+    expect(leaveCalled).toBe(true)
+    expect(router.currentRoute().path).toBe("/")
+    router.destroy()
+  })
+})
+
+describe("onBeforeRouteUpdate", () => {
+  test("fires when params change on the same route", async () => {
+    const guardRoutes: RouteRecord[] = [
+      { path: "/", component: Home },
+      { path: "/user/:id", component: User },
+    ]
+    const router = createRouter({ routes: guardRoutes, url: "/user/1" })
+    const el = container()
+    let updateCalled = false
+
+    const App = () => {
+      onBeforeRouteUpdate((to) => {
+        updateCalled = true
+        if (to.params.id === "blocked") return false
+        return undefined
+      })
+      return h(RouterView, { router })
+    }
+
+    mount(h(RouterProvider, { router }, h(App, {})), el)
+    await router.push("/user/2")
+    expect(updateCalled).toBe(true)
+    expect(router.currentRoute().path).toBe("/user/2")
+
+    // Should block navigation to /user/blocked
+    await router.push("/user/blocked")
+    expect(router.currentRoute().path).toBe("/user/2")
+    router.destroy()
+  })
+})