@acmekit/docs-app 2.13.43

package/dist/index.mjs

@@ -0,0 +1,490 @@
+// src/docs-app.tsx
+import { Suspense as Suspense2, useEffect as useEffect3, useRef as useRef3 } from "react";
+import { BrowserRouter, Routes, Route } from "react-router-dom";
+import { routes as routes2, components as components2, importers } from "virtual:acmekit/docs-routes";
+import { config as config2 } from "virtual:acmekit/docs-config";
+import { Loading as Loading2 } from "@acmekit/docs-ui";
+
+// src/providers/DocsProviders.tsx
+import { useMemo } from "react";
+import {
+  RootProviders,
+  SiteConfigProvider,
+  ScrollControllerProvider,
+  SidebarProvider,
+  NotificationProvider,
+  PaginationProvider,
+  MainNavProvider,
+  SearchProvider,
+  AiAssistantProvider
+} from "@acmekit/docs-ui";
+import { jsx } from "react/jsx-runtime";
+function DocsProviders({ children, config: config3 }) {
+  const navItems = useMemo(() => {
+    if (!config3.areas?.length) {
+      return [];
+    }
+    return config3.areas.map((area) => ({
+      type: "link",
+      link: `/${area.id}`,
+      title: area.title
+    }));
+  }, [config3.areas]);
+  return /* @__PURE__ */ jsx(RootProviders, { children: /* @__PURE__ */ jsx(
+    SiteConfigProvider,
+    {
+      config: {
+        baseUrl: "",
+        basePath: config3.basePath,
+        sidebars: config3.sidebars || [],
+        project: {
+          title: config3.title || "Documentation",
+          key: "docs"
+        },
+        logo: config3.logo || "",
+        version: config3.version
+      },
+      children: /* @__PURE__ */ jsx(ScrollControllerProvider, { scrollableSelector: "#main", children: /* @__PURE__ */ jsx(
+        SidebarProvider,
+        {
+          sidebars: config3.sidebars || [],
+          isSidebarStatic: true,
+          shouldHandlePathChange: true,
+          children: /* @__PURE__ */ jsx(NotificationProvider, { children: /* @__PURE__ */ jsx(PaginationProvider, { children: /* @__PURE__ */ jsx(MainNavProvider, { navItems, children: /* @__PURE__ */ jsx(SearchProvider, { children: /* @__PURE__ */ jsx(AiAssistantProvider, { children }) }) }) }) })
+        }
+      ) })
+    }
+  ) });
+}
+
+// src/components/Layout.tsx
+import React2 from "react";
+import { Outlet, useLocation } from "react-router-dom";
+import {
+  Sidebar,
+  MainNav,
+  ContentMenu,
+  Breadcrumbs,
+  Footer,
+  useIsBrowser,
+  useLayout,
+  useSidebar,
+  useSiteConfig
+} from "@acmekit/docs-ui";
+import clsx from "clsx";
+import { jsx as jsx2, jsxs } from "react/jsx-runtime";
+function Layout() {
+  const { isBrowser } = useIsBrowser();
+  const { desktopSidebarOpen, sidebars } = useSidebar();
+  const { mainContentRef, showCollapsedNavbar } = useLayout();
+  const { frontmatter } = useSiteConfig();
+  const { pathname } = useLocation();
+  const isAreasRoot = pathname === "/" && sidebars.length > 1;
+  React2.useEffect(() => {
+    if (!isBrowser) return;
+    const rootLayout = document.getElementById("root-layout");
+    if (desktopSidebarOpen && !isAreasRoot) {
+      rootLayout?.classList.add("lg:grid-cols-[221px_1fr]");
+    } else {
+      rootLayout?.classList.remove("lg:grid-cols-[221px_1fr]");
+    }
+  }, [desktopSidebarOpen, isBrowser, isAreasRoot]);
+  const showContentMenu = !frontmatter.hide_content_menu && !isAreasRoot;
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      className: clsx(
+        "bg-acmekit-bg-subtle font-base text-medium w-full",
+        "text-acmekit-fg-base",
+        "h-full overflow-hidden",
+        "grid grid-cols-1 lg:mx-auto",
+        !isAreasRoot && "lg:grid-cols-[221px_1fr]"
+      ),
+      id: "root-layout",
+      children: [
+        !isAreasRoot && /* @__PURE__ */ jsx2(Sidebar, {}),
+        /* @__PURE__ */ jsx2("div", { className: "relative h-screen flex", children: /* @__PURE__ */ jsx2(
+          "div",
+          {
+            className: clsx(
+              "relative max-w-full",
+              "h-full flex-1",
+              "flex flex-col",
+              "gap-docs_0.5 lg:py-docs_0.25 lg:mr-docs_0.25 scroll-m-docs_0.25",
+              !desktopSidebarOpen && "lg:ml-docs_0.25"
+            ),
+            children: /* @__PURE__ */ jsxs(
+              "div",
+              {
+                className: clsx(
+                  "bg-acmekit-bg-base",
+                  "flex-col items-center",
+                  "h-full w-full",
+                  "overflow-y-scroll overflow-x-hidden",
+                  "md:rounded-docs_DEFAULT",
+                  "shadow-elevation-card-rest dark:shadow-elevation-card-rest-dark"
+                ),
+                id: "main",
+                ref: mainContentRef,
+                children: [
+                  /* @__PURE__ */ jsx2(MainNav, {}),
+                  /* @__PURE__ */ jsx2(
+                    "div",
+                    {
+                      className: clsx(
+                        "pt-docs_4 lg:pt-docs_6 pb-docs_8 lg:pb-docs_4",
+                        showContentMenu && "grid grid-cols-1 lg:mx-auto",
+                        desktopSidebarOpen && showContentMenu && "lg:grid-cols-[1fr_221px]"
+                      ),
+                      id: "content",
+                      children: /* @__PURE__ */ jsx2("div", { className: "flex justify-center", children: /* @__PURE__ */ jsxs(
+                        "div",
+                        {
+                          className: clsx(
+                            "w-full h-fit",
+                            "max-w-inner-content-xs sm:max-w-inner-content-sm",
+                            "md:max-w-inner-content-md lg:max-w-inner-content-lg",
+                            "xl:max-w-inner-content-xl xxl:max-w-inner-content-xxl",
+                            "xxxl:max-w-inner-content-xxxl",
+                            "px-docs_1 md:px-docs_4 lg:px-0"
+                          ),
+                          children: [
+                            /* @__PURE__ */ jsx2(Breadcrumbs, {}),
+                            /* @__PURE__ */ jsx2(Outlet, {}),
+                            /* @__PURE__ */ jsx2(Footer, { showPagination: true })
+                          ]
+                        }
+                      ) })
+                    }
+                  ),
+                  showContentMenu && /* @__PURE__ */ jsx2(ContentMenu, {})
+                ]
+              }
+            )
+          }
+        ) })
+      ]
+    }
+  );
+}
+
+// src/components/DocPage.tsx
+import { useEffect, useRef } from "react";
+import { useLocation as useLocation2 } from "react-router-dom";
+import { useSiteConfig as useSiteConfig2 } from "@acmekit/docs-ui";
+
+// src/components/MDXContent.tsx
+import { MDXProvider } from "@mdx-js/react";
+import { MDXComponents } from "@acmekit/docs-ui";
+import { jsx as jsx3 } from "react/jsx-runtime";
+function MDXContent({ children }) {
+  return /* @__PURE__ */ jsx3(MDXProvider, { components: MDXComponents, children });
+}
+
+// src/components/DocPage.tsx
+import { jsx as jsx4 } from "react/jsx-runtime";
+function DocPage({ children, frontmatter }) {
+  const { setFrontmatter, setToc } = useSiteConfig2();
+  const location = useLocation2();
+  const articleRef = useRef(null);
+  useEffect(() => {
+    setFrontmatter({
+      ...frontmatter,
+      generate_toc: true
+    });
+    setToc([]);
+  }, [location.pathname, frontmatter]);
+  return /* @__PURE__ */ jsx4("article", { ref: articleRef, children: /* @__PURE__ */ jsx4(MDXContent, { children }) });
+}
+
+// src/components/HomePage.tsx
+import { Suspense } from "react";
+import { Link } from "react-router-dom";
+import { Loading } from "@acmekit/docs-ui";
+import { config } from "virtual:acmekit/docs-config";
+import { routes, components } from "virtual:acmekit/docs-routes";
+import { Fragment, jsx as jsx5, jsxs as jsxs2 } from "react/jsx-runtime";
+function HomePage() {
+  const rootRoute = routes.find((r) => r.path === "/");
+  const RootComponent = components["/"];
+  if (RootComponent) {
+    return /* @__PURE__ */ jsx5(DocPage, { frontmatter: rootRoute?.frontmatter, children: /* @__PURE__ */ jsx5(Suspense, { fallback: /* @__PURE__ */ jsx5(Loading, { count: 8 }), children: /* @__PURE__ */ jsx5(RootComponent, {}) }) });
+  }
+  if (config.areas?.length) {
+    const plugins = config.plugins || [];
+    return /* @__PURE__ */ jsxs2("div", { className: "py-docs_2", children: [
+      /* @__PURE__ */ jsx5("h1", { className: "text-docs-h1 font-docs-heading text-acmekit-fg-base mb-docs_0.5", children: config.title }),
+      /* @__PURE__ */ jsx5("p", { className: "text-body-regular text-acmekit-fg-muted mb-docs_2", children: "Browse the documentation areas below." }),
+      /* @__PURE__ */ jsx5("div", { className: "grid gap-docs_1 sm:grid-cols-2 lg:grid-cols-3", children: config.areas.map((area) => {
+        const sidebar = config.sidebars?.find(
+          (s) => s.sidebar_id === area.sidebar_id
+        );
+        const count = sidebar?.items?.length ?? 0;
+        return /* @__PURE__ */ jsxs2(
+          Link,
+          {
+            to: `/${area.id}`,
+            className: "group block rounded-docs_DEFAULT border border-acmekit-border-base bg-acmekit-bg-base p-docs_1.5 no-underline transition-all hover:shadow-elevation-card-hover dark:hover:shadow-elevation-card-hover-dark",
+            children: [
+              /* @__PURE__ */ jsx5("h3", { className: "text-compact-medium-plus text-acmekit-fg-base mb-docs_0.25 group-hover:text-acmekit-fg-interactive", children: area.title }),
+              /* @__PURE__ */ jsxs2("p", { className: "text-compact-small text-acmekit-fg-muted", children: [
+                count,
+                " ",
+                count === 1 ? "section" : "sections"
+              ] })
+            ]
+          },
+          area.id
+        );
+      }) }),
+      plugins.length > 0 && /* @__PURE__ */ jsxs2(Fragment, { children: [
+        /* @__PURE__ */ jsx5("h2", { className: "text-docs-h2 font-docs-heading text-acmekit-fg-base mt-docs_2 mb-docs_1", children: "Plugins" }),
+        /* @__PURE__ */ jsx5("div", { className: "grid gap-docs_1 sm:grid-cols-2 lg:grid-cols-3", children: plugins.map((plugin) => {
+          const sidebar = config.sidebars?.find(
+            (s) => s.sidebar_id === plugin.sidebar_id
+          );
+          const count = sidebar?.items?.length ?? 0;
+          return /* @__PURE__ */ jsxs2(
+            Link,
+            {
+              to: `/plugins/${plugin.slug}`,
+              className: "group block rounded-docs_DEFAULT border border-acmekit-border-base bg-acmekit-bg-base p-docs_1.5 no-underline transition-all hover:shadow-elevation-card-hover dark:hover:shadow-elevation-card-hover-dark",
+              children: [
+                /* @__PURE__ */ jsx5("h3", { className: "text-compact-medium-plus text-acmekit-fg-base mb-docs_0.25 group-hover:text-acmekit-fg-interactive", children: plugin.title }),
+                plugin.description && /* @__PURE__ */ jsx5("p", { className: "text-compact-small text-acmekit-fg-muted mb-docs_0.25", children: plugin.description }),
+                /* @__PURE__ */ jsxs2("p", { className: "text-compact-small text-acmekit-fg-subtle", children: [
+                  count,
+                  " ",
+                  count === 1 ? "page" : "pages"
+                ] })
+              ]
+            },
+            plugin.slug
+          );
+        }) })
+      ] })
+    ] });
+  }
+  const categories = (config.sidebars?.[0]?.items || []).filter(
+    (item) => item.type === "category" && item.children?.length
+  );
+  return /* @__PURE__ */ jsxs2("div", { className: "py-docs_2", children: [
+    /* @__PURE__ */ jsx5("h1", { className: "text-docs-h1 font-docs-heading text-acmekit-fg-base mb-docs_0.5", children: config.title }),
+    /* @__PURE__ */ jsx5("p", { className: "text-body-regular text-acmekit-fg-muted mb-docs_2", children: "Browse the documentation to get started." }),
+    categories.length > 0 && /* @__PURE__ */ jsx5("div", { className: "grid gap-docs_1 sm:grid-cols-2 lg:grid-cols-3", children: categories.map((cat) => {
+      const firstLink = cat.children?.find(
+        (c) => c.type === "link" && c.path
+      );
+      const targetPath = firstLink?.path || "/";
+      return /* @__PURE__ */ jsxs2(
+        Link,
+        {
+          to: targetPath,
+          className: "group block rounded-docs_DEFAULT border border-acmekit-border-base bg-acmekit-bg-base p-docs_1.5 no-underline transition-all hover:shadow-elevation-card-hover dark:hover:shadow-elevation-card-hover-dark",
+          children: [
+            /* @__PURE__ */ jsx5("h3", { className: "text-compact-medium-plus text-acmekit-fg-base mb-docs_0.25 group-hover:text-acmekit-fg-interactive", children: cat.title }),
+            /* @__PURE__ */ jsxs2("p", { className: "text-compact-small text-acmekit-fg-muted", children: [
+              cat.children?.length,
+              " ",
+              cat.children?.length === 1 ? "article" : "articles"
+            ] })
+          ]
+        },
+        cat.title
+      );
+    }) })
+  ] });
+}
+
+// src/components/RouteErrorBoundary.tsx
+import React5 from "react";
+import { ErrorPage } from "@acmekit/docs-ui";
+import { jsx as jsx6 } from "react/jsx-runtime";
+var RouteErrorBoundary = class extends React5.Component {
+  constructor() {
+    super(...arguments);
+    this.state = { hasError: false };
+  }
+  static getDerivedStateFromError() {
+    return { hasError: true };
+  }
+  render() {
+    if (this.state.hasError) {
+      return /* @__PURE__ */ jsx6(ErrorPage, {});
+    }
+    return this.props.children;
+  }
+};
+
+// src/components/SearchModal.tsx
+import React6, { useCallback, useEffect as useEffect2, useRef as useRef2, useState } from "react";
+import { useNavigate } from "react-router-dom";
+import { SearchInput, useSearch } from "@acmekit/docs-ui";
+import { searchIndex } from "virtual:acmekit/docs-search";
+import { jsx as jsx7, jsxs as jsxs3 } from "react/jsx-runtime";
+function scoreEntry(entry, words) {
+  let score = 0;
+  const title = entry.title.toLowerCase();
+  const desc = entry.description.toLowerCase();
+  const body = entry.body.toLowerCase();
+  for (const word of words) {
+    if (title.includes(word)) score += 3;
+    if (desc.includes(word)) score += 2;
+    if (body.includes(word)) score += 1;
+  }
+  return score;
+}
+function SearchModal() {
+  const { isOpen, setIsOpen, modalRef } = useSearch();
+  const [query, setQuery] = useState("");
+  const [activeIndex, setActiveIndex] = useState(0);
+  const navigate = useNavigate();
+  const searchWrapperRef = useRef2(null);
+  const results = React6.useMemo(() => {
+    if (!query.trim()) return [];
+    const words = query.toLowerCase().split(/\s+/).filter((w) => w.length > 0);
+    return searchIndex.map((entry) => ({
+      path: entry.path,
+      title: entry.title,
+      description: entry.description,
+      score: scoreEntry(entry, words)
+    })).filter((r) => r.score > 0).sort((a, b) => b.score - a.score).slice(0, 20);
+  }, [query]);
+  useEffect2(() => {
+    setActiveIndex(0);
+  }, [results]);
+  useEffect2(() => {
+    function onKeyDown2(e) {
+      if ((e.metaKey || e.ctrlKey) && e.key === "k") {
+        e.preventDefault();
+        setIsOpen((prev) => !prev);
+      }
+    }
+    document.addEventListener("keydown", onKeyDown2);
+    return () => document.removeEventListener("keydown", onKeyDown2);
+  }, [setIsOpen]);
+  useEffect2(() => {
+    const dialog = modalRef.current;
+    if (!dialog) return;
+    if (isOpen) {
+      dialog.showModal();
+      searchWrapperRef.current?.querySelector("input")?.focus();
+    } else {
+      dialog.close();
+      setQuery("");
+    }
+  }, [isOpen, modalRef]);
+  const navigateTo = useCallback(
+    (path) => {
+      navigate(path);
+      setIsOpen(false);
+    },
+    [navigate, setIsOpen]
+  );
+  function onKeyDown(e) {
+    if (e.key === "ArrowDown") {
+      e.preventDefault();
+      setActiveIndex((i) => Math.min(i + 1, results.length - 1));
+    } else if (e.key === "ArrowUp") {
+      e.preventDefault();
+      setActiveIndex((i) => Math.max(i - 1, 0));
+    } else if (e.key === "Enter" && results[activeIndex]) {
+      e.preventDefault();
+      navigateTo(results[activeIndex].path);
+    }
+  }
+  return /* @__PURE__ */ jsx7(
+    "dialog",
+    {
+      ref: modalRef,
+      className: "fixed inset-0 z-50 m-0 h-full w-full max-h-full max-w-full bg-transparent p-0 backdrop:bg-acmekit-bg-overlay",
+      onClick: (e) => {
+        if (e.target === e.currentTarget) setIsOpen(false);
+      },
+      onClose: () => setIsOpen(false),
+      children: /* @__PURE__ */ jsxs3("div", { className: "mx-auto mt-[15vh] w-full max-w-[540px] rounded-docs_DEFAULT border border-acmekit-border-base bg-acmekit-bg-base shadow-elevation-modal dark:shadow-elevation-modal-dark", children: [
+        /* @__PURE__ */ jsx7("div", { ref: searchWrapperRef, className: "p-docs_1", onKeyDown, children: /* @__PURE__ */ jsx7(
+          SearchInput,
+          {
+            value: query,
+            onChange: setQuery,
+            placeholder: "Search documentation...",
+            autoFocus: true
+          }
+        ) }),
+        results.length > 0 && /* @__PURE__ */ jsx7("ul", { className: "max-h-[50vh] overflow-y-auto border-t border-acmekit-border-base p-docs_0.5", children: results.map((result, i) => /* @__PURE__ */ jsx7("li", { children: /* @__PURE__ */ jsxs3(
+          "button",
+          {
+            type: "button",
+            className: `w-full rounded-docs_sm px-docs_1 py-docs_0.5 text-left transition-colors ${i === activeIndex ? "bg-acmekit-bg-base-hover" : "hover:bg-acmekit-bg-base-hover"}`,
+            onMouseEnter: () => setActiveIndex(i),
+            onClick: () => navigateTo(result.path),
+            children: [
+              /* @__PURE__ */ jsx7("span", { className: "text-compact-small-plus text-acmekit-fg-base block", children: result.title }),
+              result.description && /* @__PURE__ */ jsx7("span", { className: "text-compact-x-small text-acmekit-fg-muted block truncate", children: result.description })
+            ]
+          }
+        ) }, result.path)) }),
+        query.trim() && results.length === 0 && /* @__PURE__ */ jsx7("div", { className: "border-t border-acmekit-border-base p-docs_1 text-center", children: /* @__PURE__ */ jsx7("span", { className: "text-compact-small text-acmekit-fg-muted", children: "No results found" }) })
+      ] })
+    }
+  );
+}
+
+// src/docs-app.tsx
+import { jsx as jsx8, jsxs as jsxs4 } from "react/jsx-runtime";
+function DocsApp({ plugins = [] }) {
+  const allRoutes = [...routes2];
+  const prefetched = useRef3(/* @__PURE__ */ new Set());
+  for (const plugin of plugins) {
+    if (plugin.routes) {
+      allRoutes.push(...plugin.routes);
+    }
+  }
+  useEffect3(() => {
+    function onMouseOver(e) {
+      const anchor = e.target.closest?.("a");
+      if (!anchor) return;
+      const href = anchor.getAttribute("href");
+      if (!href || prefetched.current.has(href)) return;
+      const importer = importers[href];
+      if (importer) {
+        prefetched.current.add(href);
+        importer();
+      }
+    }
+    document.addEventListener("mouseover", onMouseOver);
+    return () => document.removeEventListener("mouseover", onMouseOver);
+  }, []);
+  return /* @__PURE__ */ jsx8(BrowserRouter, { basename: config2.basePath, children: /* @__PURE__ */ jsx8(DocsProviders, { config: config2, children: /* @__PURE__ */ jsxs4("div", { className: "h-screen w-full overflow-hidden", children: [
+    /* @__PURE__ */ jsx8(RouteErrorBoundary, { children: /* @__PURE__ */ jsx8(Suspense2, { fallback: /* @__PURE__ */ jsx8(Loading2, { count: 8 }), children: /* @__PURE__ */ jsx8(Routes, { children: /* @__PURE__ */ jsxs4(Route, { element: /* @__PURE__ */ jsx8(Layout, {}), children: [
+      /* @__PURE__ */ jsx8(Route, { index: true, element: /* @__PURE__ */ jsx8(HomePage, {}) }),
+      allRoutes.map((route) => {
+        const Component = components2[route.path];
+        if (!Component) return null;
+        if (route.type === "mdx") {
+          return /* @__PURE__ */ jsx8(
+            Route,
+            {
+              path: route.path,
+              element: /* @__PURE__ */ jsx8(DocPage, { frontmatter: route.frontmatter, children: /* @__PURE__ */ jsx8(Suspense2, { fallback: /* @__PURE__ */ jsx8(Loading2, { count: 8 }), children: /* @__PURE__ */ jsx8(Component, {}) }) })
+            },
+            route.path
+          );
+        }
+        return /* @__PURE__ */ jsx8(
+          Route,
+          {
+            path: route.path,
+            element: /* @__PURE__ */ jsx8(Suspense2, { fallback: /* @__PURE__ */ jsx8(Loading2, { count: 8 }), children: /* @__PURE__ */ jsx8(Component, {}) })
+          },
+          route.path
+        );
+      })
+    ] }) }) }) }),
+    /* @__PURE__ */ jsx8(SearchModal, {})
+  ] }) }) });
+}
+export {
+  DocsApp
+};

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@acmekit/docs-app",
+  "description": "React SPA for AcmeKit documentation.",
+  "version": "2.13.43",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    },
+    "./entry-server": "./src/entry-server.tsx",
+    "./package.json": "./package.json"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/acmekit/acmekit",
+    "directory": "packages/docs/docs-app"
+  },
+  "files": [
+    "dist",
+    "src",
+    "package.json"
+  ],
+  "scripts": {
+    "build": "yarn run -T tsup",
+    "watch": "yarn run -T tsup --watch",
+    "test": "yarn run -T vitest --run"
+  },
+  "dependencies": {
+    "@acmekit/docs-shared": "^2.13.43",
+    "@acmekit/docs-ui": "^2.13.43",
+    "@mdx-js/react": "^3.0.0",
+    "clsx": "^2.0.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "react-router-dom": "^6.26.2"
+  },
+  "devDependencies": {
+    "@types/react": "^18.2.0",
+    "@types/react-dom": "^18.2.0"
+  },
+  "peerDependencies": {
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  },
+  "packageManager": "yarn@3.2.1"
+}

package/src/__tests__/build-routes.spec.ts

@@ -0,0 +1,134 @@
+import { describe, expect, it } from "vitest"
+import type { DocsRouteEntry } from "@acmekit/docs-shared"
+import { buildRoutes } from "../routes/build-routes"
+
+// Mock React component type
+const MockComponentA = (() => null) as any
+const MockComponentB = (() => null) as any
+const MockComponentC = (() => null) as any
+
+describe("buildRoutes", () => {
+  it("should filter routes to only those with matching components", () => {
+    const routes: DocsRouteEntry[] = [
+      {
+        path: "/a",
+        componentPath: "/src/a.mdx",
+        type: "mdx",
+        frontmatter: { title: "A" },
+      },
+      {
+        path: "/b",
+        componentPath: "/src/b.mdx",
+        type: "mdx",
+        frontmatter: { title: "B" },
+      },
+      {
+        path: "/c",
+        componentPath: "/src/c.tsx",
+        type: "tsx",
+      },
+    ]
+
+    const components = {
+      "/a": MockComponentA,
+      "/c": MockComponentC,
+      // /b is intentionally missing
+    }
+
+    const result = buildRoutes(routes, components)
+
+    expect(result).toHaveLength(2)
+    expect(result.map((r) => r.path)).toEqual(["/a", "/c"])
+  })
+
+  it("should attach component reference to each route", () => {
+    const routes: DocsRouteEntry[] = [
+      {
+        path: "/page",
+        componentPath: "/src/page.mdx",
+        type: "mdx",
+        frontmatter: { title: "Page" },
+      },
+    ]
+
+    const components = { "/page": MockComponentA }
+
+    const result = buildRoutes(routes, components)
+
+    expect(result[0].component).toBe(MockComponentA)
+  })
+
+  it("should preserve all original route properties", () => {
+    const routes: DocsRouteEntry[] = [
+      {
+        path: "/test",
+        componentPath: "/src/test.mdx",
+        type: "mdx",
+        frontmatter: { title: "Test", sidebar_position: 5 },
+      },
+    ]
+
+    const components = { "/test": MockComponentA }
+
+    const result = buildRoutes(routes, components)
+
+    expect(result[0].path).toBe("/test")
+    expect(result[0].componentPath).toBe("/src/test.mdx")
+    expect(result[0].type).toBe("mdx")
+    expect(result[0].frontmatter).toEqual({
+      title: "Test",
+      sidebar_position: 5,
+    })
+  })
+
+  it("should return empty array when no routes match", () => {
+    const routes: DocsRouteEntry[] = [
+      {
+        path: "/missing",
+        componentPath: "/src/missing.mdx",
+        type: "mdx",
+      },
+    ]
+
+    const result = buildRoutes(routes, {})
+
+    expect(result).toEqual([])
+  })
+
+  it("should return empty array for empty inputs", () => {
+    expect(buildRoutes([], {})).toEqual([])
+  })
+
+  it("should handle all routes having components", () => {
+    const routes: DocsRouteEntry[] = [
+      { path: "/a", componentPath: "/src/a.mdx", type: "mdx" },
+      { path: "/b", componentPath: "/src/b.mdx", type: "mdx" },
+    ]
+
+    const components = {
+      "/a": MockComponentA,
+      "/b": MockComponentB,
+    }
+
+    const result = buildRoutes(routes, components)
+
+    expect(result).toHaveLength(2)
+  })
+
+  it("should ignore extra components not in routes", () => {
+    const routes: DocsRouteEntry[] = [
+      { path: "/a", componentPath: "/src/a.mdx", type: "mdx" },
+    ]
+
+    const components = {
+      "/a": MockComponentA,
+      "/extra": MockComponentB,
+      "/unused": MockComponentC,
+    }
+
+    const result = buildRoutes(routes, components)
+
+    expect(result).toHaveLength(1)
+    expect(result[0].path).toBe("/a")
+  })
+})