boltdocs 2.5.5 → 2.6.0

package/src/client/hooks/use-sidebar.ts

@@ -1,5 +1,5 @@
 import { useLocation } from 'react-router-dom'
-import { useConfig } from '@client/app/config-context'
+import { useConfig } from '../app/config-context'
 import type { ComponentRoute } from '../types'
 
 export function useSidebar(routes: ComponentRoute[]) {
@@ -41,7 +41,53 @@ export function useSidebar(routes: ComponentRoute[]) {
     }
   }
 
-  const groups = Array.from(groupsMap.values())
+  const groups = Array.from(groupsMap.values()).map((group) => {
+    const subRouteParents = new Map<string, ComponentRoute>()
+    const subRouteChildren = new Map<string, ComponentRoute[]>()
+
+    // First pass: Categorize as parent or child
+    for (const route of group.routes) {
+      if (route.subRouteGroup) {
+        const isParent =
+          route.path.endsWith(`/${route.subRouteGroup}`) ||
+          route.path.endsWith(`/${route.subRouteGroup}/`)
+
+        if (isParent && !subRouteParents.has(route.subRouteGroup)) {
+          subRouteParents.set(route.subRouteGroup, route)
+        } else {
+          if (!subRouteChildren.has(route.subRouteGroup)) {
+            subRouteChildren.set(route.subRouteGroup, [])
+          }
+          subRouteChildren.get(route.subRouteGroup)!.push(route)
+        }
+      }
+    }
+
+    const finalRoutes: ComponentRoute[] = []
+    const seenSubGroups = new Set<string>()
+
+    // Second pass: Assemble maintaining mostly original order
+    for (const route of group.routes) {
+      if (route.subRouteGroup) {
+        if (!seenSubGroups.has(route.subRouteGroup)) {
+          seenSubGroups.add(route.subRouteGroup)
+          const parent = subRouteParents.get(route.subRouteGroup)
+          const children = subRouteChildren.get(route.subRouteGroup) || []
+
+          if (parent) {
+            finalRoutes.push({ ...parent, subRoutes: children })
+          } else {
+            // Fallback
+            finalRoutes.push(...children)
+          }
+        }
+      } else {
+        finalRoutes.push(route)
+      }
+    }
+
+    return { ...group, routes: finalRoutes }
+  })
 
   return {
     groups,

package/src/client/hooks/use-tabs.ts

@@ -1,6 +1,6 @@
 import { useLocation } from 'react-router-dom'
 import { useEffect, useState, useRef } from 'react'
-import type { ComponentRoute, BoltdocsTab } from '@client/types'
+import type { ComponentRoute, BoltdocsTab } from '../types'
 
 export function useTabs(
   tabs: BoltdocsTab[] = [],
@@ -14,7 +14,11 @@ export function useTabs(
     width: 0,
   })
 
-  const activeRoute = routes.find((r) => r.path === location.pathname)
+  const normalize = (p: string) =>
+    p.endsWith('/') && p.length > 1 ? p.slice(0, -1) : p
+  const currentPath = normalize(location.pathname)
+
+  const activeRoute = routes.find((r) => normalize(r.path) === currentPath)
   const activeTabId = activeRoute?.tab?.toLowerCase()
   const activeIndex = tabs.findIndex(
     (tab) => tab.id.toLowerCase() === activeTabId,

package/src/client/hooks/use-version.ts

@@ -1,7 +1,7 @@
 import { useNavigate } from 'react-router-dom'
-import { getBaseFilePath } from '@client/utils/get-base-file-path'
+import { getBaseFilePath } from '../utils/get-base-file-path'
 import { useRoutes } from './use-routes'
-import { useBoltdocsStore } from '../store/use-boltdocs-store'
+import { useBoltdocsContext } from '../store/boltdocs-context'
 
 export interface VersionOption {
   key: string
@@ -26,7 +26,7 @@ export function useVersion(): UseVersionReturn {
   const { allRoutes, currentRoute, currentVersion, currentLocale, config } =
     routeContext
   const versions = config.versions
-  const setVersion = useBoltdocsStore((s) => s.setVersion)
+  const { setVersion } = useBoltdocsContext()
 
   const handleVersionChange = (version: string) => {
     if (!versions || version === currentVersion) return

package/src/client/index.ts

@@ -1,35 +1,35 @@
-export type { BoltdocsConfig, BoltdocsThemeConfig } from '../node/config'
+export type { BoltdocsConfig, BoltdocsThemeConfig } from '../shared/types'
+export { defineConfig } from '../shared/config-utils'
 export type {
   ComponentRoute,
-  CreateBoltdocsAppOptions,
   LayoutProps,
 } from './types'
-export { createBoltdocsApp } from './app'
-export { useConfig } from '@client/app/config-context'
-export { useTheme } from '@client/app/theme-context'
-export { useRoutes } from '@client/hooks/use-routes'
-export { useMdxComponents } from '@client/app/mdx-components-context'
+export * from './ssg'
+export { useConfig } from './app/config-context'
+export { useTheme } from './app/theme-context'
+export { useRoutes } from './hooks/use-routes'
+export { useMdxComponents } from './app/mdx-components-context'
 
 // Hooks
-export * from '@hooks/index'
+export * from './hooks/index'
 // Composable layout building blocks
-export { DocsLayout } from '@components/docs-layout'
-export { DefaultLayout } from '@components/default-layout'
+export { DocsLayout } from './components/docs-layout'
+export { DefaultLayout } from './components/default-layout'
 
 // Default UI components (for use in custom layout.tsx)
-export { Navbar } from '@components/ui-base/navbar'
-export { Sidebar } from '@components/ui-base/sidebar'
-export { OnThisPage } from '@components/ui-base/on-this-page'
-export { Head } from '@components/ui-base/head'
-export { Breadcrumbs } from '@components/ui-base/breadcrumbs'
-export { PageNav } from '@components/ui-base/page-nav'
-export { ErrorBoundary } from '@components/ui-base/error-boundary'
-export { CopyMarkdown } from '@components/ui-base/copy-markdown'
+export { Navbar } from './components/ui-base/navbar'
+export { Sidebar } from './components/ui-base/sidebar'
+export { OnThisPage } from './components/ui-base/on-this-page'
+export { Head } from './components/ui-base/head'
+export { Breadcrumbs } from './components/ui-base/breadcrumbs'
+export { PageNav } from './components/ui-base/page-nav'
+export { ErrorBoundary } from './components/ui-base/error-boundary'
+export { CopyMarkdown } from './components/ui-base/copy-markdown'
 
-export { NotFound } from '@components/ui-base/not-found'
-export { Loading } from '@components/ui-base/loading'
-export { CodeBlock } from '@components/mdx/code-block'
-export { Video } from '@components/mdx/video'
+export { NotFound } from './components/ui-base/not-found'
+export { Loading } from './components/ui-base/loading'
+export { CodeBlock } from './components/mdx/code-block'
+export { Video } from './components/mdx/video'
 
 // MDX Components
 export {

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

@@ -0,0 +1,127 @@
+import { useEffect, useMemo } from 'react'
+import { Outlet, useLocation, useNavigate } from 'react-router-dom'
+import { RouterProvider } from 'react-aria-components'
+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 { 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 virtualCustomComponents from 'virtual:boltdocs-mdx-components'
+
+/**
+ * Updates the HTML lang and dir attributes based on the current locale configuration.
+ */
+function I18nUpdater({ config }: { config: BoltdocsConfig }) {
+  const { currentLocale } = useBoltdocsContext()
+
+  useEffect(() => {
+    if (!config.i18n || typeof document === 'undefined') return
+    const locale = currentLocale || config.i18n.defaultLocale
+    const localeConfig = config.i18n.localeConfigs?.[locale]
+    document.documentElement.lang = localeConfig?.htmlLang || locale || 'en'
+    document.documentElement.dir = localeConfig?.direction || 'ltr'
+  }, [currentLocale, config.i18n])
+
+  return null
+}
+
+/**
+ * Synchronizes the Zustand store with the current URL pathname.
+ */
+function StoreSync({ config }: { config: BoltdocsConfig }) {
+  const location = useLocation()
+  const { setLocale, setVersion, currentLocale, currentVersion } =
+    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++
+      }
+    }
+
+    // 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 (detectedLocale !== currentLocale) setLocale(detectedLocale || '')
+    if (detectedVersion !== currentVersion) setVersion(detectedVersion ?? '')
+  }, [
+    location.pathname,
+    config,
+    setLocale,
+    setVersion,
+    currentLocale,
+    currentVersion,
+  ])
+
+  return null
+}
+
+export function BoltdocsShell({
+  config,
+  routes,
+  components = {},
+}: {
+  config: BoltdocsConfig
+  routes: ComponentRoute[]
+  components?: Record<string, React.ComponentType>
+}) {
+  const allComponents = useMemo(
+    () => ({
+      ...mdxComponentsDefault,
+      ...virtualCustomComponents,
+      ...components,
+    }),
+    [components],
+  )
+
+  const navigate = useNavigate()
+
+  return (
+    <HelmetProvider>
+      <BoltdocsProvider>
+        <ThemeProvider>
+          <MdxComponentsProvider components={allComponents}>
+            <ConfigContext.Provider value={config}>
+              <RoutesProvider routes={routes}>
+                <RouterProvider navigate={navigate}>
+                  <ScrollHandler />
+                  <StoreSync config={config} />
+                  <I18nUpdater config={config} />
+                  <Outlet />
+                </RouterProvider>
+              </RoutesProvider>
+            </ConfigContext.Provider>
+          </MdxComponentsProvider>
+        </ThemeProvider>
+      </BoltdocsProvider>
+    </HelmetProvider>
+  )
+}

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

@@ -0,0 +1,179 @@
+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'
+
+interface CreateRoutesOptions {
+  routesData: ComponentRoute[]
+  config: BoltdocsConfig
+  mdxModules: Record<string, { default?: React.ComponentType }>
+  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.
+ */
+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),
+  )
+}
+
+export function createRoutes(options: CreateRoutesOptions): RouteRecord[] {
+  const {
+    routesData,
+    config,
+    mdxModules,
+    Layout,
+    homePage: HomePage,
+    externalPages,
+    externalLayout,
+    components,
+  } = options
+
+  const EffectiveExternalLayout = externalLayout || Layout
+
+  const withBase = (path: string) => {
+    // Future support for base path in config
+    const base = config.base || '/'
+    if (path.startsWith(base)) return path
+    const b = base === '/' ? '' : base.replace(/\/$/, '')
+    const p = path.startsWith('/') ? path : `/${path}`
+    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 path = withBase(route.path === '' ? '/' : route.path)
+
+    return {
+      path,
+      element: (
+        <MdxPage MDXComponent={MDXComponent} mdxComponents={components} />
+      ),
+      loader: async () => ({
+        path,
+        frontmatter: {
+          title: route.title,
+          description: route.description || '',
+        },
+        headings: route.headings || [],
+        filePath: route.filePath,
+        locale: route.locale,
+        version: route.version,
+        group: route.group,
+        groupTitle: route.groupTitle,
+      }),
+      getStaticPaths: () => [path],
+    }
+  })
+
+  const children: RouteRecord[] = [...docRoutes]
+
+  // 2. Home page route
+  if (HomePage) {
+    const homePaths = [withBase('/')]
+    if (config.i18n) {
+      Object.keys(config.i18n.locales).forEach((locale) => {
+        homePaths.push(withBase(`/${locale}`))
+      })
+    }
+
+    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],
+        })
+      }
+    })
+  }
+
+  // 3. External pages
+  if (externalPages) {
+    Object.entries(externalPages).forEach(([rawPath, ExtComponent]) => {
+      const path = withBase(rawPath)
+      if (!children.find((r) => r.path === path)) {
+        children.push({
+          path,
+          element: (
+            <EffectiveExternalLayout>
+              <ExtComponent />
+            </EffectiveExternalLayout>
+          ),
+          getStaticPaths: () => [path],
+        })
+
+        // Also add i18n variants for external pages if needed
+        if (config.i18n) {
+          Object.keys(config.i18n.locales).forEach((locale) => {
+            const localePath = withBase(
+              `/${locale}${rawPath === '/' ? '' : rawPath}`,
+            )
+            if (!children.find((r) => r.path === localePath)) {
+              children.push({
+                path: localePath,
+                element: (
+                  <EffectiveExternalLayout>
+                    <ExtComponent />
+                  </EffectiveExternalLayout>
+                ),
+                getStaticPaths: () => [localePath],
+              })
+            }
+          })
+        }
+      }
+    })
+  }
+
+  // --- 4. 404 catch-all ---
+  children.push({
+    path: '*',
+    element: (
+      <EffectiveExternalLayout>
+        <NotFound />
+      </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]
+
+  // Wrap everything in the Boltdocs shell (providers)
+  return [
+    {
+      // No path = Layout Route
+      // This allows children to retain their absolute paths while being wrapped in the shell.
+      element: (
+        <BoltdocsShell
+          config={config}
+          routes={allMetadata}
+          components={components}
+        />
+      ),
+      children,
+    },
+  ]
+}

package/src/client/ssg/index.ts

@@ -0,0 +1,3 @@
+export { createRoutes } from './create-routes'
+export { MdxPage } from './mdx-page'
+export { BoltdocsShell } from './boltdocs-shell'

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

@@ -0,0 +1,37 @@
+import { useLoaderData } from 'react-router-dom'
+import { DocPage } from '../app/doc-page'
+
+/**
+ * Renders an MDX page by consuming pre-loaded module data.
+ * Uses DocPage to ensure consistent layout and metadata application.
+ */
+export function MdxPage({
+  MDXComponent: propMDX,
+  mdxComponents: propComponents,
+}: any) {
+  const data = useLoaderData() as any
+  const MDXComponent = propMDX || data?.MDXComponent
+  const components = propComponents || data?.mdxComponents
+
+  if (!MDXComponent) return null
+
+  return (
+    <DocPage
+      route={
+        {
+          path: data.path,
+          filePath: data.filePath,
+          title: data.frontmatter.title,
+          description: data.frontmatter.description,
+          headings: data.headings,
+          locale: data.locale,
+          version: data.version,
+          group: data.group,
+          groupTitle: data.groupTitle,
+        } as any
+      }
+      content={MDXComponent}
+      mdxComponents={components}
+    />
+  )
+}

package/src/client/store/boltdocs-context.tsx

@@ -0,0 +1,66 @@
+import { createContext, use, useMemo, useState } from 'react'
+
+export interface BoltdocsState {
+  currentLocale: string
+  currentVersion: string
+  setLocale: (locale: string) => void
+  setVersion: (version: string) => void
+  hasHydrated: boolean
+  setHasHydrated: (hasHydrated: boolean) => void
+}
+
+const BOLTDOCS_CONTEXT_SYMBOL = Symbol.for('__BDOCS_BOLTDOCS_CONTEXT__')
+const BOLTDOCS_INSTANCE_SYMBOL = Symbol.for('__BDOCS_BOLTDOCS_INSTANCE__')
+
+const BoltdocsContext =
+  (globalThis as any)[BOLTDOCS_CONTEXT_SYMBOL] ||
+  ((globalThis as any)[BOLTDOCS_CONTEXT_SYMBOL] = createContext<
+    BoltdocsState | undefined
+  >(undefined))
+
+export function BoltdocsProvider({ children }: { children: React.ReactNode }) {
+  const [locale, setLocale] = useState('')
+  const [version, setVersion] = useState('')
+  const [hasHydrated, setHasHydrated] = useState(false)
+
+  const value = useMemo(
+    () => ({
+      currentLocale: locale,
+      currentVersion: version,
+      setLocale,
+      setVersion,
+      hasHydrated,
+      setHasHydrated,
+    }),
+    [locale, version, hasHydrated],
+  )
+
+  // Sync with global registry for dual-package fallback
+  if (typeof globalThis !== 'undefined') {
+    ;(globalThis as any)[BOLTDOCS_INSTANCE_SYMBOL] = value
+  }
+
+  return (
+    <BoltdocsContext.Provider value={value}>
+      {children}
+    </BoltdocsContext.Provider>
+  )
+}
+
+export function useBoltdocsContext() {
+  const context = use(BoltdocsContext)
+
+  // Fallback to global registry if context is missing (dual-package hazard safety net)
+  if (
+    !context &&
+    typeof globalThis !== 'undefined' &&
+    (globalThis as any)[BOLTDOCS_INSTANCE_SYMBOL]
+  ) {
+    return (globalThis as any)[BOLTDOCS_INSTANCE_SYMBOL] as BoltdocsState
+  }
+
+  if (!context) {
+    throw new Error('useBoltdocsContext must be used within a BoltdocsProvider')
+  }
+  return context as BoltdocsState
+}