Skip to content

World's first open-source enterprise world model.

12.9 KB
Raw Blame
/* 内置文档:随应用打包(私有部署离线可用),版本与部署一致。
   公开路由——不依赖会话,登录前也可读(开发者接接口时未必有账号)。 */
import { useEffect, useRef, useState } from "react";
import { useQuery } from "@tanstack/react-query";
import ReactMarkdown from "react-markdown";
import remarkGfm from "remark-gfm";
import { Link, useNavigate, useParams } from "@tanstack/react-router";
import { Command, Search } from "lucide-react";
import { api } from "../api";
import { S } from "../i18n";
import {
  Button,
  cn,
  Input,
  Row,
  rowClass,
  SectionMark,
  buttonLike,} from "../ui";
import { HeaderActions } from "./HeaderActions";
import { usePageTitle } from "../useTitle";
import ingestMd from "../docs/ingest.md?raw";
import mcpMd from "../docs/mcp.md?raw";
import { fetchMe } from "../authSession";

/** 文档清单:slug → 标题 + 内容(构建期打进 bundle) */
const DOCS: { slug: string; title: string; body: string }[] = [
  { slug: "ingest", title: "Ingest interfaces", body: ingestMd },
  { slug: "mcp", title: "Agents over MCP", body: mcpMd },
];

/** 全文检索(客户端,文档已在 bundle 里):命中行 → 文档 + 以命中词为中心的摘录 */
function searchDocs(q: string): { slug: string; title: string; snippet: string }[] {
  const needle = q.trim().toLowerCase();
  if (needle.length < 2) return [];
  const hits: { slug: string; title: string; snippet: string }[] = [];
  for (const d of DOCS) {
    for (const line of d.body.split("\n")) {
      const cleaned = line.replace(/[#`*|>-]/g, " ").replace(/\s+/g, " ").trim();
      const idx = cleaned.toLowerCase().indexOf(needle);
      if (idx < 0) continue;
      // 摘录窗口以命中词为中心,避免命中被 90 字截断截丢
      const start = Math.max(0, idx - 30);
      const snippet = (start > 0 ? "…" : "") + cleaned.slice(start, start + 100);
      hits.push({ slug: d.slug, title: d.title, snippet });
      if (hits.length >= 8) return hits;
    }
  }
  return hits;
}

/** 摘录内高亮命中词(不区分大小写,全部命中都标) */
function Highlighted({ text, q }: { text: string; q: string }) {
  const needle = q.trim();
  if (!needle) return <>{text}</>;
  const parts = text.split(new RegExp(`(${needle.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")})`, "ig"));
  return (
    <>
      {parts.map((p, i) =>
        p.toLowerCase() === needle.toLowerCase() ? (
          /* 命中词用警示琥珀:结果列表里一眼定位到匹配处 */
          <mark
            key={i}
            className="u-mark"
          >
            {p}
          </mark>
        ) : (
          <span key={i}>{p}</span>
        ),
      )}
    </>
  );
}

/** 标题 → 锚点 id(TOC 与正文用同一函数保证对得上) */
function slugify(s: string): string {
  return s
    .toLowerCase()
    .replace(/[^a-z0-9一-龥]+/g, "-")
    .replace(/(^-+|-+$)/g, "");
}

/** React children → 纯文本(h2/h3 里可能嵌 code/strong) */
// eslint-disable-next-line @typescript-eslint/no-explicit-any
function textOf(children: any): string {
  if (typeof children === "string") return children;
  if (Array.isArray(children)) return children.map(textOf).join("");
  if (children && typeof children === "object" && "props" in children)
    return textOf(children.props.children);
  return "";
}

/** 从 markdown 源提取 h2/h3 目录 */
function tocOf(body: string): { id: string; text: string; level: 2 | 3 }[] {
  const out: { id: string; text: string; level: 2 | 3 }[] = [];
  for (const line of body.split("\n")) {
    const m = /^(#{2,3})\s+(.+)$/.exec(line);
    if (!m) continue;
    const text = m[2].replace(/[`*]/g, "").trim();
    out.push({ id: slugify(text), text, level: m[1].length as 2 | 3 });
  }
  return out;
}

const IS_MAC = navigator.platform.toUpperCase().includes("MAC");

export function DocsPage() {
  const { slug } = useParams({ from: "/docs/$slug" });
  const doc = DOCS.find((d) => d.slug === slug) ?? DOCS[0];
  const navigate = useNavigate();
  const [q, setQ] = useState("");
  const searchRef = useRef<HTMLDivElement>(null);
  const inputRef = useRef<HTMLInputElement>(null);
  const results = searchDocs(q);
  const toc = tocOf(doc.body);
  const mainRef = useRef<HTMLElement>(null);
  const [activeHeading, setActiveHeading] = useState<string | null>(null);
  // 标题:`Utopia | {文章名}`——Charter 是门脸字标,标题直接给文章
  usePageTitle(S.app.name, doc.title);
  // 公开页也感知登录态:已登录给用户菜单,未登录给 Sign in
  const me = useQuery({ queryKey: ["me"], queryFn: fetchMe, retry: false });
  const health = useQuery({ queryKey: ["health"], queryFn: api.health });

  // 滚动跟随:视口上沿之上最近的标题为当前小节;
  // 滚到底强制激活最后一节(短末节永远越不过判定线)
  const onScrollSpy = () => {
    const main = mainRef.current;
    if (!main) return;
    const top = main.getBoundingClientRect().top;
    let current: string | null = null;
    for (const h of toc) {
      const el = document.getElementById(h.id);
      if (el && el.getBoundingClientRect().top - top <= 96) current = h.id;
    }
    if (main.scrollTop + main.clientHeight >= main.scrollHeight - 8 && toc.length)
      current = toc[toc.length - 1].id;
    setActiveHeading(current);
  };

  useEffect(() => {
    if (!q) return;
    const onDown = (e: MouseEvent) => {
      if (searchRef.current && !searchRef.current.contains(e.target as Node)) setQ("");
    };
    const onKey = (e: KeyboardEvent) => {
      if (e.key === "Escape") setQ("");
    };
    document.addEventListener("mousedown", onDown);
    document.addEventListener("keydown", onKey);
    return () => {
      document.removeEventListener("mousedown", onDown);
      document.removeEventListener("keydown", onKey);
    };
  }, [q]);

  // 键盘呼起:⌘K / Ctrl+K 任何时候生效;`/` 仅在焦点不在输入框时(别劫持打字)
  useEffect(() => {
    const onKey = (e: KeyboardEvent) => {
      const el = document.activeElement;
      const typing =
        el instanceof HTMLInputElement ||
        el instanceof HTMLTextAreaElement ||
        (el instanceof HTMLElement && el.isContentEditable);
      if ((e.metaKey || e.ctrlKey) && e.key.toLowerCase() === "k") {
        e.preventDefault();
        inputRef.current?.focus();
        inputRef.current?.select();
      } else if (e.key === "/" && !typing) {
        e.preventDefault();
        inputRef.current?.focus();
      } else if (e.key === "Escape" && el === inputRef.current) {
        inputRef.current?.blur();
      }
    };
    document.addEventListener("keydown", onKey);
    return () => document.removeEventListener("keydown", onKey);
  }, []);

  return (
    <div className="h-screen flex flex-col overflow-hidden">
      <header className="glass-strong relative z-40 border-x-0 border-t-0 h-12 shrink-0 flex items-center px-2">
        <SectionMark className="pl-3" text={S.docs.brand} title={S.docs.backTitle} />
        {/* 居中搜索:检索打包在本地的全部文档;宽度对齐正文栏(max-w-3xl 去掉 px-8) */}
        <div
          ref={searchRef}
          className="absolute left-1/2 -translate-x-1/2 w-[min(44rem,55vw)]"
        >
          <div className="relative">
            {/* 中号:与别处的搜索框同一个高度(32),小号在顶栏里显得矮一截 */}
            <Input
              className="w-full"
              icon={<Search size={13} />}
              ref={inputRef}
              placeholder={S.docs.searchPlaceholder}
              value={q}
              onChange={(e) => setQ(e.target.value)}
            />
            {/* 快捷键提示:输入中不占视线。⌘ 用 lucide 图标;
                Ctrl 无图形符号(⌘ 是 Mac 专属键符),Windows 规范写法就是文字 */}
            {!q && (
              <kbd className="pointer-events-none absolute right-2.5 top-1/2 -translate-y-1/2 flex items-center gap-1 rounded-cell border border-line bg-surface px-2 py-1 font-sans text-fine text-ink-2">
                {IS_MAC ? <Command size={9} /> : <span>Ctrl</span>}
                <span>K</span>
              </kbd>
            )}
          </div>
          {q.trim().length >= 2 && (
            <div className="u-menu-glass u-pop-in u-pop-in-tl absolute inset-x-0 top-full mt-2 rounded-overlay u-lift-strong overflow-hidden">
              {results.length === 0 ? (
                <p className="px-4 py-3 text-small text-ink-2">{S.docs.noResults}</p>
              ) : (
                results.map((r, i) => (
                  <Row
                    key={i}
                    density="menu"
                    className="border-b border-line px-4 py-3 last:border-0"
                    onClick={() => {
                      setQ("");
                      navigate({ to: "/docs/$slug", params: { slug: r.slug } });
                    }}
                  >
                    <div className="text-fine text-ink-2">{r.title}</div>
                    <div className="text-body text-ink truncate">
                      <Highlighted text={r.snippet} q={q} />
                    </div>
                  </Row>
                ))
              )}
            </div>
          )}
        </div>

        {/* 右侧与 App、账户页同一份:换页时不该动。没登录就只剩一个「登录」 */}
        <HeaderActions
          link={{ to: "/", label: S.account.backToApp }}
          version={health.data?.version}
          user={me.data}
          signedOut={
            me.isError ? (
              <Link to="/login" className={buttonLike("ghost")}>
                {S.login.signIn}
              </Link>
            ) : null
          }
        />
      </header>

      {/* 整页滚动(滚动条贴窗口最右),侧栏 sticky 钉住——正规文档站布局 */}
      <main
        ref={mainRef}
        onScroll={onScrollSpy}
        className="flex-1 min-h-0 overflow-y-auto u-scroll"
      >
        <div className="flex items-start">
          <aside className="w-64 shrink-0 sticky top-0 h-[calc(100vh-3.5rem)] glass-strong border-y-0 border-l-0 px-2 py-3 space-y-1">
            {DOCS.map((d) => (
              <Link
                key={d.slug}
                to="/docs/$slug"
                params={{ slug: d.slug }}
                className={rowClass(d.slug === doc.slug, "nav")}
              >
                {d.title}
              </Link>
            ))}
          </aside>

          {/* 上下都留足空白:标题不顶着头,末段内容能滚到屏幕中部——人读屏幕中间。
              排版交给官方 @tailwindcss/typography(prose,16px 基准),
              自定义只剩:标题锚点 id、外链新开、表格横向滚动容器 */}
          {/* 排版走官方的 shadcn/typeset(src/typeset.css):容器里的
              标题、列表、表格、代码全由它管,内容本身不带一个类;
              字号与字体在 `.typeset-docs` 那个预设里调,颜色接我们的令牌 */}
          <article className="typeset typeset-docs [&_h1]:scroll-mt-6 [&_h2]:scroll-mt-6 [&_h3]:scroll-mt-6 flex-1 min-w-0 max-w-3xl mx-auto px-8 pt-16 pb-[40vh]">
            <ReactMarkdown
              remarkPlugins={[remarkGfm]}
              components={{
                h2: ({ children, ...p }) => (
                  <h2 id={slugify(textOf(children))} {...p}>
                    {children}
                  </h2>
                ),
                h3: ({ children, ...p }) => (
                  <h3 id={slugify(textOf(children))} {...p}>
                    {children}
                  </h3>
                ),
                a: (p) => <a target="_blank" rel="noreferrer" {...p} />,
                // 不加 u-scroll:overscroll-contain 会把竖向滚轮困在块内,页面滚不动
                table: (p) => (
                  <div className="overflow-x-auto">
                    <table {...p} />
                  </div>
                ),
              }}
            >
              {doc.body}
            </ReactMarkdown>
          </article>

          {/* 右侧目录:sticky 钉住,与正文标题同一水平线起头 */}
          {toc.length > 0 && (
            <aside className="hidden lg:block w-64 shrink-0 sticky top-0 pt-16 pr-8">
              <nav className="space-y-1">
                {toc.map((h) => (
                  <Button variant="ghost" size="sm"
                    key={h.id}
                    onClick={() =>
                      document.getElementById(h.id)?.scrollIntoView({ behavior: "smooth" })
                    }
                    className={cn(
                      "h-auto w-full justify-start whitespace-normal py-2 text-left leading-snug",
                      h.level === 3 && "pl-6",
                      activeHeading === h.id ? "text-ink" : "text-ink-2",
                    )}
                  >
                    {h.text}
                  </Button>
                ))}
              </nav>
            </aside>
          )}
        </div>
      </main>
    </div>
  );
}