@assistant-ui/docs-theme 0.0.0-stage → 0.0.2

package/src/next.tsx

@@ -0,0 +1,101 @@
+import { cloneElement, type ReactNode } from "react";
+import type { DocsLayoutProps } from "fumadocs-ui/layouts/docs";
+import type { DocsConfig } from "@farming-labs/docs";
+import {
+  createDocsLayout as createFrameworkDocsLayout,
+  createDocsMetadata as createFrameworkDocsMetadata,
+} from "@farming-labs/theme";
+import { withThemeDefaults } from "./config";
+import { DocsHeader } from "./header";
+import { DocsPageContent } from "./page-content";
+
+export const createDocsMetadata = (config: DocsConfig) =>
+  createFrameworkDocsMetadata(config);
+
+export const createDocsLayout = (
+  config: DocsConfig,
+  options: createDocsLayout.Options,
+) => {
+  const normalized = withThemeDefaults(config);
+  const DocsLayout = createFrameworkDocsLayout(
+    {
+      ...normalized,
+      // Farming Labs 0.2 uses the base preset name to label Introduction folders.
+      theme: { ...normalized.theme, name: "shadcn" },
+    },
+    options.locale ? { locale: options.locale } : undefined,
+  );
+  const docsUrl = config.docsPath ?? `/${config.entry ?? "docs"}`;
+  const localizedDocsUrl = options.locale
+    ? `${docsUrl}?lang=${encodeURIComponent(options.locale)}`
+    : docsUrl;
+  const Layout = ({ children }: { children: ReactNode }) => {
+    const layout = DocsLayout({
+      children: (
+        <DocsPageContent
+          name={options.name}
+          github={config.github}
+          editUrl={options.editUrl}
+          mcpUrl={options.mcpUrl}
+          footer={options.footer}
+        >
+          {children}
+        </DocsPageContent>
+      ),
+    });
+    const layoutProps = options.layoutProps;
+    const themedLayout = layoutProps
+      ? cloneElement(layout, {
+          ...layoutProps,
+          sidebar: layoutProps.sidebar
+            ? { ...layout.props.sidebar, ...layoutProps.sidebar }
+            : layout.props.sidebar,
+        })
+      : layout;
+    return (
+      <div className="aui-docs" data-docs-theme="assistant-ui">
+        <a className="aui-docs-skip-link" href="#nd-page">
+          Skip to content
+        </a>
+        <DocsHeader
+          brand={(config.nav?.title as ReactNode) ?? options.name}
+          brandSlot={options.brand}
+          homeUrl={
+            options.homeUrl ??
+            (config.nav?.url && config.nav.url !== docsUrl
+              ? config.nav.url
+              : localizedDocsUrl)
+          }
+          docsUrl={localizedDocsUrl}
+          name={options.name}
+          links={options.links}
+          themeToggle={
+            config.themeToggle !== false &&
+            (typeof config.themeToggle !== "object" ||
+              config.themeToggle.enabled !== false)
+          }
+        />
+        {themedLayout}
+      </div>
+    );
+  };
+  return Layout;
+};
+
+export namespace createDocsLayout {
+  export interface Options {
+    name: string;
+    /** Active locale from the site's Farming Labs i18n configuration. */
+    locale?: string;
+    /** Custom header branding, including interactive project switchers. */
+    brand?: ReactNode;
+    /** Framework layout overrides for custom page trees and sidebar slots. */
+    layoutProps?: Partial<Omit<DocsLayoutProps, "children">>;
+    homeUrl?: string;
+    links?: readonly { label: string; href: string; external?: boolean }[];
+    footer?: ReactNode;
+    mcpUrl?: string;
+    /** Override the repository edit link. `{path}` expands to the current page URL path. */
+    editUrl?: string;
+  }
+}

package/src/page-content.test.tsx

@@ -0,0 +1,87 @@
+// @vitest-environment jsdom
+
+import { act, type ReactNode } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, expect, it, vi } from "vitest";
+import { DocsPageContent } from "./page-content";
+
+const context = vi.hoisted(() => ({
+  tree: {
+    $id: "docs",
+    name: "Docs",
+    children: [
+      {
+        type: "page",
+        name: "Previous" as ReactNode,
+        url: "/guide/previous?lang=fr",
+      },
+      { type: "page", name: "Current", url: "/guide?lang=fr" },
+      { type: "page", name: "Next", url: "/guide/next?lang=fr" },
+    ],
+  },
+}));
+
+vi.mock("next/navigation", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("next/navigation")>()),
+  usePathname: () => "/guide",
+}));
+vi.mock("fumadocs-ui/contexts/tree", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("fumadocs-ui/contexts/tree")>()),
+  useTreeContext: () => ({ root: context.tree, full: context.tree }),
+}));
+vi.mock("fumadocs-ui/components/toc", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("fumadocs-ui/components/toc")>()),
+  useTOCItems: () => [{ title: "Heading", url: "#heading", depth: 2 }],
+}));
+
+afterEach(() => {
+  document.body.replaceChildren();
+  vi.unstubAllGlobals();
+});
+
+it("keeps localized actions attached when the framework replaces the page header", async () => {
+  vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);
+  document.body.innerHTML =
+    '<article id="nd-page"><div class="fd-generated-page-header"></div></article><aside id="nd-toc"></aside>';
+  const container = document.createElement("div");
+  document.body.append(container);
+  const root = createRoot(container);
+  context.tree.children[0]!.name = <span>Previous</span>;
+  try {
+    await act(async () => {
+      root.render(
+        <DocsPageContent
+          name="Project"
+          github={undefined}
+          editUrl={undefined}
+          mcpUrl={undefined}
+          footer={undefined}
+        >
+          <p>Content</p>
+        </DocsPageContent>,
+      );
+    });
+    expect(
+      document.querySelector('a[title="Previous page"]')?.getAttribute("href"),
+    ).toBe("/guide/previous?lang=fr");
+    expect(document.querySelector("#nd-toc a")?.getAttribute("href")).toBe(
+      "/guide.md?lang=fr",
+    );
+    expect(document.body.textContent).not.toContain("[object Object]");
+    expect(document.querySelector('a[title="Next: Next"]')).not.toBeNull();
+
+    const replacement = document.createElement("div");
+    replacement.className = "fd-generated-page-header";
+    await act(async () => {
+      document
+        .querySelector(".fd-generated-page-header")!
+        .replaceWith(replacement);
+    });
+    expect(
+      replacement.querySelector('[aria-label="Page controls"]'),
+    ).not.toBeNull();
+  } finally {
+    await act(async () => root.unmount());
+  }
+  expect(document.querySelector('[aria-label="Page controls"]')).toBeNull();
+});

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