@wsxjs/wsx-router 0.0.16 → 0.0.18

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@wsxjs/wsx-router",
-  "version": "0.0.16",
-  "description": "WSX Router - Native History API-based routing for WSX Framework",
+  "version": "0.0.18",
+  "description": "WSX Router - Native History API-based routing for WSXJS",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
@@ -18,7 +18,8 @@
     "!**/test"
   ],
   "dependencies": {
-    "@wsxjs/wsx-core": "0.0.16"
+    "@wsxjs/wsx-core": "0.0.18",
+    "@wsxjs/wsx-logger": "0.0.18"
   },
   "devDependencies": {
     "@typescript-eslint/eslint-plugin": "^8.37.0",
@@ -30,8 +31,8 @@
     "typescript": "^5.0.0",
     "vite": "^5.4.19",
     "vitest": "^2.1.8",
-    "@wsxjs/eslint-plugin-wsx": "0.0.16",
-    "@wsxjs/wsx-vite-plugin": "0.0.16"
+    "@wsxjs/eslint-plugin-wsx": "0.0.18",
+    "@wsxjs/wsx-vite-plugin": "0.0.18"
   },
   "keywords": [
     "wsx",
@@ -41,7 +42,7 @@
     "navigation",
     "spa"
   ],
-  "author": "WSX Framework Team",
+  "author": "WSXJS Team",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -56,7 +57,8 @@
     "build:dev": "NODE_ENV=development vite build",
     "dev": "NODE_ENV=development vite build --watch",
     "clean": "rm -rf dist",
-    "test": "vitest",
+    "test": "vitest --run",
+    "test:watch": "vitest",
     "test:ui": "vitest --ui",
     "test:coverage": "vitest --coverage",
     "typecheck": "tsc --noEmit",

package/src/RouterUtils.ts

@@ -1,4 +1,4 @@
-import { createLogger } from "@wsxjs/wsx-core";
+import { createLogger } from "@wsxjs/wsx-logger";
 
 const logger = createLogger("RouterUtils");
 
@@ -26,6 +26,20 @@ export interface RouteMatch {
  * 路由工具类 - 提供路由相关的辅助函数
  */
 export class RouterUtils {
+    /**
+     * 当前路由信息（由 WsxRouter 维护）
+     * @internal
+     */
+    private static _currentRoute: RouteInfo | null = null;
+
+    /**
+     * 设置当前路由信息（由 WsxRouter 内部调用）
+     * @internal
+     */
+    static _setCurrentRoute(routeInfo: RouteInfo): void {
+        RouterUtils._currentRoute = routeInfo;
+    }
+
     /**
      * 编程式导航
      */
@@ -43,12 +57,20 @@ export class RouterUtils {
 
     /**
      * 获取当前路由信息
+     * 如果路由已匹配（由 WsxRouter 维护），则返回包含参数的路由信息
+     * 否则返回基础路由信息（参数为空对象）
      */
     static getCurrentRoute(): RouteInfo {
+        // 如果 WsxRouter 已经维护了当前路由信息，直接返回
+        if (RouterUtils._currentRoute) {
+            return RouterUtils._currentRoute;
+        }
+
+        // 否则返回基础路由信息（向后兼容）
         const url = new URL(window.location.href);
         return {
             path: url.pathname,
-            params: {}, // 需要路由匹配后才能确定
+            params: {},
             query: Object.fromEntries(url.searchParams.entries()),
             hash: url.hash.slice(1), // 移除 # 号
         };
@@ -241,6 +263,14 @@ export class RouterUtils {
 
     /**
      * 监听路由变化
+     *
+     * 只监听 route-changed 事件，该事件在 RouterUtils._setCurrentRoute() 之后触发。
+     * 不监听 popstate 事件，因为：
+     * 1. WsxRouter 已经监听 popstate 并会触发 route-changed
+     * 2. 同时监听两个事件会导致回调被调用两次，产生竞态条件
+     * 3. popstate 触发时 RouterUtils._currentRoute 可能还未更新
+     *
+     * @see RFC-0035: 路由导航竞态条件修复
      */
     static onRouteChange(callback: (route: RouteInfo) => void): () => void {
         const handler = () => {
@@ -248,12 +278,12 @@ export class RouterUtils {
             callback(route);
         };
 
-        window.addEventListener("popstate", handler);
+        // 只监听 route-changed 事件
+        // 该事件由 WsxRouter 在更新 RouterUtils._currentRoute 之后触发
         document.addEventListener("route-changed", handler);
 
         // 返回清理函数
         return () => {
-            window.removeEventListener("popstate", handler);
             document.removeEventListener("route-changed", handler);
         };
     }

package/src/WsxLink.css

@@ -23,7 +23,7 @@
 }
 
 .wsx-link:focus {
-    outline: 2px solid var(--link-focus-color, #007bff);
+    outline: 2px solid var(--link-focus-color, var(--focus-color, #dc2626));
     outline-offset: 2px;
 }
 

package/src/WsxLink.wsx

@@ -1,5 +1,6 @@
 /** @jsxImportSource @wsxjs/wsx-core */
-import { WebComponent, autoRegister, createLogger, state } from "@wsxjs/wsx-core";
+import { WebComponent, autoRegister, state } from "@wsxjs/wsx-core";
+import { createLogger } from "@wsxjs/wsx-logger";
 
 const logger = createLogger("WsxLink");
 

package/src/WsxRouter.css

@@ -1,11 +1,14 @@
 /* WSX Router 样式 */
 :host {
-    display: block;
+    display: grid;
     width: 100%;
-    height: 100%;
 }
 
 .router-outlet {
     width: 100%;
-    height: 100%;
+}
+
+/* 关键修复：使用 CSS Grid 让所有视图重叠在同一个 grid cell，防止页面高度闪烁 */
+:host > wsx-view {
+    grid-area: 1 / 1;
 }

package/src/WsxRouter.wsx

@@ -1,5 +1,7 @@
 /** @jsxImportSource @wsxjs/wsx-core */
-import { LightComponent, autoRegister, createLogger } from "@wsxjs/wsx-core";
+import { LightComponent, autoRegister } from "@wsxjs/wsx-core";
+import { createLogger } from "@wsxjs/wsx-logger";
+import { RouterUtils, type RouteInfo } from "./RouterUtils";
 import styles from "./WsxRouter.css?inline";
 
 const logger = createLogger("WsxRouter");
@@ -26,6 +28,14 @@ const logger = createLogger("WsxRouter");
 export default class WsxRouter extends LightComponent {
     private views: Map<string, HTMLElement> = new Map();
     private currentView: HTMLElement | null = null;
+    private currentPath: string = "";
+    private isHandlingRoute: boolean = false; // 防止递归调用的标志
+    // RFC 0032: 路由匹配优化 - 缓存预编译的正则表达式和匹配结果
+    private compiledRoutes: Map<string, RegExp> = new Map();
+    private matchCache: Map<string, string> = new Map();
+    // RFC 0033: 现代路由特性
+    private enableViewTransitions: boolean = true;
+    private scrollRestoration: "auto" | "manual" = "manual";
 
     constructor() {
         super({
@@ -42,12 +52,30 @@ export default class WsxRouter extends LightComponent {
         );
     }
 
+    protected onRendered() {
+        // 在渲染完成后也收集视图和处理路由（作为备用）
+        // 注意：onRendered 可能不会被调用（如果 hasActualContent 为 true）
+        // 所以主要逻辑在 onConnected() 中
+        if (this.views.size === 0) {
+            this.collectViews();
+            logger.debug("WsxRouter collected views in onRendered:", this.views.size);
+        }
+
+        // 如果视图已收集但还没有处理路由，现在处理
+        if (this.views.size > 0 && !this.currentView) {
+            requestAnimationFrame(() => {
+                this.handleRouteChange();
+            });
+        }
+    }
+
     protected onConnected() {
         logger.debug("WsxRouter connected to DOM");
 
-        // 收集所有视图
-        this.collectViews();
-        logger.debug("WsxRouter collected views:", this.views.size);
+        // RFC 0033: 设置浏览器滚动恢复模式
+        if ("scrollRestoration" in history) {
+            history.scrollRestoration = this.scrollRestoration;
+        }
 
         // 监听原生 popstate 事件
         window.addEventListener("popstate", this.handleRouteChange);
@@ -55,8 +83,23 @@ export default class WsxRouter extends LightComponent {
         // 拦截所有链接点击，让 History API 接管
         this.addEventListener("click", this.interceptLinks);
 
-        // 初始路由
-        this.handleRouteChange();
+        // 关键修复：在 onConnected() 中也收集视图和处理初始路由
+        // 因为 onRendered() 可能不会被调用（如果 hasActualContent 为 true）
+        // 这解决了页面刷新时路由无法恢复的问题
+        requestAnimationFrame(() => {
+            // 收集视图（如果还没有收集）
+            if (this.views.size === 0) {
+                this.collectViews();
+                logger.debug(`WsxRouter collected views in onConnected: ${this.views.size}`);
+            }
+
+            // 处理初始路由（页面刷新时）
+            // 使用双重 requestAnimationFrame 确保所有子元素都已连接
+            requestAnimationFrame(() => {
+                logger.debug(`WsxRouter handling initial route: ${window.location.pathname}`);
+                this.handleRouteChange();
+            });
+        });
     }
 
     protected onDisconnected() {
@@ -68,72 +111,292 @@ export default class WsxRouter extends LightComponent {
         const views = Array.from(this.children).filter(
             (el) => el.tagName.toLowerCase() === "wsx-view"
         );
-        logger.debug("WsxRouter found views:", views.length);
+        logger.debug(`WsxRouter found ${views.length} views`);
+
+        // RFC 0032: 清除旧的缓存
+        this.views.clear();
+        this.compiledRoutes.clear();
+        this.matchCache.clear();
 
         views.forEach((view) => {
             const route = view.getAttribute("route") || "/";
             this.views.set(route, view as HTMLElement);
-            // 初始隐藏所有视图
+            logger.debug(`WsxRouter registered route: ${route}`);
+
+            // RFC 0032: 预编译参数路由的正则表达式
+            if (route.includes(":")) {
+                const pattern = route.replace(/:[^/]+/g, "([^/]+)");
+                const regex = new RegExp(`^${pattern}$`);
+                this.compiledRoutes.set(route, regex);
+                logger.debug(`WsxRouter compiled regex for route: ${route} -> ${regex}`);
+            }
+
+            // 初始状态：隐藏所有视图，等待路由匹配后再显示
+            // 这样可以确保路由遵循实际 URL，不会默认显示 home
             (view as HTMLElement).style.display = "none";
-            logger.debug(`WsxRouter hiding view for route: ${route}`);
         });
     }
 
     private handleRouteChange = () => {
-        const path = window.location.pathname;
-        logger.debug(`Route changed to: ${path}`);
+        // 防止递归调用
+        if (this.isHandlingRoute) {
+            logger.debug("Route change already in progress, skipping");
+            return;
+        }
+
+        // 如果视图为空，重新收集（可能子元素还未渲染）
+        if (this.views.size === 0) {
+            this.collectViews();
+            logger.debug(`WsxRouter re-collected views: ${this.views.size}`);
+        }
+
+        this.isHandlingRoute = true;
 
-        // 隐藏当前视图
-        if (this.currentView) {
-            this.currentView.style.display = "none";
-            logger.debug("Hiding previous view");
+        try {
+            const nextPath = window.location.pathname;
+            logger.debug(`WsxRouter: Route changed to: ${nextPath}`);
+
+            // RFC 0033: 1. 触发 before-navigate 事件（可取消）
+            const beforeEvent = new CustomEvent("before-navigate", {
+                detail: {
+                    to: nextPath,
+                    from: this.currentPath,
+                },
+                bubbles: true,
+                cancelable: true,
+            });
+
+            if (!this.dispatchEvent(beforeEvent)) {
+                // 事件被取消，阻止导航
+                logger.debug(`Navigation to ${nextPath} was cancelled`);
+                return;
+            }
+
+            // RFC 0033: 2. 执行导航（可能带 View Transition）
+            this.performNavigation(nextPath);
+        } finally {
+            // 延迟重置标志，确保所有异步操作完成
+            requestAnimationFrame(() => {
+                this.isHandlingRoute = false;
+            });
         }
+    };
 
-        // 查找匹配的视图
-        const view = this.matchRoute(path);
-        if (view) {
-            view.style.display = "block";
-            this.currentView = view;
-            logger.debug(`Showing view for route: ${view.getAttribute("route")}`);
-
-            // 传递路由参数
-            const params = this.extractParams(view.getAttribute("route") || "/", path);
-            if (params) {
-                view.setAttribute("params", JSON.stringify(params));
+    /**
+     * RFC 0033: 执行导航（带 View Transitions 支持）
+     */
+    private performNavigation(nextPath: string): void {
+        const performTransition = () => {
+            // 查找匹配的视图
+            const view = this.matchRoute(nextPath);
+
+            if (view) {
+                // 关键修复：先显示新视图，再隐藏其他所有视图
+                // 这样可以确保页面始终有内容，防止页脚跳动
+                // Step 1: 立即显示新视图
+                view.style.display = "block";
+                view.style.visibility = "visible";
+                const viewRoute = view.getAttribute("route") || "/";
+                logger.debug(`Showing view for route: ${viewRoute}`);
+
+                // Step 2: 隐藏所有其他视图（包括旧的 currentView）
+                for (const [_route, otherView] of this.views) {
+                    if (otherView !== view) {
+                        otherView.style.display = "none";
+                        otherView.style.visibility = "";
+                    }
+                }
+
+                // Step 3: 更新 currentView
+                this.currentView = view;
+
+                // 传递路由参数（延迟设置，避免触发 attributeChangedCallback 导致递归）
+                const params = this.extractParams(viewRoute, nextPath);
+                logger.debug(
+                    `Extracted params for route ${viewRoute} and path ${nextPath}:`,
+                    params
+                );
+                if (params) {
+                    requestAnimationFrame(() => {
+                        view.setAttribute("params", JSON.stringify(params));
+                        logger.debug(`Set params attribute on view: ${JSON.stringify(params)}`);
+                    });
+                }
+
+                // RFC-0035: 立即更新 RouterUtils，确保 getCurrentRoute() 返回最新信息
+                // 在显示视图之后、触发事件之前更新，确保时序正确
+                const href =
+                    window.location.href ||
+                    `${window.location.pathname}${window.location.search}${window.location.hash}`;
+                const url = new URL(href, window.location.origin || "http://localhost");
+                const routeInfo: RouteInfo = {
+                    path: nextPath,
+                    params: params || {},
+                    query: Object.fromEntries(url.searchParams.entries()),
+                    hash: url.hash.slice(1),
+                };
+                RouterUtils._setCurrentRoute(routeInfo);
+                logger.debug(`Updated RouterUtils._currentRoute:`, routeInfo);
+
+                // RFC-0035: 触发 route-changed 事件，通知 RouterUtils.onRouteChange() 监听器
+                // 在 document 上触发，确保所有监听器都能收到
+                const routeChangedEvent = new CustomEvent("route-changed", {
+                    detail: routeInfo,
+                    bubbles: true,
+                });
+                document.dispatchEvent(routeChangedEvent);
+            } else {
+                // 如果没有找到视图，隐藏所有视图
+                for (const [_route, otherView] of this.views) {
+                    otherView.style.display = "none";
+                }
+                this.currentView = null;
+                logger.warn(`No view found for path: ${nextPath}`);
+
+                // 更新 RouterUtils 中的全局路由信息（无参数）
+                const href =
+                    window.location.href ||
+                    `${window.location.pathname}${window.location.search}${window.location.hash}`;
+                const url = new URL(href, window.location.origin || "http://localhost");
+                const routeInfo: RouteInfo = {
+                    path: nextPath,
+                    params: {},
+                    query: Object.fromEntries(url.searchParams.entries()),
+                    hash: url.hash.slice(1),
+                };
+                RouterUtils._setCurrentRoute(routeInfo);
+
+                // RFC-0035: 同样需要触发 route-changed 事件
+                const routeChangedEvent = new CustomEvent("route-changed", {
+                    detail: routeInfo,
+                    bubbles: true,
+                });
+                document.dispatchEvent(routeChangedEvent);
             }
+
+            // RFC 0033: 滚动管理
+            this.handleScrollRestoration(nextPath);
+
+            // RFC 0033: 触发 after-navigate 事件
+            this.dispatchEvent(
+                new CustomEvent("after-navigate", {
+                    detail: {
+                        to: nextPath,
+                        from: this.currentPath,
+                    },
+                    bubbles: true,
+                })
+            );
+
+            // RFC-0035: 移除旧的 route-changed 事件触发
+            // 原因：已在 document 上触发 route-changed 事件（第244行）
+            // 如果在 WsxRouter 元素上再次触发，会因为 bubbles: true 导致
+            // document 上的监听器收到两次事件，产生竞态条件
+
+            // 更新当前路径
+            this.currentPath = nextPath;
+        };
+
+        // RFC 0033: View Transitions API（渐进增强）
+        if (this.enableViewTransitions && "startViewTransition" in document) {
+            (
+                document as Document & { startViewTransition: (callback: () => void) => void }
+            ).startViewTransition(performTransition);
         } else {
-            logger.warn(`No view found for path: ${path}`);
+            performTransition();
         }
+    }
 
-        // 触发路由变化事件
-        this.dispatchEvent(
-            new CustomEvent("route-changed", {
-                detail: { path, view },
-                bubbles: true,
-                composed: true,
-            })
-        );
-    };
+    /**
+     * RFC 0033: 滚动恢复处理
+     */
+    private handleScrollRestoration(_nextPath: string): void {
+        if (this.scrollRestoration === "manual") {
+            // 判断是否是后退导航
+            const isBackNavigation = this.isBackNavigation();
+
+            if (!isBackNavigation) {
+                // 前进导航：滚动到顶部
+                window.scrollTo(0, 0);
+                logger.debug("Scrolled to top for forward navigation");
+            }
+            // 后退导航：浏览器自动恢复滚动位置
+        }
+        // scrollRestoration === 'auto' 时，完全交给浏览器处理
+    }
+
+    /**
+     * RFC 0033: 检测是否是后退导航
+     */
+    private isBackNavigation(): boolean {
+        // 通过 performance.navigation API 检测（已废弃但仍可用）
+        if (
+            "navigation" in performance &&
+            (performance as Performance & { navigation: { type: number } }).navigation
+        ) {
+            const nav = (performance as Performance & { navigation: { type: number } }).navigation;
+            return nav.type === 2; // TYPE_BACK_FORWARD
+        }
+
+        // 降级方案：检查 history.state
+        if (window.history.state?.navigationType === "back") {
+            return true;
+        }
+
+        return false;
+    }
 
     private matchRoute(path: string): HTMLElement | null {
-        // 精确匹配
+        logger.warn(`matchRoute called for path: ${path}, views count: ${this.views.size}`);
+
+        // RFC 0032: 1. 检查匹配缓存
+        if (this.matchCache.has(path)) {
+            const route = this.matchCache.get(path)!;
+            logger.warn(`matchRoute: found in cache, route: ${route}`);
+            return this.views.get(route) || null;
+        }
+
+        // RFC 0032: 2. 精确匹配
         if (this.views.has(path)) {
+            this.matchCache.set(path, path);
+            logger.warn(`matchRoute: exact match found for ${path}`);
             return this.views.get(path)!;
         }
 
-        // 参数匹配
+        // RFC 0032: 3. 参数匹配（使用预编译的正则表达式）
+        logger.warn(
+            `matchRoute: checking parameter routes, compiledRoutes count: ${this.compiledRoutes.size}`
+        );
         for (const [route, view] of this.views) {
             if (route.includes(":")) {
-                const pattern = route.replace(/:[^/]+/g, "([^/]+)");
-                const regex = new RegExp(`^${pattern}$`);
-                if (regex.test(path)) {
-                    return view;
+                const regex = this.compiledRoutes.get(route);
+                if (regex) {
+                    const matches = regex.test(path);
+                    logger.warn(
+                        `matchRoute: testing route ${route} against ${path}, matches: ${matches}`
+                    );
+                    if (matches) {
+                        this.matchCache.set(path, route);
+                        logger.warn(
+                            `matchRoute: parameter match found, route: ${route}, path: ${path}`
+                        );
+                        return view;
+                    }
+                } else {
+                    logger.warn(`matchRoute: route ${route} has ':' but no compiled regex found`);
                 }
             }
         }
 
-        // 通配符匹配
-        return this.views.get("*") || null;
+        // RFC 0032: 4. 通配符匹配
+        const wildcardView = this.views.get("*") || null;
+        if (wildcardView) {
+            this.matchCache.set(path, "*");
+            logger.warn(`matchRoute: wildcard match found for ${path}`);
+        } else {
+            logger.warn(`matchRoute: no match found for ${path}, no wildcard view available`);
+        }
+        return wildcardView;
     }
 
     private extractParams(route: string, path: string): Record<string, string> | null {
@@ -165,6 +428,34 @@ export default class WsxRouter extends LightComponent {
         this.navigate(href);
     };
 
+    /**
+     * RFC 0032: 清除匹配缓存
+     * 当路由配置变更时调用，确保使用最新的路由规则
+     */
+    private clearMatchCache(): void {
+        this.matchCache.clear();
+        logger.debug("WsxRouter cleared match cache");
+    }
+
+    /**
+     * RFC 0033: 配置 View Transitions
+     */
+    public setViewTransitions(enabled: boolean): void {
+        this.enableViewTransitions = enabled;
+        logger.debug(`View Transitions ${enabled ? "enabled" : "disabled"}`);
+    }
+
+    /**
+     * RFC 0033: 配置 Scroll Restoration
+     */
+    public setScrollRestoration(mode: "auto" | "manual"): void {
+        this.scrollRestoration = mode;
+        if ("scrollRestoration" in history) {
+            history.scrollRestoration = mode;
+        }
+        logger.debug(`Scroll Restoration set to ${mode}`);
+    }
+
     /**
      * 编程式导航 - 使用原生 History API
      */