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

package/src/header.test.tsx

@@ -0,0 +1,41 @@
+// @vitest-environment jsdom
+
+import { renderToStaticMarkup } from "react-dom/server";
+import { SearchProvider } from "fumadocs-ui/contexts/search";
+import { describe, expect, it } from "vitest";
+import { DocsHeader } from "./header";
+
+describe("documentation header", () => {
+  it.each(["Ctrl", "⌘"])(
+    "displays the configured %s search shortcut",
+    (modifier) => {
+      const html = renderToStaticMarkup(
+        <SearchProvider
+          preload={false}
+          hotKey={[
+            { key: "Control", display: modifier },
+            { key: "k", display: "K" },
+          ]}
+        >
+          <DocsHeader
+            brand="Project"
+            brandSlot={null}
+            homeUrl="/"
+            docsUrl="/docs"
+            name="Project"
+            links={[]}
+            themeToggle={false}
+          />
+        </SearchProvider>,
+      );
+      const container = document.createElement("div");
+      container.innerHTML = html;
+      expect(container.querySelector("kbd")?.textContent).toBe(`${modifier} K`);
+      expect(
+        container
+          .querySelector('a[href="/docs"]')
+          ?.getAttribute("aria-current"),
+      ).toBe("true");
+    },
+  );
+});

package/src/header.tsx

@@ -0,0 +1,94 @@
+"use client";
+
+import type { ReactNode } from "react";
+import Link from "next/link";
+import { Moon, Search, Sun } from "lucide-react";
+import { useTheme } from "next-themes";
+import { useSearchContext } from "fumadocs-ui/contexts/search";
+import type { createDocsLayout } from "./next";
+
+export const DocsHeader = ({
+  brand,
+  brandSlot,
+  homeUrl,
+  docsUrl,
+  name,
+  links,
+  themeToggle,
+}: {
+  brand: ReactNode;
+  brandSlot: ReactNode;
+  homeUrl: string;
+  docsUrl: string;
+  name: string;
+  links: createDocsLayout.Options["links"];
+  themeToggle: boolean;
+}) => {
+  const { resolvedTheme, setTheme } = useTheme();
+  const { setOpenSearch, hotKey } = useSearchContext();
+  return (
+    <header className="aui-docs-header">
+      {brandSlot ? (
+        <div className="aui-docs-header-brand">{brandSlot}</div>
+      ) : (
+        <Link
+          href={homeUrl}
+          className="aui-docs-header-brand"
+          aria-label={`${name} home`}
+        >
+          {brand}
+        </Link>
+      )}
+      <div className="aui-docs-header-controls">
+        <button
+          type="button"
+          className="aui-docs-header-search"
+          aria-label="Search documentation"
+          onClick={() => setOpenSearch(true)}
+        >
+          <Search aria-hidden="true" />
+          <span>Search...</span>
+          {hotKey.length > 0 && (
+            <kbd aria-hidden="true">
+              {hotKey.map((key, index) => (
+                <span key={index}>
+                  {index > 0 && " "}
+                  {key.display}
+                </span>
+              ))}
+            </kbd>
+          )}
+        </button>
+        <nav className="aui-docs-header-links" aria-label="Site navigation">
+          <Link href={docsUrl} aria-current="true">
+            Docs
+          </Link>
+          {links?.map((link) => (
+            <a
+              key={link.href}
+              href={link.href}
+              {...(link.external
+                ? { target: "_blank", rel: "noreferrer noopener" }
+                : {})}
+            >
+              {link.label}
+            </a>
+          ))}
+        </nav>
+        {themeToggle && (
+          <button
+            type="button"
+            className="aui-docs-theme-toggle"
+            aria-label="Toggle color theme"
+            onClick={() =>
+              setTheme(resolvedTheme === "dark" ? "light" : "dark")
+            }
+          >
+            <Sun className="aui-docs-theme-sun" aria-hidden="true" />
+            <Moon className="aui-docs-theme-moon" aria-hidden="true" />
+          </button>
+        )}
+      </div>
+    </header>
+  );
+};

package/src/index.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, it } from "vitest";
+import { assistantUi } from "./index";
+import { withThemeDefaults } from "./config";
+
+describe("assistant-ui theme configuration", () => {
+  it("provides the complete theme and a sidebar without a collapse control", () => {
+    const config = withThemeDefaults({ entry: "guide" });
+    expect(config.entry).toBe("guide");
+    expect(config.theme?.name).toBe("assistant-ui");
+    expect(config.sidebar).toMatchObject({ collapsible: false, flat: true });
+    expect(config.pageActions).toEqual({
+      copyMarkdown: false,
+      openDocs: false,
+    });
+  });
+
+  it("merges theme overrides without losing unrelated defaults", () => {
+    const theme = assistantUi({ ui: { layout: { contentWidth: 960 } } });
+    expect(theme.ui?.layout?.contentWidth).toBe(960);
+    expect(theme.ui?.layout?.sidebarWidth).toBe(260);
+    expect(assistantUi().ui?.layout?.contentWidth).toBe(848);
+  });
+
+  it("preserves consumer configuration and explicit disabled features", () => {
+    const config = withThemeDefaults({
+      entry: "guide",
+      sidebar: false,
+      lastUpdated: true,
+      github: "https://github.com/example/project",
+      nav: { title: "Example", url: "/" },
+    });
+    expect(config.sidebar).toBe(false);
+    expect(config.lastUpdated).toBe(true);
+    expect(config.github).toBe("https://github.com/example/project");
+    expect(config.nav?.title).toBe("Example");
+  });
+});

package/src/index.ts

@@ -0,0 +1,38 @@
+import { createTheme, type DocsTheme } from "@farming-labs/docs";
+import { shadcn } from "@farming-labs/theme/shadcn";
+
+const createAssistantTheme = createTheme({
+  ...shadcn({
+    ui: {
+      layout: {
+        contentWidth: 848,
+        sidebarWidth: 260,
+        tocWidth: 224,
+        header: { height: 48 },
+      },
+      typography: {
+        font: {
+          style: {
+            sans: "var(--font-public-sans, ui-sans-serif), system-ui, sans-serif",
+            mono: "var(--font-jetbrains-mono, ui-monospace), monospace",
+          },
+          h1: { size: "1.5rem", weight: 500, letterSpacing: "-0.025em" },
+          h2: { size: "1.25rem", weight: 500, letterSpacing: "-0.02em" },
+          h3: { size: "1rem", weight: 500, letterSpacing: "-0.01em" },
+          body: { size: "0.875rem", lineHeight: "1.7" },
+        },
+      },
+      codeBlock: { showCopyButton: true, showLineNumbers: false },
+    },
+  }),
+  name: "assistant-ui",
+});
+
+export const assistantUi = (overrides: assistantUi.Options = {}): DocsTheme =>
+  createAssistantTheme(overrides);
+
+export namespace assistantUi {
+  export interface Options extends Partial<DocsTheme> {}
+}
+
+export { DocsBrand } from "./brand";

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