@mpen/rerouter 0.1.7 → 0.3.0

package/src/components/NavLink.tsx

@@ -0,0 +1,71 @@
+import { cc, type ClassValue } from '@mpen/classcat'
+import type { Override } from '@mpen/ts-types'
+import { useUrlPath } from '../hooks/useUrl'
+import { Link, type LinkProps } from './Link'
+
+export type NavLinkMatch = 'exact' | 'prefix'
+
+/**
+ * Props for [`NavLink`]{@link NavLink}.
+ */
+export type NavLinkProps = Override<
+    LinkProps,
+    {
+        /**
+         * Classes to apply when the link target matches the current path.
+         */
+        activeClass?: ClassValue
+
+        /**
+         * Classes to apply when the link target does not match the current path.
+         */
+        inactiveClass?: ClassValue
+
+        /**
+         * How to compare the link target to the current path.
+         *
+         * @defaultValue `'exact'`
+         */
+        match?: NavLinkMatch
+    }
+>
+
+function isActivePath(pathname: string, targetPathname: string, match: NavLinkMatch): boolean {
+    if (pathname === targetPathname) return true
+    if (match === 'exact') return false
+    if (targetPathname === '/') return false
+    return pathname.startsWith(`${targetPathname}/`)
+}
+
+/**
+ * Renders a [`Link`]{@link Link} with classes selected from the current route.
+ *
+ * @example
+ * ```tsx
+ * <NavLink
+ *     activeClass={['pill', 'active']}
+ *     inactiveClass={['pill', { muted: true }]}
+ *     to="/settings"
+ * >
+ *     Settings
+ * </NavLink>
+ * ```
+ *
+ * @param props - Link props plus active and inactive class values.
+ * @returns An anchor element that navigates through rerouter.
+ */
+export function NavLink({
+    activeClass,
+    className,
+    inactiveClass,
+    match = 'exact',
+    to,
+    ...props
+}: NavLinkProps) {
+    const pathname = useUrlPath()
+    const target = new URL(to, window.location.href)
+    const active = isActivePath(pathname, target.pathname, match)
+    const linkClassName = cc(className, active ? activeClass : inactiveClass)
+
+    return <Link {...props} className={linkClassName || undefined} to={to} />
+}

package/src/components/Router.tsx

@@ -0,0 +1,75 @@
+import { lazy, Suspense, useMemo, type ReactNode } from 'react'
+import { useUrlPath } from '../hooks'
+import { normalizeRoutes, type Route } from '../lib/routes'
+
+type LazyRouteComponent = ReturnType<typeof lazy>
+
+const lazyRouteComponents = new WeakMap<Route['component'], LazyRouteComponent>()
+
+function getLazyRouteComponent(component: Route['component']): LazyRouteComponent {
+    let LazyComponent = lazyRouteComponents.get(component)
+    if (!LazyComponent) {
+        LazyComponent = lazy(component)
+        lazyRouteComponents.set(component, LazyComponent)
+    }
+    return LazyComponent
+}
+
+/**
+ * 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
+}
+
+/**
+ * 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>} />
+ * }
+ * ```
+ */
+export function Router({ routes, loading = null }: RouterProps) {
+    const pathname = useUrlPath()
+
+    const normalizedRoutes = useMemo(
+        () =>
+            normalizeRoutes(routes).map((route) => ({
+                ...route,
+                Component: getLazyRouteComponent(route.component),
+            })),
+        [routes],
+    )
+
+    for (const { matches, Component } of normalizedRoutes) {
+        const params = matches(pathname)
+        if (!params) continue
+        return (
+            <Suspense fallback={loading}>
+                <Component {...(params as any)} />
+            </Suspense>
+        )
+    }
+
+    return null
+}

package/src/fixtures/bin/kitchen-sink.tsx

@@ -0,0 +1,15 @@
+import type { RouteObject } from '@mpen/rerouter'
+
+const ROUTES: readonly RouteObject[] = [
+    { name: 'home', pattern: '/', component: () => import('./pages/Home') },
+    {
+        name: 'kitchenSink',
+        pattern: '/hello/:foo/bar/:baz/*splat/xxx{/:optional/lol/:two}',
+        component: () => import('./pages/KitchenSink'),
+    },
+    { name: 'login', pattern: '/login', component: () => import('./pages/Login') },
+    { name: 'match', pattern: '/matches/:id', component: () => import('./pages/Match') },
+    { name: 'notFound', pattern: '*', component: () => import('./pages/NotFound') },
+]
+
+export default ROUTES

package/src/fixtures/bin/optional.tsx

@@ -0,0 +1,3 @@
+export default [
+    { name: 'optional', pattern: '/foo{/:bar}', component: () => import('./pages/Optional') },
+]

package/src/fixtures/bin/pages/Home.tsx

@@ -0,0 +1,3 @@
+export default function Home() {
+    return null
+}

package/src/fixtures/bin/pages/KitchenSink.tsx

@@ -0,0 +1,3 @@
+export default function KitchenSink() {
+    return null
+}

package/src/fixtures/bin/pages/Login.tsx

@@ -0,0 +1,3 @@
+export default function Login() {
+    return null
+}

package/src/fixtures/bin/pages/Match.tsx

@@ -0,0 +1,3 @@
+export default function Match() {
+    return null
+}

package/src/fixtures/bin/pages/NotFound.tsx

@@ -0,0 +1,3 @@
+export default function NotFound() {
+    return null
+}

package/src/fixtures/bin/pages/Optional.tsx

@@ -0,0 +1,3 @@
+export default function Optional() {
+    return null
+}

package/src/fixtures/bin/regexp-groups.tsx

@@ -0,0 +1,11 @@
+import type { RouteObject } from '@mpen/rerouter'
+
+const ROUTES: readonly RouteObject[] = [
+    {
+        name: 'blogPost',
+        pattern: '/blog/:id(\\d+){-:title}?',
+        component: () => import('./pages/Match'),
+    },
+]
+
+export default ROUTES

package/src/fixtures/bin/simple.tsx

@@ -0,0 +1 @@
+export default [{ name: 'home', pattern: '/', component: () => import('./pages/Home') }]

package/src/fixtures/bin/unnamed.tsx

@@ -0,0 +1,4 @@
+export default [
+    { name: 'home', pattern: '/', component: () => import('./pages/Home') },
+    { pattern: '/layout/:id', component: () => import('./pages/Home') },
+]

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,245 @@
+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>
+}
+
+/**
+ * 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,9 @@
+{
+    "extends": "../../tsconfig.json",
+    "compilerOptions": {
+        "jsx": "react-jsx",
+        "lib": ["DOM", "DOM.Iterable", "ESNext"],
+        "types": ["bun", "node", "react", "react-dom"]
+    },
+    "include": ["src/**/*", "examples/**/*"]
+}

package/tsdown.config.ts

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