@toapi/router 0.6.2

package/README.md

@@ -0,0 +1,236 @@
+# @toapi/router Documentation
+
+A lightweight, React-based client-side router with support for nested routes, path parameters, and immutable search parameter handling.
+
+## Overview
+
+The `@toapi/router` package provides a very lightweight routing solution for React applications with the following key features:
+
+- **Declarative routing** with React components
+- **Nested routes** with parameter inheritance
+- **Path parameters** with colon syntax (`:id`)
+- **Wildcard routes** for catch-all paths (`*` and `*name`)
+- **Immutable search parameters** for predictable state management
+- **Client-side navigation** with history management
+- **TypeScript support** for better development experience
+- **Testing-friendly** with customizable location and history
+
+## Quick Start
+
+```tsx
+import { Router, Route, Link } from "@toapi/router";
+
+function App() {
+  return (
+    <Router>
+      <nav>
+        <Link href="/">Home</Link>
+        <Link href="/users">Users</Link>
+        <Link href="/about">About</Link>
+      </nav>
+
+      <main>
+        <Route path="/">
+          <HomePage />
+        </Route>
+
+        <Route path="/users">
+          <UsersLayout />
+          <Route exact>
+            <UsersList />
+          </Route>
+          <Route path=":id">
+            <UserProfile />
+          </Route>
+        </Route>
+
+        <Route path="/about">
+          <AboutPage />
+        </Route>
+      </main>
+    </Router>
+  );
+}
+```
+
+## Components
+
+### [Router](./docs/Router.md)
+The root component that provides routing context to your application.
+
+- Manages current location state
+- Provides navigation methods
+- Supports custom location and history for testing
+- Normalizes pathnames (removes trailing slashes)
+
+### [Route](./docs/Route.md)
+Conditionally renders content based on the current pathname.
+
+- Path matching with parameters (`/users/:id`)
+- Wildcard matching (`/files/*` or `/files/*path`)
+- Exact matching option
+- Nested route support
+- Parameter inheritance from parent routes
+
+### [Link](./docs/Link.md)
+Declarative navigation component that renders as an anchor element.
+
+- Client-side navigation with history management
+- Supports absolute and relative paths
+- Query parameter handling
+
+## Hooks
+
+### [useRouter](./docs/useRouter.md)
+Provides programmatic navigation methods.
+
+```tsx
+const router = useRouter();
+router.push("/users/123");     // Navigate with history
+router.replace("/login");      // Replace current entry
+```
+
+### [usePathname](./docs/usePathname.md)
+Access the current pathname for conditional rendering and active states.
+
+```tsx
+const pathname = usePathname();
+const isActive = pathname === "/users";
+```
+
+### [useSearchParams](./docs/useSearchParams.md)
+Access and manipulate URL search parameters with immutable methods.
+
+```tsx
+const searchParams = useSearchParams();
+const query = searchParams.get("q");
+const newParams = searchParams.set("filter", "active");
+```
+
+### [useParams](./docs/useParams.md)
+Extract parameters from dynamic route segments.
+
+```tsx
+// Route: /users/:id/posts/:postId
+const params = useParams(); // { id: "123", postId: "456" }
+```
+
+### [useHash](./docs/useHash.md)
+Access the current URL hash fragment for tab navigation and anchor linking.
+
+```tsx
+const hash = useHash();
+const activeTab = hash.slice(1) || "overview";
+```
+
+## Key Features
+
+### Nested Routing
+
+Create hierarchical route structures with parameter inheritance:
+
+```tsx
+<Route path="/organizations/:orgId">
+  <OrganizationLayout />
+
+  <Route path="teams/:teamId">
+    <TeamLayout />
+
+    <Route path="members/:memberId">
+      <MemberProfile />
+    </Route>
+  </Route>
+</Route>
+```
+
+### Path Parameters
+
+Define dynamic segments with colon syntax:
+
+```tsx
+<Route path="/users/:id">          {/* /users/123 */}
+<Route path="/posts/:slug">        {/* /posts/hello-world */}
+<Route path="/api/:version">       {/* /api/v1 */}
+```
+
+### Wildcard Routes
+
+Match arbitrary paths with wildcards:
+
+```tsx
+<Route path="/files/*">            {/* Matches /files/a, /files/a/b/c, etc. */}
+<Route path="/docs/*path">         {/* Matches and captures as params.path */}
+<Route path="/api/:version/*rest"> {/* Combines params with wildcards */}
+```
+
+The `*` wildcard matches everything including slashes, making it perfect for catch-all routes. Use `*name` to capture the matched path as a parameter accessible via `useParams()`.
+
+### Immutable Search Parameters
+
+Safely update URL search parameters without mutations:
+
+```tsx
+const searchParams = useSearchParams();
+const withFilter = searchParams.set("category", "electronics");
+const withSort = withFilter.set("sort", "price");
+```
+
+### Testing Support
+
+Provide custom location and history for predictable tests:
+
+```tsx
+<Router
+  location={{ pathname: "/users/123", search: "?tab=profile", hash: "#bio" }}
+  history={mockHistory}
+>
+  <App />
+</Router>
+```
+
+## Common Patterns
+
+### Active Navigation Links
+
+```tsx
+function NavLink({ href, children }) {
+  const pathname = usePathname();
+  const isActive = pathname === href;
+
+  return (
+    <Link
+      href={href}
+      className={isActive ? 'nav-link active' : 'nav-link'}
+    >
+      {children}
+    </Link>
+  );
+}
+```
+
+### Search and Filtering
+
+```tsx
+function ProductSearch() {
+  const router = useRouter();
+  const pathname = usePathname();
+  const searchParams = useSearchParams();
+
+  const updateFilter = (key: string, value: string) => {
+    const newParams = searchParams.set(key, value);
+    router.push(`${pathname}?${newParams.toString()}`);
+  };
+
+  return (
+    <select onChange={(e) => updateFilter("category", e.target.value)}>
+      <option value="">All Categories</option>
+      <option value="electronics">Electronics</option>
+    </select>
+  );
+}
+```
+
+
+## API Reference
+
+For detailed API documentation, see the individual component and hook documentation files linked above.

package/dist/context.d.ts

@@ -0,0 +1,15 @@
+import { ImmutableSearchParams } from "./immutable-search-params";
+export declare const PathnameContext: import("react").Context<string>;
+export declare const SearchParamsContext: import("react").Context<ImmutableSearchParams>;
+export declare const HashContext: import("react").Context<string>;
+export declare const RouterContext: import("react").Context<{
+    push: (href: string) => void;
+    replace: (href: string) => void;
+}>;
+export interface RouteContextValue {
+    path: string;
+    params: Record<string, string | string[]>;
+    matchedPathname: string;
+}
+export declare const RouteContext: import("react").Context<RouteContextValue>;
+//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAElE,eAAO,MAAM,eAAe,iCAA6B,CAAC;AAE1D,eAAO,MAAM,mBAAmB,gDAE/B,CAAC;AAEF,eAAO,MAAM,WAAW,iCAA4B,CAAC;AAErD,eAAO,MAAM,aAAa;UAClB,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI;aACnB,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI;EAI/B,CAAC;AAEH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;IAC1C,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,eAAO,MAAM,YAAY,4CAIvB,CAAC"}

package/dist/context.js

@@ -0,0 +1,14 @@
+import { createContext } from "react";
+import { ImmutableSearchParams } from "./immutable-search-params";
+export const PathnameContext = createContext("/");
+export const SearchParamsContext = createContext(new ImmutableSearchParams());
+export const HashContext = createContext("");
+export const RouterContext = createContext({
+    push: () => { },
+    replace: () => { },
+});
+export const RouteContext = createContext({
+    path: "/",
+    params: {},
+    matchedPathname: "/",
+});

package/dist/immutable-search-params.d.ts

@@ -0,0 +1,7 @@
+export declare class ImmutableSearchParams extends URLSearchParams {
+    set(key: string, value: string): ImmutableSearchParams;
+    append(name: string, value: string): ImmutableSearchParams;
+    delete(key: string): ImmutableSearchParams;
+    get search(): string;
+}
+//# sourceMappingURL=immutable-search-params.d.ts.map

package/dist/immutable-search-params.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"immutable-search-params.d.ts","sourceRoot":"","sources":["../src/immutable-search-params.ts"],"names":[],"mappings":"AAAA,qBAAa,qBAAsB,SAAQ,eAAe;IAC/C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;IAM9B,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;IAMlC,MAAM,CAAC,GAAG,EAAE,MAAM;IAM3B,IAAI,MAAM,IAAI,MAAM,CAEnB;CACF"}

package/dist/immutable-search-params.js

@@ -0,0 +1,20 @@
+export class ImmutableSearchParams extends URLSearchParams {
+    set(key, value) {
+        const newSearchParams = new URLSearchParams(this);
+        newSearchParams.set(key, value);
+        return new ImmutableSearchParams(newSearchParams);
+    }
+    append(name, value) {
+        const newSearchParams = new URLSearchParams(this);
+        newSearchParams.append(name, value);
+        return new ImmutableSearchParams(newSearchParams);
+    }
+    delete(key) {
+        const newSearchParams = new URLSearchParams(this);
+        newSearchParams.delete(key);
+        return new ImmutableSearchParams(newSearchParams);
+    }
+    get search() {
+        return this.size === 0 ? "" : "?" + this.toString();
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export { Router } from "./router";
+export { Route } from "./route";
+export { Link } from "./link";
+export { useRouter } from "./use-router";
+export { usePathname } from "./use-pathname";
+export { useSearchParams } from "./use-search-params";
+export { useHash } from "./use-hash";
+export { useParams } from "./use-params";
+export { Switch } from "./switch";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAClC,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAC9B,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AACrC,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC"}

package/dist/index.js

@@ -0,0 +1,9 @@
+export { Router } from "./router";
+export { Route } from "./route";
+export { Link } from "./link";
+export { useRouter } from "./use-router";
+export { usePathname } from "./use-pathname";
+export { useSearchParams } from "./use-search-params";
+export { useHash } from "./use-hash";
+export { useParams } from "./use-params";
+export { Switch } from "./switch";

package/dist/link.d.ts

@@ -0,0 +1,8 @@
+import { type HTMLProps } from "react";
+interface Props extends HTMLProps<HTMLAnchorElement> {
+    href: string;
+    replace?: boolean;
+}
+export declare function Link({ href, replace, children, onClick, ...rawProps }: Props): import("react").JSX.Element;
+export {};
+//# sourceMappingURL=link.d.ts.map

package/dist/link.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"link.d.ts","sourceRoot":"","sources":["../src/link.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,SAAS,EAAkB,MAAM,OAAO,CAAC;AASrE,UAAU,KAAM,SAAQ,SAAS,CAAC,iBAAiB,CAAC;IAClD,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,wBAAgB,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,QAAQ,EAAE,EAAE,KAAK,+BA6B5E"}

package/dist/link.js

@@ -0,0 +1,23 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { use, useMemo } from "react";
+import { PathnameContext, RouteContext, RouterContext, SearchParamsContext, } from "./context";
+import { resolve } from "./path";
+export function Link({ href, replace, children, onClick, ...rawProps }) {
+    const { matchedPathname: parentPathname } = use(RouteContext);
+    const router = use(RouterContext);
+    const pathname = use(PathnameContext);
+    const searchParams = use(SearchParamsContext);
+    const target = useMemo(() => resolve(href, { pathname, parentPathname, searchParams }), [href, parentPathname, pathname]);
+    return (_jsx("a", { href: target, onClick: (event) => {
+            onClick?.(event);
+            if (event.defaultPrevented)
+                return;
+            event.preventDefault();
+            if (replace) {
+                router.replace(target);
+            }
+            else {
+                router.push(target);
+            }
+        }, ...rawProps, children: children }));
+}

package/dist/mock-history.d.ts

@@ -0,0 +1,9 @@
+export declare function mockHistory(pathname?: string): {
+    location: URL;
+    history: {
+        pushState: import("vitest").Mock<(_state: any, _unused: string, url: string) => void>;
+        replaceState: import("vitest").Mock<(_state: any, _unused: string, url: string) => void>;
+    };
+    back(): void;
+};
+//# sourceMappingURL=mock-history.d.ts.map

package/dist/mock-history.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock-history.d.ts","sourceRoot":"","sources":["../src/mock-history.ts"],"names":[],"mappings":"AAEA,wBAAgB,WAAW,CAAC,QAAQ,SAAM;;;kDAOV,GAAG,WAAW,MAAM,OAAO,MAAM;qDAI9B,GAAG,WAAW,MAAM,OAAO,MAAM;;;EAanE"}

package/dist/mock-history.js

@@ -0,0 +1,25 @@
+import { vi } from "vitest";
+export function mockHistory(pathname = "/") {
+    const location = new URL(pathname, "http://localhost:3000");
+    const stack = [location.href];
+    return {
+        location,
+        history: {
+            pushState: vi.fn((_state, _unused, url) => {
+                location.href = new URL(url, location.href).href;
+                stack.push(location.href);
+            }),
+            replaceState: vi.fn((_state, _unused, url) => {
+                location.href = new URL(url, location.href).href;
+                stack[stack.length - 1] = location.href;
+            }),
+        },
+        back() {
+            if (stack.length > 1) {
+                stack.pop();
+                location.href = stack[stack.length - 1];
+                window.dispatchEvent(new PopStateEvent("popstate"));
+            }
+        },
+    };
+}

package/dist/path.d.ts

@@ -0,0 +1,13 @@
+import { ImmutableSearchParams } from "./immutable-search-params";
+interface Options {
+    pathname: string;
+    parentPathname: string;
+    searchParams: ImmutableSearchParams;
+}
+export declare function resolve(path: string, { pathname, parentPathname, searchParams }: Options): string;
+export declare function removeTrailingSlash(path: string): string;
+export declare function compilePathRegex(path: string): RegExp;
+export declare function compileExactPathRegex(path: string): RegExp;
+export declare function buildFullPath(parentPath: string, path?: string): string;
+export {};
+//# sourceMappingURL=path.d.ts.map

package/dist/path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path.d.ts","sourceRoot":"","sources":["../src/path.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAElE,UAAU,OAAO;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,qBAAqB,CAAC;CACrC;AAED,wBAAgB,OAAO,CACrB,IAAI,EAAE,MAAM,EACZ,EAAE,QAAQ,EAAE,cAAc,EAAE,YAAY,EAAE,EAAE,OAAO,UAepD;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAGxD;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAiBrD;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAU1D;AAED,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,UAa9D"}

package/dist/path.js

@@ -0,0 +1,60 @@
+import { ImmutableSearchParams } from "./immutable-search-params";
+export function resolve(path, { pathname, parentPathname, searchParams }) {
+    if (path.startsWith("/")) {
+        return path;
+    }
+    if (path.startsWith("?")) {
+        return pathname + path;
+    }
+    if (path.startsWith("#")) {
+        return pathname + searchParams.search + path;
+    }
+    if (!path) {
+        return parentPathname;
+    }
+    return parentPathname === "/" ? `/${path}` : `${parentPathname}/${path}`;
+}
+export function removeTrailingSlash(path) {
+    if (path === "/")
+        return path;
+    return path.endsWith("/") ? path.slice(0, -1) : path;
+}
+export function compilePathRegex(path) {
+    if (path === "/") {
+        return /^\//;
+    }
+    // Handle wildcards: *name captures as named group, * catches all without capturing
+    const pattern = path
+        .replaceAll(/\*(\w+)/g, "(?<$1>.+)") // *name -> named capture group
+        .replaceAll(/\*/g, ".+") // * -> match everything including /
+        .replaceAll(/:(\w+)/g, "(?<$1>[^\\/]+)"); // :param -> named capture group
+    // If pattern contains a wildcard, it already matches everything - use exact match
+    if (path.includes("*")) {
+        return new RegExp(`^(${pattern})$`);
+    }
+    // For non-wildcard paths, allow optional trailing paths
+    return new RegExp(`^(${pattern})(/.*)?$`);
+}
+export function compileExactPathRegex(path) {
+    if (path === "/") {
+        return /^\/$/;
+    }
+    // Handle wildcards: *name captures as named group, * catches all without capturing
+    const pattern = path
+        .replaceAll(/\*(\w+)/g, "(?<$1>.+)") // *name -> named capture group
+        .replaceAll(/\*/g, ".+") // * -> match everything including /
+        .replaceAll(/:(\w+)/g, "(?<$1>[^\\/]+)"); // :param -> named capture group
+    return new RegExp(`^(${pattern})$`);
+}
+export function buildFullPath(parentPath, path) {
+    if (path?.startsWith("/")) {
+        return path;
+    }
+    if (path) {
+        if (parentPath === "/") {
+            return "/" + path;
+        }
+        return parentPath + "/" + path;
+    }
+    return parentPath;
+}

package/dist/route.d.ts

@@ -0,0 +1,7 @@
+export interface RouteProps {
+    path?: string;
+    exact?: boolean;
+    children: React.ReactNode;
+}
+export declare function Route({ path, exact, children }: RouteProps): import("react").JSX.Element | null;
+//# sourceMappingURL=route.d.ts.map

package/dist/route.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route.d.ts","sourceRoot":"","sources":["../src/route.tsx"],"names":[],"mappings":"AAIA,MAAM,WAAW,UAAU;IACzB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC3B;AAED,wBAAgB,KAAK,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE,UAAU,sCA0B1D"}

package/dist/route.js

@@ -0,0 +1,19 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { use, useMemo } from "react";
+import { PathnameContext, RouteContext } from "./context";
+import { buildFullPath, compileExactPathRegex, compilePathRegex } from "./path";
+export function Route({ path, exact, children }) {
+    const parentRoute = use(RouteContext);
+    const pathname = use(PathnameContext);
+    const fullPath = useMemo(() => buildFullPath(parentRoute.path, path ?? ""), [parentRoute.path, path]);
+    const pathRegex = useMemo(() => exact ? compileExactPathRegex(fullPath) : compilePathRegex(fullPath), [fullPath, exact]);
+    const match = useMemo(() => pathname.match(pathRegex), [pathname, pathRegex]);
+    const routeContextValue = useMemo(() => ({
+        path: fullPath,
+        params: match?.groups ?? {},
+        matchedPathname: match?.[1] ?? "",
+    }), [fullPath, match]);
+    if (!match)
+        return null;
+    return _jsx(RouteContext, { value: routeContextValue, children: children });
+}

package/dist/router.d.ts

@@ -0,0 +1,16 @@
+import { type ReactNode } from "react";
+interface Props {
+    children: ReactNode;
+    location?: {
+        pathname: string;
+        search: string;
+        hash: string;
+    };
+    history?: {
+        pushState: (state: any, title: string, url: string) => void;
+        replaceState: (state: any, title: string, url: string) => void;
+    };
+}
+export declare function Router({ history, location, children, }: Props): import("react").JSX.Element;
+export {};
+//# sourceMappingURL=router.d.ts.map

package/dist/router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../src/router.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAiD,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAUtF,UAAU,KAAK;IACb,QAAQ,EAAE,SAAS,CAAC;IACpB,QAAQ,CAAC,EAAE;QACT,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,EAAE,MAAM,CAAC;KACd,CAAC;IACF,OAAO,CAAC,EAAE;QACR,SAAS,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;QAC5D,YAAY,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;KAChE,CAAC;CACH;AAED,wBAAgB,MAAM,CAAC,EACrB,OAAwB,EACxB,QAA0B,EAC1B,QAAQ,GACT,EAAE,KAAK,+BAoDP"}

package/dist/router.js

@@ -0,0 +1,40 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { startTransition, useEffect, useMemo, useState } from "react";
+import { HashContext, PathnameContext, RouterContext, SearchParamsContext, } from "./context";
+import { ImmutableSearchParams } from "./immutable-search-params";
+import { removeTrailingSlash } from "./path";
+export function Router({ history = window.history, location = window.location, children, }) {
+    const [pathname, setPathname] = useState(removeTrailingSlash(location.pathname));
+    const [searchParams, setSearchParams] = useState(new ImmutableSearchParams(location.search));
+    const [hash, setHash] = useState(location.hash);
+    useEffect(() => {
+        const handlePopstate = () => {
+            startTransition(() => {
+                setPathname(removeTrailingSlash(location.pathname));
+                setSearchParams(new ImmutableSearchParams(location.search));
+                setHash(location.hash);
+            });
+        };
+        window.addEventListener("popstate", handlePopstate);
+        return () => window.removeEventListener("popstate", handlePopstate);
+    }, [location]);
+    const routerContextValue = useMemo(() => ({
+        push: (url) => {
+            history.pushState(null, "", url);
+            startTransition(() => {
+                setPathname(removeTrailingSlash(location.pathname));
+                setSearchParams(new ImmutableSearchParams(location.search));
+                setHash(location.hash);
+            });
+        },
+        replace: (url) => {
+            history.replaceState(null, "", url);
+            startTransition(() => {
+                setPathname(removeTrailingSlash(location.pathname));
+                setSearchParams(new ImmutableSearchParams(location.search));
+                setHash(location.hash);
+            });
+        },
+    }), [location, history]);
+    return (_jsx(RouterContext, { value: routerContextValue, children: _jsx(PathnameContext, { value: pathname, children: _jsx(SearchParamsContext, { value: searchParams, children: _jsx(HashContext, { value: hash, children: children }) }) }) }));
+}

package/dist/switch.d.ts

@@ -0,0 +1,8 @@
+import { type ReactElement } from "react";
+import type { Route, RouteProps } from "./route";
+interface Props {
+    children: ReactElement<RouteProps, typeof Route> | ReactElement<RouteProps, typeof Route>[];
+}
+export declare function Switch({ children }: Props): import("react").JSX.Element | null;
+export {};
+//# sourceMappingURL=switch.d.ts.map

package/dist/switch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"switch.d.ts","sourceRoot":"","sources":["../src/switch.tsx"],"names":[],"mappings":"AAAA,OAAO,EAA0B,KAAK,YAAY,EAAE,MAAM,OAAO,CAAC;AAClE,OAAO,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAQjD,UAAU,KAAK;IACb,QAAQ,EACJ,YAAY,CAAC,UAAU,EAAE,OAAO,KAAK,CAAC,GACtC,YAAY,CAAC,UAAU,EAAE,OAAO,KAAK,CAAC,EAAE,CAAC;CAC9C;AAED,wBAAgB,MAAM,CAAC,EAAE,QAAQ,EAAE,EAAE,KAAK,sCAmDzC"}

package/dist/switch.js

@@ -0,0 +1,43 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Children, use, useMemo } from "react";
+import { PathnameContext, RouteContext, } from "./context";
+import { buildFullPath, compileExactPathRegex, compilePathRegex } from "./path";
+export function Switch({ children }) {
+    const parentRoute = use(RouteContext);
+    const pathname = use(PathnameContext);
+    const props = Children.map(children, (route) => route.props);
+    const routeMeta = useMemo(() => props.map((route) => {
+        const path = route.path ?? "";
+        const fullPath = buildFullPath(parentRoute.path, path);
+        return {
+            path,
+            fullPath,
+            pathRegex: route.exact
+                ? compileExactPathRegex(fullPath)
+                : compilePathRegex(fullPath),
+        };
+    }), [
+        parentRoute.path,
+        props.map((route) => (route.exact ? "e" : "l" + route.path)).join(" "),
+    ]);
+    const match = useMemo(() => {
+        for (const meta of routeMeta) {
+            const match = pathname.match(meta.pathRegex);
+            if (match)
+                return [
+                    meta.path,
+                    {
+                        path: meta.fullPath,
+                        params: match?.groups ?? {},
+                        matchedPathname: match?.[1] ?? "",
+                    },
+                ];
+        }
+        return null;
+    }, [routeMeta, pathname]);
+    if (!match) {
+        return null;
+    }
+    const [path, context] = match;
+    return (_jsx(RouteContext, { value: context, children: props.find((route) => route.path === path)?.children }));
+}

package/dist/use-hash.d.ts

@@ -0,0 +1,2 @@
+export declare function useHash(): string;
+//# sourceMappingURL=use-hash.d.ts.map

package/dist/use-hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-hash.d.ts","sourceRoot":"","sources":["../src/use-hash.ts"],"names":[],"mappings":"AAGA,wBAAgB,OAAO,WAEtB"}

package/dist/use-hash.js

@@ -0,0 +1,5 @@
+import { use } from "react";
+import { HashContext } from "./context";
+export function useHash() {
+    return use(HashContext);
+}

package/dist/use-params.d.ts

@@ -0,0 +1,2 @@
+export declare function useParams<T extends Record<string, string | string[]> = Record<string, string | string[]>>(): T;
+//# sourceMappingURL=use-params.d.ts.map

package/dist/use-params.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-params.d.ts","sourceRoot":"","sources":["../src/use-params.ts"],"names":[],"mappings":"AAGA,wBAAgB,SAAS,CACvB,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,GAAG,MAAM,CAClD,MAAM,EACN,MAAM,GAAG,MAAM,EAAE,CAClB,KAIgB,CAAC,CACnB"}

package/dist/use-params.js

@@ -0,0 +1,6 @@
+import { use } from "react";
+import { RouteContext } from "./context";
+export function useParams() {
+    const { params } = use(RouteContext);
+    return params;
+}

package/dist/use-pathname.d.ts

@@ -0,0 +1,2 @@
+export declare function usePathname(): string;
+//# sourceMappingURL=use-pathname.d.ts.map

package/dist/use-pathname.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-pathname.d.ts","sourceRoot":"","sources":["../src/use-pathname.ts"],"names":[],"mappings":"AAGA,wBAAgB,WAAW,WAE1B"}

package/dist/use-pathname.js

@@ -0,0 +1,5 @@
+import { use } from "react";
+import { PathnameContext } from "./context";
+export function usePathname() {
+    return use(PathnameContext);
+}

package/dist/use-router.d.ts

@@ -0,0 +1,4 @@
+import { type ContextType } from "react";
+import { RouterContext } from "./context";
+export declare function useRouter(): ContextType<typeof RouterContext>;
+//# sourceMappingURL=use-router.d.ts.map

package/dist/use-router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-router.d.ts","sourceRoot":"","sources":["../src/use-router.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,WAAW,EAAgB,MAAM,OAAO,CAAC;AACvD,OAAO,EAGL,aAAa,EAEd,MAAM,WAAW,CAAC;AAGnB,wBAAgB,SAAS,IAAI,WAAW,CAAC,OAAO,aAAa,CAAC,CA6B7D"}

package/dist/use-router.js

@@ -0,0 +1,25 @@
+import { use, useMemo } from "react";
+import { PathnameContext, RouteContext, RouterContext, SearchParamsContext, } from "./context";
+import { resolve } from "./path";
+export function useRouter() {
+    const { push, replace } = use(RouterContext);
+    const { matchedPathname: parentPathname } = use(RouteContext);
+    const pathname = use(PathnameContext);
+    const searchParams = use(SearchParamsContext);
+    return useMemo(() => ({
+        push(href) {
+            push(resolve(href, {
+                pathname,
+                searchParams,
+                parentPathname,
+            }));
+        },
+        replace(href) {
+            replace(resolve(href, {
+                pathname,
+                searchParams,
+                parentPathname,
+            }));
+        },
+    }), [pathname, searchParams, parentPathname]);
+}

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

@@ -0,0 +1,2 @@
+export declare function useSearchParams(): import("./immutable-search-params").ImmutableSearchParams;
+//# sourceMappingURL=use-search-params.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"use-search-params.d.ts","sourceRoot":"","sources":["../src/use-search-params.ts"],"names":[],"mappings":"AAGA,wBAAgB,eAAe,8DAE9B"}

package/dist/use-search-params.js

@@ -0,0 +1,5 @@
+import { use } from "react";
+import { SearchParamsContext } from "./context";
+export function useSearchParams() {
+    return use(SearchParamsContext);
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@toapi/router",
+  "version": "0.6.2",
+  "author": {
+    "name": "Michel Smola",
+    "email": "michel.smola@farbenmeer.de"
+  },
+  "type": "module",
+  "module": "dist/index.js",
+  "main": "dist/index.js",
+  "private": false,
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/farbenmeer/tapi.git"
+  },
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "@testing-library/dom": "^10.4.1",
+    "@types/node": "^25.0.3",
+    "@types/react": "^19.2.7",
+    "@vitejs/plugin-react": "^6.0.0",
+    "@vitest/browser-playwright": "^4.0.16",
+    "react": "^19.1.1",
+    "vitest": "^4.0.16",
+    "playwright": "^1.59.1",
+    "vitest-browser-react": "^2.0.2"
+  },
+  "peerDependencies": {
+    "react": "^19.1.1",
+    "typescript": "^5 || ^6.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "release": "pnpm run build && pnpm publish --no-git-checks",
+    "test": "vitest"
+  }
+}