Skip to content

The Open Standard for Generative UI

7.5 KB
Raw Blame
import type * as PageTree from "fumadocs-core/page-tree";

export type TabFolder = "cookbooks" | "integrations" | "demos" | "api-reference";

export type NestedDocsRoot =
  "openui-lang" | "build-agents" | "agent-interface" | "gateway" | "reliability";

export type SidebarMode =
  | { kind: "global" }
  | { kind: TabFolder }
  | {
      kind: "nested";
      root: NestedDocsRoot;
    };

export type SidebarModeOverride = {
  pathname: string;
  mode: SidebarMode;
};

type NestedSection = {
  title: string;
  entryUrl: string;
  pathPrefix: string;
  treeFolder: string;
  /** The section this one is entered from. Its sidebar's back link returns there instead of to all docs. */
  parent?: NestedDocsRoot;
};

export const NESTED_DOCS_SECTIONS: Record<NestedDocsRoot, NestedSection> = {
  "openui-lang": {
    title: "OpenUI Lang",
    entryUrl: "/docs/openui-lang",
    pathPrefix: "/docs/openui-lang",
    treeFolder: "openui-lang",
  },
  "build-agents": {
    title: "Build Agents",
    entryUrl: "/docs/build-agents",
    pathPrefix: "/docs/build-agents",
    treeFolder: "build-agents",
  },
  "agent-interface": {
    title: "Agent Interface",
    entryUrl: "/docs/agent/getting-started/introduction",
    pathPrefix: "/docs/agent",
    treeFolder: "agent",
    parent: "build-agents",
  },
  gateway: {
    title: "Gateway",
    entryUrl: "/docs/gateway",
    pathPrefix: "/docs/gateway",
    treeFolder: "gateway",
  },
  reliability: {
    title: "Reliability Monitoring",
    entryUrl: "/docs/reliability",
    pathPrefix: "/docs/reliability",
    treeFolder: "reliability",
  },
};

export const API_REFERENCE_URL = "/docs/api-reference";
export const COOKBOOKS_URL = "/cookbooks";
// The Cookbooks overview is temporarily removed and /cookbooks redirects here; link to it directly.
export const COOKBOOKS_ENTRY_URL = "/cookbooks/conversational-analytics";
export const INTEGRATIONS_URL = "/docs/integrations";
export const DEMOS_URL = "/demos";

const promotedGlobalUrls = new Set([
  "/docs",
  "/docs/getting-started",
  "/docs/openui-lang/comparison",
  "/docs/mcp",
  "/docs/deploy",
  "/docs/production",
  "/docs/autofix",
]);

export const GLOBAL_DOCS_TREE: PageTree.Root = {
  type: "root",
  $id: "docs:global",
  name: "OpenUI",
  children: [
    { type: "separator", name: "Start" },
    { type: "page", name: "Introduction", url: "/docs" },
    { type: "page", name: "Getting Started", url: "/docs/getting-started" },
    {
      type: "page",
      name: "OpenUI vs others",
      url: "/docs/openui-lang/comparison",
    },
    { type: "page", name: "Coding Agent Setup", url: "/docs/mcp" },
    { type: "separator", name: "Build" },
    {
      type: "page",
      name: NESTED_DOCS_SECTIONS["openui-lang"].title,
      url: NESTED_DOCS_SECTIONS["openui-lang"].entryUrl,
    },
    {
      type: "page",
      name: NESTED_DOCS_SECTIONS["build-agents"].title,
      url: NESTED_DOCS_SECTIONS["build-agents"].entryUrl,
    },
    { type: "page", name: "Cookbooks", url: COOKBOOKS_ENTRY_URL },
    { type: "separator", name: "Production" },
    { type: "page", name: "Overview", url: "/docs/production" },
    {
      type: "page",
      name: NESTED_DOCS_SECTIONS.gateway.title,
      url: NESTED_DOCS_SECTIONS.gateway.entryUrl,
    },
    { type: "page", name: "Autofix", url: "/docs/autofix" },
    {
      type: "page",
      name: NESTED_DOCS_SECTIONS.reliability.title,
      url: NESTED_DOCS_SECTIONS.reliability.entryUrl,
    },
    { type: "page", name: "Deploy your app", url: "/docs/deploy" },
  ],
};

export function isPathWithin(pathname: string, prefix: string): boolean {
  return pathname === prefix || pathname.startsWith(`${prefix}/`);
}

export function getNestedRootForEntryUrl(url: string): NestedDocsRoot | undefined {
  return (Object.entries(NESTED_DOCS_SECTIONS) as [NestedDocsRoot, NestedSection][]).find(
    ([, section]) => section.entryUrl === url,
  )?.[0];
}

export function getNestedRootForPathname(pathname: string): NestedDocsRoot | undefined {
  return (Object.entries(NESTED_DOCS_SECTIONS) as [NestedDocsRoot, NestedSection][])
    .sort(([, a], [, b]) => b.pathPrefix.length - a.pathPrefix.length)
    .find(([, section]) => isPathWithin(pathname, section.pathPrefix))?.[0];
}

export function getDefaultSidebarMode(pathname: string): SidebarMode {
  if (isPathWithin(pathname, COOKBOOKS_URL)) return { kind: "cookbooks" };
  if (isPathWithin(pathname, INTEGRATIONS_URL)) return { kind: "integrations" };
  if (isPathWithin(pathname, DEMOS_URL)) return { kind: "demos" };
  if (isPathWithin(pathname, API_REFERENCE_URL)) return { kind: "api-reference" };

  if (pathname === "/docs/overview" || promotedGlobalUrls.has(pathname)) {
    return { kind: "global" };
  }

  const root = getNestedRootForPathname(pathname);
  return root ? { kind: "nested", root } : { kind: "global" };
}

export function getSidebarModeForPathname(
  pathname: string,
  override?: SidebarModeOverride,
): SidebarMode {
  return override?.pathname === pathname ? override.mode : getDefaultSidebarMode(pathname);
}

export function getGlobalActiveItemUrl(pathname: string): string | undefined {
  if (promotedGlobalUrls.has(pathname)) return pathname;

  let root = getNestedRootForPathname(pathname);
  // A section entered from another one highlights its parent in the global sidebar.
  while (root && NESTED_DOCS_SECTIONS[root].parent) root = NESTED_DOCS_SECTIONS[root].parent;
  return root ? NESTED_DOCS_SECTIONS[root].entryUrl : undefined;
}

function findNestedFolder(nodes: PageTree.Node[], treeFolder: string): PageTree.Folder | undefined {
  for (const node of nodes) {
    if (node.type !== "folder") continue;
    if (node.$ref?.folder === treeFolder) return node;

    const nested = findNestedFolder(node.children, treeFolder);
    if (nested) return nested;
  }

  return undefined;
}

/** The sidebar for a top-level tab (Cookbooks, Integrations, Demos, API Reference) is its content folder. */
export function getTabTree(tree: PageTree.Root, treeFolder: TabFolder): PageTree.Root {
  const folder = findNestedFolder(tree.children, treeFolder);
  if (!folder) throw new Error(`Docs folder "${treeFolder}" was not found in the page tree.`);

  return {
    type: "root",
    $id: `docs:${treeFolder}`,
    name: folder.name,
    children: folder.children,
  };
}

export function getNestedDocsTree(tree: PageTree.Root, root: NestedDocsRoot): PageTree.Root {
  const folder = findNestedFolder(tree.children, NESTED_DOCS_SECTIONS[root].treeFolder);
  if (!folder) throw new Error(`Nested docs root "${root}" was not found in the page tree.`);

  if (root === "build-agents") {
    const chatUIIndex = folder.children.findIndex(
      (node) => node.type === "separator" && node.name === "Chat UI",
    );
    if (chatUIIndex < 0 || folder.children[chatUIIndex + 1]?.type !== "page") {
      throw new Error('Build Agents "Chat UI" group was not found in the page tree.');
    }
    // The Chat UI group opens with its "Choose a chat UI" page.
    const insertIndex = chatUIIndex + 2;
    const agentInterface = NESTED_DOCS_SECTIONS["agent-interface"];

    // Agent Interface is the first chat UI option, right after the page that compares them.
    // It has its own sidebar, so it appears here as an entry into that section.
    return {
      type: "root",
      $id: "docs:nested:build-agents",
      name: "Build Agents",
      children: [
        ...folder.children.slice(0, insertIndex),
        { type: "page", name: agentInterface.title, url: agentInterface.entryUrl },
        ...folder.children.slice(insertIndex),
      ],
    };
  }

  return {
    type: "root",
    $id: `docs:nested:${root}`,
    name: folder.name,
    children: folder.children,
  };
}