@esmx/router 3.0.0-rc.18 → 3.0.0-rc.20

package/src/router-link.ts

@@ -0,0 +1,235 @@
+import type { Router } from './router';
+import type {
+    RouterLinkAttributes,
+    RouterLinkProps,
+    RouterLinkResolved,
+    RouterLinkType
+} from './types';
+
+// Constants definition
+const CSS_CLASSES = {
+    BASE: 'router-link',
+    ACTIVE: 'router-link-active',
+    EXACT_ACTIVE: 'router-link-exact-active'
+} satisfies Record<string, string>;
+/**
+ * Normalize navigation type with backward compatibility for deprecated replace property
+ */
+function normalizeNavigationType(props: RouterLinkProps): RouterLinkType {
+    if (props.replace) {
+        console.warn(
+            '[RouterLink] The `replace` property is deprecated and will be removed in a future version.\n' +
+                'Please use `type="replace"` instead.\n' +
+                'Before: <RouterLink replace={true} />\n' +
+                'After:  <RouterLink type="replace" />'
+        );
+        return 'replace';
+    }
+    return props.type || 'push';
+}
+
+/**
+ * Get event type list - normalize and validate event types
+ */
+function getEventTypeList(eventType: unknown | unknown[]): string[] {
+    const events = Array.isArray(eventType) ? eventType : [eventType];
+    const validEvents = events
+        .filter((type): type is string => typeof type === 'string')
+        .map((type) => type.trim())
+        .filter(Boolean);
+    return validEvents.length ? validEvents : ['click'];
+}
+
+/**
+ * Event guard check - determines if the router should handle the navigation
+ *
+ * Returns false: Let browser handle default behavior (normal link navigation)
+ * Returns true: Router takes over navigation, prevents default browser behavior
+ *
+ * This function intelligently decides when to let the browser handle clicks
+ * (like Ctrl+click for new tabs) vs when to use SPA routing
+ */
+function guardEvent(e: MouseEvent): boolean {
+    // don't redirect with control keys
+    if (e.metaKey || e.altKey || e.ctrlKey || e.shiftKey) return false;
+    // don't redirect when preventDefault called
+    if (e.defaultPrevented) return false;
+    // don't redirect on right click
+    if (e.button !== undefined && e.button !== 0) return false;
+    // Prevent default browser navigation to enable SPA routing
+    // Note: this may be a Weex event which doesn't have this method
+    if (e.preventDefault) e.preventDefault();
+
+    return true;
+}
+
+/**
+ * Execute route navigation
+ */
+async function executeNavigation(
+    router: Router,
+    props: RouterLinkProps,
+    linkType: RouterLinkType
+): Promise<void> {
+    const { to, layerOptions } = props;
+
+    switch (linkType) {
+        case 'push':
+            await router.push(to);
+            break;
+        case 'replace':
+            await router.replace(to);
+            break;
+        case 'pushWindow':
+            await router.pushWindow(to);
+            break;
+        case 'replaceWindow':
+            await router.replaceWindow(to);
+            break;
+        case 'pushLayer':
+            await router.pushLayer(
+                layerOptions
+                    ? typeof to === 'string'
+                        ? { path: to, layer: layerOptions }
+                        : { ...to, layer: layerOptions }
+                    : to
+            );
+            break;
+        default:
+            await router.push(to);
+    }
+}
+
+/**
+ * Create navigation function
+ */
+function createNavigateFunction(
+    router: Router,
+    props: RouterLinkProps,
+    navigationType: RouterLinkType
+): (e?: MouseEvent) => Promise<void> {
+    return async (e?: MouseEvent): Promise<void> => {
+        if (e && !guardEvent(e)) {
+            return;
+        }
+
+        await executeNavigation(router, props, navigationType);
+    };
+}
+
+/**
+ * Compute HTML attributes
+ */
+function computeAttributes(
+    href: string,
+    navigationType: RouterLinkType,
+    isExternal: boolean,
+    isActive: boolean,
+    isExactActive: boolean,
+    activeClass?: string
+): RouterLinkAttributes {
+    // Only pushWindow opens in a new window, replaceWindow replaces current window
+    const isNewWindow = navigationType === 'pushWindow';
+
+    // Build CSS classes
+    const classes: string[] = [CSS_CLASSES.BASE];
+    if (isActive) {
+        classes.push(activeClass || CSS_CLASSES.ACTIVE);
+    }
+    if (isExactActive) {
+        classes.push(CSS_CLASSES.EXACT_ACTIVE);
+    }
+
+    const attributes: RouterLinkAttributes = {
+        href,
+        class: classes.join(' ')
+    };
+
+    // Set target for new window
+    if (isNewWindow) {
+        attributes.target = '_blank';
+    }
+
+    // Build rel attribute
+    const relParts: string[] = [];
+    if (isNewWindow) {
+        relParts.push('noopener', 'noreferrer');
+    }
+    if (isExternal) {
+        relParts.push('external', 'nofollow');
+    }
+    if (relParts.length > 0) {
+        attributes.rel = relParts.join(' ');
+    }
+
+    return attributes;
+}
+
+/**
+ * Create event handlers generator function
+ */
+function createEventHandlersGenerator(
+    navigate: (e?: MouseEvent) => Promise<void>,
+    eventTypes: string[]
+): (
+    nameTransform?: (eventType: string) => string
+) => Record<string, (e: MouseEvent) => Promise<void>> {
+    return (nameTransform?: (eventType: string) => string) => {
+        const handlers: Record<string, (e: MouseEvent) => Promise<void>> = {};
+
+        eventTypes.forEach((eventType) => {
+            const eventName = nameTransform
+                ? nameTransform(eventType)
+                : eventType.toLowerCase();
+            handlers[eventName] = navigate;
+        });
+
+        return handlers;
+    };
+}
+
+/**
+ * Framework-agnostic link resolver
+ *
+ * @param router Router instance
+ * @param props Link configuration
+ * @returns Resolution result
+ */
+export function createLinkResolver(
+    router: Router,
+    props: RouterLinkProps
+): RouterLinkResolved {
+    const route = router.resolve(props.to);
+    const type = normalizeNavigationType(props);
+    const href = route.url.href;
+
+    const isActive = router.isRouteMatched(route, props.exact);
+    const isExactActive = router.isRouteMatched(route, 'exact');
+    const isExternal = route.url.origin !== router.route.url.origin;
+
+    const navigate = createNavigateFunction(router, props, type);
+
+    const attributes = computeAttributes(
+        href,
+        type,
+        isExternal,
+        isActive,
+        isExactActive,
+        props.activeClass
+    );
+
+    const eventTypes = getEventTypeList(props.event || 'click');
+    const getEventHandlers = createEventHandlersGenerator(navigate, eventTypes);
+
+    return {
+        route,
+        type,
+        isActive,
+        isExactActive,
+        isExternal,
+        tag: props.tag || 'a',
+        attributes,
+        navigate,
+        getEventHandlers
+    };
+}

package/src/router-push.test.ts

@@ -0,0 +1,140 @@
+import { afterEach, beforeEach, describe, expect, test } from 'vitest';
+import { Router } from './router';
+import { RouteType, RouterMode } from './types';
+
+describe('Router Push Tests', () => {
+    let router: Router;
+
+    beforeEach(async () => {
+        router = new Router({
+            mode: RouterMode.memory,
+            base: new URL('http://localhost:3000/'),
+            routes: [
+                { path: '/', component: () => 'Home' },
+                { path: '/user/:id', component: () => 'User' },
+                { path: '/about', component: () => 'About' },
+                {
+                    path: '/async',
+                    asyncComponent: () =>
+                        new Promise((resolve) =>
+                            setTimeout(() => resolve('AsyncComponent'), 10)
+                        )
+                }
+            ]
+        });
+
+        await router.replace('/');
+    });
+
+    afterEach(() => {
+        router.destroy();
+    });
+
+    describe('Basic push navigation', () => {
+        test('should successfully push to new route', async () => {
+            const route = await router.push('/user/123');
+
+            expect(route.path).toBe('/user/123');
+            expect(route.params.id).toBe('123');
+            expect(route.type).toBe(RouteType.push);
+            expect(route.handle).not.toBe(null);
+            expect(router.route.path).toBe('/user/123');
+        });
+
+        test('should handle query parameters in push', async () => {
+            const route = await router.push(
+                '/user/123?tab=profile&active=true'
+            );
+
+            expect(route.params.id).toBe('123');
+            expect(route.query.tab).toBe('profile');
+            expect(route.query.active).toBe('true');
+        });
+
+        test('should handle async component loading', async () => {
+            const route = await router.push('/async');
+
+            expect(route.path).toBe('/async');
+            expect(route.handle).not.toBe(null);
+        });
+    });
+
+    describe('Error handling', () => {
+        test('should throw error for async component loading failure', async () => {
+            const errorRouter = new Router({
+                mode: RouterMode.memory,
+                base: new URL('http://localhost:3000/'),
+                routes: [
+                    { path: '/', component: () => 'Home' },
+                    {
+                        path: '/error',
+                        asyncComponent: () =>
+                            Promise.reject(new Error('Loading failed'))
+                    }
+                ]
+            });
+
+            await errorRouter.replace('/');
+            await expect(errorRouter.push('/error')).rejects.toThrow();
+
+            errorRouter.destroy();
+        });
+
+        test('should throw error when guard prevents navigation', async () => {
+            const guardRouter = new Router({
+                mode: RouterMode.memory,
+                base: new URL('http://localhost:3000/'),
+                routes: [
+                    { path: '/', component: () => 'Home' },
+                    {
+                        path: '/protected',
+                        component: () => 'Protected',
+                        beforeEnter: () => false
+                    }
+                ]
+            });
+
+            await guardRouter.replace('/');
+            await expect(guardRouter.push('/protected')).rejects.toThrow();
+
+            guardRouter.destroy();
+        });
+    });
+
+    describe('Concurrent navigation', () => {
+        test('should handle concurrent push operations', async () => {
+            const promises = [
+                router.push('/user/1').catch((err) => err),
+                router.push('/user/2').catch((err) => err)
+            ];
+
+            const [result1, result2] = await Promise.all(promises);
+
+            const successResults = [result1, result2].filter(
+                (r) => !(r instanceof Error)
+            );
+            const errorResults = [result1, result2].filter(
+                (r) => r instanceof Error
+            );
+
+            expect(successResults).toHaveLength(1);
+            expect(errorResults).toHaveLength(1);
+        });
+    });
+
+    describe('Edge cases', () => {
+        test('should handle push to current route', async () => {
+            await router.push('/about');
+            const route = await router.push('/about');
+
+            expect(route.path).toBe('/about');
+            expect(route.handle).not.toBe(null);
+        });
+
+        test('should handle empty parameter', async () => {
+            const route = await router.push('');
+            expect(route).toBeDefined();
+            expect(typeof route.path).toBe('string');
+        });
+    });
+});

package/src/router-replace.test.ts

@@ -0,0 +1,139 @@
+import { afterEach, beforeEach, describe, expect, test } from 'vitest';
+import { Router } from './router';
+import { RouteType, RouterMode } from './types';
+
+describe('Router Replace Tests', () => {
+    let router: Router;
+
+    beforeEach(async () => {
+        router = new Router({
+            mode: RouterMode.memory,
+            base: new URL('http://localhost:3000/'),
+            routes: [
+                { path: '/', component: () => 'Home' },
+                { path: '/user/:id', component: () => 'User' },
+                { path: '/about', component: () => 'About' },
+                {
+                    path: '/async',
+                    asyncComponent: () =>
+                        new Promise((resolve) =>
+                            setTimeout(() => resolve('AsyncComponent'), 10)
+                        )
+                }
+            ]
+        });
+
+        await router.replace('/');
+    });
+
+    afterEach(() => {
+        router.destroy();
+    });
+
+    describe('Basic replace navigation', () => {
+        test('should successfully replace current route', async () => {
+            await router.push('/about');
+            const route = await router.replace('/user/123');
+
+            expect(route.path).toBe('/user/123');
+            expect(route.params.id).toBe('123');
+            expect(route.type).toBe(RouteType.replace);
+            expect(route.handle).not.toBe(null);
+            expect(router.route.path).toBe('/user/123');
+        });
+
+        test('should handle query parameters in replace', async () => {
+            const route = await router.replace(
+                '/user/123?tab=profile&active=true'
+            );
+
+            expect(route.params.id).toBe('123');
+            expect(route.query.tab).toBe('profile');
+            expect(route.query.active).toBe('true');
+        });
+
+        test('should handle async component loading', async () => {
+            const route = await router.replace('/async');
+
+            expect(route.path).toBe('/async');
+            expect(route.handle).not.toBe(null);
+        });
+    });
+
+    describe('Error handling', () => {
+        test('should throw error for async component loading failure', async () => {
+            const errorRouter = new Router({
+                mode: RouterMode.memory,
+                base: new URL('http://localhost:3000/'),
+                routes: [
+                    { path: '/', component: () => 'Home' },
+                    {
+                        path: '/error',
+                        asyncComponent: () =>
+                            Promise.reject(new Error('Loading failed'))
+                    }
+                ]
+            });
+
+            await errorRouter.replace('/');
+            await expect(errorRouter.replace('/error')).rejects.toThrow();
+
+            errorRouter.destroy();
+        });
+
+        test('should throw error when guard prevents navigation', async () => {
+            const guardRouter = new Router({
+                mode: RouterMode.memory,
+                base: new URL('http://localhost:3000/'),
+                routes: [
+                    { path: '/', component: () => 'Home' },
+                    {
+                        path: '/protected',
+                        component: () => 'Protected',
+                        beforeEnter: () => false
+                    }
+                ]
+            });
+
+            await guardRouter.replace('/');
+            await expect(guardRouter.replace('/protected')).rejects.toThrow();
+
+            guardRouter.destroy();
+        });
+    });
+
+    describe('History management', () => {
+        test('should not create new history entry', async () => {
+            await router.push('/about');
+            await router.replace('/user/123');
+
+            const backRoute = await router.back();
+            expect(backRoute?.path).toBe('/');
+        });
+
+        test('should replace current entry in history', async () => {
+            await router.push('/about');
+            await router.push('/user/456');
+            await router.replace('/user/789');
+
+            const backRoute = await router.back();
+            expect(backRoute?.path).toBe('/about');
+        });
+    });
+
+    describe('Edge cases', () => {
+        test('should handle replace to current route', async () => {
+            await router.push('/about');
+            const route = await router.replace('/about');
+
+            expect(route.path).toBe('/about');
+            expect(route.handle).not.toBe(null);
+        });
+
+        test('should handle empty parameter', async () => {
+            const route = await router.replace('');
+            expect(route).toBeDefined();
+            expect(typeof route.path).toBe('string');
+        });
+    });
+});