@assistant-ui/docs-theme 0.0.2 → 0.0.4

package/src/site/sidebar-navigation.tsx

@@ -0,0 +1,267 @@
+"use client";
+
+import { useEffect, useMemo, useRef, useState, type ReactNode } from "react";
+import Link from "next/link";
+import type { DocsNode, DocsFolder } from "./tree";
+import { findActivePath } from "./tree";
+import { ChevronDown } from "lucide-react";
+import { AnimatePresence, domAnimation, LazyMotion } from "motion/react";
+import * as m from "motion/react-m";
+import { cn } from "./utils";
+
+function SectionItem({
+  item,
+  onNavigate,
+  pathname,
+  activePath,
+  isVisible,
+}: {
+  item: DocsNode;
+  onNavigate: () => void;
+  pathname: string;
+  activePath: ReadonlySet<DocsNode>;
+  isVisible: (node: DocsNode) => boolean;
+}) {
+  if (!isVisible(item)) return null;
+
+  if (item.type === "separator") {
+    return (
+      <p className="text-muted-foreground mt-4 mb-1 px-2 text-xs font-medium first:mt-1">
+        {item.name}
+      </p>
+    );
+  }
+
+  if (item.type === "folder") {
+    const isActive = item.index && pathname === item.index.url;
+    const containsActive = activePath.has(item);
+    const hasChildren = item.children.length > 0;
+
+    return (
+      <div>
+        {item.index ? (
+          <Link
+            href={item.index.url}
+            onClick={onNavigate}
+            data-active={isActive ? "true" : "false"}
+            className={cn(
+              "flex items-center gap-2 rounded-md px-2 py-1.5 text-[13px] transition-colors duration-150",
+              isActive
+                ? "bg-accent/20 text-foreground dark:bg-accent/50 font-medium"
+                : "text-muted-foreground hover:bg-accent/30 hover:text-foreground/90 dark:hover:bg-accent/40",
+            )}
+          >
+            {item.icon}
+            <span className="truncate">{item.name}</span>
+          </Link>
+        ) : (
+          <p className="text-muted-foreground mt-3 mb-1 flex items-center gap-2 px-2 text-xs font-medium first:mt-1">
+            {item.icon}
+            {item.name}
+          </p>
+        )}
+        {hasChildren && (containsActive || !item.index) && (
+          <div className="border-border/50 ml-2 flex flex-col gap-0.5 border-l pl-2">
+            {item.children.map((child) => (
+              <SectionItem
+                key={child.$id}
+                item={child}
+                onNavigate={onNavigate}
+                pathname={pathname}
+                activePath={activePath}
+                isVisible={isVisible}
+              />
+            ))}
+          </div>
+        )}
+      </div>
+    );
+  }
+
+  const isActive = pathname === item.url;
+  return (
+    <Link
+      href={item.url}
+      onClick={onNavigate}
+      data-active={isActive ? "true" : "false"}
+      className={cn(
+        "flex items-center gap-2 rounded-md px-2 py-1.5 text-[13px] transition-colors duration-150",
+        isActive
+          ? "bg-accent/20 text-foreground dark:bg-accent/50 font-medium"
+          : "text-muted-foreground hover:bg-accent/30 hover:text-foreground/90 dark:hover:bg-accent/40",
+      )}
+    >
+      {item.icon}
+      <span className="truncate">{item.name}</span>
+    </Link>
+  );
+}
+
+function SidebarSection({
+  folder,
+  isOpen,
+  onToggle,
+  onNavigate,
+  pathname,
+  activePath,
+  isVisible,
+}: {
+  folder: DocsFolder;
+  isOpen: boolean;
+  onToggle: () => void;
+  onNavigate: () => void;
+  pathname: string;
+  activePath: ReadonlySet<DocsNode>;
+  isVisible: (node: DocsNode) => boolean;
+}) {
+  const isActive = folder.index && pathname === folder.index.url;
+
+  return (
+    <div>
+      <button
+        type="button"
+        onClick={onToggle}
+        aria-expanded={isOpen}
+        className={cn(
+          "hover:bg-accent/30 dark:hover:bg-accent/40 flex w-full items-center gap-2 rounded-md px-2 py-2 text-left text-[13px] transition-colors duration-150",
+          isActive || isOpen
+            ? "text-foreground font-medium"
+            : "text-muted-foreground/90",
+        )}
+      >
+        <span className="text-muted-foreground flex size-4 shrink-0 items-center justify-center">
+          {folder.icon}
+        </span>
+        <span className="flex-1 truncate">{folder.name}</span>
+        <ChevronDown
+          className={cn(
+            "text-muted-foreground/60 size-3.5 shrink-0 transition-transform duration-200",
+            !isOpen && "-rotate-90",
+          )}
+        />
+      </button>
+      <AnimatePresence initial={false}>
+        {isOpen && (
+          <m.div
+            initial={{ height: 0, opacity: 0 }}
+            animate={{ height: "auto", opacity: 1 }}
+            exit={{ height: 0, opacity: 0 }}
+            transition={{ duration: 0.22, ease: [0.16, 1, 0.3, 1] }}
+            className="overflow-hidden"
+          >
+            <div className="border-border/50 mt-0.5 mb-1 ml-4 flex flex-col gap-0.5 border-l pl-2">
+              {folder.children.map((child) => (
+                <SectionItem
+                  key={child.$id}
+                  item={child}
+                  onNavigate={onNavigate}
+                  pathname={pathname}
+                  activePath={activePath}
+                  isVisible={isVisible}
+                />
+              ))}
+            </div>
+          </m.div>
+        )}
+      </AnimatePresence>
+    </div>
+  );
+}
+
+const visible = () => true;
+
+export function DocsSidebarNavigation({
+  sections,
+  pathname,
+  activeSectionId,
+  isVisible = visible,
+  onNavigate,
+  banner,
+  footer,
+  platform,
+}: {
+  sections: readonly DocsFolder[];
+  pathname: string;
+  activeSectionId: string | null;
+  isVisible?: (node: DocsNode) => boolean;
+  onNavigate: () => void;
+  banner?: ReactNode;
+  footer?: ReactNode;
+  platform?: string;
+}) {
+  const navRef = useRef<HTMLElement>(null);
+  const activePath = useMemo(
+    () => new Set(findActivePath(sections, pathname)),
+    [sections, pathname],
+  );
+
+  const [openSectionId, setOpenSectionId] = useState<string | null>(
+    activeSectionId,
+  );
+
+  const [sectionScope, setSectionScope] = useState({
+    activeSectionId,
+    pathname,
+  });
+
+  if (
+    sectionScope.activeSectionId !== activeSectionId ||
+    sectionScope.pathname !== pathname
+  ) {
+    setSectionScope({ activeSectionId, pathname });
+    if (activeSectionId) setOpenSectionId(activeSectionId);
+  }
+
+  useEffect(() => {
+    if (openSectionId !== activeSectionId) return;
+    const timer = setTimeout(() => {
+      const nav = navRef.current;
+      if (!nav) return;
+      const active = nav.querySelector<HTMLElement>("[data-active='true']");
+      if (!active) return;
+      const navRect = nav.getBoundingClientRect();
+      const elRect = active.getBoundingClientRect();
+      if (elRect.top < navRect.top || elRect.bottom > navRect.bottom) {
+        active.scrollIntoView({ block: "center", behavior: "smooth" });
+      }
+    }, 260);
+    return () => clearTimeout(timer);
+  }, [pathname, openSectionId, activeSectionId]);
+
+  return (
+    <div className="flex h-full flex-col">
+      {banner && <div className="shrink-0 px-3 pt-4 lg:hidden">{banner}</div>}
+      <nav
+        aria-label="Docs"
+        ref={navRef}
+        data-docs-platform={platform}
+        className={cn(
+          "sidebar-tree-content flex min-h-0 flex-1 flex-col gap-0.5 overflow-x-hidden overflow-y-auto px-3 pt-2 pb-4 lg:pt-4",
+        )}
+      >
+        <LazyMotion features={domAnimation}>
+          {sections.map((section) => (
+            <SidebarSection
+              key={section.$id}
+              folder={section}
+              isOpen={openSectionId === section.$id}
+              onToggle={() => {
+                const id = section.$id ?? null;
+                setOpenSectionId(openSectionId !== id ? id : null);
+              }}
+              onNavigate={onNavigate}
+              pathname={pathname}
+              activePath={activePath}
+              isVisible={isVisible}
+            />
+          ))}
+        </LazyMotion>
+      </nav>
+      {footer && (
+        <div className="border-border/50 flex shrink-0 items-center gap-1 border-t px-3 py-2">
+          {footer}
+        </div>
+      )}
+    </div>
+  );
+}

package/src/site/sidebar.tsx

@@ -0,0 +1,77 @@
+"use client";
+
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useState,
+  useSyncExternalStore,
+  type ReactNode,
+} from "react";
+import { cn } from "./utils";
+import { DOCS_SIDEBAR_WIDTH } from "./constants";
+
+export const DOCS_SIDEBAR_ID = "docs-sidebar";
+
+const subscribeToViewport = (onChange: () => void) => {
+  const viewport = window.matchMedia("(max-width: 767px)");
+  viewport.addEventListener("change", onChange);
+  return () => viewport.removeEventListener("change", onChange);
+};
+const isMobileViewport = () => window.innerWidth < 768;
+const serverViewport = () => false;
+
+interface DocsSidebarContextValue {
+  open: boolean;
+  setOpen: (open: boolean) => void;
+  toggle: () => void;
+}
+
+const DocsSidebarContext = createContext<DocsSidebarContextValue | null>(null);
+
+export function useDocsSidebar() {
+  const ctx = useContext(DocsSidebarContext);
+  if (!ctx) {
+    throw new Error("useDocsSidebar must be used within DocsSidebarProvider");
+  }
+  return ctx;
+}
+
+export function DocsSidebarProvider({ children }: { children: ReactNode }) {
+  const [open, setOpen] = useState(false);
+  const toggle = useCallback(() => setOpen((prev) => !prev), []);
+
+  return (
+    <DocsSidebarContext.Provider value={{ open, setOpen, toggle }}>
+      {children}
+    </DocsSidebarContext.Provider>
+  );
+}
+
+export function DocsSidebar({ children }: { children: ReactNode }) {
+  const { open } = useDocsSidebar();
+  const isMobile = useSyncExternalStore(
+    subscribeToViewport,
+    isMobileViewport,
+    serverViewport,
+  );
+
+  return (
+    <aside
+      id={DOCS_SIDEBAR_ID}
+      inert={!open && isMobile}
+      className={cn(
+        "bg-background fixed inset-x-0 top-12 bottom-0 z-40 transition-[opacity,visibility] duration-200",
+        open ? "opacity-100" : "pointer-events-none opacity-0 max-md:invisible",
+        "md:pointer-events-auto md:visible md:right-auto md:left-0 md:z-30 md:w-(--sidebar-width) md:opacity-100",
+      )}
+      style={
+        {
+          "--sidebar-width": `${DOCS_SIDEBAR_WIDTH}px`,
+        } as React.CSSProperties
+      }
+    >
+      {children}
+    </aside>
+  );
+}

package/src/site/toc.test.tsx

@@ -0,0 +1,187 @@
+// @vitest-environment jsdom
+
+import { act } from "react";
+import { createRoot } from "react-dom/client";
+import { expect, it, vi } from "vitest";
+import { DocsTableOfContents } from "./toc";
+
+it("observes the current page's headings and releases them when the page changes", async () => {
+  vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);
+  const viewport = {
+    matches: true,
+    addEventListener: vi.fn(),
+    removeEventListener: vi.fn(),
+  };
+  vi.stubGlobal("matchMedia", () => viewport);
+  const observers: {
+    observe: ReturnType<typeof vi.fn>;
+    disconnect: ReturnType<typeof vi.fn>;
+  }[] = [];
+  vi.stubGlobal(
+    "IntersectionObserver",
+    class {
+      observe = vi.fn();
+      disconnect = vi.fn();
+      constructor() {
+        observers.push(this);
+      }
+    },
+  );
+  const container = document.createElement("div");
+  document.body.append(container);
+  const root = createRoot(container);
+  const render = (id: string) =>
+    act(async () =>
+      root.render(
+        <>
+          <h2 id={id}>Current heading</h2>
+          <DocsTableOfContents
+            items={[{ title: "Current heading", url: `#${id}`, depth: 2 }]}
+          >
+            <button>Copy page</button>
+          </DocsTableOfContents>
+        </>,
+      ),
+    );
+  try {
+    await render("install");
+    expect(container.querySelector('a[href="#install"]')?.textContent).toBe(
+      "Current heading",
+    );
+    expect(observers[0]!.observe).toHaveBeenCalledWith(
+      container.querySelector("h2"),
+    );
+    await render("usage");
+    expect(observers[0]!.disconnect).toHaveBeenCalledOnce();
+    expect(observers[1]!.observe).toHaveBeenCalledWith(
+      container.querySelector("h2"),
+    );
+    expect(container.querySelector('a[href="#install"]')).toBeNull();
+    expect(container.querySelector("button")?.textContent).toBe("Copy page");
+    await act(async () =>
+      root.render(
+        <DocsTableOfContents items={[]}>
+          <button>Copy page</button>
+        </DocsTableOfContents>,
+      ),
+    );
+    expect(observers[1]!.disconnect).toHaveBeenCalledOnce();
+    expect(container.querySelector("button")).toBeNull();
+  } finally {
+    await act(async () => root.unmount());
+    container.remove();
+    vi.unstubAllGlobals();
+  }
+});
+
+it("does no heading observation while the TOC is hidden and resumes when it becomes visible", async () => {
+  vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);
+  let onChange = () => {};
+  const viewport = {
+    matches: false,
+    addEventListener: (_: string, listener: () => void) => {
+      onChange = listener;
+    },
+    removeEventListener: vi.fn(),
+  };
+  vi.stubGlobal("matchMedia", () => viewport);
+  const observe = vi.fn();
+  const disconnect = vi.fn();
+  const Observer = vi.fn(function () {
+    return { observe, disconnect };
+  });
+  vi.stubGlobal("IntersectionObserver", Observer);
+  const container = document.createElement("div");
+  document.body.append(container);
+  const root = createRoot(container);
+  try {
+    await act(async () =>
+      root.render(
+        <>
+          <h2 id="setup">Setup</h2>
+          <DocsTableOfContents
+            items={[{ title: "Setup", url: "#setup", depth: 2 }]}
+          />
+        </>,
+      ),
+    );
+    expect(Observer).not.toHaveBeenCalled();
+    viewport.matches = true;
+    await act(async () => onChange());
+    expect(Observer).toHaveBeenCalledOnce();
+    expect(observe).toHaveBeenCalledWith(container.querySelector("h2"));
+    viewport.matches = false;
+    await act(async () => onChange());
+    expect(disconnect).toHaveBeenCalledOnce();
+  } finally {
+    await act(async () => root.unmount());
+    expect(viewport.removeEventListener).toHaveBeenCalledWith(
+      "change",
+      onChange,
+    );
+    container.remove();
+    vi.unstubAllGlobals();
+  }
+});
+
+it.each([
+  ["café-配置", "#caf%C3%A9-%E9%85%8D%E7%BD%AE"],
+  ['quoted"id', "#quoted%22id"],
+  ["literal%id", "#literal%25id"],
+])(
+  "tracks the rendered heading %s from an encoded fragment",
+  async (id, url) => {
+    vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);
+    vi.stubGlobal("matchMedia", () => ({
+      matches: true,
+      addEventListener() {},
+      removeEventListener() {},
+    }));
+    const observe = vi.fn();
+    let notify: (
+      entries: { isIntersecting: boolean; target: Element }[],
+    ) => void;
+    vi.stubGlobal(
+      "IntersectionObserver",
+      class {
+        observe = observe;
+        disconnect() {}
+        constructor(callback: typeof notify) {
+          notify = callback;
+        }
+      },
+    );
+    const container = document.createElement("div");
+    document.body.append(container);
+    const root = createRoot(container);
+    try {
+      await act(async () =>
+        root.render(
+          <>
+            <h2 id={id}>Current heading</h2>
+            <DocsTableOfContents
+              items={[{ title: "Current heading", url, depth: 2 }]}
+            />
+          </>,
+        ),
+      );
+      const heading = container.querySelector("h2")!;
+      expect(observe).toHaveBeenCalledWith(heading);
+      const item = container.querySelector("li")!;
+      const scrollIntoView = vi.fn();
+      item.scrollIntoView = scrollIntoView;
+      await act(async () =>
+        notify([{ isIntersecting: true, target: heading }]),
+      );
+      expect(scrollIntoView).toHaveBeenCalledWith({
+        behavior: "smooth",
+        block: "nearest",
+      });
+      expect(container.querySelector("a")?.getAttribute("href")).toBe(url);
+    } finally {
+      await act(async () => root.unmount());
+      container.remove();
+      vi.unstubAllGlobals();
+    }
+  },
+);

package/src/site/toc.tsx

@@ -0,0 +1,118 @@
+"use client";
+
+import { useEffect, useRef, useState, type ReactNode } from "react";
+import { cn } from "./utils";
+
+type TOCItem = {
+  title: ReactNode;
+  url: string;
+  depth: number;
+};
+
+function headingId(url: string) {
+  const fragment = url.slice(1);
+  try {
+    return decodeURIComponent(fragment);
+  } catch {
+    return fragment;
+  }
+}
+
+export function DocsTableOfContents({
+  items,
+  children,
+}: {
+  items: TOCItem[];
+  children?: ReactNode;
+}) {
+  const [activeId, setActiveId] = useState<string | null>(null);
+  const listRef = useRef<HTMLUListElement>(null);
+
+  useEffect(() => {
+    if (items.length === 0) return;
+
+    const headingIds = items.map((item) => headingId(item.url));
+
+    const viewport = window.matchMedia("(min-width: 1280px)");
+    let observer: IntersectionObserver | undefined;
+    const observeVisibleHeadings = () => {
+      observer?.disconnect();
+      if (!viewport.matches) return;
+      observer = new IntersectionObserver(
+        (entries) => {
+          for (const entry of entries) {
+            if (entry.isIntersecting) {
+              setActiveId(entry.target.id);
+              break;
+            }
+          }
+        },
+        { rootMargin: "-80px 0px -70% 0px", threshold: 0 },
+      );
+      for (const id of headingIds) {
+        const element = document.getElementById(id);
+        if (element) observer.observe(element);
+      }
+    };
+    observeVisibleHeadings();
+    viewport.addEventListener("change", observeVisibleHeadings);
+    return () => {
+      observer?.disconnect();
+      viewport.removeEventListener("change", observeVisibleHeadings);
+    };
+  }, [items]);
+
+  useEffect(() => {
+    if (!activeId || !listRef.current) return;
+
+    const activeElement = Array.from(listRef.current.children).find(
+      (item) => item.getAttribute("data-toc-id") === activeId,
+    );
+    if (activeElement) {
+      activeElement.scrollIntoView({
+        behavior: "smooth",
+        block: "nearest",
+      });
+    }
+  }, [activeId]);
+
+  if (items.length === 0) return null;
+
+  return (
+    <div className="docs-toc w-56 max-xl:hidden">
+      <div className="sticky top-[calc(var(--docs-header-height)_+_1rem)] flex max-h-[calc(100vh_-_var(--docs-header-height)_-_1rem)] flex-col pe-4 pt-4 pb-2">
+        <p className="text-muted-foreground mb-3 shrink-0 text-xs">
+          On this page
+        </p>
+        <ul
+          ref={listRef}
+          className="flex min-h-0 flex-1 [scrollbar-width:none] flex-col gap-1 overflow-x-hidden overflow-y-auto [&::-webkit-scrollbar]:hidden"
+        >
+          {items.map((item) => {
+            const id = headingId(item.url);
+            const isActive = activeId === id;
+            const indent = Math.max(0, item.depth - 2) * 12;
+
+            return (
+              <li key={item.url} data-toc-id={id}>
+                <a
+                  href={item.url}
+                  style={{ paddingLeft: indent || undefined }}
+                  className={cn(
+                    "block py-1 text-[13px] leading-snug wrap-break-word transition-colors",
+                    isActive
+                      ? "text-foreground font-medium"
+                      : "text-muted-foreground hover:text-foreground",
+                  )}
+                >
+                  {item.title}
+                </a>
+              </li>
+            );
+          })}
+        </ul>
+        <div className="mt-6 shrink-0">{children}</div>
+      </div>
+    </div>
+  );
+}

package/src/site/tree.ts

@@ -0,0 +1,36 @@
+import type { ReactNode } from "react";
+
+interface DocsNodeBase {
+  $id?: string;
+  name?: ReactNode;
+  icon?: ReactNode;
+}
+export interface DocsPage extends DocsNodeBase {
+  type: "page";
+  name: ReactNode;
+  url: string;
+}
+export interface DocsFolder extends DocsNodeBase {
+  type: "folder";
+  name: ReactNode;
+  index?: DocsPage;
+  children: DocsNode[];
+}
+export interface DocsSeparator extends DocsNodeBase {
+  type: "separator";
+}
+export type DocsNode = DocsPage | DocsFolder | DocsSeparator;
+
+export function findActivePath(
+  nodes: readonly DocsNode[],
+  pathname: string,
+): DocsNode[] | null {
+  for (const node of nodes) {
+    if (node.type === "page" && node.url === pathname) return [node];
+    if (node.type !== "folder") continue;
+    if (node.index?.url === pathname) return [node, node.index];
+    const path = findActivePath(node.children, pathname);
+    if (path) return [node, ...path];
+  }
+  return null;
+}

package/src/site/utils.ts

@@ -0,0 +1,2 @@
+export const cn = (...values: (string | false | undefined)[]) =>
+  values.filter(Boolean).join(" ");

package/src/ui.ts

@@ -0,0 +1,19 @@
+export { DocsShell, DocsContent } from "./site/layout";
+export { DocsPageShell, DocsBody } from "./site/page";
+export { DocsFooter } from "./site/footer";
+export {
+  DOCS_SIDEBAR_ID,
+  DocsSidebar,
+  DocsSidebarProvider,
+  useDocsSidebar,
+} from "./site/sidebar";
+export { DocsSidebarNavigation } from "./site/sidebar-navigation";
+export { DocsTableOfContents } from "./site/toc";
+export type {
+  DocsNode,
+  DocsPage,
+  DocsFolder,
+  DocsSeparator,
+} from "./site/tree";
+export { DocsSiteHeader } from "./site/header";
+export { DocsPagerNavigation } from "./site/pager";