@mpen/rerouter 0.1.9 → 0.3.1

package/src/components/Link.test.tsx

@@ -0,0 +1,139 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
+import { Window } from 'happy-dom'
+
+const testWindow = new Window({ url: 'http://localhost/start' })
+
+testWindow.SyntaxError = SyntaxError
+
+Object.assign(globalThis, {
+    window: testWindow,
+    document: testWindow.document,
+    navigator: testWindow.navigator,
+    location: testWindow.location,
+    history: testWindow.history,
+    Event: testWindow.Event,
+    HTMLElement: testWindow.HTMLElement,
+    MouseEvent: testWindow.MouseEvent,
+    Node: testWindow.Node,
+    PopStateEvent: testWindow.PopStateEvent,
+    SyntaxError,
+    getComputedStyle: testWindow.getComputedStyle.bind(testWindow),
+})
+
+const { cleanup, fireEvent, render, screen } = await import('@testing-library/react')
+const { Link } = await import('./Link')
+
+describe(Link.name, () => {
+    beforeEach(() => {
+        window.history.replaceState(null, '', '/start')
+    })
+
+    afterEach(() => {
+        cleanup()
+        window.history.replaceState(null, '', '/start')
+    })
+
+    test('renders a link with merged search params', () => {
+        render(
+            <Link
+                aria-label="Match details"
+                className={['match-link', { selected: true, pending: false }]}
+                to="/matches?sort=asc"
+                search={{ page: 2, sort: 'desc' }}
+            >
+                View match
+            </Link>,
+        )
+
+        const link = screen.getByRole('link', { name: 'Match details' })
+
+        expect(link.textContent).toBe('View match')
+        expect(link.getAttribute('class')).toBe('match-link selected')
+        expect(link.getAttribute('href')).toBe('/matches?sort=desc&page=2')
+    })
+
+    test('pushes the target URL and emits popstate on ordinary clicks', () => {
+        let popstateCount = 0
+        window.addEventListener(
+            'popstate',
+            () => {
+                popstateCount += 1
+            },
+            { once: true },
+        )
+
+        render(<Link to="/matches/42?tab=details">View match</Link>)
+
+        fireEvent.click(screen.getByRole('link', { name: 'View match' }))
+
+        expect(window.location.pathname).toBe('/matches/42')
+        expect(window.location.search).toBe('?tab=details')
+        expect(popstateCount).toBe(1)
+    })
+
+    test('replaces the current URL when replace is set', () => {
+        const replaceState = window.history.replaceState.bind(window.history)
+        let replacedUrl = ''
+        window.history.replaceState = ((data, title, url) => {
+            replacedUrl = String(url)
+            return replaceState(data, title, url)
+        }) as History['replaceState']
+
+        render(
+            <Link replace to="/matches/42">
+                Replace match
+            </Link>,
+        )
+
+        try {
+            fireEvent.click(screen.getByRole('link', { name: 'Replace match' }))
+
+            expect(replacedUrl).toBe('/matches/42')
+            expect(window.location.pathname).toBe('/matches/42')
+        } finally {
+            window.history.replaceState = replaceState
+        }
+    })
+
+    test('leaves modified clicks to the browser', () => {
+        let popstateCount = 0
+        window.addEventListener(
+            'popstate',
+            () => {
+                popstateCount += 1
+            },
+            { once: true },
+        )
+
+        render(<Link to="/matches/42">Open elsewhere</Link>)
+
+        const defaultWasNotPrevented = fireEvent.click(
+            screen.getByRole('link', { name: 'Open elsewhere' }),
+            { ctrlKey: true },
+        )
+
+        expect(defaultWasNotPrevented).toBe(true)
+        expect(popstateCount).toBe(0)
+    })
+
+    test('leaves non-primary button clicks to the browser', () => {
+        let popstateCount = 0
+        window.addEventListener(
+            'popstate',
+            () => {
+                popstateCount += 1
+            },
+            { once: true },
+        )
+
+        render(<Link to="/matches/42">Open with auxiliary button</Link>)
+
+        const defaultWasNotPrevented = fireEvent.click(
+            screen.getByRole('link', { name: 'Open with auxiliary button' }),
+            { button: 1 },
+        )
+
+        expect(defaultWasNotPrevented).toBe(true)
+        expect(popstateCount).toBe(0)
+    })
+})

package/src/components/Link.tsx

@@ -0,0 +1,89 @@
+import { cc, type ClassValue } from '@mpen/classcat'
+import type { OverrideProps } from '@mpen/ts-types/react'
+import { startTransition, type MouseEvent } from 'react'
+import { pushUrl, replaceUrl } from '../lib/url'
+import { mergeSearch } from '../lib/mergeSearch'
+
+/**
+ * Values accepted by [`Link`]{@link Link} for building query strings.
+ *
+ * @example
+ * ```tsx
+ * <Link to="/matches" search={{ page: 2, sort: 'desc' }}>
+ *     Matches
+ * </Link>
+ * ```
+ */
+export type SearchParamsInit =
+    | string
+    | string[][]
+    | Record<string, string | number | boolean | undefined | null>
+    | URLSearchParams
+
+/**
+ * Props for [`Link`]{@link Link}.
+ */
+export type LinkProps = OverrideProps<
+    'a',
+    {
+        /**
+         * Classes to apply to the rendered anchor.
+         */
+        className?: ClassValue
+
+        /**
+         * Destination URL passed to the rendered anchor's `href` attribute.
+         */
+        to: string
+
+        /**
+         * Query parameters to merge into [`LinkProps.to`]{@link LinkProps#to}.
+         */
+        search?: SearchParamsInit
+
+        /**
+         * Whether navigation should replace the current history entry instead of pushing a new one.
+         */
+        replace?: boolean
+
+        href: never
+        onClick: never
+    }
+>
+
+/**
+ * Renders an anchor that navigates with rerouter history updates on ordinary clicks.
+ *
+ * @example
+ * ```tsx
+ * <Link to="/matches/42" search={{ tab: 'details' }}>
+ *     View match
+ * </Link>
+ * ```
+ *
+ * @param props - Anchor props plus rerouter navigation options.
+ * @returns An anchor element that pushes or replaces the browser URL.
+ */
+export function Link({ to, search, children, className, replace, ...rest }: LinkProps) {
+    const href = search ? mergeSearch(to, search) : to
+    const linkClassName = cc(className)
+
+    const onClick = (ev: MouseEvent<HTMLAnchorElement>) => {
+        if (ev.metaKey || ev.ctrlKey || ev.shiftKey || ev.altKey) return
+        if (ev.button !== 0) return
+        ev.preventDefault()
+        startTransition(() => {
+            if (replace) {
+                replaceUrl(href)
+            } else {
+                pushUrl(href)
+            }
+        })
+    }
+
+    return (
+        <a {...rest} className={linkClassName || undefined} href={href} onClick={onClick}>
+            {children}
+        </a>
+    )
+}

package/src/components/NavLink.test.tsx

@@ -0,0 +1,119 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
+import { Window } from 'happy-dom'
+
+const testWindow = new Window({ url: 'http://localhost/start' })
+
+testWindow.SyntaxError = SyntaxError
+
+Object.assign(globalThis, {
+    window: testWindow,
+    document: testWindow.document,
+    navigator: testWindow.navigator,
+    location: testWindow.location,
+    history: testWindow.history,
+    Event: testWindow.Event,
+    HTMLElement: testWindow.HTMLElement,
+    MouseEvent: testWindow.MouseEvent,
+    Node: testWindow.Node,
+    PopStateEvent: testWindow.PopStateEvent,
+    SyntaxError,
+    getComputedStyle: testWindow.getComputedStyle.bind(testWindow),
+})
+
+const { cleanup, render } = await import('@testing-library/react')
+const { NavLink } = await import('./NavLink')
+
+describe(NavLink.name, () => {
+    beforeEach(() => {
+        window.history.replaceState(null, '', '/start')
+    })
+
+    afterEach(() => {
+        cleanup()
+        window.history.replaceState(null, '', '/start')
+    })
+
+    test('renders active classes when the target path matches the current path', () => {
+        const { getByRole } = render(
+            <NavLink
+                activeClass={{ active: true, pending: false }}
+                className="pill"
+                inactiveClass="muted"
+                to="/start?tab=details"
+            >
+                Start
+            </NavLink>,
+        )
+
+        expect(getByRole('link', { name: 'Start' }).getAttribute('class')).toBe('pill active')
+    })
+
+    test('renders inactive classes when the target path does not match the current path', () => {
+        const { getByRole } = render(
+            <NavLink
+                activeClass="active"
+                className="pill"
+                inactiveClass={{ muted: true }}
+                to="/matches"
+            >
+                Matches
+            </NavLink>,
+        )
+
+        expect(getByRole('link', { name: 'Matches' }).getAttribute('class')).toBe('pill muted')
+    })
+
+    test('normalizes relative targets using the current URL', () => {
+        window.history.replaceState(null, '', '/matches/42')
+
+        const { getByRole } = render(
+            <NavLink activeClass="active" className="pill" inactiveClass="muted" to="?tab=details">
+                Current match
+            </NavLink>,
+        )
+
+        expect(getByRole('link', { name: 'Current match' }).getAttribute('class')).toBe(
+            'pill active',
+        )
+    })
+
+    test('renders active classes for prefix matches', () => {
+        window.history.replaceState(null, '', '/fetch-loading/abc-123')
+
+        const { getByRole } = render(
+            <NavLink
+                activeClass="active"
+                className="pill"
+                inactiveClass="muted"
+                match="prefix"
+                to="/fetch-loading"
+            >
+                Fetch Loading
+            </NavLink>,
+        )
+
+        expect(getByRole('link', { name: 'Fetch Loading' }).getAttribute('class')).toBe(
+            'pill active',
+        )
+    })
+
+    test('does not render active classes for partial segment prefix matches', () => {
+        window.history.replaceState(null, '', '/fetch-loading-old')
+
+        const { getByRole } = render(
+            <NavLink
+                activeClass="active"
+                className="pill"
+                inactiveClass="muted"
+                match="prefix"
+                to="/fetch-loading"
+            >
+                Fetch Loading
+            </NavLink>,
+        )
+
+        expect(getByRole('link', { name: 'Fetch Loading' }).getAttribute('class')).toBe(
+            'pill muted',
+        )
+    })
+})

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.test.tsx

@@ -0,0 +1,183 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
+import { Window } from 'happy-dom'
+import type { RouteObject } from '../lib/routes'
+
+const testWindow = new Window({ url: 'http://localhost/start' })
+
+testWindow.SyntaxError = SyntaxError
+
+Object.assign(globalThis, {
+    window: testWindow,
+    document: testWindow.document,
+    navigator: testWindow.navigator,
+    location: testWindow.location,
+    history: testWindow.history,
+    Event: testWindow.Event,
+    HTMLElement: testWindow.HTMLElement,
+    MouseEvent: testWindow.MouseEvent,
+    Node: testWindow.Node,
+    PopStateEvent: testWindow.PopStateEvent,
+    SyntaxError,
+    getComputedStyle: testWindow.getComputedStyle.bind(testWindow),
+})
+
+const { act, cleanup, render, waitFor } = await import('@testing-library/react')
+const { Router } = await import('./Router')
+const { pushUrl } = await import('../lib/url')
+
+function wait(ms: number): Promise<void> {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms)
+    })
+}
+
+describe(Router.name, () => {
+    beforeEach(() => {
+        window.history.replaceState(null, '', '/start')
+    })
+
+    afterEach(() => {
+        cleanup()
+        window.history.replaceState(null, '', '/start')
+    })
+
+    test('delays the loading fallback while a route component is loading', async () => {
+        window.history.replaceState(null, '', '/slow')
+
+        const routes: readonly RouteObject[] = [
+            {
+                pattern: '/slow',
+                component: () =>
+                    new Promise(() => {
+                        // Keep the route pending so the fallback delay is observable.
+                    }),
+            },
+        ]
+
+        const view = render(
+            <Router loading={<div>Loading route...</div>} loadingDelayMs={25} routes={routes} />,
+        )
+
+        expect(view.queryByText('Loading route...')).toBeNull()
+
+        await act(async () => {
+            await wait(30)
+        })
+
+        expect(view.getByText('Loading route...')).toBeTruthy()
+    })
+
+    test('does not show the loading fallback when the route loads before the delay', async () => {
+        window.history.replaceState(null, '', '/quick')
+
+        const routes: readonly RouteObject[] = [
+            {
+                pattern: '/quick',
+                component: () =>
+                    wait(5).then(() => ({
+                        default: function QuickRoute() {
+                            return <div>Quick route</div>
+                        },
+                    })),
+            },
+        ]
+
+        const view = render(
+            <Router loading={<div>Loading route...</div>} loadingDelayMs={50} routes={routes} />,
+        )
+
+        expect(view.queryByText('Loading route...')).toBeNull()
+
+        await waitFor(() => {
+            expect(view.getByText('Quick route')).toBeTruthy()
+        })
+
+        expect(view.queryByText('Loading route...')).toBeNull()
+    })
+
+    test('keeps the current route visible until a slow next route reaches the delay', async () => {
+        const routes: readonly RouteObject[] = [
+            {
+                pattern: '/start',
+                component: async () => ({
+                    default: function StartRoute() {
+                        return <div>Start route</div>
+                    },
+                }),
+            },
+            {
+                pattern: '/slow',
+                component: () =>
+                    new Promise(() => {
+                        // Keep the next route pending so the delayed loading state is observable.
+                    }),
+            },
+        ]
+
+        const view = render(
+            <Router loading={<div>Loading route...</div>} loadingDelayMs={25} routes={routes} />,
+        )
+
+        await waitFor(() => {
+            expect(view.getByText('Start route')).toBeTruthy()
+        })
+
+        act(() => {
+            pushUrl('/slow')
+        })
+
+        expect(view.getByText('Start route')).toBeTruthy()
+        expect(view.queryByText('Loading route...')).toBeNull()
+
+        await act(async () => {
+            await wait(30)
+        })
+
+        expect(view.queryByText('Start route')).toBeNull()
+        expect(view.getByText('Loading route...')).toBeTruthy()
+    })
+
+    test('keeps the current route visible until a quick next route is ready', async () => {
+        const routes: readonly RouteObject[] = [
+            {
+                pattern: '/start',
+                component: async () => ({
+                    default: function StartRoute() {
+                        return <div>Start route</div>
+                    },
+                }),
+            },
+            {
+                pattern: '/quick',
+                component: () =>
+                    wait(5).then(() => ({
+                        default: function QuickRoute() {
+                            return <div>Quick route</div>
+                        },
+                    })),
+            },
+        ]
+
+        const view = render(
+            <Router loading={<div>Loading route...</div>} loadingDelayMs={50} routes={routes} />,
+        )
+
+        await waitFor(() => {
+            expect(view.getByText('Start route')).toBeTruthy()
+        })
+
+        act(() => {
+            pushUrl('/quick')
+        })
+
+        expect(view.getByText('Start route')).toBeTruthy()
+        expect(view.queryByText('Loading route...')).toBeNull()
+
+        await waitFor(() => {
+            expect(view.getByText('Quick route')).toBeTruthy()
+        })
+
+        expect(view.queryByText('Start route')).toBeNull()
+        expect(view.queryByText('Loading route...')).toBeNull()
+    })
+})