@assistant-ui/docs-theme 0.0.0 → 0.0.3

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";

package/styles/site.css

@@ -0,0 +1,223 @@
+@source "../dist/site";
+
+:root {
+  --docs-header-height: 48px;
+  --docs-article-width: 56rem;
+}
+
+.docs-layout {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr);
+
+  @media (min-width: 1280px) {
+    &:has(.docs-toc) {
+      grid-template-columns: minmax(0, 1fr) 14rem;
+    }
+  }
+}
+
+html:has(.docs-layout) {
+  scroll-padding-top: calc(var(--docs-header-height) + 6rem);
+
+  @media (min-width: 768px) {
+    scroll-padding-top: calc(var(--docs-header-height) + 2.5rem);
+  }
+
+  @media (min-width: 1280px) {
+    scroll-padding-top: calc(var(--docs-header-height) + 2rem);
+  }
+}
+
+.docs-prose {
+  font-size: 0.875rem;
+  line-height: 1.7;
+
+  & :where(p):not(:where([class~="not-prose"], [class~="not-prose"] *)) {
+    margin-top: 1.25rem;
+    margin-bottom: 1.25rem;
+  }
+
+  & :where(h2):not(:where([class~="not-prose"], [class~="not-prose"] *)) {
+    font-size: 1.25rem;
+    font-weight: 500;
+    letter-spacing: -0.02em;
+    margin-top: 2.5rem;
+    margin-bottom: 1rem;
+    line-height: 1.4;
+  }
+
+  & :where(h3):not(:where([class~="not-prose"], [class~="not-prose"] *)) {
+    font-size: 1rem;
+    font-weight: 500;
+    letter-spacing: -0.01em;
+    margin-top: 2rem;
+    margin-bottom: 0.75rem;
+    line-height: 1.5;
+  }
+
+  & :where(h4):not(:where([class~="not-prose"], [class~="not-prose"] *)) {
+    font-size: 0.875rem;
+    font-weight: 600;
+    margin-top: 1.5rem;
+    margin-bottom: 0.5rem;
+    line-height: 1.5;
+  }
+
+  & :where(ul, ol):not(:where([class~="not-prose"], [class~="not-prose"] *)) {
+    margin-top: 1rem;
+    margin-bottom: 1rem;
+  }
+
+  & :where(li):not(:where([class~="not-prose"], [class~="not-prose"] *)) {
+    margin-top: 0.25rem;
+    margin-bottom: 0.25rem;
+  }
+
+  &
+    :where(code):not(:where(pre code)):not(
+      :where([class~="not-prose"], [class~="not-prose"] *)
+    ) {
+    font-size: 0.8125rem;
+    padding: 0.15rem 0.4rem;
+    border-radius: 0.5rem;
+    border: none;
+    background: var(--muted);
+    font-weight: 500;
+  }
+
+  & [class~="not-prose"] :where(code):not(:where(pre code)) {
+    font-size: 0.75rem;
+    padding: 0.0625rem 0.3rem;
+    border-radius: 0.5rem;
+    border: none;
+    background: var(--muted);
+    font-weight: 500;
+  }
+
+  & :where(pre):not(:where([class~="not-prose"], [class~="not-prose"] *)) {
+    margin-top: 1.25rem;
+    margin-bottom: 1.25rem;
+    border-radius: 0.75rem;
+  }
+
+  &
+    :where(blockquote):not(
+      :where([class~="not-prose"], [class~="not-prose"] *)
+    ) {
+    font-style: normal;
+    font-weight: 400;
+    color: var(--muted-foreground);
+    margin-top: 1.25rem;
+    margin-bottom: 1.25rem;
+    padding-left: 1rem;
+    border-left-width: 2px;
+    border-left-color: var(--border);
+  }
+
+  &
+    :where(a):not(:where([class~="not-prose"], [class~="not-prose"] *)):not(
+      [data-card]
+    ) {
+    text-decoration: underline;
+    text-underline-offset: 2px;
+    text-decoration-color: var(--muted-foreground);
+  }
+
+  & :where(.prose-no-margin):has(table) {
+    margin-top: 0rem;
+    margin-bottom: 0rem;
+  }
+
+  & :where(table):not(:where([class~="not-prose"], [class~="not-prose"] *)) {
+    margin-top: 0rem;
+    margin-bottom: 0rem;
+    width: 100%;
+    border-collapse: separate;
+    border-spacing: 0;
+    background: var(--muted);
+    border-radius: 0.75rem;
+    overflow: hidden;
+
+    & thead {
+      background: transparent;
+    }
+
+    & th {
+      padding: 0.5rem 0.75rem;
+      text-align: left;
+      font-weight: 500;
+      color: var(--muted-foreground);
+      border: none;
+    }
+
+    & td {
+      padding: 0.5rem 0.75rem;
+      border: none;
+      vertical-align: top;
+    }
+
+    & tr {
+      border: none;
+    }
+
+    & tbody tr {
+      background: var(--background);
+    }
+
+    & tbody tr:first-child td:first-child {
+      border-top-left-radius: 0.5rem;
+    }
+
+    & tbody tr:first-child td:last-child {
+      border-top-right-radius: 0.5rem;
+    }
+
+    & tbody tr:last-child td:first-child {
+      border-bottom-left-radius: 0.5rem;
+    }
+
+    & tbody tr:last-child td:last-child {
+      border-bottom-right-radius: 0.5rem;
+    }
+
+    & code {
+      font-size: 0.75rem;
+      padding: 0.0625rem 0.25rem;
+    }
+  }
+
+  & :where(hr):not(:where([class~="not-prose"], [class~="not-prose"] *)) {
+    margin-top: 2rem;
+    margin-bottom: 2rem;
+    border-color: var(--border);
+  }
+
+  &
+    :where(h2 + p, h3 + p, h4 + p):not(
+      :where([class~="not-prose"], [class~="not-prose"] *)
+    ) {
+    margin-top: 0;
+  }
+
+  &
+    :where(h2 + ul, h3 + ul, h4 + ul, h2 + ol, h3 + ol, h4 + ol):not(
+      :where([class~="not-prose"], [class~="not-prose"] *)
+    ) {
+    margin-top: 0.5rem;
+  }
+
+  & :where(img):not(:where([class~="not-prose"], [class~="not-prose"] *)) {
+    margin-left: auto;
+    margin-right: auto;
+    border-radius: 0.75rem;
+  }
+}
+
+.sidebar-tree-content {
+  scrollbar-width: none;
+}
+
+.sidebar-tree-content::-webkit-scrollbar {
+  width: 0;
+  height: 0;
+}