@wsxjs/wsx-press 0.0.18

package/src/client/components/DocSearch.wsx

@@ -0,0 +1,328 @@
+/**
+ * @jsxImportSource @wsxjs/wsx-core
+ * DocSearch Component
+ *
+ * A search component that uses Fuse.js to search through documentation.
+ * Supports real-time search, result highlighting, and keyboard navigation.
+ */
+
+import { LightComponent, autoRegister, state } from "@wsxjs/wsx-core";
+import { createLogger } from "@wsxjs/wsx-logger";
+import Fuse from "fuse.js";
+import type { SearchIndex, SearchResult, SearchDocument } from "../../types";
+import styles from "./DocSearch.css?inline";
+
+const logger = createLogger("DocSearch");
+
+/**
+ * 搜索索引缓存（全局共享）
+ * 导出以便测试时重置
+ */
+export const searchIndexCache: {
+    data: SearchIndex | null;
+    promise: Promise<SearchIndex> | null;
+} = {
+    data: null,
+    promise: null,
+};
+
+/**
+ * 加载搜索索引（带缓存）
+ */
+async function loadSearchIndex(): Promise<SearchIndex> {
+    // 如果已有缓存，直接返回
+    if (searchIndexCache.data) {
+        return searchIndexCache.data;
+    }
+
+    // 如果正在加载，等待现有请求
+    if (searchIndexCache.promise) {
+        return searchIndexCache.promise;
+    }
+
+    // 创建新的加载请求
+    searchIndexCache.promise = (async () => {
+        try {
+            const response = await fetch("/.wsx-press/search-index.json");
+            if (!response.ok) {
+                throw new Error(`Failed to load search index: ${response.statusText}`);
+            }
+            const data = (await response.json()) as SearchIndex;
+            searchIndexCache.data = data;
+            searchIndexCache.promise = null;
+            return data;
+        } catch (error) {
+            searchIndexCache.promise = null;
+            throw error;
+        }
+    })();
+
+    return searchIndexCache.promise;
+}
+
+/**
+ * DocSearch Component
+ *
+ * Provides real-time search functionality for documentation.
+ */
+@autoRegister({ tagName: "wsx-doc-search" })
+export default class DocSearch extends LightComponent {
+    @state private query: string = "";
+    @state private results: SearchResult[] = [];
+    @state private isOpen: boolean = false;
+    @state private isLoading: boolean = false;
+    @state private selectedIndex: number = -1;
+
+    private fuse: Fuse<SearchDocument> | null = null;
+    private searchTimeout: number | null = null;
+
+    constructor() {
+        super({
+            styles,
+            styleName: "wsx-doc-search",
+        });
+        logger.info("DocSearch initialized");
+    }
+
+    protected async onConnected() {
+        // 预加载搜索索引
+        try {
+            const index = await loadSearchIndex();
+            this.fuse = new Fuse(index.documents, index.options);
+        } catch (error) {
+            logger.error("Failed to load search index", error);
+        }
+    }
+
+    /**
+     * 处理搜索输入
+     */
+    private handleInput = (e: Event) => {
+        const target = e.target as HTMLInputElement;
+        this.query = target.value;
+
+        // 清除之前的定时器
+        if (this.searchTimeout !== null) {
+            clearTimeout(this.searchTimeout);
+        }
+
+        // 如果查询为空，清空结果
+        if (!this.query.trim()) {
+            this.results = [];
+            this.selectedIndex = -1;
+            this.isOpen = false;
+            return;
+        }
+
+        // 延迟搜索（防抖）
+        this.searchTimeout = window.setTimeout(() => {
+            this.performSearch();
+        }, 300);
+    };
+
+    /**
+     * 执行搜索
+     */
+    private async performSearch(): Promise<void> {
+        if (!this.fuse) {
+            // 如果索引未加载，尝试加载
+            try {
+                this.isLoading = true;
+                const index = await loadSearchIndex();
+                this.fuse = new Fuse(index.documents, index.options);
+            } catch (error) {
+                logger.error("Failed to load search index", error);
+                this.isLoading = false;
+                return;
+            }
+        }
+
+        this.isLoading = false;
+
+        if (!this.query.trim()) {
+            this.results = [];
+            this.isOpen = false;
+            return;
+        }
+
+        // 执行搜索
+        const searchResults = this.fuse.search(this.query.trim());
+        this.results = searchResults as SearchResult[];
+        // 如果有查询但没有结果，也要显示"无结果"消息，所以 isOpen 应该为 true
+        this.isOpen = this.query.trim().length > 0;
+        this.selectedIndex = -1;
+    }
+
+    /**
+     * 处理键盘导航
+     */
+    private handleKeyDown = (e: KeyboardEvent) => {
+        if (!this.isOpen || this.results.length === 0) {
+            return;
+        }
+
+        switch (e.key) {
+            case "ArrowDown":
+                e.preventDefault();
+                this.selectedIndex = Math.min(this.selectedIndex + 1, this.results.length - 1);
+                break;
+            case "ArrowUp":
+                e.preventDefault();
+                this.selectedIndex = Math.max(this.selectedIndex - 1, -1);
+                break;
+            case "Enter":
+                e.preventDefault();
+                if (this.selectedIndex >= 0 && this.selectedIndex < this.results.length) {
+                    this.selectResult(this.results[this.selectedIndex]);
+                } else if (this.results.length > 0) {
+                    this.selectResult(this.results[0]);
+                }
+                break;
+            case "Escape":
+                e.preventDefault();
+                this.isOpen = false;
+                this.query = "";
+                this.results = [];
+                this.selectedIndex = -1;
+                break;
+        }
+    };
+
+    /**
+     * 选择搜索结果
+     */
+    private selectResult(result: SearchResult): void {
+        // 触发自定义事件，让父组件处理导航
+        const event = new CustomEvent("doc-search-select", {
+            detail: { route: result.item.route },
+            bubbles: true,
+        });
+        this.dispatchEvent(event);
+
+        // 关闭搜索
+        this.isOpen = false;
+        this.query = "";
+        this.results = [];
+        this.selectedIndex = -1;
+    }
+
+    /**
+     * 高亮匹配文本，返回 JSX 元素数组
+     */
+    private highlightTextNodes(
+        text: string,
+        matches: Array<{ indices: [number, number][] }> | undefined
+    ): (HTMLElement | string)[] {
+        if (!matches || matches.length === 0) {
+            return [text];
+        }
+
+        // 合并所有匹配位置
+        const allIndices: Array<[number, number]> = [];
+        for (const match of matches) {
+            if (match.indices) {
+                allIndices.push(...match.indices);
+            }
+        }
+
+        // 按开始位置排序
+        allIndices.sort((a, b) => a[0] - b[0]);
+
+        // 合并重叠的区间
+        const merged: Array<[number, number]> = [];
+        for (const [start, end] of allIndices) {
+            if (merged.length === 0 || merged[merged.length - 1][1] < start) {
+                merged.push([start, end + 1]);
+            } else {
+                merged[merged.length - 1][1] = Math.max(merged[merged.length - 1][1], end + 1);
+            }
+        }
+
+        // 构建节点数组
+        const nodes: (HTMLElement | string)[] = [];
+        let lastIndex = 0;
+        for (const [start, end] of merged) {
+            // 添加匹配前的文本
+            if (start > lastIndex) {
+                nodes.push(text.substring(lastIndex, start));
+            }
+            // 添加高亮标记
+            const mark = document.createElement("mark");
+            mark.textContent = text.substring(start, end);
+            nodes.push(mark);
+            lastIndex = end;
+        }
+        // 添加剩余文本
+        if (lastIndex < text.length) {
+            nodes.push(text.substring(lastIndex));
+        }
+
+        return nodes;
+    }
+
+    render() {
+        return (
+            <div class="doc-search">
+                <div class="search-input-wrapper">
+                    <input
+                        type="text"
+                        class="search-input"
+                        placeholder="搜索文档..."
+                        value={this.query}
+                        onInput={this.handleInput}
+                        onKeyDown={this.handleKeyDown}
+                        onFocus={() => {
+                            if (this.results.length > 0) {
+                                this.isOpen = true;
+                            }
+                        }}
+                    />
+                    {this.isLoading && <div class="search-loading">加载中...</div>}
+                </div>
+
+                {this.isOpen && this.results.length > 0 && (
+                    <div class="search-results">
+                        {this.results.map((result, index) => {
+                            const isSelected = index === this.selectedIndex;
+                            const titleMatches = result.matches?.find((m) => m.key === "title");
+                            const contentMatches = result.matches?.find((m) => m.key === "content");
+
+                            return (
+                                <div
+                                    key={result.item.id}
+                                    class={`search-result ${isSelected ? "selected" : ""}`}
+                                    onClick={() => this.selectResult(result)}
+                                    onMouseEnter={() => {
+                                        this.selectedIndex = index;
+                                    }}
+                                >
+                                    <div class="result-title">
+                                        {titleMatches
+                                            ? this.highlightTextNodes(result.item.title, [
+                                                  titleMatches,
+                                              ])
+                                            : result.item.title}
+                                    </div>
+                                    <div class="result-category">{result.item.category}</div>
+                                    {contentMatches && (
+                                        <div class="result-snippet">
+                                            {this.highlightTextNodes(
+                                                result.item.content.substring(0, 100),
+                                                [contentMatches]
+                                            )}
+                                        </div>
+                                    )}
+                                </div>
+                            );
+                        })}
+                    </div>
+                )}
+
+                {this.isOpen &&
+                    this.query.trim() &&
+                    this.results.length === 0 &&
+                    !this.isLoading && <div class="search-no-results">未找到匹配的文档</div>}
+            </div>
+        );
+    }
+}

package/src/client/components/DocSidebar.css

@@ -0,0 +1,97 @@
+wsx-doc-sidebar {
+    display: flex;
+    flex-direction: column;
+    width: 280px;
+    min-width: 280px;
+    height: 100%;
+    background: var(--wsx-press-sidebar-bg, #f9fafb);
+    border-right: 1px solid var(--wsx-press-border, #e5e7eb);
+    overflow-y: auto;
+    position: sticky;
+    top: 70px; /* Navigation height */
+    max-height: calc(100vh - 70px);
+}
+
+.doc-sidebar {
+    display: flex;
+    flex-direction: column;
+    width: 100%;
+    height: 100%;
+}
+
+.doc-sidebar-loading,
+.doc-sidebar-empty {
+    padding: 2rem;
+    text-align: center;
+    color: var(--wsx-press-text-secondary, #6b7280);
+}
+
+.doc-sidebar-nav {
+    padding: 1.5rem 0;
+}
+
+.doc-sidebar-category {
+    margin-bottom: 2rem;
+}
+
+.doc-sidebar-category:last-child {
+    margin-bottom: 0;
+}
+
+.doc-sidebar-category-title {
+    font-size: 0.875rem;
+    font-weight: 600;
+    text-transform: uppercase;
+    letter-spacing: 0.05em;
+    color: var(--wsx-press-text-secondary, #6b7280);
+    padding: 0.5rem 1.5rem;
+    margin: 0 0 0.5rem 0;
+}
+
+.doc-sidebar-list {
+    list-style: none;
+    margin: 0;
+    padding: 0;
+}
+
+.doc-sidebar-item {
+    margin: 0;
+}
+
+.doc-sidebar-link {
+    display: block;
+    padding: 0.5rem 1.5rem;
+    color: var(--wsx-press-text-primary, #111827);
+    text-decoration: none;
+    font-size: 0.875rem;
+    line-height: 1.5;
+    transition: all 0.2s ease;
+    border-left: 3px solid transparent;
+}
+
+.doc-sidebar-link:hover {
+    background: var(--wsx-press-sidebar-hover-bg, #f3f4f6);
+    color: var(--wsx-press-text-primary, #111827);
+}
+
+.doc-sidebar-link.active {
+    background: var(--wsx-press-sidebar-active-bg, #eff6ff);
+    color: var(--wsx-press-sidebar-active-color, #2563eb);
+    border-left-color: var(--wsx-press-sidebar-active-color, #2563eb);
+    font-weight: 500;
+}
+
+/* 响应式设计 */
+@media (max-width: 1024px) {
+    wsx-doc-sidebar {
+        width: 240px;
+        min-width: 240px;
+    }
+}
+
+@media (max-width: 768px) {
+    wsx-doc-sidebar {
+        display: none; /* 在移动设备上隐藏侧边栏 */
+    }
+}
+

package/src/client/components/DocSidebar.wsx

@@ -0,0 +1,173 @@
+/**
+ * @jsxImportSource @wsxjs/wsx-core
+ * DocSidebar Component
+ *
+ * Sidebar navigation for documentation pages.
+ * Displays organized documentation menu by category.
+ */
+
+import { LightComponent, autoRegister, state } from "@wsxjs/wsx-core";
+import { createLogger } from "@wsxjs/wsx-logger";
+import { RouterUtils } from "@wsxjs/wsx-router";
+import type { DocMetadata } from "../../types";
+import { metadataCache } from "./DocPage.wsx";
+import styles from "./DocSidebar.css?inline";
+
+const logger = createLogger("DocSidebar");
+
+/**
+ * DocSidebar Component
+ *
+ * Displays a sidebar navigation menu organized by documentation categories.
+ */
+@autoRegister({ tagName: "wsx-doc-sidebar" })
+export default class DocSidebar extends LightComponent {
+    @state private metadata: Record<string, DocMetadata> = {};
+    @state private currentRoute: string = "";
+    @state private isLoading: boolean = true;
+
+    private routeChangeUnsubscribe: (() => void) | null = null;
+
+    constructor() {
+        super({
+            styles,
+            styleName: "wsx-doc-sidebar",
+        });
+    }
+
+    protected async onConnected() {
+        // 加载元数据
+        await this.loadMetadata();
+
+        // 监听路由变化
+        this.routeChangeUnsubscribe = RouterUtils.onRouteChange(() => {
+            this.updateCurrentRoute();
+        });
+
+        // 初始更新当前路由
+        this.updateCurrentRoute();
+    }
+
+    protected onDisconnected() {
+        if (this.routeChangeUnsubscribe) {
+            this.routeChangeUnsubscribe();
+            this.routeChangeUnsubscribe = null;
+        }
+    }
+
+    /**
+     * 加载文档元数据
+     */
+    private async loadMetadata(): Promise<void> {
+        try {
+            this.isLoading = true;
+            if (metadataCache.data) {
+                this.metadata = metadataCache.data;
+            } else {
+                const response = await fetch("/.wsx-press/docs-meta.json");
+                if (response.ok) {
+                    this.metadata = (await response.json()) as Record<string, DocMetadata>;
+                }
+            }
+        } catch (error) {
+            logger.error("Failed to load metadata", error);
+        } finally {
+            this.isLoading = false;
+        }
+    }
+
+    /**
+     * 更新当前路由
+     */
+    private updateCurrentRoute(): void {
+        const routeInfo = RouterUtils.getCurrentRoute();
+        this.currentRoute = routeInfo.path;
+    }
+
+    /**
+     * 按分类组织文档
+     */
+    private organizeByCategory(): Record<string, DocMetadata[]> {
+        const organized: Record<string, DocMetadata[]> = {};
+
+        Object.values(this.metadata).forEach((doc) => {
+            const category = doc.category || "other";
+            if (!organized[category]) {
+                organized[category] = [];
+            }
+            organized[category].push(doc);
+        });
+
+        // 按分类名称排序
+        const sortedCategories = Object.keys(organized).sort();
+
+        // 对每个分类内的文档排序（按标题）
+        sortedCategories.forEach((category) => {
+            organized[category].sort((a, b) => a.title.localeCompare(b.title));
+        });
+
+        return organized;
+    }
+
+    /**
+     * 处理文档链接点击
+     */
+    private handleDocClick = (route: string, e: Event): void => {
+        e.preventDefault();
+        RouterUtils.navigate(route);
+    };
+
+    /**
+     * 检查文档是否为当前文档
+     */
+    private isCurrentDoc(route: string): boolean {
+        return this.currentRoute === route;
+    }
+
+    render() {
+        if (this.isLoading) {
+            return (
+                <aside class="doc-sidebar">
+                    <div class="doc-sidebar-loading">加载中...</div>
+                </aside>
+            );
+        }
+
+        const organized = this.organizeByCategory();
+        const categories = Object.keys(organized);
+
+        if (categories.length === 0) {
+            return (
+                <aside class="doc-sidebar">
+                    <div class="doc-sidebar-empty">暂无文档</div>
+                </aside>
+            );
+        }
+
+        return (
+            <aside class="doc-sidebar">
+                <nav class="doc-sidebar-nav">
+                    {categories.map((category) => (
+                        <div key={category} class="doc-sidebar-category">
+                            <h3 class="doc-sidebar-category-title">{category}</h3>
+                            <ul class="doc-sidebar-list">
+                                {organized[category].map((doc) => (
+                                    <li key={doc.route} class="doc-sidebar-item">
+                                        <a
+                                            href={doc.route}
+                                            class={`doc-sidebar-link ${this.isCurrentDoc(doc.route) ? "active" : ""}`}
+                                            onClick={(e) => this.handleDocClick(doc.route, e)}
+                                        >
+                                            {doc.title}
+                                        </a>
+                                    </li>
+                                ))}
+                            </ul>
+                        </div>
+                    ))}
+                </nav>
+            </aside>
+        );
+    }
+}
+

package/src/client/components/DocTOC.css

@@ -0,0 +1,105 @@
+wsx-doc-toc {
+    display: flex;
+    flex-direction: column;
+    width: 240px;
+    min-width: 240px;
+    height: 100%;
+    overflow-y: auto;
+    position: sticky;
+    top: 70px; /* Navigation height */
+    max-height: calc(100vh - 70px);
+}
+
+.doc-toc {
+    display: flex;
+    flex-direction: column;
+    width: 100%;
+    padding: 1.5rem 1rem;
+}
+
+.doc-toc-empty {
+    padding: 1rem;
+    text-align: center;
+    color: var(--wsx-press-text-secondary, #6b7280);
+    font-size: 0.875rem;
+}
+
+.doc-toc-title {
+    font-size: 0.875rem;
+    font-weight: 600;
+    text-transform: uppercase;
+    letter-spacing: 0.05em;
+    color: var(--wsx-press-text-secondary, #6b7280);
+    margin: 0 0 1rem 0;
+    padding: 0;
+}
+
+.doc-toc-nav {
+    width: 100%;
+}
+
+.doc-toc-list {
+    list-style: none;
+    margin: 0;
+    padding: 0;
+}
+
+.doc-toc-sublist {
+    margin-top: 0.25rem;
+    padding-left: 1rem;
+}
+
+.doc-toc-item {
+    margin: 0;
+    line-height: 1.6;
+}
+
+.doc-toc-item-level-1 {
+    margin-bottom: 0.5rem;
+}
+
+.doc-toc-item-level-2 {
+    margin-bottom: 0.375rem;
+    font-size: 0.875rem;
+}
+
+.doc-toc-item-level-3 {
+    margin-bottom: 0.25rem;
+    font-size: 0.8125rem;
+}
+
+.doc-toc-item-level-4,
+.doc-toc-item-level-5,
+.doc-toc-item-level-6 {
+    margin-bottom: 0.25rem;
+    font-size: 0.75rem;
+}
+
+.doc-toc-link {
+    display: block;
+    color: var(--wsx-press-text-secondary, #6b7280);
+    text-decoration: none;
+    transition: color 0.2s ease;
+    padding: 0.25rem 0;
+    border-left: 2px solid transparent;
+    padding-left: 0.5rem;
+    margin-left: -0.5rem;
+}
+
+.doc-toc-link:hover {
+    color: var(--wsx-press-text-primary, #111827);
+}
+
+.doc-toc-link.active {
+    color: var(--wsx-press-toc-active-color, #2563eb);
+    border-left-color: var(--wsx-press-toc-active-color, #2563eb);
+    font-weight: 500;
+}
+
+/* 响应式设计 */
+@media (max-width: 1280px) {
+    wsx-doc-toc {
+        display: none; /* 在较小屏幕上隐藏 TOC */
+    }
+}
+