@studiolambda/router 0.1.0

package/dist/src/react/hooks/usePrefetch.d.ts

@@ -0,0 +1,27 @@
+import { Handler } from '../router';
+import { Matcher } from '../../router/matcher';
+/**
+ * Options for the `usePrefetch` hook.
+ */
+export interface PrefetchOptions {
+    /**
+     * Optional matcher override. When omitted the hook reads
+     * from `MatcherContext`.
+     */
+    matcher?: Matcher<Handler>;
+}
+/**
+ * Returns a function that triggers the prefetch logic for a
+ * given URL by resolving it against the matcher and calling
+ * the route's prefetch function. Used by the Link component
+ * for hover and viewport prefetch strategies.
+ *
+ * Since prefetch triggered from Link happens outside of a
+ * navigation event, a stub NavigationPrecommitController is
+ * passed (the redirect capability is not meaningful here).
+ *
+ * @param options - Optional matcher override.
+ * @returns A function that accepts a URL string and invokes
+ *   the matched route's prefetch handler, if any.
+ */
+export declare function usePrefetch(options?: PrefetchOptions): (url: string) => void | Promise<void>;

package/dist/src/react/hooks/usePrefetchEffect.d.ts

@@ -0,0 +1,69 @@
+import { RefObject } from 'react';
+import { Handler } from '../router';
+import { Matcher } from '../../router/matcher';
+/**
+ * Prefetch trigger strategy. Determines which DOM event
+ * activates the prefetch for the target element.
+ *
+ * - `viewport` — prefetch fires when the element enters
+ *   the viewport via an IntersectionObserver.
+ * - `hover` — prefetch fires on `mouseenter`.
+ */
+export type PrefetchStrategy = 'viewport' | 'hover';
+/**
+ * Options for the `usePrefetchEffect` hook.
+ */
+export interface PrefetchEffectOptions {
+    /**
+     * The URL to prefetch. When undefined, the effect is
+     * a no-op (no observer or listener is attached).
+     */
+    href: string | undefined;
+    /**
+     * Prefetch trigger strategy. When undefined, the effect
+     * is a no-op — no proactive prefetch is set up.
+     */
+    on: PrefetchStrategy | undefined;
+    /**
+     * Whether to only prefetch once. When true, hover
+     * listeners use the `{ once }` option and viewport
+     * observers disconnect after the first intersection.
+     * Defaults to `true`.
+     */
+    once?: boolean;
+    /**
+     * Optional matcher override. When omitted, reads from
+     * `MatcherContext` via `usePrefetch`.
+     */
+    matcher?: Matcher<Handler>;
+}
+/**
+ * Attaches prefetch behavior to a DOM element via a ref.
+ * Sets up an IntersectionObserver (for `viewport` strategy)
+ * or a mouseenter listener (for `hover` strategy) that
+ * triggers route prefetching when activated.
+ *
+ * When `on` is undefined or `href` is undefined, no
+ * observer or listener is attached — the hook is a no-op.
+ *
+ * This hook is used internally by the Link component and
+ * can also be used standalone to add prefetch behavior to
+ * any DOM element.
+ *
+ * @param ref - A ref to the DOM element to observe. The
+ *   element must be mounted before the effect runs.
+ * @param options - Configuration for the prefetch behavior
+ *   including the URL, trigger strategy, and matcher.
+ *
+ * @example
+ * ```tsx
+ * function Card({ href }: { href: string }) {
+ *   const ref = useRef<HTMLDivElement>(null)
+ *
+ *   usePrefetchEffect(ref, { href, on: 'viewport' })
+ *
+ *   return <div ref={ref}>...</div>
+ * }
+ * ```
+ */
+export declare function usePrefetchEffect(ref: RefObject<Element | null>, options: PrefetchEffectOptions): void;

package/dist/src/react/hooks/useSearchParams.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Updater function signature for setting search params.
+ * Accepts either a new URLSearchParams instance, a plain
+ * record of string key-value pairs, or a function that
+ * receives the current params and returns updated params.
+ */
+export type SearchParamsUpdater = URLSearchParams | Record<string, string> | ((current: URLSearchParams) => URLSearchParams | Record<string, string>);
+/**
+ * Options for the search params navigation performed by
+ * the setter function returned from `useSearchParams`.
+ */
+export interface SetSearchParamsOptions {
+    /**
+     * History behavior for the navigation. Defaults to
+     * `'replace'` since search param changes typically
+     * should not create new history entries.
+     */
+    history?: NavigationHistoryBehavior;
+}
+/**
+ * Returns the current URL's search parameters as a
+ * `URLSearchParams` instance and a setter function to
+ * update them via navigation.
+ *
+ * The getter reads from `navigation.currentEntry.url`
+ * on each render, so it always reflects the committed
+ * URL. The setter performs a navigation with the updated
+ * search string, defaulting to `history: 'replace'` to
+ * avoid polluting the history stack with parameter changes.
+ *
+ * The React Compiler handles memoization of the setter,
+ * so no manual `useCallback` is needed.
+ *
+ * Must be used inside a `<Router>` component tree.
+ *
+ * @returns A tuple of `[searchParams, setSearchParams]`.
+ *
+ * @example
+ * ```tsx
+ * function SearchPage() {
+ *   const [searchParams, setSearchParams] = useSearchParams()
+ *   const query = searchParams.get('q') ?? ''
+ *
+ *   return (
+ *     <input
+ *       value={query}
+ *       onChange={function (event) {
+ *         setSearchParams({ q: event.target.value })
+ *       }}
+ *     />
+ *   )
+ * }
+ * ```
+ */
+export declare function useSearchParams(): [
+    URLSearchParams,
+    (updater: SearchParamsUpdater, options?: SetSearchParamsOptions) => NavigationResult
+];

package/dist/src/react/index.d.ts

@@ -0,0 +1,31 @@
+export * from './components/Middlewares';
+export * from './components/Router';
+export * from './components/NotFound';
+export * from './components/Link';
+export * from './context/MatcherContext';
+export * from './context/TransitionContext';
+export * from './context/PropsContext';
+export * from './context/NavigationContext';
+export * from './context/NavigationSignalContext';
+export * from './context/NavigationTypeContext';
+export * from './context/PathnameContext';
+export * from './hooks/useNavigation';
+export * from './hooks/useNavigate';
+export * from './hooks/useNavigationSignal';
+export * from './hooks/useNavigationType';
+export * from './hooks/usePrefetch';
+export * from './hooks/useNextMatch';
+export * from './hooks/useNavigationHandlers';
+export * from './hooks/useParams';
+export * from './hooks/useIsPending';
+export * from './hooks/usePathname';
+export * from './hooks/useSearchParams';
+export * from './hooks/useBack';
+export * from './hooks/useForward';
+export * from './hooks/useNavigationEvents';
+export * from './hooks/useActiveLinkProps';
+export * from './hooks/usePrefetchEffect';
+export * from './navigation/createMemoryNavigation';
+export * from './extractPathname';
+export * from './createRouter';
+export * from './router';

package/dist/src/react/navigation/createMemoryNavigation.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Options for creating a memory navigation instance.
+ */
+export interface MemoryNavigationOptions {
+    /**
+     * The initial URL for the memory navigation. This is the
+     * URL that `currentEntry.url` will return. Typically the
+     * request URL from the server for SSR, or a test URL.
+     *
+     * @example `'https://example.com/user/42?tab=posts'`
+     */
+    readonly url: string;
+}
+/**
+ * Creates a minimal in-memory Navigation object suitable for
+ * server-side rendering and testing environments where the
+ * browser Navigation API is unavailable.
+ *
+ * The returned object satisfies the subset of the `Navigation`
+ * interface consumed by the Router component:
+ *
+ * - `currentEntry.url` — returns the initial URL
+ * - `addEventListener` / `removeEventListener` — no-ops
+ *   (no events fire in a memory environment)
+ * - `navigate()` — no-op that returns a NavigationResult
+ *   with immediately-resolved promises
+ * - `canGoBack` / `canGoForward` — always false
+ * - `entries()` — returns a single-entry array
+ *
+ * The object is cast to `Navigation` for compatibility with
+ * the Router's `navigation` prop and `NavigationContext`.
+ * Properties not listed above are not implemented and will
+ * throw if accessed by consumer code outside the Router.
+ *
+ * @param options - Configuration including the initial URL.
+ * @returns A Navigation-compatible object for SSR or testing.
+ *
+ * @example
+ * ```tsx
+ * // Server-side rendering
+ * const navigation = createMemoryNavigation({
+ *   url: request.url,
+ * })
+ *
+ * const html = renderToString(
+ *   <Router navigation={navigation} matcher={matcher}>
+ *     <App />
+ *   </Router>
+ * )
+ * ```
+ */
+export declare function createMemoryNavigation(options: MemoryNavigationOptions): Navigation;

package/dist/src/react/router.d.ts

@@ -0,0 +1,139 @@
+import { ReactNode, ComponentType } from 'react';
+/**
+ * Defines the route handler configuration for a matched route.
+ * Contains the component to render, optional prefetch logic,
+ * middleware components, scroll/focus behavior, and form handling.
+ */
+export interface Handler {
+    /**
+     * The React component to render for this route.
+     * Can be a regular component or a `lazy()` component
+     * for code-split routes.
+     */
+    readonly component: ComponentType;
+    /**
+     * Optional prefetch function invoked during the precommit phase.
+     * Receives a context with matched route params, destination URL,
+     * and the precommit controller for redirects.
+     */
+    readonly prefetch?: PrefetchFunc;
+    /**
+     * Middleware components that wrap the route component.
+     * Applied via reduceRight so the first middleware in
+     * the array wraps outermost, and the last wraps innermost.
+     */
+    readonly middlewares?: ComponentType<MiddlewareProps>[];
+    /**
+     * Controls whether the browser performs scroll restoration
+     * after the navigation handler completes.
+     * - `after-transition` (default): browser handles scrolling
+     *   after the handler promise resolves.
+     * - `manual`: disables automatic scrolling so the route
+     *   component can call `event.scroll()` manually.
+     */
+    readonly scroll?: NavigationScrollBehavior;
+    /**
+     * Controls whether the browser resets focus after navigation.
+     * - `after-transition` (default): focuses the first autofocus
+     *   element or the body after the handler resolves.
+     * - `manual`: disables automatic focus reset so the route
+     *   component can manage focus manually.
+     */
+    readonly focusReset?: NavigationFocusReset;
+    /**
+     * Optional handler for form submissions (POST navigations).
+     * When a navigation includes FormData and the matched route
+     * has a formHandler, it is called instead of the normal
+     * component render flow.
+     */
+    readonly formHandler?: FormHandler;
+}
+/**
+ * Context passed to prefetch functions during the precommit
+ * phase of a navigation. Provides the matched route parameters,
+ * the destination URL, and the Navigation API's precommit
+ * controller for redirects.
+ */
+export interface PrefetchContext {
+    /**
+     * Dynamic route parameters extracted from the matched URL
+     * pattern. For example, a route registered as `/user/:id`
+     * matching `/user/42` produces `{ id: '42' }`.
+     */
+    readonly params: Record<string, string>;
+    /**
+     * The full destination URL being navigated to. Includes
+     * the pathname, search parameters, and hash. Useful for
+     * constructing query keys or reading search params during
+     * prefetch.
+     */
+    readonly url: URL;
+    /**
+     * The precommit controller from the Navigation API,
+     * providing `redirect()` to abort the current navigation
+     * and redirect elsewhere, and `addHandler()` to register
+     * additional post-commit handlers. When prefetch is
+     * triggered outside a real navigation (e.g. Link hover),
+     * this is a stub with no-op methods.
+     */
+    readonly controller: NavigationPrecommitController;
+}
+/**
+ * Function invoked during the precommit phase of a navigation.
+ * Receives a context object with the matched route parameters,
+ * destination URL, and the Navigation API's precommit controller
+ * for redirects or additional handler registration.
+ *
+ * @param context - The prefetch context containing route params,
+ *   destination URL, and the precommit controller.
+ * @returns Void or a promise that resolves when prefetching
+ *   is complete.
+ */
+export type PrefetchFunc = {
+    (context: PrefetchContext): void | Promise<void>;
+};
+/**
+ * Target for a redirect route. Can be a static absolute path
+ * string, or a callback that receives the prefetch context and
+ * returns the path to redirect to. The callback form enables
+ * dynamic redirects that use matched route parameters or the
+ * destination URL to compute the target.
+ *
+ * @example
+ * ```ts
+ * // Static redirect
+ * route('/old').redirect('/new')
+ *
+ * // Dynamic redirect using route params
+ * route('/old-user/:id').redirect(({ params }) => `/user/${params.id}`)
+ * ```
+ */
+export type RedirectTarget = string | ((context: PrefetchContext) => string);
+/**
+ * Handler invoked when a form submission navigation matches
+ * this route. Receives the submitted FormData and the original
+ * NavigateEvent for full access to the navigation context.
+ *
+ * @param formData - The FormData from the submitted form.
+ * @param event - The original NavigateEvent that triggered
+ *   the form submission.
+ * @returns Void or a promise that resolves when the form
+ *   submission handling is complete.
+ */
+export type FormHandler = {
+    (formData: FormData, event: NavigateEvent): void | Promise<void>;
+};
+/**
+ * Props passed to middleware wrapper components. Each middleware
+ * receives `children` and decides whether to render them,
+ * enabling patterns like authentication guards and layout
+ * wrappers.
+ */
+export interface MiddlewareProps {
+    /**
+     * The downstream content to render. A middleware can choose
+     * to render this directly, wrap it in additional providers,
+     * or omit it entirely (e.g. for auth redirects).
+     */
+    children: ReactNode;
+}

package/dist/src/react/test-helpers.d.ts

@@ -0,0 +1,50 @@
+import { ReactNode } from 'react';
+/**
+ * Result returned by `renderHook`. Provides access to the
+ * current hook return value and a cleanup function.
+ *
+ * @typeParam T - The return type of the hook under test.
+ */
+export interface RenderHookResult<T> {
+    /**
+     * The current return value of the hook. Updated after
+     * each render.
+     */
+    readonly current: T;
+    /**
+     * Unmounts the test component and removes it from the
+     * DOM. Must be called after each test to avoid leaks.
+     */
+    readonly unmount: () => void;
+}
+/**
+ * Options for `renderHook`.
+ *
+ * @typeParam T - The return type of the hook under test.
+ */
+export interface RenderHookOptions {
+    /**
+     * Optional wrapper component that provides context
+     * providers around the hook test component.
+     */
+    wrapper?: (props: {
+        children: ReactNode;
+    }) => ReactNode;
+}
+/**
+ * Renders a React hook inside a minimal test component and
+ * returns the hook's current value. Mimics the API of
+ * `@testing-library/react`'s `renderHook` without requiring
+ * that dependency.
+ *
+ * The hook is rendered inside an `act()` boundary. The
+ * returned `current` property always reflects the latest
+ * hook return value.
+ *
+ * @typeParam T - The return type of the hook.
+ * @param hook - A function that calls the hook under test
+ *   and returns its result.
+ * @param options - Optional wrapper for context providers.
+ * @returns The hook result and an unmount function.
+ */
+export declare function renderHook<T>(hook: () => T, options?: RenderHookOptions): RenderHookResult<T>;

package/dist/src/router/index.d.ts

@@ -0,0 +1 @@
+export * from './matcher';

package/dist/src/router/matcher.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Describes a route matcher that maps URL path patterns to
+ * handlers. Supports static segments, dynamic `:param`
+ * segments, and wildcard `*param` segments with a trie-based
+ * lookup.
+ *
+ * @typeParam T - The handler type associated with each route.
+ */
+export interface Matcher<T> {
+    /**
+     * Registers a route pattern with a corresponding handler.
+     * Patterns use `/`-separated segments where `:name` denotes
+     * a dynamic parameter (e.g. `/user/:id/posts`) and `*name`
+     * denotes a wildcard that captures the rest of the path
+     * (e.g. `/files/*path`). A bare `*` captures into a param
+     * named `'*'`.
+     *
+     * @param pattern - The URL path pattern to register.
+     * @param handler - The handler to associate with this pattern.
+     */
+    readonly register: (pattern: string, handler: T) => void;
+    /**
+     * Attempts to match a URL path against registered routes.
+     * Static segments take priority over dynamic ones, which
+     * take priority over wildcard segments. Returns the matched
+     * handler and extracted parameters, or `null` if no route
+     * matches.
+     *
+     * @param path - The URL path to match (e.g. `/user/42`).
+     * @returns The resolved match with handler and params, or null.
+     */
+    readonly match: (path: string) => Resolved<T> | null;
+}
+/**
+ * The result of a successful route match. Contains the handler
+ * registered for the matched pattern and a record of extracted
+ * dynamic parameters.
+ *
+ * @typeParam T - The handler type associated with the route.
+ */
+export interface Resolved<T> {
+    /**
+     * The handler that was registered for the matched route pattern.
+     */
+    readonly handler: T;
+    /**
+     * Dynamic path parameters extracted from the URL. Keys are the
+     * parameter names from the pattern (without the `:` prefix),
+     * values are the corresponding URL segments.
+     *
+     * @example
+     * Pattern `/user/:id` matched against `/user/42`
+     * produces `{ id: "42" }`.
+     */
+    readonly params: Record<string, string>;
+}
+/**
+ * Configuration options for creating a new matcher instance.
+ *
+ * @typeParam T - The handler type associated with each route.
+ */
+export interface Options<T> {
+    /**
+     * An existing trie root node to use instead of creating
+     * an empty one. Useful for pre-built or shared route trees.
+     */
+    readonly root?: Node<T>;
+}
+/**
+ * A node in the route-matching trie. Each node represents a
+ * single URL path segment and may hold a handler (indicating
+ * a complete route), static children (keyed by segment string),
+ * a single dynamic child (for `:param` segments), and/or a
+ * wildcard child (for `*param` segments that capture the rest
+ * of the path).
+ *
+ * @typeParam T - The handler type associated with each route.
+ */
+export interface Node<T> {
+    /**
+     * Map of static child segments. Each key is a literal path
+     * segment string (e.g. `"user"`, `"posts"`).
+     */
+    readonly children: Map<string, Node<T>>;
+    /**
+     * The handler registered at this node, or `undefined` if
+     * this node is only an intermediate segment in a longer
+     * pattern.
+     */
+    handler?: T;
+    /**
+     * The single dynamic child node for `:param` segments.
+     * Only one dynamic segment is allowed per trie level.
+     */
+    child?: Node<T>;
+    /**
+     * The parameter name for this dynamic segment (without the
+     * `:` prefix). Only set on nodes created from `:param`
+     * patterns.
+     */
+    readonly name?: string;
+    /**
+     * The wildcard child node for `*param` segments. Captures
+     * all remaining path segments into a single parameter.
+     * Only one wildcard is allowed per trie level and it must
+     * be the last segment in the pattern.
+     */
+    wildcard?: Node<T>;
+}
+/**
+ * Creates a new trie-based route matcher. Routes are registered
+ * with patterns containing static segments, dynamic (`:param`)
+ * segments, and wildcard (`*param`) segments. Matching
+ * prioritises static segments over dynamic ones, and dynamic
+ * over wildcards, performing a depth-first search through the
+ * trie.
+ *
+ * Wildcard segments capture all remaining path segments into a
+ * single parameter joined by `/`. A bare `*` captures into
+ * a param named `'*'`. Wildcards must be the last segment
+ * in a pattern.
+ *
+ * @typeParam T - The handler type associated with each route.
+ * @param options - Optional configuration with a pre-built root node.
+ * @returns A matcher instance with `register` and `match` methods.
+ */
+export declare function createMatcher<T>(options?: Options<T>): Matcher<T>;

package/package.json

@@ -0,0 +1,107 @@
+{
+  "name": "@studiolambda/router",
+  "version": "0.1.0",
+  "license": "MIT",
+  "keywords": [
+    "router",
+    "react-router",
+    "isomorphic",
+    "routing",
+    "url",
+    "management",
+    "history",
+    "location"
+  ],
+  "description": "Lightweight, isomorphic and framework agnostic router for modern UIs",
+  "author": {
+    "name": "Erik C. Forés",
+    "email": "soc@erik.cat",
+    "url": "https://erik.cat"
+  },
+  "homepage": "https://erik.cat/blog/router-docs",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/StudioLambda/Router.git"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "type": "module",
+  "types": "./dist/src/router/index.d.ts",
+  "main": "./dist/router.cjs",
+  "module": "./dist/router.js",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/src/router/index.d.ts",
+      "import": "./dist/router.js",
+      "require": "./dist/router.cjs"
+    },
+    "./react": {
+      "types": "./dist/src/react/index.d.ts",
+      "import": "./dist/router_react.js",
+      "require": "./dist/router_react.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "package.json"
+  ],
+  "scripts": {
+    "build:only": "vite build",
+    "build": "npm run build:only",
+    "prebuild": "npm run format:check && npm run lint",
+    "lint": "oxlint",
+    "format": "oxfmt --write .",
+    "format:check": "oxfmt --check .",
+    "dev": "vite .",
+    "test": "vitest run",
+    "test:ui": "vitest --ui --coverage",
+    "test:cover": "vitest run --coverage",
+    "prepack": "npm run build"
+  },
+  "devEngines": {
+    "packageManager": {
+      "name": "npm",
+      "version": ">=11.0.0"
+    },
+    "runtime": {
+      "name": "node",
+      "version": ">=24.0.0"
+    }
+  },
+  "peerDependencies": {
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "devDependencies": {
+    "@rolldown/plugin-babel": "^0.2.2",
+    "@types/node": "^25.5.0",
+    "@types/react": "^19.2.2",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^6.0.1",
+    "@vitest/coverage-v8": "^4.0.7",
+    "babel-plugin-react-compiler": "^1.0.0",
+    "happy-dom": "^20.0.10",
+    "oxfmt": "^0.42.0",
+    "oxlint": "^1.57.0",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "typescript": "^6.0.2",
+    "vite": "^8.0.3",
+    "vite-plugin-dts": "^4.5.4",
+    "vitest": "^4.0.7"
+  }
+}