boltdocs 2.7.10 → 2.8.0

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

@@ -1,182 +0,0 @@
-import { useMemo } from 'react'
-import { useNavigate } from 'react-router-dom'
-import { getBaseFilePath } from '../utils/get-base-file-path'
-import { useRoutes } from './use-routes'
-import { useConfig } from '../app/config-context'
-import { useBoltdocsContext } from '../store/boltdocs-context'
-import type { BoltdocsLocale } from '../../shared/types'
-
-export interface LocaleOption {
-  key: BoltdocsLocale
-  label: string
-  value: string
-  isCurrent: boolean
-}
-
-export interface UseI18nReturn {
-  currentLocale: BoltdocsLocale | undefined
-  currentLocaleLabel: string | undefined
-  availableLocales: LocaleOption[]
-  handleLocaleChange: (locale: BoltdocsLocale) => void
-}
-
-/**
- * Hook to manage and switch between different locales (languages) of the documentation.
- */
-export function useI18n(): UseI18nReturn {
-  const navigate = useNavigate()
-  const config = useConfig()
-  const { allRoutes, currentRoute, currentLocale, currentVersion } = useRoutes()
-  const i18n = config.i18n
-  const { setLocale } = useBoltdocsContext()
-
-  const handleLocaleChange = (locale: string) => {
-    if (!i18n || locale === currentLocale) return
-
-    // Update store
-    setLocale(locale)
-
-    const base = config.base || '/'
-    const safeBase = base === '/' ? '' : base.replace(/\/$/, '')
-    const isDocRoute = !!currentRoute?.filePath
-
-    let targetPath = ''
-
-    if (currentRoute) {
-      // Case A: We are on a known route. Determine if it is doc or external.
-      if (isDocRoute) {
-        // Documentation Context logic
-        const baseFile = getBaseFilePath(
-          currentRoute.filePath,
-          currentRoute.version,
-          currentRoute.locale,
-        )
-
-        const targetRoute = allRoutes.find(
-          (r) =>
-            getBaseFilePath(r.filePath, r.version, r.locale) === baseFile &&
-            (r.locale || i18n.defaultLocale) === locale &&
-            r.version === currentRoute.version,
-        )
-
-        if (targetRoute) {
-          targetPath = targetRoute.path
-        } else {
-          // Recovery: Find target index, or hardcode reconstruct using version space
-          const defaultIndexRoute = allRoutes.find(
-            (r) =>
-              getBaseFilePath(r.filePath, r.version, r.locale) === 'index.md' &&
-              (r.locale || i18n.defaultLocale) === locale &&
-              r.version === currentRoute.version,
-          )
-
-          if (defaultIndexRoute) {
-            targetPath = defaultIndexRoute.path
-          } else {
-            // Hardcoded absolute construction preserving existing version structure
-            const vPath = currentRoute.version ? `/${currentRoute.version}` : ''
-            const lPath = locale === i18n.defaultLocale ? '' : `/${locale}`
-            targetPath = `${safeBase}${vPath}${lPath}` || '/'
-          }
-        }
-      } else {
-        // External Context Logic: simply rewrite the current absolute path
-        // Extract pure relative component by stripping existing locale prefix
-        let rawExternal = currentRoute.path
-
-        // Strip existing locale if any
-        const parts = rawExternal.split('/').filter(Boolean)
-        if (
-          parts.length > 0 &&
-          (Array.isArray(i18n.locales)
-            ? i18n.locales.includes(parts[0])
-            : !!i18n.locales[parts[0]])
-        ) {
-          // Already prefixed external route like /es/about -> become /about
-          parts.shift()
-          rawExternal = '/' + parts.join('/')
-        }
-
-        // Re-apply new locale
-        if (locale === i18n.defaultLocale) {
-          targetPath = rawExternal === '' ? '/' : rawExternal
-        } else {
-          const cleanExt = rawExternal.startsWith('/')
-            ? rawExternal
-            : `/${rawExternal}`
-          targetPath = `/${locale}${cleanExt === '/' ? '' : cleanExt}`
-        }
-      }
-    } else {
-      // Case B: Fallback for Unknown / 404 page
-      // Try to find first available page that matches the intended combo
-      const targetRoute = allRoutes.find(
-        (r) =>
-          (r.locale || i18n.defaultLocale) === locale &&
-          (r.version || config.versions?.defaultVersion) ===
-            (currentVersion || config.versions?.defaultVersion),
-      )
-
-      if (targetRoute) {
-        targetPath = targetRoute.path
-      } else {
-        const vPath =
-          currentVersion && currentVersion !== config.versions?.defaultVersion
-            ? `/${currentVersion}`
-            : ''
-        targetPath =
-          locale === i18n.defaultLocale
-            ? `${safeBase}${vPath}`
-            : `${safeBase}${vPath}/${locale}`
-      }
-    }
-
-    // Final safety check: cleanup double slashes and empty targets
-    if (!targetPath || targetPath === '') targetPath = '/'
-    targetPath = targetPath.replace(/\/+/g, '/')
-
-    navigate(targetPath)
-  }
-
-  const locales = i18n?.locales
-  const defaultLabel = locales
-    ? Array.isArray(locales)
-      ? currentLocale
-      : (locales as Record<string, string>)[currentLocale as string]
-    : undefined
-
-  const currentLocaleConfig = i18n?.localeConfigs?.[currentLocale as string]
-  const currentLocaleLabel =
-    currentLocaleConfig?.label || defaultLabel || currentLocale
-
-  const availableLocales = useMemo(() => {
-    return i18n
-      ? Array.isArray(i18n.locales)
-        ? i18n.locales.map((key) => {
-            const localeConfig = i18n?.localeConfigs?.[key]
-            return {
-              key: key as BoltdocsLocale,
-              label: localeConfig?.label || key,
-              value: key,
-              isCurrent: key === currentLocale,
-            }
-          })
-        : Object.entries(i18n.locales).map(([key, label]) => {
-            const localeConfig = i18n?.localeConfigs?.[key]
-            return {
-              key: key as BoltdocsLocale,
-              label: localeConfig?.label || label,
-              value: key,
-              isCurrent: key === currentLocale,
-            }
-          })
-      : []
-  }, [i18n, currentLocale])
-
-  return {
-    currentLocale,
-    currentLocaleLabel,
-    availableLocales,
-    handleLocaleChange,
-  }
-}

package/src/client/hooks/use-localized-to.ts

@@ -1,113 +0,0 @@
-import { useConfig } from '../app/config-context'
-import type { LinkProps as RouterLinkProps } from 'react-router-dom'
-import { useRoutes } from './use-routes'
-
-/**
- * Hook to automatically localize a path based on the current version and locale context.
- * It ensures that navigation preserves the active version and language across the entire site.
- */
-export function useLocalizedTo(to: string): string
-export function useLocalizedTo(to: RouterLinkProps['to']): RouterLinkProps['to']
-export function useLocalizedTo(
-  to: RouterLinkProps['to'],
-): RouterLinkProps['to'] {
-  const config = useConfig()
-  const {
-    currentLocale: activeLocale,
-    currentVersion: activeVersion,
-    allRoutes,
-  } = useRoutes()
-
-  if (!config || typeof to !== 'string') return to
-
-  // External, absolute, or anchor links don't need localization prefixing
-  if (
-    to.startsWith('http') ||
-    to.startsWith('//') ||
-    to.startsWith('#') ||
-    to.startsWith('site:')
-  ) {
-    return to.replace('site:', '')
-  }
-
-  // 0. Identify if the incoming path is explicitly registered as a known route
-  const [pathOnly, hashAndQuery] = to.split(/([?#].*)/s)
-  const normalizedTo =
-    pathOnly.endsWith('/') && pathOnly.length > 1
-      ? pathOnly.slice(0, -1)
-      : pathOnly
-
-  const isKnownRoute = allRoutes?.some((r) => {
-    const rp =
-      r.path.endsWith('/') && r.path.length > 1 ? r.path.slice(0, -1) : r.path
-    return rp === (normalizedTo || '/')
-  })
-
-  const i18n = config.i18n
-  const versions = config.versions
-  const base = (config.base || '/docs').replace(/\/$/, '')
-  const baseSegment = base.startsWith('/') ? base.substring(1) : base
-
-  const rawParts = pathOnly.split('/').filter(Boolean)
-
-  // Classify: it's a Doc Path if it explicitly contains base segment,
-  // OR if it's an 'unknown' path (backward compatible fallback assumes unknown = doc).
-  const hasExplicitBase =
-    baseSegment && rawParts.length > 0 && rawParts[0] === baseSegment
-  const isDocsPath = hasExplicitBase || (!isKnownRoute && rawParts.length > 0)
-
-  // 3. Clean the 'to' path of ANY existing prefixes to avoid stacking
-  const parts = [...rawParts]
-  let pIdx = 0
-
-  // Strip base segment if present at start
-  if (baseSegment && parts[pIdx] === baseSegment) pIdx++
-
-  // Strip versions if present
-  if (versions && parts.length > pIdx) {
-    const vMatch = versions.versions.find((v) => v.path === parts[pIdx])
-    if (vMatch) pIdx++
-  }
-
-  // Strip locales if present
-  const isLocale =
-    i18n &&
-    parts.length > pIdx &&
-    (Array.isArray(i18n.locales)
-      ? i18n.locales.includes(parts[pIdx])
-      : parts[pIdx] in i18n.locales)
-  if (isLocale) pIdx++
-
-  // The actual relative route remaining
-  const routeContent = parts.slice(pIdx)
-
-  // 4. Reconstruct dynamically based on context
-  const resultParts: string[] = []
-
-  if (isDocsPath) {
-    // Reconstruct DOCS path: /base/version/locale/content
-    if (baseSegment) resultParts.push(baseSegment)
-    if (versions && activeVersion) resultParts.push(activeVersion)
-    if (i18n && activeLocale) resultParts.push(activeLocale)
-  } else {
-    // Reconstruct EXTERNAL path: /locale/content
-    if (i18n && activeLocale) resultParts.push(activeLocale)
-  }
-
-  resultParts.push(...routeContent)
-
-  let finalPath = `/${resultParts.join('/')}`
-
-  // Preserve trailing slash if present in input and output isn't just root
-  if (
-    pathOnly.endsWith('/') &&
-    pathOnly.length > 1 &&
-    !finalPath.endsWith('/')
-  ) {
-    finalPath += '/'
-  }
-
-  // Restore original query/hash
-  const result = (finalPath || '/') + (hashAndQuery || '')
-  return result
-}

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

@@ -1,5 +0,0 @@
-import { useLocation as useReactLocation } from 'react-router-dom'
-
-export const useLocation = () => {
-  return useReactLocation()
-}

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

@@ -1,130 +0,0 @@
-import { useMemo } from 'react'
-import { useLocation } from 'react-router-dom'
-import { useConfig } from '../app/config-context'
-import { useTheme } from '../app/theme-context'
-import type { NavbarLink } from '../types'
-import { getTranslated } from '../utils/i18n'
-import { useRoutes } from './use-routes'
-
-export function useNavbar() {
-  const config = useConfig()
-  const { theme, resolvedTheme } = useTheme()
-  const location = useLocation()
-  const { currentLocale } = useRoutes()
-
-  const themeConfig = config.theme || {}
-  const title = getTranslated(themeConfig.title, currentLocale) || 'Boltdocs'
-  const rawLinks = themeConfig.navbar || []
-  const socialLinks = themeConfig.socialLinks || []
-  const githubRepo = themeConfig.githubRepo
-
-  // Transform links to the new NavbarLink structure
-  const links: NavbarLink[] = useMemo(() => {
-    return rawLinks.map((item: any) => {
-      const href = (item.href || item.to || item.link || '') as string
-
-      // Robust active state calculation
-      const getIsActive = (h: string) => {
-        const activePath = location.pathname
-        if (activePath === h) return true
-        if (!h || h === '/') return activePath === '/'
-
-        const cleanPathParts = (p: string) => {
-          const parts = p.split('/').filter(Boolean)
-          let i = 0
-          // Skip locale
-          if (
-            config.i18n?.locales &&
-            parts[i] &&
-            config.i18n.locales[parts[i]]
-          ) {
-            i++
-          }
-          // Skip version
-          if (config.versions?.versions && parts[i]) {
-            if (config.versions.versions.some((v) => v.path === parts[i])) {
-              i++
-            }
-          }
-          return parts.slice(i)
-        }
-
-        const hParts = cleanPathParts(h)
-        const pParts = cleanPathParts(activePath)
-
-        if (hParts.length === 0) return pParts.length === 0
-
-        // Must match at least as many parts as the candidate link
-        if (pParts.length < hParts.length) return false
-
-        // Every part of hParts must match pParts at the same position
-        return hParts.every((part, i) => pParts[i] === part)
-      }
-
-      // Process nested items recursively
-      const processItems = (items?: any[]): NavbarLink[] => {
-        if (!items || items.length === 0) return undefined as any
-        return items.map((subItem: any) => {
-          const subHref = (subItem.href ||
-            subItem.to ||
-            subItem.link ||
-            '') as string
-          return {
-            label: getTranslated(subItem.label || subItem.text, currentLocale),
-            href: subHref,
-            active: getIsActive(subHref),
-            to:
-              subHref.startsWith('http') || subHref.startsWith('//')
-                ? 'external'
-                : undefined,
-          }
-        })
-      }
-
-      const linkItems = processItems(item.items)
-
-      return {
-        label: getTranslated(item.label || item.text, currentLocale),
-        href,
-        active: getIsActive(href),
-        to:
-          href.startsWith('http') || href.startsWith('//')
-            ? 'external'
-            : undefined,
-        items: linkItems,
-      }
-    })
-  }, [rawLinks, location.pathname, currentLocale, config])
-
-  const logo = themeConfig.logo
-  // Use resolvedTheme so 'system' correctly maps to 'dark' or 'light'
-  // based on the OS preference, instead of always falling back to 'light'.
-  const logoSrc = !logo
-    ? null
-    : typeof logo === 'string'
-      ? logo
-      : resolvedTheme === 'dark'
-        ? (logo as any).dark
-        : (logo as any).light
-
-  const logoProps = {
-    alt:
-      (logo && typeof logo === 'object' ? (logo as any).alt : undefined) ||
-      title,
-    width: logo && typeof logo === 'object' ? (logo as any).width : undefined,
-    height: logo && typeof logo === 'object' ? (logo as any).height : undefined,
-  }
-
-  const github = githubRepo ? `https://github.com/${githubRepo}` : null
-
-  return {
-    links,
-    title,
-    logo: logoSrc,
-    logoProps,
-    github,
-    social: socialLinks,
-    config,
-    theme,
-  }
-}

package/src/client/hooks/use-page-nav.ts

@@ -1,46 +0,0 @@
-import { useMemo } from 'react'
-import { useLocation } from 'react-router-dom'
-import { useRoutes } from './use-routes'
-
-/**
- * Hook to manage the previous and next button functionality for documentation pages.
- * Intelligent: respects current locale, version, and tab to keep navigation logical.
- */
-export function usePageNav() {
-  const { routes, currentRoute } = useRoutes()
-  const location = useLocation()
-
-  return useMemo(() => {
-    if (!currentRoute) {
-      return {
-        prevPage: null,
-        nextPage: null,
-        currentRoute: null,
-      }
-    }
-
-    const activeTabId = currentRoute.tab?.toLowerCase()
-
-    // Subset of routes that match the current context (locale and version are already filtered by useRoutes)
-    // We further filter by tab to keep the user in the same logical section
-    const contextRoutes = activeTabId
-      ? routes.filter((r) => r.tab?.toLowerCase() === activeTabId)
-      : routes.filter((r) => !r.tab)
-
-    const currentIndex = contextRoutes.findIndex(
-      (r) => r.path === location.pathname,
-    )
-
-    const prevPage = currentIndex > 0 ? contextRoutes[currentIndex - 1] : null
-    const nextPage =
-      currentIndex !== -1 && currentIndex < contextRoutes.length - 1
-        ? contextRoutes[currentIndex + 1]
-        : null
-
-    return {
-      prevPage,
-      nextPage,
-      currentRoute,
-    }
-  }, [routes, currentRoute, location.pathname])
-}

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

@@ -1,108 +0,0 @@
-import { useMemo } from 'react'
-import { useLocation } from 'react-router-dom'
-import { useConfig } from '../app/config-context'
-import { useRoutesContext } from '../app/routes-context'
-import { useBoltdocsContext } from '../store/boltdocs-context'
-import { normalizePath } from '../utils/path'
-
-/**
- * Hook to access the framework's routing state.
- * Returns both the complete set of routes and a filtered list based on the current
- * version and locale.
- */
-export function useRoutes() {
-  const { routes: allRoutes } = useRoutesContext()
-  const config = useConfig()
-  const location = useLocation()
-
-  // Use Zustand store for active state
-  const {
-    hasHydrated,
-    currentLocale: currentLocaleStore,
-    currentVersion: currentVersionStore,
-  } = useBoltdocsContext()
-
-  const currentPath = normalizePath(location.pathname)
-
-  // Find the current active route matching the pathname
-  const currentRoute = allRoutes?.find?.(
-    (r) => normalizePath(r.path) === currentPath,
-  )
-
-  // 2. STRICT SOURCE OF TRUTH:
-  // Derive the active states exclusively from the hydrated Context Store.
-  // This ensures that user preference (LocalStorage) takes precedence over ambiguous URL fallbacks.
-  const currentLocale = config.i18n
-    ? currentLocaleStore || config.i18n.defaultLocale
-    : undefined
-
-  const currentVersion = config.versions
-    ? currentVersionStore || config.versions.defaultVersion
-    : undefined
-
-  // Filter routes to those matching the current version and locale
-  const routes = useMemo(() => {
-    if (!allRoutes) return []
-
-    // Pre-calculate alternate presence using a Map of maps or a composite key
-    // Key: filePath | (locale || defaultLocale) | (version || defaultVersion)
-    const alternateCounts = new Map<string, number>()
-    const defaultLocale = config.i18n?.defaultLocale || ''
-    const defaultVersion = config.versions?.defaultVersion || ''
-
-    for (const r of allRoutes) {
-      const locale = r.locale || defaultLocale
-      const version = r.version || defaultVersion
-      const key = `${r.filePath}::${locale}::${version}`
-      alternateCounts.set(key, (alternateCounts.get(key) || 0) + 1)
-    }
-
-    return allRoutes.filter((r) => {
-      const localeMatch = config.i18n
-        ? (r.locale || config.i18n.defaultLocale) === currentLocale
-        : true
-      const versionMatch = config.versions
-        ? (r.version || config.versions.defaultVersion) === currentVersion
-        : true
-
-      if (!(localeMatch && versionMatch)) return false
-
-      // Resolve duplicate paths (aliases) like /docs vs /docs/en
-      // 3. Resolve duplicate route aliases (e.g., /docs/page vs /docs/latest/page or /docs/es/page)
-      // If duplicates exist, we only show the style (prefixed or unprefixed) that matches the user's current page style.
-      const isCurrentLocalePrefixed = !!currentRoute?.locale
-      const isCurrentVersionPrefixed = !!currentRoute?.version
-
-      const isRouteLocalePrefixed = !!r.locale
-      const isRouteVersionPrefixed = !!r.version
-
-      const locale = r.locale || defaultLocale
-      const version = r.version || defaultVersion
-      const key = `${r.filePath}::${locale}::${version}`
-      const hasAlternate = (alternateCounts.get(key) || 0) > 1
-
-      if (hasAlternate) {
-        // Style mismatch checks
-        const localeMismatch =
-          config.i18n && isCurrentLocalePrefixed !== isRouteLocalePrefixed
-        const versionMismatch =
-          config.versions && isCurrentVersionPrefixed !== isRouteVersionPrefixed
-
-        if (localeMismatch || versionMismatch) {
-          return false
-        }
-      }
-
-      return true
-    })
-  }, [allRoutes, config, currentLocale, currentVersion, currentRoute])
-
-  return {
-    routes,
-    allRoutes,
-    currentRoute,
-    currentLocale: currentLocale as import('../../shared/types').BoltdocsLocale,
-    currentVersion:
-      currentVersion as import('../../shared/types').BoltdocsVersion,
-  }
-}