The Open Standard for Generative UI
import type * as PageTree from "fumadocs-core/page-tree";
import assert from "node:assert/strict";
import { describe, it } from "node:test";
import {
GLOBAL_DOCS_TREE,
NESTED_DOCS_SECTIONS,
getDefaultSidebarMode,
getGlobalActiveItemUrl,
getNestedDocsTree,
getNestedRootForEntryUrl,
getNestedRootForPathname,
getSidebarModeForPathname,
getTabTree,
} from "./docs-navigation";
describe("global docs navigation", () => {
it("exposes the agreed information architecture", () => {
const entries = GLOBAL_DOCS_TREE.children.map((node) => ({
type: node.type,
name: node.name,
url: node.type === "page" ? node.url : undefined,
children: undefined,
}));
assert.deepEqual(entries, [
{ type: "separator", name: "Start", url: undefined, children: undefined },
{ type: "page", name: "Introduction", url: "/docs", children: undefined },
{
type: "page",
name: "Getting Started",
url: "/docs/getting-started",
children: undefined,
},
{
type: "page",
name: "OpenUI vs others",
url: "/docs/openui-lang/comparison",
children: undefined,
},
{ type: "page", name: "Coding Agent Setup", url: "/docs/mcp", children: undefined },
{ type: "separator", name: "Build", url: undefined, children: undefined },
{
type: "page",
name: "OpenUI Lang",
url: "/docs/openui-lang",
children: undefined,
},
{
type: "page",
name: "Build Agents",
url: "/docs/build-agents",
children: undefined,
},
{ type: "separator", name: "Production", url: undefined, children: undefined },
{ type: "page", name: "Overview", url: "/docs/production", children: undefined },
{ type: "page", name: "Gateway", url: "/docs/gateway", children: undefined },
{ type: "page", name: "Autofix", url: "/docs/autofix", children: undefined },
{
type: "page",
name: "Reliability Monitoring",
url: "/docs/reliability",
children: undefined,
},
{ type: "page", name: "Deploy your app", url: "/docs/deploy", children: undefined },
]);
});
it("treats nested roots as navigation sections rather than products", () => {
assert.equal(getNestedRootForEntryUrl("/docs/openui-lang"), "openui-lang");
assert.equal(getNestedRootForEntryUrl("/docs/build-agents"), "build-agents");
assert.equal(
getNestedRootForEntryUrl("/docs/agent/getting-started/introduction"),
"agent-interface",
);
assert.equal(getNestedRootForEntryUrl("/docs/gateway"), "gateway");
assert.equal(getNestedRootForEntryUrl("/docs/autofix"), undefined);
assert.equal(getNestedRootForEntryUrl("/docs/production"), undefined);
assert.equal(getNestedRootForEntryUrl("/docs/reliability"), "reliability");
assert.equal(getNestedRootForEntryUrl("/docs/api-reference"), undefined);
assert.equal(getNestedRootForEntryUrl("/docs/openui-lang/quickstart"), undefined);
});
it("uses a nested sidebar for direct links into a nested section", () => {
assert.deepEqual(getDefaultSidebarMode("/docs"), { kind: "global" });
assert.deepEqual(getDefaultSidebarMode("/docs/autofix"), { kind: "global" });
assert.deepEqual(getDefaultSidebarMode("/docs/production"), { kind: "global" });
assert.deepEqual(getDefaultSidebarMode("/docs/overview"), { kind: "global" });
assert.deepEqual(getDefaultSidebarMode("/docs/getting-started"), { kind: "global" });
assert.deepEqual(getDefaultSidebarMode("/docs/openui-lang/comparison"), { kind: "global" });
assert.deepEqual(getDefaultSidebarMode("/docs/openui-lang/quickstart"), {
kind: "nested",
root: "openui-lang",
});
assert.deepEqual(getDefaultSidebarMode("/docs/agent/core-concepts/artifacts"), {
kind: "nested",
root: "agent-interface",
});
assert.deepEqual(getDefaultSidebarMode("/docs/build-agents/assistant-ui"), {
kind: "nested",
root: "build-agents",
});
assert.deepEqual(getDefaultSidebarMode("/docs/build-agents/frameworks/vercel-ai-sdk"), {
kind: "nested",
root: "build-agents",
});
assert.deepEqual(getDefaultSidebarMode("/docs/api-reference/cli"), {
kind: "api-reference",
});
assert.deepEqual(getDefaultSidebarMode("/docs/gateway/reliability/error-correction"), {
kind: "nested",
root: "gateway",
});
assert.deepEqual(getDefaultSidebarMode("/docs/reliability/installation"), {
kind: "nested",
root: "reliability",
});
assert.deepEqual(getDefaultSidebarMode("/docs/mcp"), { kind: "global" });
});
it("shows the destination section after client-side navigation", () => {
const globalOverride = {
pathname: "/docs",
mode: { kind: "global" } as const,
};
assert.deepEqual(getSidebarModeForPathname("/docs/openui-lang/renderer", globalOverride), {
kind: "nested",
root: "openui-lang",
});
assert.deepEqual(getSidebarModeForPathname("/docs", globalOverride), { kind: "global" });
const nestedPathname = "/docs/openui-lang/renderer";
const showGlobalOverride = {
pathname: nestedPathname,
mode: { kind: "global" } as const,
};
assert.deepEqual(getSidebarModeForPathname(nestedPathname, showGlobalOverride), {
kind: "global",
});
assert.deepEqual(getSidebarModeForPathname("/docs/gateway", showGlobalOverride), {
kind: "nested",
root: "gateway",
});
});
it("promotes overview pages while grouping product pages under their roots", () => {
assert.equal(getGlobalActiveItemUrl("/docs/getting-started"), "/docs/getting-started");
assert.equal(getGlobalActiveItemUrl("/docs/autofix"), "/docs/autofix");
assert.equal(getGlobalActiveItemUrl("/docs/production"), "/docs/production");
assert.equal(
getGlobalActiveItemUrl("/docs/openui-lang/comparison"),
"/docs/openui-lang/comparison",
);
assert.equal(getGlobalActiveItemUrl("/docs/openui-lang/quickstart"), "/docs/openui-lang");
assert.equal(getGlobalActiveItemUrl("/docs/openui-lang/renderer"), "/docs/openui-lang");
assert.equal(
getGlobalActiveItemUrl("/docs/agent/core-concepts/artifacts"),
"/docs/build-agents",
);
assert.equal(getGlobalActiveItemUrl("/docs/build-agents/copilotkit"), "/docs/build-agents");
assert.equal(getGlobalActiveItemUrl("/docs/gateway/api/responses"), "/docs/gateway");
assert.equal(getGlobalActiveItemUrl("/docs/reliability/dashboard"), "/docs/reliability");
});
});
describe("nested docs navigation", () => {
const fullTree: PageTree.Root = {
name: "OpenUI",
children: [
{
type: "folder",
name: "OpenUI Lang",
root: true,
$ref: { folder: "openui-lang" },
children: [
{ type: "page", name: "Introduction", url: "/docs/openui-lang" },
{ type: "page", name: "Quick Start", url: "/docs/openui-lang/quickstart" },
],
},
{
type: "folder",
name: "Cookbooks",
root: true,
$ref: { folder: "cookbooks" },
children: [
{
type: "page",
name: "Conversational analytics",
url: "/cookbooks/conversational-analytics",
},
],
},
{
type: "folder",
name: "Integrations",
root: true,
$ref: { folder: "integrations" },
children: [
{
type: "page",
name: "Agent frameworks",
url: "/docs/integrations#agent-frameworks",
},
{ type: "page", name: "Harnesses", url: "/docs/integrations#harnesses" },
],
},
{
type: "folder",
name: "API Reference",
root: true,
$ref: { folder: "api-reference" },
children: [{ type: "page", name: "Overview", url: "/docs/api-reference" }],
},
{
type: "folder",
name: "Build Agents",
root: true,
$ref: { folder: "build-agents" },
children: [
{ type: "page", name: "Overview", url: "/docs/build-agents" },
{ type: "separator", name: "Backend" },
{
type: "page",
name: "Set up UI generation",
url: "/docs/build-agents/ui-generation",
},
{
type: "folder",
name: "Agent frameworks",
defaultOpen: false,
children: [
{
type: "page",
name: "Vercel AI SDK",
url: "/docs/build-agents/frameworks/vercel-ai-sdk",
},
],
},
{ type: "separator", name: "Chat UI" },
{ type: "page", name: "Choose a chat UI", url: "/docs/build-agents/chat-ui" },
{ type: "page", name: "assistant-ui", url: "/docs/build-agents/assistant-ui" },
],
},
{
type: "folder",
name: "Agent Interface",
$ref: { folder: "agent" },
children: [
{ type: "separator", name: "Getting Started" },
{
type: "page",
name: "Introduction",
url: "/docs/agent/getting-started/introduction",
},
{ type: "separator", name: "Core Concepts" },
{ type: "page", name: "Artifacts", url: "/docs/agent/core-concepts/artifacts" },
{ type: "separator", name: "Guides" },
{ type: "page", name: "Custom artifacts", url: "/docs/agent/guides/custom-artifacts" },
{ type: "separator", name: "Reference" },
{ type: "page", name: "Props", url: "/docs/agent/reference/agentinterface-props" },
],
},
],
};
it("gives the Cookbooks, Integrations, Demos, and API Reference tabs their own sidebars", () => {
const tabs = [
["/cookbooks", "cookbooks"],
["/cookbooks/conversational-analytics", "cookbooks"],
["/docs/integrations", "integrations"],
["/demos", "demos"],
["/docs/api-reference", "api-reference"],
] as const;
for (const [pathname, kind] of tabs) {
assert.deepEqual(getDefaultSidebarMode(pathname), { kind });
assert.equal(getNestedRootForPathname(pathname), undefined);
assert.equal(getGlobalActiveItemUrl(pathname), undefined);
}
assert.deepEqual(
getSidebarModeForPathname("/cookbooks/conversational-analytics", {
pathname: "/docs/openui-lang",
mode: { kind: "global" },
}),
{ kind: "cookbooks" },
);
assert.deepEqual(getDefaultSidebarMode("/cookbooks-other"), { kind: "global" });
assert.deepEqual(getTabTree(fullTree, "cookbooks"), {
type: "root",
$id: "docs:cookbooks",
name: "Cookbooks",
children: [
{
type: "page",
name: "Conversational analytics",
url: "/cookbooks/conversational-analytics",
},
],
});
assert.deepEqual(getTabTree(fullTree, "integrations"), {
type: "root",
$id: "docs:integrations",
name: "Integrations",
children: [
{
type: "page",
name: "Agent frameworks",
url: "/docs/integrations#agent-frameworks",
},
{ type: "page", name: "Harnesses", url: "/docs/integrations#harnesses" },
],
});
assert.deepEqual(getTabTree(fullTree, "api-reference"), {
type: "root",
$id: "docs:api-reference",
name: "API Reference",
children: [{ type: "page", name: "Overview", url: "/docs/api-reference" }],
});
});
it("extracts a maintained nested tree from the Fumadocs tree", () => {
assert.deepEqual(getNestedDocsTree(fullTree, "openui-lang"), {
type: "root",
$id: "docs:nested:openui-lang",
name: "OpenUI Lang",
children: [
{ type: "page", name: "Introduction", url: "/docs/openui-lang" },
{ type: "page", name: "Quick Start", url: "/docs/openui-lang/quickstart" },
],
});
});
it("links to Agent Interface after the Build Agents chat UI comparison page", () => {
assert.deepEqual(getNestedDocsTree(fullTree, "build-agents"), {
type: "root",
$id: "docs:nested:build-agents",
name: "Build Agents",
children: [
{ type: "page", name: "Overview", url: "/docs/build-agents" },
{ type: "separator", name: "Backend" },
{
type: "page",
name: "Set up UI generation",
url: "/docs/build-agents/ui-generation",
},
{
type: "folder",
name: "Agent frameworks",
defaultOpen: false,
children: [
{
type: "page",
name: "Vercel AI SDK",
url: "/docs/build-agents/frameworks/vercel-ai-sdk",
},
],
},
{ type: "separator", name: "Chat UI" },
{ type: "page", name: "Choose a chat UI", url: "/docs/build-agents/chat-ui" },
{
type: "page",
name: "Agent Interface",
url: "/docs/agent/getting-started/introduction",
},
{ type: "page", name: "assistant-ui", url: "/docs/build-agents/assistant-ui" },
],
});
});
it("gives Agent Interface its own sidebar, entered from Build Agents", () => {
assert.equal(NESTED_DOCS_SECTIONS["agent-interface"].parent, "build-agents");
assert.deepEqual(getNestedDocsTree(fullTree, "agent-interface"), {
type: "root",
$id: "docs:nested:agent-interface",
name: "Agent Interface",
children: [
{ type: "separator", name: "Getting Started" },
{
type: "page",
name: "Introduction",
url: "/docs/agent/getting-started/introduction",
},
{ type: "separator", name: "Core Concepts" },
{ type: "page", name: "Artifacts", url: "/docs/agent/core-concepts/artifacts" },
{ type: "separator", name: "Guides" },
{ type: "page", name: "Custom artifacts", url: "/docs/agent/guides/custom-artifacts" },
{ type: "separator", name: "Reference" },
{ type: "page", name: "Props", url: "/docs/agent/reference/agentinterface-props" },
],
});
});
it("maps any page within a nested section to its root", () => {
assert.equal(getNestedRootForPathname("/docs/openui-lang/renderer"), "openui-lang");
assert.equal(getNestedRootForPathname("/docs/api-reference"), undefined);
assert.equal(getNestedRootForPathname("/docs/agent/customize/sidebar"), "agent-interface");
assert.equal(getNestedRootForPathname("/docs/build-agents/custom-chat-ui"), "build-agents");
assert.equal(getNestedRootForPathname("/docs"), undefined);
});
it("fails clearly when the requested nested root is absent", () => {
assert.throws(
() => getNestedDocsTree(fullTree, "gateway"),
/Nested docs root "gateway" was not found/,
);
});
});