boltdocs 1.10.2 → 2.0.0

package/src/client/app/index.tsx

@@ -1,90 +1,22 @@
-import React, { useEffect, useState } from "react";
-import ReactDOM from "react-dom/client";
-import {
-  BrowserRouter,
-  Routes,
-  Route,
-  Outlet,
-  useLocation,
-} from "react-router-dom";
-import { ThemeLayout } from "../theme/ui/Layout";
-import { NotFound } from "../theme/ui/NotFound";
-import { Loading } from "../theme/ui/Loading";
-import { MDXProvider } from "@mdx-js/react";
-import { ComponentRoute, CreateBoltdocsAppOptions } from "../types";
-import {
-  createContext,
-  useContext,
-  Suspense,
-  lazy,
-  useLayoutEffect,
-} from "react";
-import { Link as LucideLink } from "lucide-react";
-
-export const ConfigContext = createContext<any>(null);
-
-export function useConfig() {
-  return useContext(ConfigContext);
-}
-
-import { CodeBlock } from "../theme/components/CodeBlock";
-const Video = lazy(() =>
-  import("../theme/components/Video").then((m) => ({ default: m.Video })),
-);
-const PackageManagerTabs = lazy(() =>
-  import("../theme/components/PackageManagerTabs").then((m) => ({
-    default: m.PackageManagerTabs,
-  })),
-);
-declare global {
-  interface ImportMeta {
-    env: Record<string, any>;
-  }
-}
-
-import { PreloadProvider } from "./preload";
-
-const Heading = ({
-  level,
-  id,
-  children,
-}: {
-  level: number;
-  id?: string;
-  children: React.ReactNode;
-}) => {
-  const Tag = `h${level}` as keyof JSX.IntrinsicElements;
-  return (
-    <Tag id={id} className="boltdocs-heading">
-      {children}
-      {id && (
-        <a href={`#${id}`} className="header-anchor" aria-label="Anchor">
-          <LucideLink size={16} />
-        </a>
-      )}
-    </Tag>
-  );
-};
-
-const mdxComponents = {
-  h1: (props: any) => <Heading level={1} {...props} />,
-  h2: (props: any) => <Heading level={2} {...props} />,
-  h3: (props: any) => <Heading level={3} {...props} />,
-  h4: (props: any) => <Heading level={4} {...props} />,
-  h5: (props: any) => <Heading level={5} {...props} />,
-  h6: (props: any) => <Heading level={6} {...props} />,
-  pre: (props: any) => <CodeBlock {...props}>{props.children}</CodeBlock>,
-  video: (props: any) => (
-    <Suspense fallback={<div className="video-skeleton" />}>
-      <Video {...props} />
-    </Suspense>
-  ),
-  PackageManagerTabs: (props: any) => (
-    <Suspense fallback={<div className="pkg-tabs-skeleton" />}>
-      <PackageManagerTabs {...props} />
-    </Suspense>
-  ),
-};
+import React, { useEffect, useState, useMemo } from 'react'
+import ReactDOM from 'react-dom/client'
+import { BrowserRouter, Routes, Route } from 'react-router-dom'
+import { NotFound } from '@components/ui-base/not-found'
+import { Loading } from '@components/ui-base/loading'
+import { ThemeProvider } from './theme-context'
+import type { ComponentRoute, CreateBoltdocsAppOptions } from '../types'
+import type { BoltdocsConfig } from '@node/config'
+
+import UserLayout from 'virtual:boltdocs-layout'
+
+import { PreloadProvider } from './preload'
+import { BoltdocsRouterProvider } from './router'
+import { ConfigContext } from './config-context'
+import { ScrollHandler } from './scroll-handler'
+import { DocsLayout } from './docs-layout'
+import { MdxPage } from './mdx-page'
+import { MdxComponentsProvider } from './mdx-components-context'
+import { mdxComponentsDefault } from './mdx-component'
 
 export function AppShell({
   initialRoutes,
@@ -93,194 +25,127 @@ export function AppShell({
   modules,
   hot,
   homePage: HomePage,
+  externalPages,
   components: customComponents = {},
 }: {
-  initialRoutes: ComponentRoute[];
-  initialConfig: any;
-  docsDirName: string;
-  modules: Record<string, () => Promise<any>>;
-  hot?: any;
-  homePage?: React.ComponentType;
-  components?: Record<string, React.ComponentType<any>>;
+  initialRoutes: ComponentRoute[]
+  initialConfig: BoltdocsConfig
+  docsDirName: string
+  modules: Record<string, () => Promise<{ default: React.ComponentType<any> }>>
+  hot?: CreateBoltdocsAppOptions['hot']
+  homePage?: React.ComponentType
+  externalPages?: Record<string, React.ComponentType>
+  components?: Record<string, React.ComponentType>
 }) {
-  const [routesInfo, setRoutesInfo] = useState<ComponentRoute[]>(initialRoutes);
-  const [config] = useState(initialConfig);
+  const [routesInfo, setRoutesInfo] = useState<ComponentRoute[]>(initialRoutes)
+  const [config] = useState(initialConfig)
+  const computedExternalPages = externalPages || {}
 
-  const resolveRoutes = (infos: ComponentRoute[]) => {
-    return infos
+  const resolvedRoutes = useMemo(() => {
+    return routesInfo
       .filter(
-        (route) => !(HomePage && (route.path === "/" || route.path === "")),
+        (route) =>
+          !(HomePage && (route.path === '/' || route.path === '')) &&
+          !computedExternalPages[route.path === '' ? '/' : route.path],
       )
       .map((route) => {
         const loaderKey = Object.keys(modules).find(
-          (k) => k === `/${docsDirName}/${route.filePath}`,
-        );
-        const loader = loaderKey ? modules[loaderKey] : null;
+          (k) =>
+            k === `/${docsDirName}/${route.filePath}` || // Vite dev/build relative path
+            k.endsWith(`/${docsDirName}/${route.filePath}`) || // SSG absolute path fallback
+            k.endsWith(`/${docsDirName}\\${route.filePath.replace(/\\/g, '/')}`), // Windows fallback
+        )
+        const loader = loaderKey ? modules[loaderKey] : null
 
         return {
           ...route,
-          Component: React.lazy(() => {
-            if (!loader)
-              return Promise.resolve({ default: () => <NotFound /> });
-            return loader() as any;
+          Component: React.lazy<React.ComponentType<any>>(async () => {
+            if (!loader) return { default: NotFound as React.ComponentType<any> }
+            const mod = await loader()
+            return mod
           }),
-        };
-      });
-  };
-
-  const [resolvedRoutes, setResolvedRoutes] = useState<any[]>(() =>
-    resolveRoutes(initialRoutes),
-  );
+        }
+      })
+  }, [routesInfo, modules, docsDirName, HomePage, computedExternalPages])
 
   // Subscribe to HMR events
   useEffect(() => {
     if (hot) {
-      hot.on("boltdocs:routes-update", (newRoutes: ComponentRoute[]) => {
-        setRoutesInfo(newRoutes);
-      });
+      hot.on('boltdocs:routes-update', (newRoutes: ComponentRoute[]) => {
+        setRoutesInfo(newRoutes)
+      })
     }
-  }, [hot]);
+  }, [hot])
 
-  // Sync resolved routes when info or modules change
-  useEffect(() => {
-    setResolvedRoutes(resolveRoutes(routesInfo));
-  }, [routesInfo, modules, docsDirName]);
+  const allComponents = useMemo(
+    () => ({ ...mdxComponentsDefault, ...customComponents }),
+    [customComponents],
+  )
 
   return (
-    <ConfigContext.Provider value={config}>
-      <PreloadProvider routes={routesInfo} modules={modules}>
-        <ScrollHandler />
-        <Routes>
-          {/* Custom home page WITHOUT docs layout */}
-          {HomePage && (
-            <Route
-              path="/"
-              element={
-                <ThemeLayout
-                  config={config}
-                  routes={routesInfo}
-                  sidebar={null}
-                  toc={null}
-                  breadcrumbs={null}
-                  {...config.themeConfig?.layoutProps}
-                >
-                  <HomePage />
-                </ThemeLayout>
-              }
-            />
-          )}
-
-          {/* Documentation pages WITH sidebar + TOC layout */}
-          <Route
-            key="docs-layout"
-            element={<DocsLayout config={config} routes={routesInfo} />}
-          >
-            {resolvedRoutes.map((route: any) => (
-              <Route
-                key={route.path}
-                path={route.path === "" ? "/" : route.path}
-                element={
-                  <React.Suspense fallback={<Loading />}>
-                    <MdxPage
-                      Component={route.Component}
-                      customComponents={customComponents}
+    <ThemeProvider>
+      <MdxComponentsProvider components={allComponents}>
+        <ConfigContext.Provider value={config}>
+          <BoltdocsRouterProvider>
+            <PreloadProvider routes={routesInfo} modules={modules}>
+              <ScrollHandler />
+              <Routes>
+                {/* Custom home page with user layout */}
+                {HomePage && (
+                  <Route
+                    path="/"
+                    element={
+                      <UserLayout>
+                        <HomePage />
+                      </UserLayout>
+                    }
+                  />
+                )}
+
+                {/* Custom External Pages with user layout */}
+                {Object.entries(computedExternalPages).map(
+                  ([extPath, ExtComponent]) => (
+                    <Route
+                      key={extPath}
+                      path={extPath}
+                      element={
+                        <UserLayout>
+                          <ExtComponent />
+                        </UserLayout>
+                      }
                     />
-                  </React.Suspense>
-                }
-              />
-            ))}
-          </Route>
-
-          <Route
-            path="*"
-            element={
-              <ThemeLayout
-                config={config}
-                routes={routesInfo}
-                {...config.themeConfig?.layoutProps}
-              >
-                <NotFound />
-              </ThemeLayout>
-            }
-          />
-        </Routes>
-      </PreloadProvider>
-    </ConfigContext.Provider>
-  );
-}
-
-/**
- * Handles scroll restoration and hash scrolling on navigation.
- */
-function ScrollHandler() {
-  const { pathname, hash } = useLocation();
-
-  useLayoutEffect(() => {
-    const container = document.querySelector(".boltdocs-content");
-    if (!container) return;
-
-    if (hash) {
-      const id = hash.replace("#", "");
-      const element = document.getElementById(id);
-      if (element) {
-        const offset = 80;
-        const containerRect = container.getBoundingClientRect().top;
-        const elementRect = element.getBoundingClientRect().top;
-        const elementPosition = elementRect - containerRect;
-        const offsetPosition = elementPosition - offset + container.scrollTop;
-
-        container.scrollTo({
-          top: offsetPosition,
-          behavior: "smooth",
-        });
-        return;
-      }
-    }
-    container.scrollTo(0, 0);
-  }, [pathname, hash]);
-
-  return null;
-}
-
-/** Wrapper layout for doc pages (sidebar + content + TOC) */
-function DocsLayout({
-  config,
-  routes,
-}: {
-  config: any;
-  routes: ComponentRoute[];
-}) {
-  return (
-    <ThemeLayout
-      config={config}
-      routes={routes}
-      {...config.themeConfig?.layoutProps}
-    >
-      <Outlet />
-    </ThemeLayout>
-  );
-}
-
-/**
- * Renders an MDX page securely, injecting required custom components.
- * For example, this overrides the default `<pre>` HTML tags emitted by MDX
- * with the Boltdocs `CodeBlock` component for syntax highlighting.
- *
- * @param props - Contains the dynamically loaded React component representing the MDX page
- */
-function MdxPage({
-  Component,
-  customComponents = {},
-}: {
-  Component: React.LazyExoticComponent<any>;
-  customComponents?: Record<string, React.ComponentType<any>>;
-}) {
-  const allComponents = { ...mdxComponents, ...customComponents };
-  return (
-    <MDXProvider components={allComponents}>
-      <Component />
-    </MDXProvider>
-  );
+                  ),
+                )}
+
+                <Route key="docs-layout" element={<DocsLayout />}>
+                  {resolvedRoutes.map((route) => (
+                    <Route
+                      key={route.path}
+                      path={route.path === '' ? '/' : route.path}
+                      element={
+                        <React.Suspense fallback={<Loading />}>
+                          <MdxPage Component={route.Component} />
+                        </React.Suspense>
+                      }
+                    />
+                  ))}
+                </Route>
+
+                <Route
+                  path="*"
+                  element={
+                    <UserLayout>
+                      <NotFound />
+                    </UserLayout>
+                  }
+                />
+              </Routes>
+            </PreloadProvider>
+          </BoltdocsRouterProvider>
+        </ConfigContext.Provider>
+      </MdxComponentsProvider>
+    </ThemeProvider>
+  )
 }
 
 /**
@@ -305,13 +170,22 @@ function MdxPage({
  * ```
  */
 export function createBoltdocsApp(options: CreateBoltdocsAppOptions) {
-  const { target, routes, docsDirName, config, modules, hot, homePage } =
-    options;
-  const container = document.querySelector(target);
+  const {
+    target,
+    routes,
+    docsDirName,
+    config,
+    modules,
+    hot,
+    homePage,
+    externalPages,
+    components,
+  } = options
+  const container = document.querySelector(target)
   if (!container) {
     throw new Error(
       `[boltdocs] Mount target "${target}" not found in document.`,
-    );
+    )
   }
 
   const app = (
@@ -324,16 +198,17 @@ export function createBoltdocsApp(options: CreateBoltdocsAppOptions) {
           modules={modules}
           hot={hot}
           homePage={homePage}
-          components={options.components}
+          externalPages={externalPages}
+          components={components}
         />
       </BrowserRouter>
     </React.StrictMode>
-  );
+  )
 
   // SSG pre-renders a shell with mock components for SEO crawlers.
   // We always use createRoot because the SSG output doesn't match the
   // real client-side component tree (components are lazy/dynamic).
   // Clear any SSG placeholder content before mounting.
-  container.innerHTML = "";
-  ReactDOM.createRoot(container as HTMLElement).render(app);
+  container.innerHTML = ''
+  ReactDOM.createRoot(container as HTMLElement).render(app)
 }

package/src/client/app/mdx-component.tsx

@@ -0,0 +1,52 @@
+import type React from 'react'
+import { Link as LucideLink } from 'lucide-react'
+import * as MdxComponents from '@components/mdx'
+
+const Heading = ({
+  level,
+  id,
+  children,
+}: {
+  level: number
+  id?: string
+  children?: React.ReactNode
+}) => {
+  const Tag = `h${level}` as keyof JSX.IntrinsicElements
+  return (
+    <Tag id={id} className="boltdocs-heading">
+      {children}
+      {id && (
+        <a href={`#${id}`} className="header-anchor" aria-label="Anchor">
+          <LucideLink size={16} />
+        </a>
+      )}
+    </Tag>
+  )
+}
+
+export const mdxComponentsDefault = {
+  ...MdxComponents,
+  h1: (props: React.HTMLAttributes<HTMLHeadingElement>) => (
+    <Heading level={1} {...props} />
+  ),
+  h2: (props: React.HTMLAttributes<HTMLHeadingElement>) => (
+    <Heading level={2} {...props} />
+  ),
+  h3: (props: React.HTMLAttributes<HTMLHeadingElement>) => (
+    <Heading level={3} {...props} />
+  ),
+  h4: (props: React.HTMLAttributes<HTMLHeadingElement>) => (
+    <Heading level={4} {...props} />
+  ),
+  h5: (props: React.HTMLAttributes<HTMLHeadingElement>) => (
+    <Heading level={5} {...props} />
+  ),
+  h6: (props: React.HTMLAttributes<HTMLHeadingElement>) => (
+    <Heading level={6} {...props} />
+  ),
+  pre: (props: React.HTMLAttributes<HTMLPreElement>) => (
+    <MdxComponents.CodeBlock {...props}>
+      {props.children}
+    </MdxComponents.CodeBlock>
+  ),
+}

package/src/client/app/mdx-components-context.tsx

@@ -0,0 +1,23 @@
+import React, { createContext, useContext } from 'react'
+
+export type MdxComponentsType = Record<string, React.ComponentType<any>>
+
+const MdxComponentsContext = createContext<MdxComponentsType>({})
+
+export function useMdxComponents() {
+  return useContext(MdxComponentsContext)
+}
+
+export function MdxComponentsProvider({
+  components,
+  children,
+}: {
+  components: MdxComponentsType
+  children: React.ReactNode
+}) {
+  return (
+    <MdxComponentsContext.Provider value={components}>
+      {children}
+    </MdxComponentsContext.Provider>
+  )
+}

package/src/client/app/mdx-page.tsx

@@ -0,0 +1,20 @@
+import React from 'react'
+import { MDXProvider } from '@mdx-js/react'
+import { useMdxComponents } from './mdx-components-context'
+
+/**
+ * Renders an MDX page securely, injecting required custom components.
+ * This overrides the default HTML tags emitted by MDX with stylized components.
+ */
+export function MdxPage({
+  Component,
+}: {
+  Component: React.ComponentType<any>
+}) {
+  const allComponents = useMdxComponents()
+  return (
+    <MDXProvider components={allComponents as any}>
+      <Component />
+    </MDXProvider>
+  )
+}

package/src/client/app/preload.tsx

@@ -1,18 +1,18 @@
-import React, { createContext, useContext, useCallback } from "react";
-import { ComponentRoute } from "../types";
+import { createContext, use, useCallback, useRef } from 'react'
+import type { ComponentRoute } from '../types'
 
 interface PreloadContextType {
-  preload: (path: string) => void;
-  routes: ComponentRoute[];
+  preload: (path: string) => void
+  routes: ComponentRoute[]
 }
 
 const PreloadContext = createContext<PreloadContextType>({
   preload: () => {},
   routes: [],
-});
+})
 
 export function usePreload() {
-  return useContext(PreloadContext);
+  return use(PreloadContext)
 }
 
 export function PreloadProvider({
@@ -20,39 +20,47 @@ export function PreloadProvider({
   modules,
   children,
 }: {
-  routes: ComponentRoute[];
-  modules: Record<string, () => Promise<any>>;
-  children: React.ReactNode;
+  routes: ComponentRoute[]
+  modules: Record<string, () => Promise<unknown>>
+  children: React.ReactNode
 }) {
+  const preloadTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+
   const preload = useCallback(
     (path: string) => {
-      // Normalize path (remove hash and search)
-      const cleanPath = path.split("#")[0].split("?")[0];
-
-      // Support index routes matching "/"
-      const route = routes.find(
-        (r) => r.path === cleanPath || (cleanPath === "/" && r.path === ""),
-      );
-
-      if (route && route.filePath) {
-        const loaderKey = Object.keys(modules).find((k) =>
-          k.endsWith("/" + route.filePath),
-        );
-
-        if (loaderKey) {
-          // Trigger the dynamic import
-          modules[loaderKey]().catch((err: any) => {
-            console.error(`[boltdocs] Failed to preload route ${path}:`, err);
-          });
-        }
+      if (preloadTimerRef.current) {
+        clearTimeout(preloadTimerRef.current)
       }
+
+      preloadTimerRef.current = setTimeout(() => {
+        // Normalize path (remove hash and search)
+        const cleanPath = path.split('#')[0].split('?')[0]
+
+        // Support index routes matching "/"
+        const route = routes.find(
+          (r) => r.path === cleanPath || (cleanPath === '/' && r.path === ''),
+        )
+
+        if (route?.filePath) {
+          const loaderKey = Object.keys(modules).find((k) =>
+            k.endsWith('/' + route.filePath),
+          )
+
+          if (loaderKey) {
+            // Trigger the dynamic import
+            modules[loaderKey]().catch((err: unknown) => {
+              console.error(`[boltdocs] Failed to preload route ${path}:`, err)
+            })
+          }
+        }
+      }, 100) // 100ms debounce
     },
     [routes, modules],
-  );
+  )
 
   return (
     <PreloadContext.Provider value={{ preload, routes }}>
       {children}
     </PreloadContext.Provider>
-  );
+  )
 }

package/src/client/app/router.tsx

@@ -0,0 +1,30 @@
+import type React from 'react'
+import { startTransition } from 'react'
+import { RouterProvider } from 'react-aria-components'
+import { useNavigate, useHref } from 'react-router-dom'
+
+/**
+ * Connects React Aria Components (RAC) to React Router.
+ * This ensures all RAC links and buttons use client-side navigation
+ * instead of full page reloads.
+ */
+export function BoltdocsRouterProvider({
+  children,
+}: {
+  children: React.ReactNode
+}) {
+  const navigate = useNavigate()
+
+  return (
+    <RouterProvider
+      navigate={(to, options) => {
+        startTransition(() => {
+          navigate(to, options)
+        })
+      }}
+      useHref={useHref}
+    >
+      {children as any}
+    </RouterProvider>
+  )
+}