boltdocs 2.5.6 → 2.6.0

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

@@ -1,119 +1,66 @@
-import React, { createContext, useContext, useState, useEffect, useCallback } from 'react'
+import { createContext, use, useMemo, useState } from 'react'
 
-interface BoltdocsState {
-  currentLocale: string | undefined
-  currentVersion: string | undefined
+export interface BoltdocsState {
+  currentLocale: string
+  currentVersion: string
+  setLocale: (locale: string) => void
+  setVersion: (version: string) => void
   hasHydrated: boolean
-
-  // Actions
-  setLocale: (locale: string | undefined) => void
-  setVersion: (version: string | undefined) => void
-  setHasHydrated: (val: boolean) => void
+  setHasHydrated: (hasHydrated: boolean) => void
 }
 
-interface BoltdocsContextValue extends BoltdocsState {}
-
-const BoltdocsContext = createContext<BoltdocsContextValue | undefined>(undefined)
-
-const STORAGE_KEY = 'boltdocs-storage'
+const BOLTDOCS_CONTEXT_SYMBOL = Symbol.for('__BDOCS_BOLTDOCS_CONTEXT__')
+const BOLTDOCS_INSTANCE_SYMBOL = Symbol.for('__BDOCS_BOLTDOCS_INSTANCE__')
 
-/**
- * Load persisted state from localStorage
- */
-function loadPersistedState(): Partial<BoltdocsState> {
-  try {
-    const stored = localStorage.getItem(STORAGE_KEY)
-    if (stored) {
-      const parsed = JSON.parse(stored)
-      // zustand persist stores the entire state object under a "state" key
-      return parsed?.state || parsed
-    }
-  } catch (e) {
-    // ignore parse errors
-  }
-  return {}
-}
+const BoltdocsContext =
+  (globalThis as any)[BOLTDOCS_CONTEXT_SYMBOL] ||
+  ((globalThis as any)[BOLTDOCS_CONTEXT_SYMBOL] = createContext<
+    BoltdocsState | undefined
+  >(undefined))
 
-/**
- * Provider component that wraps the app and manages state
- */
 export function BoltdocsProvider({ children }: { children: React.ReactNode }) {
-  const persisted = loadPersistedState()
-
-  const [currentLocale, setCurrentLocale] = useState<string | undefined>(
-    persisted.currentLocale
-  )
-  const [currentVersion, setCurrentVersion] = useState<string | undefined>(
-    persisted.currentVersion
-  )
+  const [locale, setLocale] = useState('')
+  const [version, setVersion] = useState('')
   const [hasHydrated, setHasHydrated] = useState(false)
 
-  // Mark as hydrated after initial load
-  useEffect(() => {
-    setHasHydrated(true)
-  }, [])
-
-  // Persist state changes to localStorage
-  useEffect(() => {
-    if (hasHydrated) {
-      const stateToPersist = {
-        currentLocale,
-        currentVersion,
-      }
-      try {
-        localStorage.setItem(
-          STORAGE_KEY,
-          JSON.stringify({ state: stateToPersist })
-        )
-      } catch (e) {
-        // ignore storage errors
-      }
-    }
-  }, [currentLocale, currentVersion, hasHydrated])
-
-  const setLocale = useCallback((locale: string | undefined) => {
-    setCurrentLocale(locale)
-  }, [])
-
-  const setVersion = useCallback((version: string | undefined) => {
-    setCurrentVersion(version)
-  }, [])
-
-  const setHasHydratedAction = useCallback((val: boolean) => {
-    setHasHydrated(val)
-  }, [])
+  const value = useMemo(
+    () => ({
+      currentLocale: locale,
+      currentVersion: version,
+      setLocale,
+      setVersion,
+      hasHydrated,
+      setHasHydrated,
+    }),
+    [locale, version, hasHydrated],
+  )
 
-  const value: BoltdocsContextValue = {
-    currentLocale,
-    currentVersion,
-    hasHydrated,
-    setLocale,
-    setVersion,
-    setHasHydrated: setHasHydratedAction,
+  // 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>
+    <BoltdocsContext.Provider value={value}>
+      {children}
+    </BoltdocsContext.Provider>
   )
 }
 
-/**
- * Hook to access the Boltdocs context.
- * Must be used within a BoltdocsProvider.
- */
-export function useBoltdocsContext(): BoltdocsContextValue {
-  const context = useContext(BoltdocsContext)
+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
-}
-
-/**
- * Backwards-compatible hook that mimics the Zustand store API.
- * Accepts a selector function and returns the selected value.
- */
-export function useBoltdocsStore<T>(selector: (state: BoltdocsState) => T): T {
-  const context = useBoltdocsContext()
-  return selector(context)
+  return context as BoltdocsState
 }

package/src/client/theme/neutral.css

@@ -90,6 +90,10 @@
   }
 }
 
+@variant dark 
+(
+&:where(.dark, .dark *));
+
 .animate-pulse {
   animation: pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite;
 }
@@ -99,9 +103,9 @@
 }
 
 :root[data-theme="dark"],
-:root:not(.theme-light) {
-  --color-bg-main: var(--color-neutral-950);
-  --color-bg-surface: var(--color-neutral-900);
+:root.dark {
+  --color-bg-main: var(--color-neutral-900);
+  --color-bg-surface: var(--color-neutral-800);
   --color-bg-muted: var(--color-neutral-800);
   --color-text-main: var(--color-neutral-50);
   --color-text-muted: var(--color-neutral-400);
@@ -112,6 +116,7 @@
   --color-code-text: var(--color-neutral-200);
 }
 
+
 @layer base {
   *,
   *::before,
@@ -271,7 +276,6 @@
     border-radius: var(--radius-lg);
     margin: 2rem 0;
     display: block;
-    box-shadow: 0 10px 30px -10px rgba(0, 0, 0, 0.1);
   }
   .boltdocs-page table {
     width: 100%;
@@ -294,41 +298,6 @@
   .boltdocs-page tr:hover td {
     background-color: var(--color-bg-surface);
   }
-  .boltdocs-page :not(pre) > code {
-    background-color: var(--color-bg-surface);
-    padding: 0.15rem 0.45rem;
-    border-radius: 5px;
-    font-family: var(--font-mono);
-    font-size: 0.85em;
-    color: var(--color-primary-400);
-    border: 1px solid var(--color-border-subtle);
-  }
-  .boltdocs-page pre {
-    margin: 1.5rem 0;
-    border-radius: var(--radius-md);
-    overflow-x: auto;
-    font-family: var(--font-mono);
-    font-size: 0.8125rem;
-    line-height: 1.7;
-    background-color: var(--color-code-bg);
-    color: var(--color-code-text);
-    border: 1px solid var(--color-border-subtle);
-  }
-  .boltdocs-page pre > code {
-    display: grid;
-    padding: 1rem;
-    background-color: transparent;
-    border: none;
-    color: inherit;
-    font-size: inherit;
-  }
-  .boltdocs-page pre > code .line {
-    padding: 0 1.25rem;
-  }
-  .boltdocs-page pre > code .line.highlighted {
-    background-color: oklch(0.6 0.22 280 / 10%);
-    border-left: 2px solid var(--color-primary-500);
-  }
 
   @media (max-width: 768px) {
     .boltdocs-page h1 {
@@ -369,20 +338,91 @@
     opacity: 1;
   }
 
-  /* ═══ Shiki Dual Theme ═══ */
-  .shiki-wrapper .shiki.shiki-themes {
+  /* ═══ Shiki Styles ═══ */
+  
+  /* Shiki Light/Dark Mode */
+  :root .shiki,
+  :root .shiki span {
+    font-family: var(--font-mono);
+    font-size: 12px !important;
     background-color: transparent !important;
-    color: var(--shiki-light) !important;
-  }
-  .shiki-wrapper .shiki.shiki-themes span {
-    color: var(--shiki-light);
   }
-  :root[data-theme="dark"] .shiki-wrapper .shiki.shiki-themes,
-  :root:not(.theme-light) .shiki-wrapper .shiki.shiki-themes {
+
+  :root.dark .shiki,
+  :root.dark .shiki span {
     color: var(--shiki-dark) !important;
   }
-  :root[data-theme="dark"] .shiki-wrapper .shiki.shiki-themes span,
-  :root:not(.theme-light) .shiki-wrapper .shiki.shiki-themes span {
-    color: var(--shiki-dark) !important;
+
+  /* Base Shiki Pre & Span Styles */
+  pre.shiki {
+    @apply py-2 text-[12px] leading-[1.6];
+  }
+
+  pre.shiki span.line {
+    @apply relative block px-4 py-0;
+    min-height: 1.6em;
+  }
+
+  /* Shiki Word Wrap */
+  pre.shiki-word-wrap {
+    @apply whitespace-pre-wrap break-words;
+  }
+
+  pre.shiki-word-wrap span.line {
+    @apply block w-full;
+  }
+
+  /* Shiki Line Numbers */
+  pre.shiki-line-numbers code {
+    counter-reset: step;
+    counter-increment: step 0;
+  }
+
+  pre.shiki-line-numbers .line {
+    @apply pl-12!; 
+  }
+
+  /* Hide the last line if it is completely empty to avoid extra numbers */
+  pre.shiki-line-numbers .line:last-child:empty,
+  pre.shiki-line-numbers .line:last-child:has(> :empty) {
+     display: none;
+  }
+
+  pre.shiki-line-numbers .line::before {
+    counter-increment: step;
+    content: counter(step);
+    @apply absolute left-0 top-0 inline-flex w-10 justify-end pr-3;
+    @apply text-[11px] text-text-muted opacity-30 select-none;
+    line-height: inherit; /* Sync with line text */
+  }
+
+  /* Shiki Highlight */
+  pre span.shiki-line-highlight {
+    @apply relative z-0 inline-block w-full;
+    &::after {
+      content: "";
+      @apply absolute top-0 left-0 -z-10 h-full w-full border-l-2 border-primary-500 bg-primary-500/10! opacity-100;
+    }
+  }
+
+  /* Shiki Notation Diff */
+  pre.has-diff span.line.diff {
+    @apply relative inline-block w-full;
+  }
+
+  pre.has-diff span.line.diff.add {
+    @apply bg-emerald-500/10! dark:bg-emerald-500/10!;
+    &::before {
+      content: "+";
+      @apply absolute left-2 text-emerald-500 font-bold;
+    }
+  }
+
+  pre.has-diff span.line.diff.remove {
+    @apply bg-danger-500/10! opacity-70;
+    &::before {
+      content: "-";
+      @apply absolute left-2 text-danger-500 font-bold;
+    }
   }
 }