@assistant-ui/docs-theme 0.0.0 → 0.0.3

package/src/layout-hosts.test.tsx

@@ -0,0 +1,98 @@
+// @vitest-environment jsdom
+
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { act } from "react";
+import { createRoot } from "react-dom/client";
+import { renderToStaticMarkup } from "react-dom/server";
+import { RootProvider } from "@farming-labs/theme";
+import { afterAll, afterEach, beforeEach, expect, it, vi } from "vitest";
+import { createDocsLayout } from "./next";
+
+vi.mock("next/navigation", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("next/navigation")>()),
+  usePathname: () => "/docs",
+  useSearchParams: () => new URLSearchParams(),
+  useParams: () => ({}),
+  useRouter: () => ({ push: vi.fn(), replace: vi.fn(), prefetch: vi.fn() }),
+}));
+
+const contentDir = mkdtempSync(join(tmpdir(), "assistant-ui-docs-hosts-"));
+writeFileSync(
+  join(contentDir, "page.mdx"),
+  "---\ntitle: Welcome\ndescription: Start here\n---\n\n## Setup\n",
+);
+afterAll(() => rmSync(contentDir, { recursive: true }));
+
+beforeEach(() => {
+  window.history.replaceState(null, "", "/docs");
+  vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);
+  vi.stubGlobal("matchMedia", () => ({
+    matches: false,
+    addListener: vi.fn(),
+    removeListener: vi.fn(),
+    addEventListener: vi.fn(),
+    removeEventListener: vi.fn(),
+  }));
+  const observer = vi.fn(function () {
+    return { observe: vi.fn(), unobserve: vi.fn(), disconnect: vi.fn() };
+  });
+  vi.stubGlobal("IntersectionObserver", observer);
+  vi.stubGlobal("ResizeObserver", observer);
+});
+
+it("renders the complete layout with shared framework contexts", () => {
+  const Layout = createDocsLayout(
+    { entry: "docs", contentDir, themeToggle: false },
+    { name: "Project" },
+  );
+  const html = renderToStaticMarkup(
+    <RootProvider theme={{ enabled: false }}>
+      <Layout>
+        <h2 id="setup">Setup</h2>
+      </Layout>
+    </RootProvider>,
+  );
+  expect(html).toContain('id="nd-page"');
+  expect(html).toContain("fd-generated-page-header");
+  expect(html).toContain('id="nd-toc-placeholder"');
+  expect(html).toContain("Welcome");
+});
+
+afterEach(() => {
+  document.body.replaceChildren();
+  vi.unstubAllGlobals();
+});
+
+it("renders the populated TOC host and attaches the theme actions", async () => {
+  const Layout = createDocsLayout(
+    { entry: "docs", contentDir, themeToggle: false },
+    { name: "Project" },
+  );
+  const container = document.createElement("div");
+  document.body.append(container);
+  const root = createRoot(container);
+  try {
+    await act(async () => {
+      root.render(
+        <RootProvider theme={{ enabled: false }}>
+          <Layout>
+            <h2 id="setup">Setup</h2>
+          </Layout>
+        </RootProvider>,
+      );
+    });
+    const toc = container.querySelector("#nd-toc");
+    expect(toc).not.toBeNull();
+    expect(toc?.querySelector('a[href="#setup"]')?.textContent).toBe("Setup");
+    expect(toc?.querySelector('a[href="/docs.md"]')).not.toBeNull();
+    expect(
+      container.querySelector(
+        '.fd-generated-page-header [aria-label="Page controls"]',
+      ),
+    ).not.toBeNull();
+  } finally {
+    await act(async () => root.unmount());
+  }
+});

package/src/navigation.test.ts

@@ -0,0 +1,123 @@
+import { describe, expect, it } from "vitest";
+import { getEditUrl, getPageNeighbors } from "./navigation";
+
+const tree: Parameters<typeof getPageNeighbors>[0] = [
+  { type: "page", name: "Overview", url: "/guide" },
+  { type: "separator", name: "Learn" },
+  {
+    type: "folder",
+    name: "API",
+    index: { type: "page", name: "Introduction", url: "/guide/api" },
+    children: [
+      { type: "page", name: "Client", url: "/guide/api/client" },
+      {
+        type: "folder",
+        name: "Advanced",
+        children: [
+          { type: "page", name: "Streaming", url: "/guide/api/streaming" },
+        ],
+      },
+    ],
+  },
+];
+
+describe("documentation navigation", () => {
+  it("follows the tree order across folder indexes and sections", () => {
+    const { current, previous, next } = getPageNeighbors(tree, "/guide/api");
+    expect(current?.name).toBe("Introduction");
+    expect(previous?.url).toBe("/guide");
+    expect(next).toEqual({
+      name: "Client",
+      url: "/guide/api/client",
+      section: "API",
+    });
+  });
+
+  it("keeps first and last pages at the boundaries", () => {
+    expect(getPageNeighbors(tree, "/guide").previous).toBeUndefined();
+    const last = getPageNeighbors(tree, "/guide/api/streaming");
+    expect(last.next).toBeUndefined();
+    expect(last.current?.section).toBe("Advanced");
+    expect(last.previous?.name).toBe("Client");
+  });
+
+  it("accepts trailing slashes without changing the navigation target", () => {
+    expect(getPageNeighbors(tree, "/guide/api/").current?.url).toBe(
+      "/guide/api",
+    );
+  });
+
+  it("matches localized routes while preserving the locale in navigation links", () => {
+    const { current, next } = getPageNeighbors(
+      [
+        { type: "page", name: "Accueil", url: "/guide?lang=fr" },
+        { type: "page", name: "Client", url: "/guide/client?lang=fr" },
+      ],
+      "/guide",
+    );
+    expect(current?.name).toBe("Accueil");
+    expect(next?.url).toBe("/guide/client?lang=fr");
+  });
+
+  it("does not invent neighbors for an unknown route or empty tree", () => {
+    for (const result of [
+      getPageNeighbors(tree, "/missing"),
+      getPageNeighbors([], "/guide"),
+    ]) {
+      expect(result).toEqual({
+        current: undefined,
+        previous: undefined,
+        next: undefined,
+      });
+    }
+  });
+});
+
+describe("repository edit links", () => {
+  it("uses each consumer's repository, branch, directory, and route", () => {
+    expect(
+      getEditUrl("/guide/api/", {
+        url: "https://github.com/example/project/",
+        branch: "docs",
+        directory: "/website/",
+      }),
+    ).toBe(
+      "https://github.com/example/project/edit/docs/website/app/guide/api/page.mdx",
+    );
+  });
+
+  it("supports a repository URL without extra configuration", () => {
+    expect(getEditUrl("/docs", "https://github.com/example/project")).toBe(
+      "https://github.com/example/project/edit/main/app/docs/page.mdx",
+    );
+  });
+
+  it.each(["", "/", "////"])(
+    "treats directory %j as the repository root",
+    (directory) => {
+      expect(
+        getEditUrl("/docs", {
+          url: "https://github.com/example/project",
+          directory,
+        }),
+      ).toBe("https://github.com/example/project/edit/main/app/docs/page.mdx");
+    },
+  );
+
+  it("trims long boundary slash runs while preserving interior slashes", () => {
+    const slashes = "/".repeat(100_000);
+    const directory = `website${slashes}content`;
+    expect(
+      getEditUrl("/docs", {
+        url: "https://github.com/example/project",
+        directory: `${slashes}${directory}${slashes}`,
+      }),
+    ).toBe(
+      `https://github.com/example/project/edit/main/${directory}/app/docs/page.mdx`,
+    );
+  });
+
+  it("omits editing when no repository is configured", () => {
+    expect(getEditUrl("/docs")).toBeUndefined();
+  });
+});

package/src/navigation.ts

@@ -0,0 +1,61 @@
+import type { ReactNode } from "react";
+import type { useTreeContext } from "fumadocs-ui/contexts/tree";
+
+export const getPageNeighbors = (
+  nodes: ReturnType<typeof useTreeContext>["root"]["children"],
+  pathname: string,
+) => {
+  const pages: getPageNeighbors.Link[] = [];
+  const visit = (items: typeof nodes, section?: ReactNode) => {
+    for (const node of items) {
+      if (node.type === "page")
+        pages.push({ name: node.name, url: node.url, section });
+      if (node.type === "folder") {
+        if (node.index)
+          pages.push({ name: node.index.name, url: node.index.url });
+        visit(node.children, node.name);
+      }
+    }
+  };
+  visit(nodes);
+  const index = pages.findIndex(
+    (page) =>
+      page.url.split(/[?#]/, 1)[0]?.replace(/\/$/, "") ===
+      pathname.replace(/\/$/, ""),
+  );
+  return {
+    current: pages[index],
+    previous: index >= 0 ? pages[index - 1] : undefined,
+    next: index >= 0 ? pages[index + 1] : undefined,
+  };
+};
+
+export namespace getPageNeighbors {
+  export interface Link {
+    name: ReactNode;
+    url: string;
+    section?: ReactNode;
+  }
+}
+
+export const getEditUrl = (pathname: string, github?: getEditUrl.Options) => {
+  if (!github) return undefined;
+  const base = typeof github === "string" ? { url: github } : github;
+  const path = base.directory ?? "";
+  let start = 0;
+  let end = path.length;
+  while (path[start] === "/") start++;
+  while (end > start && path[end - 1] === "/") end--;
+  const directory = path.slice(start, end);
+  return `${base.url.replace(/\/$/, "")}/edit/${base.branch ?? "main"}/${directory ? `${directory}/` : ""}app${pathname.replace(/\/$/, "")}/page.mdx`;
+};
+
+export namespace getEditUrl {
+  export type Options =
+    | string
+    | {
+        url: string;
+        branch?: string;
+        directory?: string;
+      };
+}

package/src/next.test.tsx

@@ -0,0 +1,110 @@
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { Children, isValidElement, type ReactNode } from "react";
+import type { DocsLayoutProps } from "fumadocs-ui/layouts/docs";
+import { DocsLayout as FrameworkLayout } from "@farming-labs/theme";
+import { afterAll, describe, expect, it } from "vitest";
+import { createDocsLayout } from "./next";
+import { DocsHeader } from "./header";
+
+const contentDir = mkdtempSync(join(tmpdir(), "assistant-ui-docs-"));
+for (const [locale, title] of [
+  ["en", "Welcome"],
+  ["fr", "Bienvenue"],
+] as const) {
+  const directory = join(contentDir, locale);
+  mkdirSync(directory);
+  writeFileSync(join(directory, "page.mdx"), `---\ntitle: ${title}\n---\n`);
+}
+afterAll(() => rmSync(contentDir, { recursive: true }));
+
+const getFrameworkLayout = (children: ReactNode) => {
+  const layout = Children.toArray(children).find(
+    (child) => isValidElement(child) && child.type === FrameworkLayout,
+  );
+  expect(isValidElement<DocsLayoutProps>(layout)).toBe(true);
+  if (!isValidElement<DocsLayoutProps>(layout))
+    throw new Error("Missing framework layout");
+  return layout;
+};
+
+describe("Farming Labs layout contract", () => {
+  it("keeps the synchronous layout root and merges consumer overrides", () => {
+    const banner = <div>Project language</div>;
+    const tree = { name: "Project", children: [] };
+    const Layout = createDocsLayout(
+      { entry: "docs", contentDir },
+      { name: "Project", layoutProps: { tree, sidebar: { banner } } },
+    );
+    const layout = getFrameworkLayout(
+      Layout({ children: <p>Content</p> }).props.children,
+    );
+    expect(layout.props.tree).toBe(tree);
+    expect(layout.props.sidebar).toMatchObject({ collapsible: false, banner });
+    expect(layout.props.children).toBeDefined();
+  });
+
+  it.each([undefined, "/docs"])(
+    "preserves the active locale in the default brand link (%s)",
+    (homeUrl) => {
+      const Layout = createDocsLayout(
+        {
+          entry: "docs",
+          ...(homeUrl ? { nav: { url: homeUrl } } : {}),
+          contentDir,
+          i18n: { locales: ["en", "fr"], defaultLocale: "en" },
+        },
+        { name: "Project", locale: "fr" },
+      );
+      const children = Layout({ children: null }).props.children;
+      const layout = getFrameworkLayout(children);
+      const header = Children.toArray(children).find(
+        (child) => isValidElement(child) && child.type === DocsHeader,
+      );
+      expect(
+        isValidElement<{ docsUrl: string }>(header) && header.props.docsUrl,
+      ).toBe("/docs?lang=fr");
+      expect(
+        isValidElement<{ homeUrl: string }>(header) && header.props.homeUrl,
+      ).toBe("/docs?lang=fr");
+      expect(layout.props.nav?.url).toBe("/docs?lang=fr");
+      expect(layout.props.tree.children).toContainEqual(
+        expect.objectContaining({ name: "Bienvenue", url: "/docs?lang=fr" }),
+      );
+    },
+  );
+
+  it.each([
+    { nav: "/", override: undefined, expected: "/" },
+    { nav: "/docs", override: "/", expected: "/" },
+    {
+      nav: "https://example.com",
+      override: undefined,
+      expected: "https://example.com",
+    },
+  ])(
+    "preserves an explicit home destination ($expected)",
+    ({ nav, override, expected }) => {
+      const Layout = createDocsLayout(
+        {
+          entry: "docs",
+          contentDir,
+          nav: { url: nav },
+          i18n: { locales: ["en", "fr"], defaultLocale: "en" },
+        },
+        {
+          name: "Project",
+          locale: "fr",
+          ...(override === undefined ? {} : { homeUrl: override }),
+        },
+      );
+      const header = Children.toArray(
+        Layout({ children: null }).props.children,
+      ).find((child) => isValidElement(child) && child.type === DocsHeader);
+      expect(
+        isValidElement<{ homeUrl: string }>(header) && header.props.homeUrl,
+      ).toBe(expected);
+    },
+  );
+});

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();
+});