@mpen/rerouter 0.1.9 → 0.3.1

package/src/components/Router.tsx

@@ -0,0 +1,207 @@
+import { startTransition, Suspense, useEffect, useMemo, useState, type ReactNode } from 'react'
+import { useUrlPath } from '../hooks'
+import {
+    normalizeRoutes,
+    type NormalizedRoute,
+    type Route,
+    type RouteComponent,
+} from '../lib/routes'
+
+const DEFAULT_LOADING_DELAY_MS = 400
+const loadedRouteComponents = new WeakMap<Route['component'], RouteComponent<any>>()
+const loadingRouteComponents = new WeakMap<Route['component'], Promise<RouteComponent<any>>>()
+
+type RouteMatch = {
+    route: NormalizedRoute
+    params: Record<string, string | undefined>
+    pathname: string
+}
+
+type RenderedRoute = RouteMatch & {
+    Component: RouteComponent<any>
+}
+
+function loadRouteComponent(component: Route['component']): Promise<RouteComponent<any>> {
+    const loaded = loadedRouteComponents.get(component)
+    if (loaded) return Promise.resolve(loaded)
+
+    let loading = loadingRouteComponents.get(component)
+    if (!loading) {
+        loading = component().then((module) => {
+            loadedRouteComponents.set(component, module.default)
+            loadingRouteComponents.delete(component)
+            return module.default
+        })
+        loadingRouteComponents.set(component, loading)
+    }
+
+    return loading
+}
+
+function findRouteMatch(routes: readonly NormalizedRoute[], pathname: string): RouteMatch | null {
+    for (const route of routes) {
+        const params = route.matches(pathname)
+        if (!params) continue
+        return { route, params, pathname }
+    }
+
+    return null
+}
+
+function getLoadedRoute(match: RouteMatch | null): RenderedRoute | null {
+    if (!match) return null
+
+    const Component = loadedRouteComponents.get(match.route.component)
+    if (!Component) return null
+
+    return {
+        ...match,
+        Component,
+    }
+}
+
+function scheduleTransition(cb: () => void): void {
+    queueMicrotask(() => {
+        startTransition(cb)
+    })
+}
+
+function useRenderedRoute(
+    match: RouteMatch | null,
+    loadingDelayMs: number,
+): { renderedRoute: RenderedRoute | null; showLoading: boolean } {
+    const [renderedRoute, setRenderedRoute] = useState(() => getLoadedRoute(match))
+    const [showLoading, setShowLoading] = useState(false)
+    const [loadError, setLoadError] = useState<unknown>(null)
+
+    useEffect(() => {
+        if (!match) {
+            scheduleTransition(() => {
+                setRenderedRoute(null)
+                setShowLoading(false)
+                setLoadError(null)
+            })
+            return
+        }
+
+        const loaded = getLoadedRoute(match)
+        if (loaded) {
+            scheduleTransition(() => {
+                setRenderedRoute(loaded)
+                setShowLoading(false)
+                setLoadError(null)
+            })
+            return
+        }
+
+        let active = true
+        let timeout: ReturnType<typeof setTimeout> | undefined
+
+        scheduleTransition(() => {
+            setShowLoading(false)
+        })
+
+        if (loadingDelayMs <= 0) {
+            timeout = setTimeout(() => {
+                if (active) setShowLoading(true)
+            }, 0)
+        } else {
+            timeout = setTimeout(() => {
+                if (active) setShowLoading(true)
+            }, loadingDelayMs)
+        }
+
+        loadRouteComponent(match.route.component)
+            .then((Component) => {
+                if (!active) return
+                if (timeout) clearTimeout(timeout)
+
+                startTransition(() => {
+                    setRenderedRoute({ ...match, Component })
+                    setShowLoading(false)
+                    setLoadError(null)
+                })
+            })
+            .catch((error: unknown) => {
+                if (!active) return
+                setLoadError(error)
+            })
+
+        return () => {
+            active = false
+            if (timeout) clearTimeout(timeout)
+        }
+    }, [loadingDelayMs, match])
+
+    if (loadError) throw loadError
+
+    return { renderedRoute, showLoading }
+}
+
+/**
+ * Props for [`Router`]{@link Router}.
+ *
+ * @example
+ * ```tsx
+ * <Router routes={routes} loading={<div>Loading...</div>} />
+ * ```
+ */
+export interface RouterProps {
+    /**
+     * Route definitions to match against the current URL pathname.
+     */
+    routes: readonly Route[]
+    /**
+     * Optional fallback rendered while a matched route component module is loading.
+     */
+    loading?: ReactNode
+
+    /**
+     * Delay before rendering [`RouterProps.loading`]{@link RouterProps#loading} for a suspended
+     * route, in milliseconds.
+     *
+     * @defaultValue `400`
+     */
+    loadingDelayMs?: number
+}
+
+/**
+ * Renders the first route that matches the current URL pathname.
+ *
+ * @param props - The router props.
+ * @returns The matched lazy route component, the loading fallback, or `null`.
+ *
+ * @example
+ * ```tsx
+ * import routes from './routes'
+ *
+ * function App() {
+ *     return <Router routes={routes} loading={<div>Loading...</div>} loadingDelayMs={400} />
+ * }
+ * ```
+ */
+export function Router({
+    routes,
+    loading = null,
+    loadingDelayMs = DEFAULT_LOADING_DELAY_MS,
+}: RouterProps) {
+    const pathname = useUrlPath()
+
+    const normalizedRoutes = useMemo(() => normalizeRoutes(routes), [routes])
+    const match = useMemo(
+        () => findRouteMatch(normalizedRoutes, pathname),
+        [normalizedRoutes, pathname],
+    )
+    const { renderedRoute, showLoading } = useRenderedRoute(match, loadingDelayMs)
+
+    if (showLoading) return loading
+    if (!renderedRoute) return null
+
+    const { Component, params } = renderedRoute
+
+    return (
+        <Suspense fallback={loading}>
+            <Component {...(params as any)} />
+        </Suspense>
+    )
+}

package/src/hooks/index.ts

@@ -0,0 +1 @@
+export { useUrlPath, useUrlSearchParams } from './useUrl'

package/src/hooks/useUrl.ts

@@ -0,0 +1,22 @@
+import { useMemo, useSyncExternalStore } from 'react'
+
+// Snapshot getters
+const getPathname = () => window.location.pathname
+const getSearch = () => window.location.search
+
+function subscribe(cb: () => void): () => void {
+    const handler = () => cb()
+    window.addEventListener('popstate', handler)
+    return () => {
+        window.removeEventListener('popstate', handler)
+    }
+}
+
+export function useUrlPath(): string {
+    return useSyncExternalStore(subscribe, getPathname, getPathname)
+}
+
+export function useUrlSearchParams(): URLSearchParams {
+    const search = useSyncExternalStore(subscribe, getSearch, getSearch)
+    return useMemo(() => new URLSearchParams(search), [search])
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export * from './components/Link'
+export * from './components/NavLink'
+export * from './components/Router'
+export * from './lib/routes'
+export * from './lib/url'
+export * from './hooks'

package/src/lib/mergeSearch.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, test } from 'bun:test'
+import { mergeSearch } from './mergeSearch'
+
+describe(mergeSearch.name, () => {
+    test('adds search params to a path without a query string', () => {
+        expect(mergeSearch('/matches', { page: 2, archived: false })).toBe(
+            '/matches?page=2&archived=false',
+        )
+    })
+
+    test('overwrites matching params and keeps unrelated existing params', () => {
+        expect(mergeSearch('/matches?page=1&sort=asc', { page: 2 })).toBe(
+            '/matches?page=2&sort=asc',
+        )
+    })
+
+    test('preserves hash fragments after the merged query string', () => {
+        expect(mergeSearch('/matches?page=1#details', { page: 2, tab: 'stats' })).toBe(
+            '/matches?page=2&tab=stats#details',
+        )
+    })
+
+    test('adds search params before a hash fragment when no query string exists', () => {
+        expect(mergeSearch('/matches#details', { tab: 'stats' })).toBe('/matches?tab=stats#details')
+    })
+
+    test('accepts URLSearchParams and tuple search params', () => {
+        expect(mergeSearch('/matches?filter=open', new URLSearchParams('filter=all'))).toBe(
+            '/matches?filter=all',
+        )
+        expect(mergeSearch('/matches', [['filter', 'open']])).toBe('/matches?filter=open')
+    })
+
+    test('encodes merged params using URLSearchParams serialization', () => {
+        expect(mergeSearch('/matches?q=old', { q: 'hello world' })).toBe('/matches?q=hello+world')
+    })
+})

package/src/lib/mergeSearch.ts

@@ -0,0 +1,21 @@
+import type { SearchParamsInit } from '../components/Link'
+
+export function mergeSearch(to: string, search: SearchParamsInit): string {
+    const hashIndex = to.indexOf('#')
+    const hash = hashIndex !== -1 ? to.slice(hashIndex) : ''
+    const pathAndQuery = hashIndex !== -1 ? to.slice(0, hashIndex) : to
+
+    const queryIndex = pathAndQuery.indexOf('?')
+    const path = queryIndex !== -1 ? pathAndQuery.slice(0, queryIndex) : pathAndQuery
+    const existingQuery = queryIndex !== -1 ? pathAndQuery.slice(queryIndex + 1) : ''
+
+    const params = new URLSearchParams(existingQuery)
+    const newParams = new URLSearchParams(search as any)
+
+    for (const [key, value] of newParams) {
+        params.set(key, value)
+    }
+
+    const queryString = params.toString()
+    return `${path}${queryString ? '?' + queryString : ''}${hash}`
+}

package/src/lib/routes.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, test } from 'bun:test'
+import { normalizeRoutes, type RouteObject } from './routes'
+
+const loadComponent: RouteObject['component'] = async () => ({
+    default: () => null,
+})
+
+describe('normalizeRoutes', () => {
+    test('matches routes without names', () => {
+        const [route] = normalizeRoutes([
+            {
+                pattern: '/fetch-loading/:id',
+                component: loadComponent,
+            },
+        ])
+
+        expect(route.name).toBeUndefined()
+        expect(route.matches('/fetch-loading/abc-123')).toEqual({ id: 'abc-123' })
+    })
+
+    test('matches catch-all routes', () => {
+        for (const pattern of ['*', '/*']) {
+            const [route] = normalizeRoutes([
+                {
+                    pattern,
+                    component: loadComponent,
+                },
+            ])
+
+            expect(route.matches('/')).toEqual({})
+            expect(route.matches('/anything')).toEqual({})
+            expect(route.matches('/nested/path')).toEqual({})
+        }
+    })
+
+    test('matches regexp params with optional groups', () => {
+        const [route] = normalizeRoutes([
+            {
+                name: 'blogPost',
+                pattern: '/blog/:id(\\d+){-:title}?',
+                component: loadComponent,
+            },
+        ])
+
+        expect(route.matches('/blog/123')).toEqual({ id: '123' })
+        expect(route.matches('/blog/123-hello%20world')).toEqual({
+            id: '123',
+            title: 'hello world',
+        })
+        expect(route.matches('/blog/not-a-number')).toBeNull()
+    })
+
+    test('matches named wildcards', () => {
+        const [route] = normalizeRoutes([
+            {
+                name: 'files',
+                pattern: '/files/*path',
+                component: loadComponent,
+            },
+        ])
+
+        expect(route.matches('/files/docs/api')).toEqual({ path: 'docs/api' })
+        expect(route.matches('/files/docs%20and%20api/reference')).toEqual({
+            path: 'docs and api/reference',
+        })
+    })
+})

package/src/lib/routes.ts

@@ -0,0 +1,247 @@
+import { match as pathMatch } from 'path-to-regexp'
+import type { ComponentType } from 'react'
+
+/**
+ * Route params captured from the current URL pathname.
+ */
+export type RouteParams = Record<string, string | undefined>
+
+/**
+ * A React component that receives URL params captured for its route.
+ *
+ * @example
+ * ```tsx
+ * const UserPage: RouteComponent<{ id: string }> = ({ id }) => <div>{id}</div>
+ * ```
+ */
+export type RouteComponent<TParams extends RouteParams = RouteParams> = ComponentType<TParams>
+
+/**
+ * A dynamically imported route component module.
+ *
+ * @example
+ * ```tsx
+ * export default function UserPage({ id }: { id: string }) {
+ *     return <div>{id}</div>
+ * }
+ * ```
+ */
+export type RouteComponentModule<TParams extends RouteParams = RouteParams> = {
+    default: RouteComponent<TParams>
+}
+
+/**
+ * Loads a route component on demand.
+ *
+ * @example
+ * ```tsx
+ * const loadUserPage: RouteComponentLoader<{ id: string }> = () => import('./pages/UserPage')
+ * ```
+ */
+export type RouteComponentLoader<TParams extends RouteParams = RouteParams> = () => Promise<
+    RouteComponentModule<TParams>
+>
+
+/**
+ * Object route definition consumed by [`Router`]{@link Router}.
+ *
+ * @example
+ * ```tsx
+ * const route: RouteObject = {
+ *     name: 'userProfile',
+ *     pattern: '/users/:id',
+ *     component: () => import('./pages/UserProfile'),
+ * }
+ * ```
+ */
+export type RouteObject = {
+    /**
+     * Optional route name used by the CLI to generate a URL helper.
+     *
+     * Routes without a name still participate in runtime matching, but are skipped by the
+     * helper generator.
+     */
+    name?: string
+    pattern: string | URLPattern
+    component: RouteComponentLoader<any>
+}
+
+export type Routes = RouteObject[]
+
+/**
+ * Route definition consumed by [`Router`]{@link Router}.
+ *
+ * @example
+ * ```tsx
+ * const routes: readonly Route[] = [
+ *     { name: 'home', pattern: '/', component: () => import('./pages/Home') },
+ *     { pattern: '/users/:id', component: () => import('./pages/UserLayout') },
+ * ]
+ * ```
+ */
+export type Route = RouteObject
+
+/**
+ * Route definition normalized into a single object shape with a pathname matcher.
+ */
+export type NormalizedRoute = {
+    name?: string
+    pattern: string | URLPattern
+    component: RouteComponentLoader<any>
+    matches(pathname: string): RouteParams | null
+}
+
+function toUrlPattern(pattern: string | URLPattern): URLPattern {
+    if (typeof pattern !== 'string') return pattern
+    return new URLPattern({ pathname: pattern })
+}
+
+function decodeRouteParams(groups: Record<string, unknown>): RouteParams {
+    const params: RouteParams = {}
+    for (const [key, value] of Object.entries(groups)) {
+        if (value == null) params[key] = undefined
+        else params[key] = decodeURIComponent(String(value))
+    }
+    return params
+}
+
+function stripLegacyParamPattern(pattern: string, startIndex: number): number {
+    let depth = 1
+    let endIndex = startIndex + 1
+    while (endIndex < pattern.length && depth > 0) {
+        const char = pattern[endIndex]
+        if (char === '\\') {
+            endIndex += 2
+            continue
+        }
+        if (char === '(') depth++
+        else if (char === ')') depth--
+        endIndex++
+    }
+    return endIndex
+}
+
+/**
+ * Converts legacy `path-to-regexp` syntax that is ignored by URL generation into syntax accepted
+ * by the current parser.
+ *
+ * @param pattern - The route pattern to normalize.
+ * @returns The pattern with custom regexp constraints stripped and optional group suffixes removed.
+ *
+ * @example
+ * ```ts
+ * normalizeLegacyPathToRegexpSyntax('/blog/:id(\\d+){-:title}?')
+ * // '/blog/:id{-:title}'
+ * ```
+ *
+ * @internal
+ */
+export function normalizeLegacyPathToRegexpSyntax(pattern: string): string {
+    let normalized = ''
+    for (let i = 0; i < pattern.length; i++) {
+        const char = pattern[i]
+        if (char === '\\') {
+            normalized += char
+            if (i + 1 < pattern.length) normalized += pattern[++i]
+            continue
+        }
+
+        if (char === ':' || char === '*') {
+            normalized += char
+            while (i + 1 < pattern.length && /[$_\p{ID_Continue}]/u.test(pattern[i + 1])) {
+                normalized += pattern[++i]
+            }
+            if (pattern[i + 1] === '(') {
+                i = stripLegacyParamPattern(pattern, i + 1) - 1
+            }
+            continue
+        }
+
+        if (char === '}' && pattern[i + 1] === '?') {
+            normalized += char
+            i++
+            continue
+        }
+
+        normalized += char
+    }
+    return normalized
+}
+
+/**
+ * Normalizes routes into objects with a shared matcher implementation.
+ *
+ * @param routes - The route definitions to normalize.
+ * @returns Routes with stable `name`, `pattern`, `component`, and `matches` fields.
+ *
+ * @example
+ * ```tsx
+ * const normalized = normalizeRoutes(routes)
+ * const match = normalized[0]?.matches('/users/123')
+ * ```
+ */
+export function normalizeRoutes(routes: readonly Route[]): NormalizedRoute[] {
+    return routes.map((route) => {
+        const { name, pattern, component } = route
+
+        if (typeof pattern !== 'string') {
+            const urlPattern = toUrlPattern(pattern)
+            return {
+                name,
+                pattern,
+                component,
+                matches(pathname: string) {
+                    const match = urlPattern.exec({ pathname } as any)
+                    if (!match) return null
+                    return ((match as any).pathname?.groups ?? {}) as RouteParams
+                },
+            }
+        }
+
+        if (pattern === '*' || pattern === '/*') {
+            return {
+                name,
+                pattern,
+                component,
+                matches: (_pathname: string) => ({}),
+            }
+        }
+
+        let matcher: ReturnType<typeof pathMatch> | undefined
+        let urlPattern: URLPattern | undefined
+        try {
+            matcher = pathMatch(pattern, { decode: decodeURIComponent })
+        } catch {
+            try {
+                urlPattern = toUrlPattern(pattern)
+            } catch {
+                matcher = pathMatch(normalizeLegacyPathToRegexpSyntax(pattern), {
+                    decode: decodeURIComponent,
+                })
+            }
+        }
+        return {
+            name,
+            pattern,
+            component,
+            matches(pathname: string) {
+                if (urlPattern) {
+                    const match = urlPattern.exec({ pathname } as any)
+                    if (!match) return null
+                    return decodeRouteParams((match as any).pathname?.groups ?? {})
+                }
+
+                if (!matcher) return null
+                const match = matcher(pathname)
+                if (!match) return null
+                const params: RouteParams = {}
+                for (const [key, value] of Object.entries(match.params as any)) {
+                    if (value == null) params[key] = undefined
+                    else if (Array.isArray(value)) params[key] = value.join('/')
+                    else params[key] = String(value)
+                }
+                return params
+            },
+        }
+    })
+}

package/src/lib/url.ts

@@ -0,0 +1,9 @@
+export function pushUrl(next: string, state?: unknown): void {
+    window.history.pushState(state, '', next)
+    window.dispatchEvent(new PopStateEvent('popstate'))
+}
+
+export function replaceUrl(next: string, state?: unknown): void {
+    window.history.replaceState(state, '', next)
+    window.dispatchEvent(new PopStateEvent('popstate'))
+}

package/tsconfig.json

@@ -0,0 +1,10 @@
+{
+    "extends": "../../tsconfig.json",
+    "compilerOptions": {
+        "jsx": "react-jsx",
+        "lib": ["DOM", "DOM.Iterable", "ESNext"],
+        "types": ["react", "react-dom"]
+    },
+    "include": ["src/**/*", "examples/**/*.ts", "examples/**/*.tsx"],
+    "exclude": ["**/*.test.*", "cli/**/*", "examples/dist/**/*", "examples/server/**/*"]
+}

package/tsdown.config.ts

@@ -0,0 +1,21 @@
+import { defineConfig } from 'tsdown'
+
+// https://tsdown.dev/reference/api/Interface.UserConfig
+export default defineConfig({
+    entry: {
+        index: 'src/index.ts',
+        bin: 'cli/bin.ts',
+    },
+    format: 'esm',
+    platform: 'neutral',
+    deps: {
+        neverBundle: [/^(node|bun):/, 'react'],
+    },
+    exports: {
+        legacy: true,
+        bin: {
+            rerouter: './cli/bin.ts',
+        },
+    },
+    dts: true, // The client must use "moduleResolution": "bundler", "node16" or "nodenext". "node" will not resolve the types properly.
+})

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2023 Mark Penner
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.