node-resource-utils 0.0.0-stage → 1.1.8

package/resources/src/components/docs/DocsSearch.tsx

@@ -0,0 +1,365 @@
+'use client';
+
+import {
+  createContext,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ReactNode,
+} from 'react';
+import { useRouter } from 'next/navigation';
+import { Input, Modal, Spin, type InputRef } from 'antd';
+import {
+  ArrowRightOutlined,
+  FileTextOutlined,
+  SearchOutlined,
+} from '@ant-design/icons';
+import { docHref, type DocNav, type DocNavPage, type DocSearchHit } from '@/lib/docs-shared';
+
+/**
+ * 文档站搜索。
+ *
+ * 三层结构：
+ *   DocsSearchProvider —— 弹窗、快捷键、请求与键盘导航都在这里，只实现一次
+ *   useDocsSearch()    —— 任何子组件都能打开搜索（顶栏、首页大搜索框共用）
+ *   DocsSearchLauncher —— 两种外观：顶栏紧凑版、首页大号版
+ *
+ * 搜索走 `/api/docs/search`，前端不做全量索引：文档多了也不会把
+ * 整站正文塞进首屏 HTML。请求带 180ms 防抖与 AbortController，
+ * 快速输入时旧结果不会覆盖新结果。
+ */
+
+type SearchContextValue = { openSearch: () => void };
+
+const SearchContext = createContext<SearchContextValue | null>(null);
+
+export function useDocsSearch(): SearchContextValue {
+  return useContext(SearchContext) ?? { openSearch: () => undefined };
+}
+
+function collectPages(nav: DocNav): { page: DocNavPage; groupTitle: string }[] {
+  const out: { page: DocNavPage; groupTitle: string }[] = [];
+
+  const walk = (sections: DocNav['sections'], trail: string[]) => {
+    for (const section of sections) {
+      if (section.type === 'page') {
+        out.push({ page: section, groupTitle: trail.join(' / ') });
+        continue;
+      }
+      const nextTrail = [...trail, section.title];
+      for (const page of section.pages) out.push({ page, groupTitle: nextTrail.join(' / ') });
+      for (const child of section.groups) walk([{ type: 'group', ...child }], nextTrail);
+    }
+  };
+
+  walk(nav.sections, []);
+  return out;
+}
+
+function tokenize(q: string): string[] {
+  return q
+    .toLowerCase()
+    .split(/[\s,，、/]+/)
+    .map((t) => t.trim())
+    .filter(Boolean);
+}
+
+function highlight(text: string, tokens: string[]): ReactNode {
+  if (!tokens.length) return text;
+  const lower = text.toLowerCase();
+  const ranges: [number, number][] = [];
+  for (const t of tokens) {
+    let from = 0;
+    for (;;) {
+      const i = lower.indexOf(t, from);
+      if (i < 0) break;
+      ranges.push([i, i + t.length]);
+      from = i + t.length;
+    }
+  }
+  if (!ranges.length) return text;
+
+  ranges.sort((a, b) => a[0] - b[0]);
+  const merged: [number, number][] = [];
+  for (const r of ranges) {
+    const last = merged[merged.length - 1];
+    if (last && r[0] <= last[1]) last[1] = Math.max(last[1], r[1]);
+    else merged.push([...r]);
+  }
+
+  const out: ReactNode[] = [];
+  let pos = 0;
+  merged.forEach(([s, e], i) => {
+    if (s > pos) out.push(text.slice(pos, s));
+    out.push(
+      <mark key={i} className="wb-docs-search-mark">
+        {text.slice(s, e)}
+      </mark>
+    );
+    pos = e;
+  });
+  if (pos < text.length) out.push(text.slice(pos));
+  return out;
+}
+
+export default function DocsSearchProvider({
+  nav,
+  children,
+}: {
+  nav: DocNav;
+  children: ReactNode;
+}) {
+  const router = useRouter();
+  const [open, setOpen] = useState(false);
+  const [query, setQuery] = useState('');
+  const [items, setItems] = useState<DocSearchHit[]>([]);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState('');
+  const [active, setActive] = useState(0);
+  const inputRef = useRef<InputRef>(null);
+  const listRef = useRef<HTMLDivElement>(null);
+
+  const tokens = useMemo(() => tokenize(query), [query]);
+  const quick = useMemo(() => collectPages(nav).slice(0, 6), [nav]);
+  const q = query.trim();
+
+  /* ------------------------------ 快捷键 ------------------------------ */
+  useEffect(() => {
+    const onKey = (e: KeyboardEvent) => {
+      if ((e.ctrlKey || e.metaKey) && e.key.toLowerCase() === 'k') {
+        e.preventDefault();
+        setOpen((v) => !v);
+      }
+    };
+    window.addEventListener('keydown', onKey);
+    return () => window.removeEventListener('keydown', onKey);
+  }, []);
+
+  /* ------------------------------ 打开 / 关闭 ------------------------------ */
+  useEffect(() => {
+    if (!open) return;
+    const timer = window.setTimeout(() => inputRef.current?.focus(), 80);
+    return () => window.clearTimeout(timer);
+  }, [open]);
+
+  useEffect(() => {
+    if (open) return;
+    setQuery('');
+    setItems([]);
+    setError('');
+    setLoading(false);
+    setActive(0);
+  }, [open]);
+
+  /* ------------------------------ 搜索请求 ------------------------------ */
+  useEffect(() => {
+    if (!open) return;
+    if (!q) {
+      setItems([]);
+      setLoading(false);
+      setError('');
+      return;
+    }
+
+    setLoading(true);
+    setError('');
+    // 立刻清空旧结果：否则新关键词还没返回时，按 Enter 会打开上一轮的结果
+    setItems([]);
+    const ctrl = new AbortController();
+    const timer = window.setTimeout(async () => {
+      try {
+        const res = await fetch(`/api/docs/search?q=${encodeURIComponent(q)}&limit=12`, {
+          signal: ctrl.signal,
+          cache: 'no-store',
+        });
+        const json = (await res.json()) as {
+          code?: number;
+          data?: { items?: DocSearchHit[] };
+          message?: string;
+        };
+        if (ctrl.signal.aborted) return;
+        if (json.code === 0) setItems(json.data?.items ?? []);
+        else {
+          setItems([]);
+          setError(json.message || '搜索暂时不可用');
+        }
+      } catch {
+        if (!ctrl.signal.aborted) {
+          setItems([]);
+          setError('搜索暂时不可用，请稍后再试');
+        }
+      } finally {
+        if (!ctrl.signal.aborted) setLoading(false);
+      }
+    }, 180);
+
+    return () => {
+      window.clearTimeout(timer);
+      ctrl.abort();
+    };
+  }, [q, open]);
+
+  useEffect(() => {
+    setActive(0);
+  }, [q, items]);
+
+  useEffect(() => {
+    if (!open) return;
+    const el = listRef.current?.querySelector<HTMLElement>('[data-active="1"]');
+    el?.scrollIntoView({ block: 'nearest' });
+  }, [active, open]);
+
+  const go = (slug: string) => {
+    setOpen(false);
+    router.push(docHref(slug));
+  };
+
+  const onKeyDown = (e: React.KeyboardEvent<HTMLInputElement>) => {
+    // 空查询时列表里是「常用文档」，键盘导航要和当前可见行数一致
+    const rowCount = q ? items.length : quick.length;
+    if (e.key === 'ArrowDown') {
+      e.preventDefault();
+      setActive((i) => (rowCount ? (i + 1) % rowCount : 0));
+    } else if (e.key === 'ArrowUp') {
+      e.preventDefault();
+      setActive((i) => (rowCount ? (i - 1 + rowCount) % rowCount : 0));
+    } else if (e.key === 'Enter') {
+      e.preventDefault();
+      const slug = items[active]?.slug ?? (!q ? quick[active]?.page.slug : undefined);
+      if (slug) go(slug);
+    }
+  };
+
+  return (
+    <SearchContext.Provider value={{ openSearch: () => setOpen(true) }}>
+      {children}
+
+      <Modal
+        open={open}
+        onCancel={() => setOpen(false)}
+        footer={null}
+        closable={false}
+        width={680}
+        destroyOnHidden
+        styles={{ body: { padding: 0 } }}
+      >
+        <div className="wb-docs-search-head">
+          <SearchOutlined className="wb-docs-search-head-icon" />
+          <Input
+            ref={inputRef}
+            variant="borderless"
+            value={query}
+            onChange={(e) => setQuery(e.target.value)}
+            onKeyDown={onKeyDown}
+            placeholder="搜索功能、操作步骤或问题…"
+            aria-label="搜索文档"
+          />
+          <kbd className="wb-docs-kbd">Esc</kbd>
+        </div>
+
+        <div className="wb-docs-search-body" ref={listRef} role="listbox">
+          {!q && (
+            <>
+              <div className="wb-docs-search-label">常用文档</div>
+              {quick.length === 0 && (
+                <div className="wb-docs-search-empty">文档内容为空，先往 content/docs 添加 Markdown 文件。</div>
+              )}
+              {quick.map(({ page, groupTitle }, i) => (
+                <button
+                  type="button"
+                  role="option"
+                  aria-selected={i === active}
+                  key={page.slug}
+                  data-active={i === active ? '1' : '0'}
+                  className={`wb-docs-search-row ${i === active ? 'is-active' : ''}`}
+                  onMouseEnter={() => setActive(i)}
+                  onClick={() => go(page.slug)}
+                >
+                  <span className="wb-docs-search-row-icon"><FileTextOutlined /></span>
+                  <span className="wb-docs-search-row-main">
+                    <span className="wb-docs-search-row-title">{page.title}</span>
+                    <span className="wb-docs-search-row-sub">
+                      {groupTitle || '帮助中心'} · 约 {page.readingMinutes} 分钟
+                    </span>
+                  </span>
+                  <ArrowRightOutlined className="wb-docs-search-row-arrow" />
+                </button>
+              ))}
+            </>
+          )}
+
+          {q && (
+            <>
+              <div className="wb-docs-search-label">
+                搜索结果
+                {!loading && !error && <span>{items.length} 篇</span>}
+                {loading && <Spin size="small" />}
+              </div>
+
+              {error && <div className="wb-docs-search-empty">{error}</div>}
+
+              {!loading && !error && items.length === 0 && (
+                <div className="wb-docs-search-empty">
+                  没有找到「{q}」相关内容
+                  <div className="wb-docs-search-empty-sub">换个关键词，或浏览左侧目录</div>
+                </div>
+              )}
+
+              {items.map((hit, i) => (
+                <button
+                  type="button"
+                  role="option"
+                  aria-selected={i === active}
+                  key={hit.slug}
+                  data-active={i === active ? '1' : '0'}
+                  className={`wb-docs-search-row ${i === active ? 'is-active' : ''}`}
+                  onMouseEnter={() => setActive(i)}
+                  onClick={() => go(hit.slug)}
+                >
+                  <span className="wb-docs-search-row-icon"><FileTextOutlined /></span>
+                  <span className="wb-docs-search-row-main">
+                    <span className="wb-docs-search-row-title">{highlight(hit.title, tokens)}</span>
+                    <span className="wb-docs-search-row-sub">
+                      {hit.groupTitle ? `${hit.groupTitle} · ` : ''}
+                      {highlight(hit.excerpt || hit.description, tokens)}
+                    </span>
+                  </span>
+                  <ArrowRightOutlined className="wb-docs-search-row-arrow" />
+                </button>
+              ))}
+            </>
+          )}
+        </div>
+
+        <div className="wb-docs-search-foot">
+          <span>↑↓ 选择 · Enter 打开 · Esc 关闭</span>
+          <span>Ctrl K 随时唤起</span>
+        </div>
+      </Modal>
+    </SearchContext.Provider>
+  );
+}
+
+export function DocsSearchLauncher({ variant = 'header' }: { variant?: 'header' | 'hero' }) {
+  const { openSearch } = useDocsSearch();
+
+  if (variant === 'hero') {
+    return (
+      <button type="button" className="wb-docs-hero-search" onClick={openSearch}>
+        <SearchOutlined />
+        <span>搜索功能、操作步骤或问题…</span>
+        <kbd className="wb-docs-kbd">Ctrl K</kbd>
+      </button>
+    );
+  }
+
+  return (
+    <button type="button" className="wb-docs-search-trigger" onClick={openSearch}>
+      <SearchOutlined />
+      <span>搜索文档</span>
+      <kbd className="wb-docs-kbd">Ctrl K</kbd>
+    </button>
+  );
+}