@wsxjs/wsx-router 0.0.5

package/src/RouterUtils.ts

@@ -0,0 +1,260 @@
+import { createLogger } from "@wsxjs/wsx-core";
+
+const logger = createLogger("RouterUtils");
+
+/**
+ * 路由信息接口
+ */
+export interface RouteInfo {
+    path: string;
+    params: Record<string, string>;
+    query: Record<string, string>;
+    hash: string;
+    meta?: Record<string, string | number | boolean>;
+}
+
+/**
+ * 路由匹配结果
+ */
+export interface RouteMatch {
+    route: string;
+    params: Record<string, string>;
+    exact: boolean;
+}
+
+/**
+ * 路由工具类 - 提供路由相关的辅助函数
+ */
+export class RouterUtils {
+    /**
+     * 编程式导航
+     */
+    static navigate(path: string, replace = false): void {
+        if (replace) {
+            window.history.replaceState(null, "", path);
+        } else {
+            window.history.pushState(null, "", path);
+        }
+
+        // 触发路由变化事件
+        window.dispatchEvent(new PopStateEvent("popstate"));
+        logger.debug(`Navigated to: ${path} (replace: ${replace})`);
+    }
+
+    /**
+     * 获取当前路由信息
+     */
+    static getCurrentRoute(): RouteInfo {
+        const url = new URL(window.location.href);
+        return {
+            path: url.pathname,
+            params: {}, // 需要路由匹配后才能确定
+            query: Object.fromEntries(url.searchParams.entries()),
+            hash: url.hash.slice(1), // 移除 # 号
+        };
+    }
+
+    /**
+     * 解析路由路径，提取参数
+     */
+    static parseRoute(route: string, path: string): RouteMatch | null {
+        // 精确匹配
+        if (route === path) {
+            return {
+                route,
+                params: {},
+                exact: true,
+            };
+        }
+
+        // 通配符匹配
+        if (route === "*") {
+            return {
+                route,
+                params: {},
+                exact: false,
+            };
+        }
+
+        // 参数匹配
+        if (route.includes(":")) {
+            const paramNames = route.match(/:([^/]+)/g)?.map((p) => p.slice(1)) || [];
+            const pattern = route.replace(/:[^/]+/g, "([^/]+)");
+            const regex = new RegExp(`^${pattern}$`);
+            const matches = path.match(regex);
+
+            if (matches && paramNames.length > 0) {
+                const params: Record<string, string> = {};
+                paramNames.forEach((name, index) => {
+                    params[name] = matches[index + 1];
+                });
+
+                return {
+                    route,
+                    params,
+                    exact: true,
+                };
+            }
+        }
+
+        // 前缀匹配（用于嵌套路由）
+        if (route.endsWith("/*")) {
+            const prefix = route.slice(0, -2);
+            if (path.startsWith(prefix)) {
+                return {
+                    route,
+                    params: {},
+                    exact: false,
+                };
+            }
+        }
+
+        return null;
+    }
+
+    /**
+     * 构建路由路径，替换参数
+     */
+    static buildPath(route: string, params: Record<string, string> = {}): string {
+        let path = route;
+
+        // 替换路径参数
+        Object.entries(params).forEach(([key, value]) => {
+            path = path.replace(`:${key}`, encodeURIComponent(value));
+        });
+
+        return path;
+    }
+
+    /**
+     * 检查路由是否匹配当前路径
+     */
+    static isRouteActive(route: string, exact = false): boolean {
+        const currentPath = window.location.pathname;
+
+        if (exact) {
+            return currentPath === route;
+        }
+
+        // 对于根路径，需要精确匹配
+        if (route === "/") {
+            return currentPath === "/";
+        }
+
+        return currentPath.startsWith(route);
+    }
+
+    /**
+     * 获取路由层级
+     */
+    static getRouteDepth(path: string): number {
+        return path.split("/").filter((segment) => segment.length > 0).length;
+    }
+
+    /**
+     * 获取父级路由
+     */
+    static getParentRoute(path: string): string {
+        const segments = path.split("/").filter((segment) => segment.length > 0);
+        if (segments.length <= 1) {
+            return "/";
+        }
+        segments.pop();
+        return "/" + segments.join("/");
+    }
+
+    /**
+     * 合并路由路径
+     */
+    static joinPaths(...paths: string[]): string {
+        return paths
+            .map((path) => path.replace(/^\/+|\/+$/g, "")) // 移除首尾斜杠
+            .filter((path) => path.length > 0)
+            .join("/")
+            .replace(/^/, "/"); // 添加开头斜杠
+    }
+
+    /**
+     * 检查是否为外部链接
+     */
+    static isExternalUrl(url: string): boolean {
+        return /^https?:\/\//.test(url) || /^mailto:/.test(url) || /^tel:/.test(url);
+    }
+
+    /**
+     * 获取查询参数
+     */
+    static getQueryParam(key: string): string | null {
+        const url = new URL(window.location.href);
+        return url.searchParams.get(key);
+    }
+
+    /**
+     * 设置查询参数
+     */
+    static setQueryParam(key: string, value: string, replace = false): void {
+        const url = new URL(window.location.href);
+        url.searchParams.set(key, value);
+
+        const newUrl = url.pathname + url.search + url.hash;
+        this.navigate(newUrl, replace);
+    }
+
+    /**
+     * 删除查询参数
+     */
+    static removeQueryParam(key: string, replace = false): void {
+        const url = new URL(window.location.href);
+        url.searchParams.delete(key);
+
+        const newUrl = url.pathname + url.search + url.hash;
+        this.navigate(newUrl, replace);
+    }
+
+    /**
+     * 返回上一页
+     */
+    static goBack(): void {
+        window.history.back();
+    }
+
+    /**
+     * 前进一页
+     */
+    static goForward(): void {
+        window.history.forward();
+    }
+
+    /**
+     * 替换当前页面
+     */
+    static replace(path: string): void {
+        this.navigate(path, true);
+    }
+
+    /**
+     * 获取历史记录长度
+     */
+    static getHistoryLength(): number {
+        return window.history.length;
+    }
+
+    /**
+     * 监听路由变化
+     */
+    static onRouteChange(callback: (route: RouteInfo) => void): () => void {
+        const handler = () => {
+            const route = this.getCurrentRoute();
+            callback(route);
+        };
+
+        window.addEventListener("popstate", handler);
+        document.addEventListener("route-changed", handler);
+
+        // 返回清理函数
+        return () => {
+            window.removeEventListener("popstate", handler);
+            document.removeEventListener("route-changed", handler);
+        };
+    }
+}

package/src/WsxLink.css

@@ -0,0 +1,74 @@
+/* WSX Link 基础样式 - 使用 CSS Parts 允许宿主自定义 */
+:host {
+    display: inline-block;
+    min-width: fit-content;
+    min-height: fit-content;
+    width: auto;
+    height: auto;
+}
+
+.wsx-link {
+    color: var(--link-color, #007bff);
+    text-decoration: var(--link-decoration, underline);
+    cursor: pointer;
+    transition: color 0.2s ease;
+    display: inline-block;
+    min-height: 1.2em;
+    line-height: 1.2;
+}
+
+.wsx-link:hover {
+    color: var(--link-hover-color, #0056b3);
+    text-decoration: var(--link-hover-decoration, underline);
+}
+
+.wsx-link:focus {
+    outline: 2px solid var(--link-focus-color, #007bff);
+    outline-offset: 2px;
+}
+
+/* 激活状态 */
+.wsx-link.active {
+    color: var(--link-active-color, #6c757d);
+    font-weight: var(--link-active-weight, bold);
+}
+
+/* 禁用状态 */
+:host([disabled]) .wsx-link {
+    color: var(--link-disabled-color, #6c757d);
+    cursor: not-allowed;
+    pointer-events: none;
+}
+
+/* 外部链接图标 */
+:host([external]) .wsx-link::after {
+    content: "↗";
+    font-size: 0.8em;
+    margin-left: 0.2em;
+    opacity: 0.7;
+}
+
+/* 变体样式 */
+:host([variant="button"]) .wsx-link {
+    background-color: var(--button-bg, #007bff);
+    color: var(--button-color, white);
+    padding: 0.5rem 1rem;
+    border-radius: 0.25rem;
+    text-decoration: none;
+    display: inline-block;
+}
+
+:host([variant="button"]) .wsx-link:hover {
+    background-color: var(--button-hover-bg, #0056b3);
+    color: var(--button-hover-color, white);
+}
+
+:host([variant="tab"]) .wsx-link {
+    padding: 0.5rem 1rem;
+    border-bottom: 2px solid transparent;
+    text-decoration: none;
+}
+
+:host([variant="tab"]) .wsx-link.active {
+    border-bottom-color: var(--tab-active-border, #007bff);
+}

package/src/WsxLink.wsx

@@ -0,0 +1,162 @@
+/** @jsxImportSource @wsxjs/wsx-core */
+import { WebComponent, autoRegister, createLogger } from "@wsxjs/wsx-core";
+import styles from "./WsxLink.css?inline";
+
+const logger = createLogger("WsxLink");
+
+/**
+ * WSX Link - 路由导航链接组件
+ *
+ * 属性：
+ * - to: 目标路径
+ * - replace: 是否替换历史记录（默认 false）
+ * - active-class: 激活状态样式类（默认 'active'）
+ * - exact: 是否精确匹配（默认 false）
+ *
+ * 使用示例：
+ * ```html
+ * <wsx-link to="/users">用户列表</wsx-link>
+ * <wsx-link to="/users/123" active-class="current">用户详情</wsx-link>
+ * <wsx-link to="/settings" replace>设置</wsx-link>
+ * ```
+ */
+@autoRegister({ tagName: "wsx-link" })
+export default class WsxLink extends WebComponent {
+    static observedAttributes = ["to", "replace", "active-class", "exact"];
+
+    private to: string = "";
+    private replace: boolean = false;
+    private activeClass: string = "active";
+    private exact: boolean = false;
+
+    constructor() {
+        super({
+            styles,
+            styleName: "wsx-link",
+        });
+    }
+
+    render() {
+        return (
+            <a href={this.to} class="wsx-link" onClick={this.handleClick} part="link">
+                <slot></slot>
+            </a>
+        );
+    }
+
+    protected onConnected() {
+        // Initialize attributes from HTML when connected
+        this.to = this.getAttribute("to") || "";
+        this.replace = this.hasAttribute("replace");
+        this.activeClass = this.getAttribute("active-class") || "active";
+        this.exact = this.hasAttribute("exact");
+
+        // Update the href of the rendered link
+        const link = this.shadowRoot.querySelector(".wsx-link") as HTMLAnchorElement;
+        if (link) {
+            link.href = this.to;
+        }
+
+        // 监听路由变化以更新激活状态
+        window.addEventListener("popstate", this.updateActiveState);
+        document.addEventListener("route-changed", this.updateActiveState);
+
+        // 初始更新激活状态
+        this.updateActiveState();
+    }
+
+    protected onDisconnected() {
+        window.removeEventListener("popstate", this.updateActiveState);
+        document.removeEventListener("route-changed", this.updateActiveState);
+    }
+
+    protected onAttributeChanged(name: string, _oldValue: string, newValue: string) {
+        switch (name) {
+            case "to":
+                this.to = newValue || "";
+                this.rerender(); // Re-render to update href in JSX
+                this.updateActiveState();
+                break;
+            case "replace":
+                this.replace = newValue !== null && newValue !== "false";
+                break;
+            case "active-class":
+                this.activeClass = newValue || "active";
+                this.updateActiveState();
+                break;
+            case "exact":
+                this.exact = newValue !== null && newValue !== "false";
+                this.updateActiveState();
+                break;
+        }
+    }
+
+    private handleClick = (event: MouseEvent) => {
+        // 防止默认链接行为
+        event.preventDefault();
+
+        if (!this.to) {
+            logger.warn("No 'to' attribute specified");
+            return;
+        }
+
+        // 检查是否为外部链接
+        if (this.isExternalLink(this.to)) {
+            window.open(this.to, "_blank");
+            return;
+        }
+
+        // 使用 History API 进行导航
+        if (this.replace) {
+            window.history.replaceState(null, "", this.to);
+        } else {
+            window.history.pushState(null, "", this.to);
+        }
+
+        // 触发路由变化事件
+        window.dispatchEvent(new PopStateEvent("popstate"));
+
+        logger.debug(`Navigated to: ${this.to}`);
+    };
+
+    private updateActiveState = () => {
+        const currentPath = window.location.pathname;
+        const isActive = this.exact
+            ? currentPath === this.to
+            : currentPath.startsWith(this.to) && this.to !== "/";
+
+        const link = this.shadowRoot?.querySelector("a");
+        if (link) {
+            if (isActive) {
+                link.classList.add(this.activeClass);
+                this.setAttribute("active", "");
+            } else {
+                link.classList.remove(this.activeClass);
+                this.removeAttribute("active");
+            }
+        }
+    };
+
+    private isExternalLink(url: string): boolean {
+        return (
+            url.startsWith("http://") ||
+            url.startsWith("https://") ||
+            url.startsWith("mailto:") ||
+            url.startsWith("tel:")
+        );
+    }
+
+    /**
+     * 编程式导航
+     */
+    public navigate() {
+        if (this.to) {
+            this.handleClick(
+                new MouseEvent("click", {
+                    bubbles: true,
+                    cancelable: true,
+                })
+            );
+        }
+    }
+}

package/src/WsxRouter.css

@@ -0,0 +1,11 @@
+/* WSX Router 样式 */
+:host {
+    display: block;
+    width: 100%;
+    height: 100%;
+}
+
+.router-outlet {
+    width: 100%;
+    height: 100%;
+}

package/src/WsxRouter.wsx

@@ -0,0 +1,180 @@
+/** @jsxImportSource @wsxjs/wsx-core */
+import { WebComponent, autoRegister, createLogger } from "@wsxjs/wsx-core";
+import styles from "./WsxRouter.css?inline";
+
+const logger = createLogger("WsxRouter");
+
+/**
+ * WSX Router - 基于原生 History API 的极简路由
+ *
+ * 设计原则：
+ * - 充分利用 History API 和 URL API
+ * - 不重新发明轮子，只做优雅封装
+ * - 声明式路由配置
+ * - 自动拦截导航
+ *
+ * 使用示例：
+ * ```html
+ * <wsx-router>
+ *   <wsx-view route="/" component="home-page"></wsx-view>
+ *   <wsx-view route="/users/:id" component="user-detail"></wsx-view>
+ *   <wsx-view route="*" component="not-found"></wsx-view>
+ * </wsx-router>
+ * ```
+ */
+@autoRegister({ tagName: "wsx-router" })
+export default class WsxRouter extends WebComponent {
+    private views: Map<string, HTMLElement> = new Map();
+    private currentView: HTMLElement | null = null;
+
+    constructor() {
+        super({ styles });
+    }
+
+    render() {
+        return (
+            <div class="router-outlet">
+                <slot></slot>
+            </div>
+        );
+    }
+
+    protected onConnected() {
+        logger.debug("WsxRouter connected to DOM");
+
+        // 收集所有视图
+        this.collectViews();
+        logger.debug("WsxRouter collected views:", this.views.size);
+
+        // 监听原生 popstate 事件
+        window.addEventListener("popstate", this.handleRouteChange);
+
+        // 拦截所有链接点击，让 History API 接管
+        this.addEventListener("click", this.interceptLinks);
+
+        // 初始路由
+        this.handleRouteChange();
+    }
+
+    protected onDisconnected() {
+        window.removeEventListener("popstate", this.handleRouteChange);
+    }
+
+    private collectViews() {
+        // Get the slot element
+        const slot = this.shadowRoot?.querySelector("slot");
+        if (!slot) {
+            logger.error("WsxRouter: No slot found");
+            return;
+        }
+
+        // Get slotted elements (light DOM children)
+        const slottedElements = slot.assignedElements();
+
+        // Filter for wsx-view elements
+        const views = slottedElements.filter((el) => el.tagName.toLowerCase() === "wsx-view");
+        logger.debug("WsxRouter found views:", views.length);
+
+        views.forEach((view) => {
+            const route = view.getAttribute("route") || "/";
+            this.views.set(route, view as HTMLElement);
+            // 初始隐藏所有视图
+            (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.currentView) {
+            this.currentView.style.display = "none";
+            logger.debug("Hiding previous view");
+        }
+
+        // 查找匹配的视图
+        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));
+            }
+        } else {
+            logger.warn(`No view found for path: ${path}`);
+        }
+
+        // 触发路由变化事件
+        this.dispatchEvent(
+            new CustomEvent("route-changed", {
+                detail: { path, view },
+                bubbles: true,
+                composed: true,
+            })
+        );
+    };
+
+    private matchRoute(path: string): HTMLElement | null {
+        // 精确匹配
+        if (this.views.has(path)) {
+            return this.views.get(path)!;
+        }
+
+        // 参数匹配
+        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;
+                }
+            }
+        }
+
+        // 通配符匹配
+        return this.views.get("*") || null;
+    }
+
+    private extractParams(route: string, path: string): Record<string, string> | null {
+        if (!route.includes(":")) return null;
+
+        const paramNames = route.match(/:([^/]+)/g)?.map((p) => p.slice(1)) || [];
+        const pattern = route.replace(/:[^/]+/g, "([^/]+)");
+        const regex = new RegExp(`^${pattern}$`);
+        const matches = path.match(regex);
+
+        if (!matches || !paramNames.length) return null;
+
+        const params: Record<string, string> = {};
+        paramNames.forEach((name, index) => {
+            params[name] = matches[index + 1];
+        });
+
+        return params;
+    }
+
+    private interceptLinks = (event: MouseEvent) => {
+        const link = (event.target as HTMLElement).closest("a");
+        if (!link) return;
+
+        const href = link.getAttribute("href");
+        if (!href || href.startsWith("http") || href.startsWith("#")) return;
+
+        event.preventDefault();
+        this.navigate(href);
+    };
+
+    /**
+     * 编程式导航 - 使用原生 History API
+     */
+    public navigate(path: string) {
+        window.history.pushState(null, "", path);
+        this.handleRouteChange();
+    }
+}