boltdocs 2.6.1 → 2.7.0

package/src/client/ssg/boltdocs-shell.tsx

@@ -1,19 +1,24 @@
 import { useEffect, useMemo } from 'react'
-import { Outlet, useLocation, useNavigate } from 'react-router-dom'
-import { RouterProvider } from 'react-aria-components'
+import { Outlet, useLocation } from 'react-router-dom'
 import { BoltdocsProvider, useBoltdocsContext } from '../store/boltdocs-context'
 import { ThemeProvider } from '../app/theme-context'
 import { MdxComponentsProvider } from '../app/mdx-components-context'
-import { HelmetProvider } from 'react-helmet-async'
+import { HelmetProvider } from '../app/helmet-compat'
 import { ConfigContext } from '../app/config-context'
 import { ScrollHandler } from '../app/scroll-handler'
 import { mdxComponentsDefault } from '../app/mdx-component'
 import { RoutesProvider } from '../app/routes-context'
 import type { BoltdocsConfig } from '../../shared/types'
 import type { ComponentRoute } from '../types'
+import { UIProvider } from '../app/ui-context'
 
 import virtualCustomComponents from 'virtual:boltdocs-mdx-components'
 
+/** Normalize a path: strip trailing slash unless it is exactly '/'. */
+function normalizePath(p: string): string {
+  return p.endsWith('/') && p.length > 1 ? p.slice(0, -1) : p
+}
+
 /**
  * Updates the HTML lang and dir attributes based on the current locale configuration.
  */
@@ -33,53 +38,34 @@ function I18nUpdater({ config }: { config: BoltdocsConfig }) {
 
 /**
  * Synchronizes the Zustand store with the current URL pathname.
+ * Receives a pre-built Map for O(1) route lookups instead of O(n) .find().
  */
-function StoreSync({ config }: { config: BoltdocsConfig }) {
+function StoreSync({
+  config,
+  routeMap,
+}: {
+  config: BoltdocsConfig
+  routeMap: Map<string, ComponentRoute>
+}) {
   const location = useLocation()
-  const { setLocale, setVersion, currentLocale, currentVersion } =
-    useBoltdocsContext()
+  const { setLocale, setVersion } = useBoltdocsContext()
 
   useEffect(() => {
-    const parts = location.pathname.split('/').filter(Boolean)
-    let cIdx = 0
-    let detectedVersion = config.versions?.defaultVersion
-    let detectedLocale = config.i18n?.defaultLocale
-
-    // 0. Skip docs prefix if present
-    if (parts[cIdx] === 'docs') cIdx++
-
-    // 1. Version detection
-    if (config.versions && parts.length > cIdx) {
-      const versionMatch = config.versions.versions.find(
-        (v) => v.path === parts[cIdx],
-      )
-      if (versionMatch) {
-        detectedVersion = versionMatch.path
-        cIdx++
-      }
-    }
+    const currentPath = normalizePath(location.pathname)
+    const matchedRoute = routeMap.get(currentPath)
 
-    // 2. Locale detection
-    if (
-      config.i18n &&
-      parts.length > cIdx &&
-      config.i18n.locales[parts[cIdx]]
-    ) {
-      detectedLocale = parts[cIdx]
-    } else if (config.i18n && parts.length === 0) {
-      detectedLocale = currentLocale || config.i18n.defaultLocale
+    if (matchedRoute) {
+      if (config.i18n) {
+        const targetLocale = matchedRoute.locale || config.i18n.defaultLocale
+        setLocale(targetLocale)
+      }
+      if (config.versions) {
+        const targetVersion =
+          matchedRoute.version || config.versions.defaultVersion
+        setVersion(targetVersion)
+      }
     }
-
-    if (detectedLocale !== currentLocale) setLocale(detectedLocale || '')
-    if (detectedVersion !== currentVersion) setVersion(detectedVersion ?? '')
-  }, [
-    location.pathname,
-    config,
-    setLocale,
-    setVersion,
-    currentLocale,
-    currentVersion,
-  ])
+  }, [location.pathname, config, routeMap, setLocale, setVersion])
 
   return null
 }
@@ -102,26 +88,61 @@ export function BoltdocsShell({
     [components],
   )
 
-  const navigate = useNavigate()
+  const { pathname } = useLocation()
+
+  const currentPath = useMemo(() => normalizePath(pathname || '/'), [pathname])
+
+  // Build a single O(1) lookup Map from the routes array.
+  // This replaces the 3 separate O(n) .find() calls that previously ran on every render.
+  const routeMap = useMemo(() => {
+    const map = new Map<string, ComponentRoute>()
+    for (const r of routes) {
+      const key = normalizePath(r.path === '' ? '/' : r.path)
+      map.set(key, r)
+    }
+    return map
+  }, [routes])
+
+  // Calculate frame-perfect initial values derived AUTHORITATIVELY from the static route match
+  const initialData = useMemo(() => {
+    const matched = routeMap.get(currentPath)
+
+    let initLocale = undefined
+    let initVersion = undefined
+
+    if (matched) {
+      if (config.i18n) {
+        initLocale = matched.locale || config.i18n.defaultLocale
+      }
+      if (config.versions) {
+        initVersion = matched.version || config.versions.defaultVersion
+      }
+    }
+
+    return { initLocale, initVersion }
+  }, [currentPath, config, routeMap])
 
   return (
     <HelmetProvider>
-      <BoltdocsProvider>
+      <RoutesProvider routes={routes}>
         <ThemeProvider>
-          <MdxComponentsProvider components={allComponents}>
-            <ConfigContext.Provider value={config}>
-              <RoutesProvider routes={routes}>
-                <RouterProvider navigate={navigate}>
-                  <ScrollHandler />
-                  <StoreSync config={config} />
+          <UIProvider>
+            <MdxComponentsProvider components={allComponents}>
+              <ConfigContext.Provider value={config}>
+                <ScrollHandler />
+                <BoltdocsProvider
+                  initialLocale={initialData.initLocale}
+                  initialVersion={initialData.initVersion}
+                >
+                  <StoreSync config={config} routeMap={routeMap} />
                   <I18nUpdater config={config} />
                   <Outlet />
-                </RouterProvider>
-              </RoutesProvider>
-            </ConfigContext.Provider>
-          </MdxComponentsProvider>
+                </BoltdocsProvider>
+              </ConfigContext.Provider>
+            </MdxComponentsProvider>
+          </UIProvider>
         </ThemeProvider>
-      </BoltdocsProvider>
+      </RoutesProvider>
     </HelmetProvider>
   )
 }

package/src/client/ssg/create-routes.tsx

@@ -2,47 +2,86 @@ import type { RouteRecord } from '@bdocs/ssg'
 import type { ComponentRoute, BoltdocsConfig } from '../types'
 import { MdxPage } from './mdx-page'
 import { BoltdocsShell } from './boltdocs-shell'
-import { NotFound } from '../components/ui-base/not-found'
+import { NotFound } from '../components/ui-base'
+const Loading = () => <div className="text-muted text-sm py-4">Loading...</div>
+import type React from 'react'
+import { useEffect } from 'react'
+import { Navigate } from 'react-router-dom'
 
 interface CreateRoutesOptions {
   routesData: ComponentRoute[]
   config: BoltdocsConfig
-  mdxModules: Record<string, { default?: React.ComponentType }>
+  mdxModules: Record<string, any>
   Layout: React.ComponentType<{ children: React.ReactNode }>
-  homePage?: React.ComponentType
+
   externalPages?: Record<string, React.ComponentType>
   externalLayout?: React.ComponentType<{ children: React.ReactNode }>
   components?: Record<string, React.ComponentType>
 }
 
 /**
- * Finds the matching module key from import.meta.glob for a given filePath.
+ * Stable component to render MDX pages.
+ * By being outside createRoutes, it prevents React from unmounting the page on HMR.
  */
-function findModuleKey(
-  modules: Record<string, any>,
-  filePath: string,
-): string | undefined {
-  const normalizedFilePath = filePath.replace(/\\/g, '/')
-  return Object.keys(modules).find(
-    (key) =>
-      key.endsWith(`/${normalizedFilePath}`) ||
-      key.endsWith(normalizedFilePath),
-  )
+const MdxRouteElement = ({
+  moduleLoader,
+  moduleKey,
+  route,
+  components,
+}: {
+  moduleLoader: any
+  moduleKey: string | undefined
+  route: ComponentRoute
+  components: any
+}) => {
+  const MDXComponent = moduleLoader?.default ?? moduleLoader ?? null
+
+  useEffect(() => {
+    if (!import.meta.hot || !moduleKey) return
+
+    const handler = (data: { relPath: string }) => {
+      const incoming = data.relPath.replace(/\\/g, '/').replace(/^\//, '')
+      const routeFile = route.filePath.replace(/\\/g, '/').replace(/^\//, '')
+
+      if (incoming !== routeFile) return
+
+      const cacheBustUrl = moduleKey + '?t=' + Date.now()
+      import(/* @vite-ignore */ cacheBustUrl).then((m: any) => {
+        MDXComponent
+      })
+    }
+
+    import.meta.hot.on('boltdocs:mdx-update', handler)
+    return () => import.meta.hot?.off('boltdocs:mdx-update', handler)
+  }, [moduleKey, route.filePath])
+
+  if (!MDXComponent) return <Loading />
+
+  return <MdxPage MDXComponent={MDXComponent} mdxComponents={components} />
 }
 
+import { useMdxComponents } from '../app/mdx-components-context'
+
+const NotFoundWrapper = () => {
+  const components = useMdxComponents()
+  const ActiveNotFound = components.NotFound || components['404'] || NotFound
+  return <ActiveNotFound />
+}
+
+import { DocsLayout } from '../app/docs-layout'
+
 export function createRoutes(options: CreateRoutesOptions): RouteRecord[] {
   const {
     routesData,
     config,
     mdxModules,
-    Layout,
-    homePage: HomePage,
     externalPages,
     externalLayout,
     components,
   } = options
 
-  const EffectiveExternalLayout = externalLayout || Layout
+  const EffectiveExternalLayout =
+    externalLayout || (({ children }: any) => <>{children}</>)
 
   const withBase = (path: string) => {
     // Future support for base path in config
@@ -53,23 +92,103 @@ export function createRoutes(options: CreateRoutesOptions): RouteRecord[] {
     return `${b}${p}` || '/'
   }
 
-  // 1. Documentation routes
-  const docRoutes: RouteRecord[] = routesData.map((route) => {
-    const moduleKey = findModuleKey(mdxModules, route.filePath)
-    const MDXComponent = moduleKey ? mdxModules[moduleKey]?.default : null
+  const defaultVersionMetadata: ComponentRoute[] = []
+
+  // Inject virtual explicit routes for default version to ensure paths like /docs/latest/... aren't 404s
+  const defaultVersion = config.versions?.defaultVersion
+  const docsBase = (config.base || '/docs').replace(/\/$/, '')
+
+  if (defaultVersion) {
+    routesData.forEach((route) => {
+      // If this route explicitly already belongs to a version, do not clone.
+      if (route.version) return
+
+      // Compute path without docs base prefix to properly place version token
+      const p = route.path || ''
+      const subPath = p.startsWith(docsBase)
+        ? p.substring(docsBase.length).replace(/^\//, '')
+        : p.replace(/^\//, '')
+
+      // Detect if it already includes the target version segment
+      const hasVersionPrefix =
+        subPath === defaultVersion || subPath.startsWith(`${defaultVersion}/`)
+
+      if (!hasVersionPrefix) {
+        // Standardize reconstruction: [docsBase] / [version] / [remaining_path]
+        const explicitPath =
+          `${docsBase}/${defaultVersion}/${subPath}`
+            .replace(/\/+/g, '/')
+            .replace(/\/$/, '') || '/'
 
+        defaultVersionMetadata.push({
+          ...route,
+          path: explicitPath,
+          version: defaultVersion,
+        })
+      }
+    })
+  }
+
+  const docMetadata = [...routesData, ...defaultVersionMetadata]
+
+  // 0. Build a single pre-computed lookup map for the MDX modules (O(N) build, O(1) access).
+  // This replaces the inner findModuleKey loops that executed an O(N) scan for EVERY route.
+  const moduleMap = new Map<string, string>()
+  const mdxModuleKeys = Object.keys(mdxModules)
+
+  if (mdxModuleKeys.length > 0) {
+    // Detect docs directory structure from keys (e.g., "/docs/intro.md")
+    const firstKeyNormalized = mdxModuleKeys[0].replace(/\\/g, '/')
+    const parts = firstKeyNormalized.split('/').filter(Boolean)
+    const docsDirName = parts[0] || 'docs'
+    const primaryPrefix = `/${docsDirName}/`
+    const altPrefix = `./${docsDirName}/`
+
+    for (const rawKey of mdxModuleKeys) {
+      const k = rawKey.replace(/\\/g, '/')
+      let relativePath = ''
+      if (k.indexOf(primaryPrefix) !== -1) {
+        relativePath = k.substring(
+          k.indexOf(primaryPrefix) + primaryPrefix.length,
+        )
+      } else if (k.startsWith(altPrefix)) {
+        relativePath = k.substring(altPrefix.length)
+      }
+
+      if (relativePath) {
+        moduleMap.set(relativePath, rawKey)
+      } else {
+        // Fallback: store full normalized key as a catch-all
+        moduleMap.set(k, rawKey)
+      }
+    }
+  }
+
+  // 1. Documentation routes
+  const docRoutes: RouteRecord[] = docMetadata.map((route) => {
+    // Perform constant-time lookup using the pre-computed map
+    const normalizedFilePath = route.filePath.replace(/\\/g, '/')
+    const moduleKey = moduleMap.get(normalizedFilePath)
+    const moduleLoader = moduleKey ? mdxModules[moduleKey] : null
     const path = withBase(route.path === '' ? '/' : route.path)
 
     return {
       path,
       element: (
-        <MdxPage MDXComponent={MDXComponent} mdxComponents={components} />
+        <MdxRouteElement
+          key={moduleKey || path}
+          moduleKey={moduleKey}
+          moduleLoader={moduleLoader}
+          route={route}
+          components={components}
+        />
       ),
       loader: async () => ({
         path,
         frontmatter: {
           title: route.title,
           description: route.description || '',
+          ...(route.frontmatter || {}),
         },
         headings: route.headings || [],
         filePath: route.filePath,
@@ -77,43 +196,152 @@ export function createRoutes(options: CreateRoutesOptions): RouteRecord[] {
         version: route.version,
         group: route.group,
         groupTitle: route.groupTitle,
+        date: route.date,
+        lastUpdated: route.lastUpdated,
       }),
       getStaticPaths: () => [path],
     }
   })
 
-  const children: RouteRecord[] = [...docRoutes]
+  // 2. Auto-fallback for the base paths (e.g. /docs, /docs/es) to the first documentation page
+  let baseDocsPath = (config.base || '/docs').replace(/\/$/, '')
+  if (!baseDocsPath) baseDocsPath = '/'
+
+  const locales = config.i18n?.locales
+    ? Array.isArray(config.i18n.locales)
+      ? config.i18n.locales
+      : Object.keys(config.i18n.locales)
+    : []
+
+  // 2a. Generate dynamic permutation matrix of version/locale combinations
+  const allVersions = config.versions?.versions?.map((v) => v.path) || []
+
+  const targetBasePaths: Array<{
+    path: string
+    filter: (p: string) => boolean
+  }> = []
 
-  // 2. Home page route
-  if (HomePage) {
-    const homePaths = [withBase('/')]
-    if (config.i18n) {
-      Object.keys(config.i18n.locales).forEach((locale) => {
-        homePaths.push(withBase(`/${locale}`))
+  // Insert base root always
+  targetBasePaths.push({
+    path: baseDocsPath,
+    filter: () => true, // Take first available doc generally
+  })
+
+  // Permutation builder: version loop nested with locale loop
+  // Ensures paths like /docs/v2.0, /docs/es, and /docs/v2.0/es ALL receive fallback logic.
+  const subPaths: string[] = []
+  if (allVersions.length > 0) {
+    allVersions.forEach((v) => subPaths.push(`/${v}`))
+  }
+  if (locales.length > 0) {
+    locales.forEach((l) => subPaths.push(`/${l}`))
+  }
+  if (allVersions.length > 0 && locales.length > 0) {
+    allVersions.forEach((v) => {
+      locales.forEach((l) => {
+        subPaths.push(`/${v}/${l}`)
       })
-    }
+    })
+  }
 
-    homePaths.forEach((path) => {
-      // Avoid duplicate routes if documentation also maps to '/'
-      if (!children.find((r) => r.path === path)) {
-        children.push({
-          path,
-          element: (
-            <EffectiveExternalLayout>
-              <HomePage />
-            </EffectiveExternalLayout>
-          ),
-          getStaticPaths: () => [path],
+  // Map permutations onto the physical base docs route
+  subPaths.forEach((sp) => {
+    const fullP = baseDocsPath === '/' ? sp : `${baseDocsPath}${sp}`
+    targetBasePaths.push({
+      path: fullP,
+      filter: (rp) => rp.startsWith(fullP.replace(/\/$/, '') + '/'),
+    })
+  })
+
+  // Pre-compute a Set of absolute and normalized path strings from the real routes
+  // to perform O(1) validation checks within the redirection loops below.
+  const docPathRegistry = new Set(
+    docRoutes.map((r) => (r.path || '').replace(/\/$/, '')),
+  )
+
+  // Pre-compute external pages paths so we do not hijack them with redirects
+  const externalPaths = new Set<string>()
+  if (externalPages) {
+    Object.keys(externalPages).forEach((rawPath) => {
+      const p = rawPath.startsWith('/') ? rawPath : `/${rawPath}`
+      externalPaths.add(p.replace(/\/$/, ''))
+      if (config.i18n) {
+        Object.keys(config.i18n.locales).forEach((locale) => {
+          externalPaths.add(
+            `/${locale}${p === '/' ? '' : p}`.replace(/\/$/, ''),
+          )
         })
       }
     })
   }
 
+  // 2b. Deploy smart redirects
+  targetBasePaths.forEach(({ path: bPath, filter }) => {
+    if (bPath === '/') return // Never hijack global app root
+
+    const normalizedPath = bPath.replace(/\/$/, '')
+    const hasExplicitMatch =
+      docPathRegistry.has(normalizedPath) || externalPaths.has(normalizedPath)
+
+    if (!hasExplicitMatch) {
+      const defaultTab = config.theme?.tabs?.[0]?.id
+      const defaultTabPath = defaultTab
+        ? `${normalizedPath}/${defaultTab}`.replace(/\/+/g, '/')
+        : null
+
+      // Prioritize: Find a real route that matches the default tab first, then fall back to the first route beginning with this pattern.
+      const matchedRoute =
+        defaultTabPath && docPathRegistry.has(defaultTabPath.replace(/\/$/, ''))
+          ? docRoutes.find(
+              (r) =>
+                r.path.replace(/\/$/, '') === defaultTabPath.replace(/\/$/, ''),
+            )
+          : docRoutes.find((r) => filter(r.path) && r.path !== normalizedPath)
+
+      // Ultimate fallback: the absolute first document
+      const finalTarget = matchedRoute
+        ? matchedRoute.path
+        : docRoutes.length > 0
+          ? docRoutes[0].path
+          : null
+
+      if (finalTarget) {
+        docRoutes.push({
+          path: bPath,
+          element: <Navigate to={finalTarget} replace />,
+          loader: async () => ({ path: bPath }),
+          getStaticPaths: () => [bPath],
+        })
+      }
+    }
+  })
+
+  // Group all documentation routes under the persistent DocsLayout
+  const docsLayoutRoute: RouteRecord = {
+    element: <DocsLayout />,
+    children: docRoutes,
+  }
+
+  const children: RouteRecord[] = [docsLayoutRoute]
+
   // 3. External pages
+  const externalMetadata: ComponentRoute[] = []
   if (externalPages) {
     Object.entries(externalPages).forEach(([rawPath, ExtComponent]) => {
-      const path = withBase(rawPath)
+      // Use the raw path directly (do not prefix with base docs path)
+      const path = rawPath.startsWith('/') ? rawPath : `/${rawPath}`
       if (!children.find((r) => r.path === path)) {
+        externalMetadata.push({
+          path,
+          locale: config.i18n?.defaultLocale,
+          title:
+            rawPath === '/'
+              ? 'Home'
+              : rawPath.replace(/^\//, '').split('/').pop() || 'Page',
+          filePath: '',
+          headings: [],
+        } as any)
+
         children.push({
           path,
           element: (
@@ -121,16 +349,26 @@ export function createRoutes(options: CreateRoutesOptions): RouteRecord[] {
               <ExtComponent />
             </EffectiveExternalLayout>
           ),
+          loader: async () => ({
+            path,
+            locale: config.i18n?.defaultLocale,
+          }),
           getStaticPaths: () => [path],
         })
 
-        // Also add i18n variants for external pages if needed
+        // Also add i18n variants for external pages if needed (do not prefix with base docs path)
         if (config.i18n) {
           Object.keys(config.i18n.locales).forEach((locale) => {
-            const localePath = withBase(
-              `/${locale}${rawPath === '/' ? '' : rawPath}`,
-            )
+            const localePath = `/${locale}${rawPath === '/' ? '' : rawPath}`
             if (!children.find((r) => r.path === localePath)) {
+              externalMetadata.push({
+                path: localePath,
+                locale,
+                title: rawPath,
+                filePath: '',
+                headings: [],
+              } as any)
+
               children.push({
                 path: localePath,
                 element: (
@@ -138,6 +376,10 @@ export function createRoutes(options: CreateRoutesOptions): RouteRecord[] {
                     <ExtComponent />
                   </EffectiveExternalLayout>
                 ),
+                loader: async () => ({
+                  path: localePath,
+                  locale,
+                }),
                 getStaticPaths: () => [localePath],
               })
             }
@@ -152,14 +394,12 @@ export function createRoutes(options: CreateRoutesOptions): RouteRecord[] {
     path: '*',
     element: (
       <EffectiveExternalLayout>
-        <NotFound />
+        <NotFoundWrapper />
       </EffectiveExternalLayout>
     ),
   })
 
-  // --- 5. Construct Metadata for UI Providers ---
-  // We need to pass the full metadata to BoltdocsShell so that Sidebar/Tabs can work.
-  const allMetadata: ComponentRoute[] = [...routesData]
+  const allMetadata = [...docMetadata, ...externalMetadata]
 
   // Wrap everything in the Boltdocs shell (providers)
   return [

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

@@ -12,7 +12,6 @@ export function MdxPage({
   const data = useLoaderData() as any
   const MDXComponent = propMDX || data?.MDXComponent
   const components = propComponents || data?.mdxComponents
-
   if (!MDXComponent) return null
 
   return (
@@ -28,6 +27,8 @@ export function MdxPage({
           version: data.version,
           group: data.group,
           groupTitle: data.groupTitle,
+          lastUpdated: data.lastUpdated,
+          frontmatter: data.frontmatter,
         } as any
       }
       content={MDXComponent}