@assistant-ui/docs-theme 0.0.0 → 0.0.3

package/src/page-content.tsx

@@ -0,0 +1,416 @@
+"use client";
+
+import {
+  useEffect,
+  useRef,
+  useState,
+  useSyncExternalStore,
+  type ReactNode,
+} from "react";
+import { createPortal } from "react-dom";
+import Link from "next/link";
+import { usePathname } from "next/navigation";
+import * as DropdownMenu from "@radix-ui/react-dropdown-menu";
+import { useTreeContext } from "fumadocs-ui/contexts/tree";
+import { useTOCItems } from "fumadocs-ui/components/toc";
+import {
+  Check,
+  CircleAlert,
+  ChevronLeft,
+  ChevronRight,
+  Copy,
+  FileText,
+  MoreHorizontal,
+  Pencil,
+} from "lucide-react";
+import { ClaudeIcon, McpIcon, OpenAIIcon } from "./action-icons";
+
+import { getEditUrl, getPageNeighbors } from "./navigation";
+import type { createDocsLayout } from "./next";
+
+type PageLink = getPageNeighbors.Link;
+
+const documentSubscribers = new Set<() => void>();
+let documentObserver: MutationObserver | undefined;
+
+const subscribeToDocument = (onChange: () => void) => {
+  documentSubscribers.add(onChange);
+  if (!documentObserver) {
+    documentObserver = new MutationObserver(() => {
+      for (const subscriber of documentSubscribers) subscriber();
+    });
+    documentObserver.observe(document.body, { childList: true, subtree: true });
+  }
+  return () => {
+    documentSubscribers.delete(onChange);
+    if (documentSubscribers.size === 0) {
+      documentObserver?.disconnect();
+      documentObserver = undefined;
+    }
+  };
+};
+
+const useDocumentElement = (selector: string | null) =>
+  useSyncExternalStore(
+    subscribeToDocument,
+    () => (selector ? document.querySelector<HTMLElement>(selector) : null),
+    () => null,
+  );
+
+const subscribeToOrigin = () => () => {};
+const getOrigin = () => window.location.origin;
+const getServerOrigin = () => "";
+
+const PageActionLabel = ({
+  title,
+  description,
+}: {
+  title: string;
+  description: string;
+}) => (
+  <span className="aui-docs-action-label">
+    <span>{title}</span>
+    <span>{description}</span>
+  </span>
+);
+
+const DocsPageControls = ({
+  previous,
+  next,
+  title,
+  pathname,
+  markdownUrl,
+  siteName,
+  editUrl,
+  mcpUrl,
+}: {
+  previous: PageLink | undefined;
+  next: PageLink | undefined;
+  title: string;
+  pathname: string;
+  markdownUrl: string;
+  siteName: string;
+  editUrl: string | undefined;
+  mcpUrl: string | undefined;
+}) => {
+  const toc = useTOCItems();
+  // The upstream Farming Labs and Fumadocs layouts supply these portal hosts.
+  const headerHost = useDocumentElement("#nd-page .fd-generated-page-header");
+  const tocHost = useDocumentElement(toc.length > 0 ? "#nd-toc" : null);
+  const [message, setMessage] = useState("");
+  const [copying, setCopying] = useState(false);
+  const origin = useSyncExternalStore(
+    subscribeToOrigin,
+    getOrigin,
+    getServerOrigin,
+  );
+  const markdown = useRef<Promise<string> | null>(null);
+  const githubUrl = editUrl?.replaceAll("{path}", pathname);
+  const publishedUrl = `${origin}${markdownUrl}`;
+  const claudeUrl = `https://claude.ai/new?q=${encodeURIComponent(`Read ${publishedUrl} (the ${siteName} documentation page "${title}") so I can ask questions about it.`)}`;
+
+  const loadMarkdown = () => {
+    markdown.current ??= fetch(markdownUrl)
+      .then((response) => {
+        if (!response.ok) throw new Error("Could not load this page");
+        return response.text();
+      })
+      .catch((error: unknown) => {
+        markdown.current = null;
+        throw error;
+      });
+    return markdown.current;
+  };
+
+  const copy = async (kind: "page" | "mcp") => {
+    setCopying(true);
+    try {
+      const text =
+        kind === "page"
+          ? await loadMarkdown()
+          : new URL(mcpUrl ?? "", window.location.origin).href;
+      await navigator.clipboard.writeText(text);
+      setMessage(kind === "page" ? "Page copied" : "MCP server URL copied");
+    } catch {
+      setMessage("Could not copy. Please try again.");
+    } finally {
+      setCopying(false);
+    }
+  };
+
+  useEffect(() => {
+    if (!message) return;
+    const timer = window.setTimeout(() => setMessage(""), 3000);
+    return () => window.clearTimeout(timer);
+  }, [message]);
+
+  return (
+    <>
+      {headerHost &&
+        createPortal(
+          <nav
+            className="aui-docs-page-controls not-prose"
+            aria-label="Page controls"
+          >
+            {previous ? (
+              <Link
+                href={previous.url}
+                className="aui-docs-pager-button"
+                aria-label="Previous page"
+                title={
+                  typeof previous.name === "string" ||
+                  typeof previous.name === "number"
+                    ? `Previous: ${previous.name}`
+                    : "Previous page"
+                }
+              >
+                <ChevronLeft aria-hidden="true" />
+              </Link>
+            ) : (
+              <button
+                className="aui-docs-pager-button"
+                aria-label="Previous page"
+                disabled
+              >
+                <ChevronLeft aria-hidden="true" />
+              </button>
+            )}
+            {next ? (
+              <Link
+                href={next.url}
+                className="aui-docs-pager-button"
+                aria-label="Next page"
+                title={
+                  typeof next.name === "string" || typeof next.name === "number"
+                    ? `Next: ${next.name}`
+                    : "Next page"
+                }
+              >
+                <ChevronRight aria-hidden="true" />
+              </Link>
+            ) : (
+              <button
+                className="aui-docs-pager-button"
+                aria-label="Next page"
+                disabled
+              >
+                <ChevronRight aria-hidden="true" />
+              </button>
+            )}
+            <DropdownMenu.Root
+              onOpenChange={(open) => {
+                if (open) void loadMarkdown().catch(() => {});
+              }}
+            >
+              <DropdownMenu.Trigger
+                className="aui-docs-pager-button"
+                aria-label="More page actions"
+              >
+                <MoreHorizontal aria-hidden="true" />
+              </DropdownMenu.Trigger>
+              <DropdownMenu.Portal>
+                <DropdownMenu.Content
+                  className="aui-docs-actions-menu"
+                  align="end"
+                  sideOffset={4}
+                  collisionPadding={16}
+                >
+                  <DropdownMenu.Item
+                    className="aui-docs-actions-menu-item"
+                    disabled={copying}
+                    onSelect={() => void copy("page")}
+                  >
+                    <Copy aria-hidden="true" />
+                    <PageActionLabel
+                      title={copying ? "Copying..." : "Copy page"}
+                      description="Markdown, ready to paste into an LLM"
+                    />
+                  </DropdownMenu.Item>
+                  <DropdownMenu.Item
+                    className="aui-docs-actions-menu-item"
+                    asChild
+                  >
+                    <a
+                      href={markdownUrl}
+                      target="_blank"
+                      rel="noreferrer noopener"
+                    >
+                      <FileText aria-hidden="true" />
+                      <PageActionLabel
+                        title="View as Markdown"
+                        description="This page as plain text"
+                      />
+                    </a>
+                  </DropdownMenu.Item>
+                  <DropdownMenu.Item
+                    className="aui-docs-actions-menu-item"
+                    asChild
+                  >
+                    <a
+                      href={claudeUrl}
+                      target="_blank"
+                      rel="noreferrer noopener"
+                    >
+                      <ClaudeIcon />
+                      <PageActionLabel
+                        title="Open in Claude"
+                        description="Ask Claude about this page"
+                      />
+                    </a>
+                  </DropdownMenu.Item>
+                  <DropdownMenu.Item
+                    className="aui-docs-actions-menu-item"
+                    asChild
+                  >
+                    <a
+                      href="https://chatgpt.com/codex/"
+                      target="_blank"
+                      rel="noreferrer noopener"
+                    >
+                      <OpenAIIcon />
+                      <PageActionLabel
+                        title="Open in Codex"
+                        description="Open Codex in ChatGPT"
+                      />
+                    </a>
+                  </DropdownMenu.Item>
+                  {mcpUrl && (
+                    <>
+                      <DropdownMenu.Separator className="aui-docs-actions-menu-separator" />
+                      <DropdownMenu.Item
+                        className="aui-docs-actions-menu-item"
+                        onSelect={() => void copy("mcp")}
+                      >
+                        <McpIcon />
+                        <PageActionLabel
+                          title="Copy MCP server URL"
+                          description="Use these docs from any MCP client"
+                        />
+                      </DropdownMenu.Item>
+                    </>
+                  )}
+                </DropdownMenu.Content>
+              </DropdownMenu.Portal>
+            </DropdownMenu.Root>
+          </nav>,
+          headerHost,
+        )}
+      {tocHost &&
+        createPortal(
+          <div className="aui-docs-toc-actions not-prose">
+            <button
+              type="button"
+              onClick={() => void copy("page")}
+              disabled={copying}
+            >
+              <Copy aria-hidden="true" />
+              {copying ? "Copying..." : "Copy page"}
+            </button>
+            <a href={markdownUrl} target="_blank" rel="noreferrer noopener">
+              <FileText aria-hidden="true" />
+              View as Markdown
+            </a>
+            {githubUrl && (
+              <a href={githubUrl} target="_blank" rel="noreferrer noopener">
+                <Pencil aria-hidden="true" />
+                Edit on GitHub
+              </a>
+            )}
+          </div>,
+          tocHost,
+        )}
+      <output className="aui-docs-action-status" aria-live="polite">
+        {message && (
+          <span>
+            {message.startsWith("Could not") ? (
+              <CircleAlert aria-hidden="true" />
+            ) : (
+              <Check aria-hidden="true" />
+            )}
+            {message}
+          </span>
+        )}
+      </output>
+    </>
+  );
+};
+
+export const DocsPageContent = ({
+  children,
+  name,
+  github,
+  editUrl,
+  mcpUrl,
+  footer,
+}: {
+  children: ReactNode;
+  name: string;
+  github: getEditUrl.Options | undefined;
+  editUrl: string | undefined;
+  mcpUrl: string | undefined;
+  footer: createDocsLayout.Options["footer"];
+}) => {
+  const pathname = usePathname().replace(/\/$/, "");
+  const { root } = useTreeContext();
+  const { previous, next, current } = getPageNeighbors(root.children, pathname);
+  const title = current?.name;
+  const pageUrl = new URL(current?.url ?? pathname, "https://docs.local");
+  const markdownUrl = `${pathname}.md${pageUrl.search}`;
+
+  return (
+    <div className="aui-docs-page-content">
+      <DocsPageControls
+        key={markdownUrl}
+        pathname={pathname}
+        markdownUrl={markdownUrl}
+        title={typeof title === "string" ? title : name}
+        siteName={name}
+        editUrl={editUrl ?? getEditUrl(pathname, github)}
+        mcpUrl={mcpUrl}
+        previous={previous}
+        next={next}
+      />
+      <div className="aui-docs-page-body">{children}</div>
+      {(previous || next) && (
+        <nav
+          className="aui-docs-page-navigation not-prose"
+          aria-label="Page navigation"
+        >
+          {previous ? (
+            <Link href={previous.url} rel="prev">
+              <ChevronLeft aria-hidden="true" />
+              <span>
+                {previous.section && (
+                  <span className="aui-docs-page-section">
+                    {previous.section} /{" "}
+                  </span>
+                )}
+                {previous.name}
+              </span>
+            </Link>
+          ) : (
+            <span />
+          )}
+          {next ? (
+            <Link href={next.url} rel="next">
+              <span>
+                {next.section && (
+                  <span className="aui-docs-page-section">
+                    {next.section} /{" "}
+                  </span>
+                )}
+                {next.name}
+              </span>
+              <ChevronRight aria-hidden="true" />
+            </Link>
+          ) : (
+            <span />
+          )}
+        </nav>
+      )}
+      {footer && (
+        <footer className="aui-docs-legal-footer not-prose">{footer}</footer>
+      )}
+    </div>
+  );
+};

package/src/provider.ts

@@ -0,0 +1 @@
+export { RootProvider } from "@farming-labs/theme";

package/src/site/constants.ts

@@ -0,0 +1 @@
+export const DOCS_SIDEBAR_WIDTH = 260;

package/src/site/footer.tsx

@@ -0,0 +1,59 @@
+import Link from "next/link";
+import { ChevronLeft, ChevronRight } from "lucide-react";
+import type { ReactNode } from "react";
+
+type FooterItem = {
+  name: ReactNode;
+  url: string;
+  section?: ReactNode;
+};
+
+type DocsFooterProps = {
+  previous?: FooterItem | undefined;
+  next?: FooterItem | undefined;
+};
+
+export function DocsFooter({ previous, next }: DocsFooterProps) {
+  if (!previous && !next) return null;
+
+  return (
+    <nav
+      aria-label="Previous and next page"
+      className="not-prose mt-16 flex items-center justify-between gap-4 text-sm"
+    >
+      {previous ? (
+        <Link
+          href={previous.url}
+          className="group text-muted-foreground hover:text-foreground inline-flex min-w-0 items-center gap-1.5 transition-colors"
+        >
+          <ChevronLeft className="size-4 shrink-0 transition-transform group-hover:-translate-x-0.5" />
+          <span className="min-w-0 truncate">
+            {previous.section ? (
+              <span className="opacity-60">{previous.section} / </span>
+            ) : null}
+            {previous.name}
+          </span>
+        </Link>
+      ) : (
+        <span />
+      )}
+
+      {next ? (
+        <Link
+          href={next.url}
+          className="group text-muted-foreground hover:text-foreground inline-flex min-w-0 items-center gap-1.5 transition-colors"
+        >
+          <span className="min-w-0 truncate">
+            {next.section ? (
+              <span className="opacity-60">{next.section} / </span>
+            ) : null}
+            {next.name}
+          </span>
+          <ChevronRight className="size-4 shrink-0 transition-transform group-hover:translate-x-0.5" />
+        </Link>
+      ) : (
+        <span />
+      )}
+    </nav>
+  );
+}

package/src/site/header.test.tsx

@@ -0,0 +1,89 @@
+// @vitest-environment jsdom
+
+import { act, Fragment, useState } from "react";
+import { createRoot } from "react-dom/client";
+import { expect, it, vi } from "vitest";
+import { DocsSiteHeader } from "./header";
+import { DocsSidebar, DocsSidebarProvider } from "./sidebar";
+
+function SidebarState() {
+  const [value, setValue] = useState(0);
+  return <button onClick={() => setValue(value + 1)}>Section {value}</button>;
+}
+
+it("keeps one sidebar mounted and closes the competing mobile menu", async () => {
+  vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);
+  vi.stubGlobal("matchMedia", () => ({
+    addEventListener() {},
+    removeEventListener() {},
+  }));
+  const container = document.createElement("div");
+  document.body.append(container);
+  const root = createRoot(container);
+  const button = (label: string) =>
+    container.querySelector<HTMLButtonElement>(
+      `button[aria-label="${label}"]`,
+    )!;
+  try {
+    await act(async () =>
+      root.render(
+        <DocsSidebarProvider>
+          <DocsSiteHeader
+            brand="Project"
+            mobileControls={null}
+            condensedNavigation={null}
+            desktopNavigation={null}
+            navigationRoot={Fragment}
+            scrolled={false}
+            mobileNavigation={(close) => (
+              <button aria-label="Navigate" onClick={close}>
+                Home
+              </button>
+            )}
+          />
+          <DocsSidebar>
+            <SidebarState />
+          </DocsSidebar>
+        </DocsSidebarProvider>,
+      ),
+    );
+    expect(button("Toggle sidebar").getAttribute("aria-controls")).toBe(
+      container.querySelector("aside")?.id,
+    );
+    const navigation = document.getElementById(
+      button("Site navigation").getAttribute("aria-controls")!,
+    );
+    expect(navigation?.hasAttribute("inert")).toBe(true);
+    await act(async () => button("Toggle sidebar").click());
+    expect(button("Toggle sidebar").getAttribute("aria-expanded")).toBe("true");
+    await act(async () =>
+      container.querySelector<HTMLButtonElement>("aside button")!.click(),
+    );
+    await act(async () => button("Site navigation").click());
+    expect(button("Site navigation").getAttribute("aria-expanded")).toBe(
+      "true",
+    );
+    expect(navigation?.hasAttribute("inert")).toBe(false);
+    expect(button("Toggle sidebar").getAttribute("aria-expanded")).toBe(
+      "false",
+    );
+    await act(async () => button("Toggle sidebar").click());
+    expect(button("Site navigation").getAttribute("aria-expanded")).toBe(
+      "false",
+    );
+    expect(container.querySelectorAll("aside")).toHaveLength(1);
+    expect(container.querySelector("aside button")?.textContent).toBe(
+      "Section 1",
+    );
+    await act(async () => button("Site navigation").click());
+    await act(async () => button("Navigate").click());
+    expect(button("Site navigation").getAttribute("aria-expanded")).toBe(
+      "false",
+    );
+    expect(document.activeElement).toBe(button("Site navigation"));
+  } finally {
+    await act(async () => root.unmount());
+    container.remove();
+    vi.unstubAllGlobals();
+  }
+});

package/src/site/header.tsx

@@ -0,0 +1,117 @@
+"use client";
+
+import {
+  useId,
+  useRef,
+  useState,
+  type ComponentType,
+  type ReactNode,
+} from "react";
+import { Menu, PanelLeft, X } from "lucide-react";
+import { DOCS_SIDEBAR_ID, useDocsSidebar } from "./sidebar";
+import { cn } from "./utils";
+
+export function DocsSiteHeader({
+  brand,
+  mobileControls,
+  condensedNavigation,
+  desktopNavigation,
+  mobileNavigation,
+  navigationRoot: NavigationRoot,
+  scrolled,
+}: {
+  brand: ReactNode;
+  mobileControls: ReactNode;
+  condensedNavigation: ReactNode;
+  desktopNavigation: ReactNode;
+  mobileNavigation: (close: () => void) => ReactNode;
+  navigationRoot: ComponentType<{ children: ReactNode }>;
+  scrolled: boolean;
+}) {
+  const {
+    open: sidebarOpen,
+    setOpen: setSidebarOpen,
+    toggle: toggleSidebar,
+  } = useDocsSidebar();
+  const [navMenuOpen, setNavMenuOpen] = useState(false);
+  const navMenuId = useId();
+  const navMenuToggle = useRef<HTMLButtonElement>(null);
+  const closeNavigation = () => {
+    setNavMenuOpen(false);
+    navMenuToggle.current?.focus();
+  };
+  const toggleNavigation = () => {
+    if (!navMenuOpen) setSidebarOpen(false);
+    setNavMenuOpen((open) => !open);
+  };
+  const toggleMenu = () => {
+    if (!sidebarOpen) setNavMenuOpen(false);
+    toggleSidebar();
+  };
+  return (
+    <header className="sticky top-0 z-50">
+      <NavigationRoot>
+        <div
+          className={cn(
+            "relative z-10 transition-colors duration-200",
+            scrolled ? "bg-background/80 backdrop-blur-md" : "bg-transparent",
+            "group-data-[menu-open=true]:bg-background",
+            "flex h-12 w-full items-center px-4",
+          )}
+        >
+          <div className="flex min-w-0 flex-1 items-center">{brand}</div>
+          <div className="ml-auto flex shrink-0 items-center gap-1 md:hidden">
+            {mobileControls}
+            <button
+              type="button"
+              ref={navMenuToggle}
+              onClick={toggleNavigation}
+              className="text-muted-foreground hover:text-foreground flex size-8 items-center justify-center transition-colors"
+              aria-label="Site navigation"
+              aria-expanded={navMenuOpen}
+              aria-controls={navMenuId}
+            >
+              {navMenuOpen ? (
+                <X className="size-4" />
+              ) : (
+                <Menu className="size-4" />
+              )}
+            </button>
+            <button
+              type="button"
+              onClick={toggleMenu}
+              className="text-muted-foreground hover:text-foreground flex size-8 items-center justify-center transition-colors"
+              aria-label="Toggle sidebar"
+              aria-expanded={sidebarOpen}
+              aria-controls={DOCS_SIDEBAR_ID}
+            >
+              {sidebarOpen ? (
+                <X className="size-4" />
+              ) : (
+                <PanelLeft className="size-4" />
+              )}
+            </button>
+          </div>
+          <div className="ml-auto hidden items-center gap-4 md:flex lg:hidden">
+            {condensedNavigation}
+          </div>
+          <div className="ml-auto hidden items-center gap-4 lg:flex">
+            {desktopNavigation}
+          </div>
+        </div>
+        <div
+          className={cn(
+            "bg-background fixed inset-x-0 top-12 bottom-0 z-40 transition-opacity duration-200 md:hidden",
+            navMenuOpen ? "opacity-100" : "pointer-events-none opacity-0",
+          )}
+          id={navMenuId}
+          inert={!navMenuOpen}
+        >
+          <div className="flex h-full flex-col gap-1 overflow-y-auto px-4 pt-4">
+            {mobileNavigation(closeNavigation)}
+          </div>
+        </div>
+      </NavigationRoot>
+    </header>
+  );
+}