boltdocs 2.7.10 → 2.8.0

package/src/client/app/head.tsx

@@ -1,122 +0,0 @@
-import { useMemo } from 'react'
-import { useLocation } from 'react-router-dom'
-import { Helmet } from './helmet-compat'
-import { useConfig } from './config-context'
-import { getTranslated } from '../utils/i18n'
-import { useRoutes } from '../hooks/use-routes'
-
-interface HeadProps {
-  siteTitle?: string | Record<string, string>
-  siteDescription?: string | Record<string, string>
-  routes: Array<{
-    path: string
-    title: string
-    description?: string
-    seo?: Record<string, unknown>
-  }>
-}
-
-export function Head({ siteTitle, siteDescription, routes }: HeadProps) {
-  const location = useLocation()
-  const config = useConfig()
-  const { currentLocale } = useRoutes()
-
-  // Find the current route's metadata — memoized so the O(n) search only
-  // re-runs when the routes array or the current URL changes, not on every render.
-  const currentRoute = useMemo(
-    () => routes?.find?.((r) => r.path === location.pathname),
-    [routes, location.pathname],
-  )
-  const pageTitle = currentRoute?.title
-  const translatedSiteDescription = getTranslated(
-    siteDescription,
-    currentLocale,
-  )
-  const pageDescription =
-    currentRoute?.description || translatedSiteDescription || ''
-
-  const translatedSiteTitle = getTranslated(siteTitle, currentLocale)
-  const finalTitle = pageTitle
-    ? `${pageTitle} | ${translatedSiteTitle}`
-    : translatedSiteTitle
-
-  const seo = currentRoute?.seo || {}
-
-  // Merge custom global metatags
-  const globalMetatags = config?.seo?.metatags || {}
-
-  // Calculate specific ones
-  const defaultOgImage = config?.seo?.thumbnails?.background
-  const ogImage = (seo['og:image'] || defaultOgImage) as string | undefined
-
-  return (
-    <Helmet>
-      <title>{finalTitle}</title>
-      <meta name="description" content={pageDescription} />
-
-      {/* Default OG Tags */}
-      <meta property="og:title" content={finalTitle} />
-      <meta property="og:description" content={pageDescription} />
-      <meta property="og:type" content="article" />
-      {/* Canonical URL for both <link> and og:url */}
-      {typeof window !== 'undefined' && (
-        <meta property="og:url" content={window.location.href} />
-      )}
-      {typeof window !== 'undefined' && (
-        <link
-          rel="canonical"
-          href={window.location.origin + location.pathname}
-        />
-      )}
-
-      {/* Default Twitter Card */}
-      <meta name="twitter:card" content="summary" />
-      <meta name="twitter:title" content={finalTitle} />
-      <meta name="twitter:description" content={pageDescription} />
-      {ogImage && <meta name="twitter:image" content={ogImage} />}
-      {ogImage && <meta property="og:image" content={ogImage} />}
-
-      {/* Generator */}
-      <meta name="generator" content="Boltdocs" />
-
-      {/* User-defined global metatags */}
-      {Object.entries(globalMetatags).map(([key, value]) => {
-        const isProperty =
-          key.startsWith('og:') ||
-          key.startsWith('music:') ||
-          key.startsWith('video:') ||
-          key.startsWith('article:') ||
-          key.startsWith('book:') ||
-          key.startsWith('profile:')
-        return isProperty ? (
-          <meta key={key} property={key} content={value as string} />
-        ) : (
-          <meta key={key} name={key} content={value as string} />
-        )
-      })}
-
-      {/* Page granular SEO tags (override global) */}
-      {Object.entries(seo).map(([key, value]) => {
-        if (key === 'noindex' && value === true)
-          return <meta key="noindex" name="robots" content="noindex" />
-        if (key === 'robots')
-          return <meta key="robots" name="robots" content={value as string} />
-        if (key === 'canonical')
-          return <link key="canonical" rel="canonical" href={value as string} />
-
-        const isProperty =
-          key.startsWith('og:') ||
-          key.startsWith('music:') ||
-          key.startsWith('video:') ||
-          key.startsWith('article:') ||
-          key.startsWith('book:') ||
-          key.startsWith('profile:')
-        return isProperty ? (
-          <meta key={key} property={key} content={value as string} />
-        ) : (
-          <meta key={key} name={key} content={value as string} />
-        )
-      })}
-    </Helmet>
-  )
-}

package/src/client/app/helmet-compat.tsx

@@ -1,36 +0,0 @@
-/**
- * Shared Helmet module compatibility helpers.
- *
- * react-helmet-async ships different module shapes depending on whether it is
- * loaded via CJS or ESM. Instead of duplicating the same detection logic in
- * every component that needs Helmet/HelmetProvider, we centralise it here.
- */
-import type { ComponentType, ReactNode } from 'react'
-import * as ReactHelmetAsync from 'react-helmet-async'
-
-type HelmetModule = {
-  Helmet?: ComponentType<{ children?: ReactNode }>
-  HelmetProvider?: ComponentType<{ children?: ReactNode }>
-  default?: {
-    Helmet?: ComponentType<{ children?: ReactNode }>
-    HelmetProvider?: ComponentType<{ children?: ReactNode }>
-  }
-}
-
-const mod = ReactHelmetAsync as unknown as HelmetModule
-
-/**
- * The `<Helmet>` component, resolved across CJS/ESM module shapes.
- * Falls back to a transparent fragment wrapper if the module cannot be resolved.
- */
-export const Helmet: ComponentType<{ children?: ReactNode }> =
-  mod.Helmet || mod.default?.Helmet || (({ children }) => <>{children}</>)
-
-/**
- * The `<HelmetProvider>` component, resolved across CJS/ESM module shapes.
- * Falls back to a transparent fragment wrapper if the module cannot be resolved.
- */
-export const HelmetProvider: ComponentType<{ children?: ReactNode }> =
-  mod.HelmetProvider ||
-  mod.default?.HelmetProvider ||
-  (({ children }) => <>{children}</>)

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

@@ -1,8 +0,0 @@
-import { NotFound } from '../components/ui-base/not-found'
-import { mdx_components_default } from '../components/mdx'
-
-export const mdxComponentsDefault = {
-  ...mdx_components_default,
-  NotFound,
-  '404': NotFound,
-}

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

@@ -1,72 +0,0 @@
-import { createContext, use, useMemo } from 'react'
-import type { BoltdocsMdxComponents } from '../../shared/types'
-
-export type MdxComponentsType = {
-  [key: string]: React.ComponentType<any>
-} & {
-  Frontmatter?: Record<string, React.ComponentType<any>>
-}
-
-const MDX_COMPONENTS_CONTEXT_SYMBOL = Symbol.for(
-  '__BDOCS_MDX_COMPONENTS_CONTEXT__',
-)
-const MDX_COMPONENTS_INSTANCE_SYMBOL = Symbol.for(
-  '__BDOCS_MDX_COMPONENTS_INSTANCE__',
-)
-
-const MdxComponentsContext =
-  (globalThis as any)[MDX_COMPONENTS_CONTEXT_SYMBOL] ||
-  ((globalThis as any)[MDX_COMPONENTS_CONTEXT_SYMBOL] =
-    createContext<MdxComponentsType>({}))
-
-export function useMdxComponents(): BoltdocsMdxComponents {
-  const context = use(MdxComponentsContext)
-
-  // Fallback to global registry for dual-package hazards
-  if (
-    (!context || Object.keys(context).length === 0) &&
-    (globalThis as any)[MDX_COMPONENTS_INSTANCE_SYMBOL]
-  ) {
-    return (globalThis as any)[
-      MDX_COMPONENTS_INSTANCE_SYMBOL
-    ] as BoltdocsMdxComponents
-  }
-
-  return context as any as BoltdocsMdxComponents
-}
-
-export function MdxComponentsProvider({
-  components,
-  children,
-}: {
-  components: Record<string, React.ComponentType<any>>
-  children: React.ReactNode
-}) {
-  const processedComponents = useMemo(() => {
-    const processed: Record<string, any> = {}
-    const frontmatter: Record<string, React.ComponentType<any>> = {}
-
-    Object.entries(components).forEach(([key, value]) => {
-      if (key.startsWith('Frontmatter_')) {
-        const cleanKey = key.slice('Frontmatter_'.length)
-        frontmatter[cleanKey] = value
-      } else {
-        processed[key] = value
-      }
-    })
-
-    processed.Frontmatter = frontmatter
-    return processed as MdxComponentsType
-  }, [components])
-
-  // Sync with global registry
-  if (typeof globalThis !== 'undefined') {
-    ;(globalThis as any)[MDX_COMPONENTS_INSTANCE_SYMBOL] = processedComponents
-  }
-
-  return (
-    <MdxComponentsContext.Provider value={processedComponents}>
-      {children}
-    </MdxComponentsContext.Provider>
-  )
-}

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

@@ -1,34 +0,0 @@
-import { createContext, use } from 'react'
-import type { ComponentRoute } from '../types'
-
-interface RoutesContextType {
-  routes: ComponentRoute[]
-}
-
-const RoutesContext = createContext<RoutesContextType>({
-  routes: [],
-})
-
-/**
- * Hook to access the processed routes list from the closest provider.
- */
-export function useRoutesContext() {
-  return use(RoutesContext)
-}
-
-/**
- * Provider component for the documentation routes.
- */
-export function RoutesProvider({
-  routes,
-  children,
-}: {
-  routes: ComponentRoute[]
-  children: React.ReactNode
-}) {
-  return (
-    <RoutesContext.Provider value={{ routes }}>
-      {children}
-    </RoutesContext.Provider>
-  )
-}

package/src/client/app/scroll-handler.tsx

@@ -1,74 +0,0 @@
-import { useEffect, useLayoutEffect } from 'react'
-import { useLocation } from 'react-router-dom'
-
-/**
- * Handles scroll restoration and hash scrolling on navigation.
- * It ensures the page scrolls to top on pathname changes,
- * or specifically to an anchor element if a hash is present.
- */
-export function ScrollHandler() {
-  const { pathname, hash } = useLocation()
-
-  // Helper to handle scroll logic
-  const handleScroll = (behavior: ScrollBehavior = 'auto') => {
-    const container = document.querySelector('.boltdocs-content') || window
-
-    const getScrollTop = () => {
-      if (container === window) return window.scrollY
-      return (container as HTMLElement).scrollTop
-    }
-
-    const scrollTo = (top: number, scrollBehavior: ScrollBehavior) => {
-      if (container === window) {
-        window.scrollTo({ top, behavior: scrollBehavior })
-      } else {
-        ;(container as HTMLElement).scrollTo({ top, behavior: scrollBehavior })
-      }
-    }
-
-    if (hash) {
-      const id = hash.replace('#', '')
-      const element = document.getElementById(id)
-      if (element) {
-        const offset = 80
-        const containerTop =
-          container === window
-            ? 0
-            : (container as HTMLElement).getBoundingClientRect().top
-        const elementRect = element.getBoundingClientRect().top
-        const elementPosition = elementRect - containerTop
-        const offsetPosition = elementPosition - offset + getScrollTop()
-
-        scrollTo(offsetPosition, behavior)
-        return true
-      }
-    }
-
-    scrollTo(0, behavior)
-    return false
-  }
-
-  // 1. Immediate sync scroll before paint
-  // biome-ignore lint/correctness/useExhaustiveDependencies: pathname is used as a trigger for scroll-to-top on navigation
-  useLayoutEffect(() => {
-    handleScroll('auto')
-  }, [pathname, hash])
-
-  // 2. Delayed async scroll as fallback/stabilizer after paint & passive effects
-  useEffect(() => {
-    // Immediate run after paint (helps override old component unmount/revert side effects)
-    handleScroll('auto')
-
-    // Double-check inside requestAnimationFrame to catch concurrent renders or dynamic layout recalculations
-    const rafId = requestAnimationFrame(() => {
-      handleScroll('auto')
-      // Dispatch resize event so external components/scroll libraries (like GSAP ScrollTrigger) recalculate trigger offsets
-      window.dispatchEvent(new Event('resize'))
-    })
-
-    return () => cancelAnimationFrame(rafId)
-  }, [pathname, hash])
-
-  return null
-}
-

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

@@ -1,103 +0,0 @@
-import { createContext, use, useState, useEffect } from 'react'
-
-export type Theme = 'light' | 'dark' | 'system'
-export type ResolvedTheme = 'light' | 'dark'
-
-interface ThemeContextType {
-  theme: Theme
-  resolvedTheme: ResolvedTheme
-  setTheme: (theme: Theme) => void
-}
-
-const THEME_CONTEXT_SYMBOL = Symbol.for('__BDOCS_THEME_CONTEXT__')
-const THEME_INSTANCE_SYMBOL = Symbol.for('__BDOCS_THEME_INSTANCE__')
-const THEME_EVENT = 'boltdocs-theme-change'
-
-const ThemeContext =
-  (globalThis as any)[THEME_CONTEXT_SYMBOL] ||
-  ((globalThis as any)[THEME_CONTEXT_SYMBOL] = createContext<
-    ThemeContextType | undefined
-  >(undefined))
-
-export function ThemeProvider({ children }: { children: React.ReactNode }) {
-  const [theme, setThemeState] = useState<Theme>('system')
-  const [resolvedTheme, setResolvedTheme] = useState<ResolvedTheme>('dark')
-
-  const applyTheme = (targetTheme: Theme) => {
-    const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)')
-    const isDark =
-      targetTheme === 'dark' || (targetTheme === 'system' && mediaQuery.matches)
-
-    const root = window.document.documentElement
-    root.classList.toggle('dark', isDark)
-    root.dataset.theme = isDark ? 'dark' : 'light'
-    setResolvedTheme(isDark ? 'dark' : 'light')
-  }
-
-  useEffect(() => {
-    const savedTheme = localStorage.getItem('boltdocs-theme') as Theme | null
-    if (savedTheme) {
-      setThemeState(savedTheme)
-      applyTheme(savedTheme)
-    } else {
-      applyTheme('system')
-    }
-
-    const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)')
-    const listener = () => {
-      const current =
-        (localStorage.getItem('boltdocs-theme') as Theme) || 'system'
-      if (current === 'system') applyTheme('system')
-    }
-
-    mediaQuery.addEventListener('change', listener)
-    return () => mediaQuery.removeEventListener('change', listener)
-  }, [])
-
-  const setTheme = (newTheme: Theme) => {
-    setThemeState(newTheme)
-    localStorage.setItem('boltdocs-theme', newTheme)
-    applyTheme(newTheme)
-
-    // Notify external listeners (dual-package hazard)
-    if (typeof window !== 'undefined') {
-      window.dispatchEvent(new CustomEvent(THEME_EVENT, { detail: newTheme }))
-    }
-  }
-
-  const value = { theme, resolvedTheme, setTheme }
-
-  // Sync with global registry
-  if (typeof globalThis !== 'undefined') {
-    ;(globalThis as any)[THEME_INSTANCE_SYMBOL] = value
-  }
-
-  return <ThemeContext.Provider value={value}>{children}</ThemeContext.Provider>
-}
-
-export function useTheme() {
-  const context = use(ThemeContext)
-  const [, forceUpdate] = useState({})
-
-  useEffect(() => {
-    if (context) return
-
-    const handler = () => forceUpdate({})
-    window.addEventListener(THEME_EVENT, handler)
-    return () => window.removeEventListener(THEME_EVENT, handler)
-  }, [context])
-
-  // Fallback to global registry for dual-package hazards
-  if (
-    !context &&
-    typeof globalThis !== 'undefined' &&
-    (globalThis as any)[THEME_INSTANCE_SYMBOL]
-  ) {
-    return (globalThis as any)[THEME_INSTANCE_SYMBOL] as ThemeContextType
-  }
-
-  if (context === undefined) {
-    throw new Error('useTheme must be used within a ThemeProvider')
-  }
-  return context as ThemeContextType
-}

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

@@ -1,42 +0,0 @@
-import { createContext, useContext, useState, useEffect } from 'react'
-import { useLocation } from 'react-router-dom'
-
-interface UIContextType {
-  isSidebarOpen: boolean
-  toggleSidebar: () => void
-  closeSidebar: () => void
-}
-
-const UIContext = createContext<UIContextType | undefined>(undefined)
-
-export function UIProvider({ children }: { children: React.ReactNode }) {
-  const [isSidebarOpen, setIsSidebarOpen] = useState(false)
-  const location = useLocation()
-
-  const toggleSidebar = () => setIsSidebarOpen((prev) => !prev)
-  const closeSidebar = () => setIsSidebarOpen(false)
-
-  // Close sidebar on navigation
-  useEffect(() => {
-    setIsSidebarOpen(false)
-  }, [location.pathname])
-
-  return (
-    <UIContext.Provider value={{ isSidebarOpen, toggleSidebar, closeSidebar }}>
-      {children}
-    </UIContext.Provider>
-  )
-}
-
-export function useUI() {
-  const context = useContext(UIContext)
-  if (context === undefined) {
-    // Safe fallback for split bundles, independent component renders, or during SSR
-    return {
-      isSidebarOpen: false,
-      toggleSidebar: () => {},
-      closeSidebar: () => {},
-    }
-  }
-  return context
-}

package/src/client/components/docs-layout-default.tsx

@@ -1,85 +0,0 @@
-import { DocsLayout as DocsLayoutPrimitive } from './primitives/docs-layout'
-import { Navbar } from './ui-base/navbar'
-import { Sidebar } from './ui-base/sidebar'
-import { OnThisPage } from './ui-base/on-this-page'
-import { Breadcrumbs } from './ui-base/breadcrumbs'
-import { PageNav } from './ui-base/page-nav'
-import { ErrorBoundary } from './ui-base/error-boundary'
-import { CopyMarkdown } from './ui-base/copy-markdown'
-import { useRoutes } from '../hooks/use-routes'
-import { useConfig } from '../app/config-context'
-
-interface DocsLayoutThemeProps {
-  children?: React.ReactNode
-}
-
-/**
- * Pre-assembled high-fidelity documentation layout component.
- * Fully styled and optimized to adapt seamlessly to our custom Parchment/Slate theme.
- */
-function DocsLayoutComponent({ children }: DocsLayoutThemeProps) {
-  const { routes: filteredRoutes, currentRoute } = useRoutes()
-  const config = useConfig()
-
-  return (
-    <DocsLayoutPrimitive className="selection:bg-primary-500/10 selection:text-primary-500">
-      <Navbar />
-      <DocsLayoutPrimitive.Body className="bg-main">
-        <Sidebar routes={filteredRoutes || []} config={config} />
-        <DocsLayoutPrimitive.Content className="animate-in fade-in duration-500 scroll-smooth">
-          <DocsLayoutPrimitive.ContentMdx className="max-w-3xl sm:max-w-4xl lg:max-w-4xl px-2 pt-8 pb-24">
-            <DocsLayoutPrimitive.Header>
-              <div className="mb-4 border-b border-subtle pb-4 flex flex-wrap items-center justify-between gap-3">
-                <Breadcrumbs />
-                <CopyMarkdown
-                  mdxRaw={currentRoute?._rawContent}
-                  route={currentRoute}
-                />
-              </div>
-
-              {/* Inject Main Page Heading automatically */}
-              {currentRoute?.title && (
-                <h1 className="text-4xl font-bold tracking-tight text-default mb-3">
-                  {currentRoute.title}
-                </h1>
-              )}
-              {currentRoute?.description && (
-                <p className="text-lg text-muted-foreground mb-6 leading-relaxed">
-                  {currentRoute.description}
-                </p>
-              )}
-            </DocsLayoutPrimitive.Header>
-
-            <ErrorBoundary>
-              <div className="prose prose-neutral dark:prose-invert max-w-none">
-                {children}
-              </div>
-            </ErrorBoundary>
-
-            <DocsLayoutPrimitive.Footer>
-              <PageNav />
-            </DocsLayoutPrimitive.Footer>
-          </DocsLayoutPrimitive.ContentMdx>
-        </DocsLayoutPrimitive.Content>
-        <OnThisPage
-          headings={currentRoute?.headings}
-          editLink={config.theme?.editLink}
-          communityHelp={config.theme?.communityHelp}
-          filePath={currentRoute?.filePath}
-        />
-      </DocsLayoutPrimitive.Body>
-    </DocsLayoutPrimitive>
-  )
-}
-
-// Expose the primitive sub-components directly on the Default DocsLayout
-// to maintain complete backward-compatibility for custom theme assemblies.
-export const DocsLayout = Object.assign(DocsLayoutComponent, {
-  Body: DocsLayoutPrimitive.Body,
-  Content: DocsLayoutPrimitive.Content,
-  ContentMdx: DocsLayoutPrimitive.ContentMdx,
-  Header: DocsLayoutPrimitive.Header,
-  Footer: DocsLayoutPrimitive.Footer,
-}) as any
-
-export default DocsLayout