@farbenmeer/router 0.1.0

package/README.md

@@ -0,0 +1,222 @@
+# @farbenmeer/router Documentation
+
+A lightweight, React-based client-side router with support for nested routes, path parameters, and immutable search parameter handling.
+
+## Overview
+
+The `@farbenmeer/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 bracket notation (`[id]`)
+- **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 "@farbenmeer/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]`)
+- 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 bracket notation:
+
+```tsx
+<Route path="/users/[id]">          {/* /users/123 */}
+<Route path="/posts/[slug]">        {/* /posts/hello-world */}
+<Route path="/api/[version]">       {/* /api/v1 */}
+```
+
+### 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,14 @@
+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 declare const RouteContext: import("react").Context<{
+    path: string;
+    params: Record<string, string | string[]>;
+    matchedPathname: string;
+}>;
+//# 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,eAAO,MAAM,YAAY;UACjB,MAAM;YACJ,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;qBACxB,MAAM;EAKvB,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,6 @@
+export declare class ImmutableSearchParams extends URLSearchParams {
+    set(key: string, value: string): ImmutableSearchParams;
+    append(name: string, value: string): ImmutableSearchParams;
+    delete(key: string): ImmutableSearchParams;
+}
+//# 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;CAK5B"}

package/dist/immutable-search-params.js

@@ -0,0 +1,17 @@
+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);
+    }
+}

package/dist/index.d.ts

@@ -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";
+//# 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"}

package/dist/index.js

@@ -0,0 +1,8 @@
+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";

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-runtime").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;AAQrE,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,2CA4C5E"}

package/dist/link.js

@@ -0,0 +1,38 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { use, useMemo } from "react";
+import { PathnameContext, RouteContext, RouterContext, SearchParamsContext, } from "./context";
+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(() => {
+        if (href.startsWith("/")) {
+            return href;
+        }
+        if (href.startsWith("?")) {
+            return pathname + href;
+        }
+        if (href.startsWith("#")) {
+            return (pathname +
+                (searchParams.size > 0 ? "?" + searchParams.toString() : "") +
+                href);
+        }
+        if (!href) {
+            return parentPathname;
+        }
+        return parentPathname + "/" + href;
+    }, [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/route.d.ts

@@ -0,0 +1,8 @@
+interface Props {
+    path?: string;
+    exact?: boolean;
+    children: React.ReactNode;
+}
+export declare function Route({ path, exact, children }: Props): import("react/jsx-runtime").JSX.Element | null;
+export {};
+//# 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":"AAGA,UAAU,KAAK;IACb,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,KAAK,kDA0BrD"}

package/dist/route.js

@@ -0,0 +1,39 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { use, useMemo } from "react";
+import { PathnameContext, RouteContext } from "./context";
+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 });
+}
+function compilePathRegex(path) {
+    if (path === "/") {
+        return /^\//;
+    }
+    return new RegExp(`^(${path.replaceAll(/\[(\w+)\]/g, "(?<$1>[\\w-]+)")})(/.*)?$`);
+}
+function compileExactPathRegex(path) {
+    if (path === "/") {
+        return /^\/$/;
+    }
+    return new RegExp(`^(${path.replaceAll(/\[(\w+)\]/g, "(?<$1>[\\w-]+)")})$`);
+}
+function buildFullPath(parentPath, path) {
+    if (path?.startsWith("/")) {
+        return path;
+    }
+    if (path) {
+        return parentPath + "/" + path;
+    }
+    return parentPath;
+}

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(props: Props): import("react/jsx-runtime").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,EAAsC,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAS3E,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,KAAK,EAAE,KAAK,2CAwDlC"}

package/dist/router.js

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

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[]> = Record<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,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,KAI5C,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,5 @@
+export declare function useRouter(): {
+    push: (href: string) => void;
+    replace: (href: string) => void;
+};
+//# 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":"AAGA,wBAAgB,SAAS;;;EAExB"}

package/dist/use-router.js

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

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,33 @@
+{
+  "name": "@farbenmeer/router",
+  "version": "0.1.0",
+  "author": {
+    "name": "Michel Smola",
+    "email": "michel.smola@farbenmeer.de"
+  },
+  "type": "module",
+  "module": "dist/index.js",
+  "main": "dist/index.js",
+  "private": false,
+  "license": "MIT",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "release": "bun run build && bun publish"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@happy-dom/global-registrator": "^18.0.1",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/jest-dom": "^6.8.0",
+    "@testing-library/react": "^16.3.0",
+    "@types/bun": "latest",
+    "react": "^19.1.1"
+  },
+  "peerDependencies": {
+    "typescript": "^5",
+    "react": "^19.1.1"
+  }
+}