boltdocs 1.10.2 → 1.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "boltdocs",
-  "version": "1.10.2",
+  "version": "1.11.0",
   "description": "A lightweight documentation generator for React projects.",
   "main": "dist/node/index.js",
   "module": "dist/node/index.mjs",
@@ -19,11 +19,29 @@
       "import": "./dist/client/index.mjs",
       "require": "./dist/client/index.js"
     },
-    "./style.css": "./dist/client/index.css"
+    "./client/hooks": {
+      "types": "./dist/client/hooks/index.d.ts",
+      "import": "./dist/client/hooks/index.mjs",
+      "require": "./dist/client/hooks/index.js"
+    },
+    "./client/primitives": {
+      "types": "./dist/client/components/primitives/index.d.ts",
+      "import": "./dist/client/components/primitives/index.mjs",
+      "require": "./dist/client/components/primitives/index.js"
+    },
+    "./client/types": {
+      "types": "./dist/client/types.d.ts",
+      "import": "./dist/client/types.mjs",
+      "require": "./dist/client/types.js"
+    },
+    "./theme/neutral.css": "./src/client/theme/neutral.css"
   },
   "scripts": {
     "build": "tsup",
-    "dev": "tsup --watch"
+    "dev": "tsup --watch",
+    "format": "pnpm exec biome format --write",
+    "lint": "pnpm exec biome lint --write",
+    "check": "pnpm exec biome check --write"
   },
   "keywords": [
     "docs",
@@ -42,26 +60,30 @@
   "dependencies": {
     "@mdx-js/react": "^3.1.1",
     "@mdx-js/rollup": "^3.1.1",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "codesandbox": "^2.2.3",
     "fast-glob": "^3.3.3",
     "github-slugger": "^2.0.0",
     "gray-matter": "^4.0.3",
     "lucide-react": "^0.575.0",
-    "react-live": "^4.1.8",
+    "react-aria-components": "^1.16.0",
     "react-router-dom": "^6.30.3",
-    "rehype-pretty-code": "^0.14.1",
     "rehype-slug": "^6.0.0",
     "remark-frontmatter": "^5.0.0",
     "remark-gfm": "^4.0.1",
+    "scroll-into-view-if-needed": "^3.1.0",
     "sharp": "^0.34.5",
     "shiki": "^3.23.0",
     "svgo": "^4.0.1",
+    "tailwind-merge": "^3.5.0",
     "unist-util-visit": "^5.1.0",
     "vite": "^7.3.1",
     "vite-plugin-image-optimizer": "^2.0.3"
   },
   "peerDependencies": {
-    "react": "^18.0.0",
-    "react-dom": "^18.0.0"
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0"
   },
   "packageManager": "pnpm@10.30.2",
   "devDependencies": {

package/src/client/app/config-context.tsx

@@ -0,0 +1,18 @@
+import { createContext, use } from 'react'
+import type { BoltdocsConfig } from '@node/config'
+
+/**
+ * Context for the global documentation configuration.
+ */
+export const ConfigContext = createContext<BoltdocsConfig | null>(null)
+
+/**
+ * Hook to access the Boltdocs configuration.
+ */
+export function useConfig() {
+  const context = use(ConfigContext)
+  if (!context) {
+    throw new Error('useConfig must be used within a ConfigProvider')
+  }
+  return context
+}

package/src/client/app/docs-layout.tsx

@@ -0,0 +1,14 @@
+import { Outlet } from 'react-router-dom'
+import UserLayout from 'virtual:boltdocs-layout'
+
+/**
+ * Wraps the docs Outlet with the user's (or default) layout component.
+ * The Layout receives the routed page as `children`.
+ */
+export function DocsLayout() {
+  return (
+    <UserLayout>
+      <Outlet />
+    </UserLayout>
+  )
+}

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,124 @@ 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 }>>
+  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;
+        )
+        const loader = loaderKey ? modules[loaderKey] : null
 
         return {
           ...route,
           Component: React.lazy(() => {
-            if (!loader)
-              return Promise.resolve({ default: () => <NotFound /> });
-            return loader() as any;
+            if (!loader) return Promise.resolve({ default: NotFound })
+            return loader() as any
           }),
-        };
-      });
-  };
-
-  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>
-  );
+                  ),
+                )}
+
+                {/* Documentation pages WITH sidebar + TOC layout */}
+                <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 +167,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 +195,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>
+  )
+}