boltdocs 2.6.1 → 2.7.0

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

@@ -0,0 +1,272 @@
+import { useCallback, useEffect, useMemo, useRef } from 'react'
+import { useLocation } from './use-location'
+import type { BoltdocsIntegrationsConfig } from '../../shared/types'
+
+declare global {
+  interface Window {
+    gtag?: (...args: unknown[]) => void
+    dataLayer?: unknown[]
+    gtag_report_conversion?: (url?: string) => boolean
+  }
+}
+
+export interface AnalyticsEvent {
+  action: string
+  category?: string
+  label?: string
+  value?: number
+  params?: Record<string, unknown>
+}
+
+export interface AnalyticsInstance {
+  trackPageView: (path: string, title?: string) => void
+  trackEvent: (event: AnalyticsEvent) => void
+  trackSearch: (query: string, resultsCount?: number) => void
+  trackDownload: (file: string, type?: string) => void
+  trackExternalLink: (url: string) => void
+  isEnabled: boolean
+}
+
+function createAnalyticsInstance(
+  config?: BoltdocsIntegrationsConfig,
+): AnalyticsInstance {
+  if (typeof window === 'undefined') {
+    return createDisabledAnalytics()
+  }
+
+  const isGtagAvailable = typeof window.gtag === 'function'
+
+  if (isGtagAvailable) {
+    return createGtagAnalytics(config)
+  }
+
+  if (window.dataLayer) {
+    return createDataLayerAnalytics(config)
+  }
+
+  return createDisabledAnalytics()
+}
+
+function createGtagAnalytics(
+  config?: BoltdocsIntegrationsConfig,
+): AnalyticsInstance {
+  return {
+    trackPageView: (path: string, title?: string) => {
+      window.gtag?.('event', 'page_view', {
+        page_path: path,
+        page_title: title || document.title,
+        send_to: config?.ga4?.measurementId,
+      })
+    },
+    trackEvent: ({ action, category, label, value, params }) => {
+      window.gtag?.('event', action, {
+        event_category: category,
+        event_label: label,
+        value,
+        send_to: config?.ga4?.measurementId,
+        ...params,
+      })
+    },
+    trackSearch: (query: string, resultsCount?: number) => {
+      window.gtag?.('event', 'search', {
+        search_term: query,
+        results_count: resultsCount,
+        send_to: config?.ga4?.measurementId,
+      })
+    },
+    trackDownload: (file: string, type?: string) => {
+      window.gtag?.('event', 'file_download', {
+        file_name: file,
+        file_type: type || file.split('.').pop(),
+        send_to: config?.ga4?.measurementId,
+      })
+    },
+    trackExternalLink: (url: string) => {
+      window.gtag?.('event', 'external_link', {
+        link_url: url,
+        send_to: config?.ga4?.measurementId,
+      })
+    },
+    isEnabled: true,
+  }
+}
+
+function createDataLayerAnalytics(
+  config?: BoltdocsIntegrationsConfig,
+): AnalyticsInstance {
+  return {
+    trackPageView: (path: string, title?: string) => {
+      window.dataLayer?.push({
+        event: 'page_view',
+        page_path: path,
+        page_title: title || document.title,
+        send_to: config?.gtm?.tagId,
+      })
+    },
+    trackEvent: ({ action, category, label, value, params }) => {
+      window.dataLayer?.push({
+        event: action,
+        event_category: category,
+        event_label: label,
+        value,
+        send_to: config?.gtm?.tagId,
+        ...params,
+      })
+    },
+    trackSearch: (query: string, resultsCount?: number) => {
+      window.dataLayer?.push({
+        event: 'search',
+        search_term: query,
+        results_count: resultsCount,
+        send_to: config?.gtm?.tagId,
+      })
+    },
+    trackDownload: (file: string, type?: string) => {
+      window.dataLayer?.push({
+        event: 'file_download',
+        file_name: file,
+        file_type: type || file.split('.').pop(),
+        send_to: config?.gtm?.tagId,
+      })
+    },
+    trackExternalLink: (url: string) => {
+      window.dataLayer?.push({
+        event: 'external_link',
+        link_url: url,
+        send_to: config?.gtm?.tagId,
+      })
+    },
+    isEnabled: true,
+  }
+}
+
+function createDisabledAnalytics(): AnalyticsInstance {
+  return {
+    trackPageView: () => {},
+    trackEvent: () => {},
+    trackSearch: () => {},
+    trackDownload: () => {},
+    trackExternalLink: () => {},
+    isEnabled: false,
+  }
+}
+
+export interface UseAnalyticsOptions {
+  config?: BoltdocsIntegrationsConfig
+  autoTrackPageViews?: boolean
+  autoTrackDownloads?: boolean
+  autoTrackExternalLinks?: boolean
+  excludePatterns?: RegExp[]
+}
+
+const CONFIG_INSTANCE_SYMBOL = Symbol.for('__BDOCS_CONFIG_INSTANCE__')
+
+export function useAnalytics(options: UseAnalyticsOptions = {}) {
+  const {
+    config: optionsConfig,
+    autoTrackPageViews = true,
+    autoTrackDownloads = true,
+    autoTrackExternalLinks = true,
+    excludePatterns = [],
+  } = options
+
+  const globalConfig =
+    typeof globalThis !== 'undefined'
+      ? ((globalThis as any)[CONFIG_INSTANCE_SYMBOL] as
+          | { integrations?: BoltdocsIntegrationsConfig }
+          | undefined)
+      : undefined
+  const config = optionsConfig ?? globalConfig?.integrations
+
+  const analytics = useMemo(() => createAnalyticsInstance(config), [config])
+
+  const previousPath = useRef<string>('')
+  const location = useLocation()
+
+  useEffect(() => {
+    if (!autoTrackPageViews || !analytics.isEnabled) return
+
+    const path = location.pathname + location.search
+
+    if (path !== previousPath.current) {
+      previousPath.current = path
+      analytics.trackPageView(path, document.title)
+    }
+  }, [location.pathname, autoTrackPageViews, analytics])
+
+  useEffect(() => {
+    if (!autoTrackDownloads || !analytics.isEnabled) return
+
+    const handleClick = (event: MouseEvent) => {
+      const target = (event.target as Element)?.closest('a')
+      if (!target) return
+
+      const href = target.getAttribute('href')
+      if (!href) return
+
+      if (excludePatterns.some((pattern) => pattern.test(href))) return
+
+      const isDownload =
+        target.hasAttribute('download') ||
+        /\.(pdf|doc|docx|xls|xlsx|ppt|pptx|zip|rar|7z|tar|gz|mp3|mp4|avi|mov|png|jpg|jpeg|gif|svg|webp)$/i.test(
+          href,
+        )
+
+      if (isDownload) {
+        const fileName = href.split('/').pop() || href
+        analytics.trackDownload(fileName, fileName.split('.').pop())
+      }
+    }
+
+    document.addEventListener('click', handleClick)
+    return () => document.removeEventListener('click', handleClick)
+  }, [autoTrackDownloads, autoTrackExternalLinks, analytics, excludePatterns])
+
+  useEffect(() => {
+    if (!autoTrackExternalLinks || !analytics.isEnabled) return
+
+    const handleClick = (event: MouseEvent) => {
+      const target = (event.target as Element)?.closest('a')
+      if (!target) return
+
+      const href = target.getAttribute('href')
+      if (!href) return
+
+      if (excludePatterns.some((pattern) => pattern.test(href))) return
+
+      const isExternal =
+        href.startsWith('http://') ||
+        href.startsWith('https://') ||
+        href.startsWith('//')
+
+      if (isExternal && !href.includes(window.location.hostname)) {
+        analytics.trackExternalLink(href)
+      }
+    }
+
+    document.addEventListener('click', handleClick)
+    return () => document.removeEventListener('click', handleClick)
+  }, [autoTrackExternalLinks, analytics, excludePatterns])
+
+  return analytics
+}
+
+export function useTrackPageView() {
+  const analytics = useMemo(() => createAnalyticsInstance(), [])
+  return useCallback(
+    (path: string, title?: string) => {
+      analytics.trackPageView(path, title)
+    },
+    [analytics],
+  )
+}
+
+export function useTrackEvent() {
+  const analytics = useMemo(() => createAnalyticsInstance(), [])
+  return useCallback(
+    (event: AnalyticsEvent) => {
+      analytics.trackEvent(event)
+    },
+    [analytics],
+  )
+}

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

@@ -1,20 +1,23 @@
+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: string
+  key: BoltdocsLocale
   label: string
   value: string
   isCurrent: boolean
 }
 
 export interface UseI18nReturn {
-  currentLocale: string | undefined
+  currentLocale: BoltdocsLocale | undefined
   currentLocaleLabel: string | undefined
   availableLocales: LocaleOption[]
-  handleLocaleChange: (locale: string) => void
+  handleLocaleChange: (locale: BoltdocsLocale) => void
 }
 
 /**
@@ -22,8 +25,8 @@ export interface UseI18nReturn {
  */
 export function useI18n(): UseI18nReturn {
   const navigate = useNavigate()
-  const routeContext = useRoutes()
-  const { allRoutes, currentRoute, currentLocale, config } = routeContext
+  const config = useConfig()
+  const { allRoutes, currentRoute, currentLocale, currentVersion } = useRoutes()
   const i18n = config.i18n
   const { setLocale } = useBoltdocsContext()
 
@@ -33,78 +36,142 @@ export function useI18n(): UseI18nReturn {
     // Update store
     setLocale(locale)
 
-    let targetPath = '/'
+    const base = config.base || '/'
+    const safeBase = base === '/' ? '' : base.replace(/\/$/, '')
+    const isDocRoute = !!currentRoute?.filePath
+
+    let targetPath = ''
 
     if (currentRoute) {
-      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,
-      )
+      // 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,
+        )
 
-      if (targetRoute) {
-        targetPath = targetRoute.path
-      } else {
-        const defaultIndexRoute = allRoutes.find(
+        const targetRoute = allRoutes.find(
           (r) =>
-            getBaseFilePath(r.filePath, r.version, r.locale) === 'index.md' &&
+            getBaseFilePath(r.filePath, r.version, r.locale) === baseFile &&
             (r.locale || i18n.defaultLocale) === locale &&
             r.version === currentRoute.version,
         )
-        targetPath = defaultIndexRoute
-          ? defaultIndexRoute.path
-          : locale === i18n.defaultLocale
-            ? currentRoute.version
-              ? `/${currentRoute.version}`
-              : '/'
-            : currentRoute.version
-              ? `/${currentRoute.version}/${locale}`
-              : `/${locale}`
+
+        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 {
-      // Fallback for when we don't have a current route (e.g. 404 page)
-      // Try to find the root documentation page for the target locale
+      // Case B: Fallback for Unknown / 404 page
+      // Try to find first available page that matches the intended combo
       const targetRoute = allRoutes.find(
         (r) =>
-          (r.filePath === 'index.mdx' || r.filePath === 'index.md') &&
           (r.locale || i18n.defaultLocale) === locale &&
-          !r.version, // Prefer non-versioned root
+          (r.version || config.versions?.defaultVersion) ===
+            (currentVersion || config.versions?.defaultVersion),
       )
 
       if (targetRoute) {
         targetPath = targetRoute.path
       } else {
-        targetPath = locale === i18n.defaultLocale ? '/' : `/${locale}`
+        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 currentLocaleConfig =
-    config.i18n?.localeConfigs?.[currentLocale as string]
+  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 ||
-    config.i18n?.locales[currentLocale as string] ||
-    currentLocale
-
-  const availableLocales = config.i18n
-    ? Object.entries(config.i18n.locales).map(([key, defaultLabel]) => {
-        const localeConfig = config.i18n?.localeConfigs?.[key]
-        return {
-          key,
-          label: localeConfig?.label || defaultLabel,
-          value: key,
-          isCurrent: key === currentLocale,
-        }
-      })
-    : []
+    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,

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

@@ -6,30 +6,62 @@ 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: RouterLinkProps['to']) {
+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 } =
-    useRoutes()
+  const {
+    currentLocale: activeLocale,
+    currentVersion: activeVersion,
+    allRoutes,
+  } = useRoutes()
 
   if (!config || typeof to !== 'string') return to
 
-  // External or absolute links don't need localization
-  if (to.startsWith('http') || to.startsWith('//')) 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
 
-  if (!i18n && !versions) return to
+  const rawParts = pathOnly.split('/').filter(Boolean)
 
-  // 1. Identify the input intent
-  const isDocLink = to.startsWith('/docs')
+  // 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 = to.split('/').filter(Boolean)
+  const parts = [...rawParts]
   let pIdx = 0
 
-  // Strip '/docs' if present at start
-  if (parts[pIdx] === 'docs') pIdx++
+  // Strip base segment if present at start
+  if (baseSegment && parts[pIdx] === baseSegment) pIdx++
 
   // Strip versions if present
   if (versions && parts.length > pIdx) {
@@ -38,36 +70,44 @@ export function useLocalizedTo(to: RouterLinkProps['to']) {
   }
 
   // Strip locales if present
-  if (i18n && parts.length > pIdx && i18n.locales[parts[pIdx]]) pIdx++
+  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 strictly from base
+  // 4. Reconstruct dynamically based on context
   const resultParts: string[] = []
 
-  if (isDocLink) {
-    resultParts.push('docs')
-    if (versions && activeVersion) {
-      resultParts.push(activeVersion)
-    }
-  }
-
-  if (i18n && activeLocale) {
-    // Only prefix if it's NOT the default locale (cleaner URLs)
-    if (activeLocale !== i18n.defaultLocale) {
-      resultParts.push(activeLocale)
-    }
+  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)
 
-  const finalPath = `/${resultParts.join('/')}`
+  let finalPath = `/${resultParts.join('/')}`
 
-  // Cleanup trailing slashes unless it's just root
-  if (finalPath.length > 1 && finalPath.endsWith('/')) {
-    return finalPath.slice(0, -1)
+  // Preserve trailing slash if present in input and output isn't just root
+  if (
+    pathOnly.endsWith('/') &&
+    pathOnly.length > 1 &&
+    !finalPath.endsWith('/')
+  ) {
+    finalPath += '/'
   }
 
-  return finalPath || '/'
+  // Restore original query/hash
+  const result = (finalPath || '/') + (hashAndQuery || '')
+  return result
 }