boltdocs 2.6.2 → 2.7.0

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

@@ -1,3 +1,4 @@
+import { useMemo } from 'react'
 import { useLocation } from 'react-router-dom'
 import { useConfig } from '../app/config-context'
 import { useTheme } from '../app/theme-context'
@@ -18,53 +19,82 @@ export function useNavbar() {
   const githubRepo = themeConfig.githubRepo
 
   // Transform links to the new NavbarLink structure
-  const links: NavbarLink[] = 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])) {
+  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)
         }
-        return parts.slice(i)
-      }
 
-      const hParts = cleanPathParts(h)
-      const pParts = cleanPathParts(activePath)
+        const hParts = cleanPathParts(h)
+        const pParts = cleanPathParts(activePath)
 
-      if (hParts.length === 0) return pParts.length === 0
+        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
+        // 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)
-    }
+        // Every part of hParts must match pParts at the same position
+        return hParts.every((part, i) => pParts[i] === part)
+      }
 
-    return {
-      label: getTranslated(item.label || item.text, currentLocale),
-      href,
-      active: getIsActive(href),
-      to:
-        href.startsWith('http') || href.startsWith('//')
-          ? 'external'
-          : undefined,
-    }
-  })
+      // 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'

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

@@ -1,3 +1,4 @@
+import { useMemo } from 'react'
 import { useLocation } from 'react-router-dom'
 import { useRoutes } from './use-routes'
 
@@ -9,35 +10,37 @@ export function usePageNav() {
   const { routes, currentRoute } = useRoutes()
   const location = useLocation()
 
-  if (!currentRoute) {
-    return {
-      prevPage: null,
-      nextPage: null,
-      currentRoute: null,
+  return useMemo(() => {
+    if (!currentRoute) {
+      return {
+        prevPage: null,
+        nextPage: null,
+        currentRoute: null,
+      }
     }
-  }
 
-  const activeTabId = currentRoute.tab?.toLowerCase()
+    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)
+    // 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 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
+    const prevPage = currentIndex > 0 ? contextRoutes[currentIndex - 1] : null
+    const nextPage =
+      currentIndex !== -1 && currentIndex < contextRoutes.length - 1
+        ? contextRoutes[currentIndex + 1]
+        : null
 
-  return {
-    prevPage,
-    nextPage,
-    currentRoute,
-  }
+    return {
+      prevPage,
+      nextPage,
+      currentRoute,
+    }
+  }, [routes, currentRoute, location.pathname])
 }

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

@@ -1,7 +1,9 @@
+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.
@@ -20,106 +22,87 @@ export function useRoutes() {
     currentVersion: currentVersionStore,
   } = useBoltdocsContext()
 
-  const normalize = (p: string) =>
-    p.endsWith('/') && p.length > 1 ? p.slice(0, -1) : p
-  const currentPath = normalize(location.pathname)
+  const currentPath = normalizePath(location.pathname)
 
-  // Find the current route matching the pathname
+  // Find the current active route matching the pathname
   const currentRoute = allRoutes?.find?.(
-    (r) => normalize(r.path) === currentPath,
+    (r) => normalizePath(r.path) === currentPath,
   )
 
-  // Derive current locale and version
-  // Priority: URL (currentRoute) > Zustand Store (Persistence) > Config Default
+  // 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
-    ? currentRoute?.locale ||
-      (hasHydrated ? currentLocaleStore : undefined) ||
-      config.i18n.defaultLocale
+    ? currentLocaleStore || config.i18n.defaultLocale
     : undefined
 
   const currentVersion = config.versions
-    ? currentRoute?.version ||
-      (hasHydrated ? currentVersionStore : undefined) ||
-      config.versions.defaultVersion
+    ? currentVersionStore || config.versions.defaultVersion
     : undefined
 
   // Filter routes to those matching the current version and locale
-  const routes = 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
-    // We prefer the version that matches the current route's prefix style
-    const i18n = config.i18n
-    if (i18n) {
-      const isCurrentRoutePrefixed = !!currentRoute?.locale
-      const isRoutePrefixed = !!r.locale
-
-      const hasAlternate = allRoutes?.some?.(
-        (alt) =>
-          alt !== r &&
-          alt.filePath === r.filePath &&
-          alt.version === r.version &&
-          (alt.locale || i18n.defaultLocale) ===
-            (r.locale || i18n.defaultLocale),
-      )
-
-      if (hasAlternate && isCurrentRoutePrefixed !== isRoutePrefixed) {
-        return false
-      }
+  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 true
-  })
-
-  // Labels and lists for UI convenience
-  const currentLocaleConfig =
-    config.i18n?.localeConfigs?.[currentLocale as string]
-  const currentLocaleLabel =
-    currentLocaleConfig?.label ||
-    config.i18n?.locales[currentLocale as string] ||
-    currentLocale
-
-  const currentVersionConfig = config.versions?.versions?.find?.(
-    (v) => v.path === currentVersion,
-  )
-  const currentVersionLabel = currentVersionConfig?.label || currentVersion
-
-  const availableLocales = config.i18n
-    ? Object.entries(config.i18n.locales).map(([key, defaultLabel]) => {
-        const localeConfig = config.i18n?.localeConfigs?.[key]
-        return {
-          key: key as import('../../shared/types').BoltdocsLocale,
-          label: localeConfig?.label || defaultLabel,
-          isCurrent: key === currentLocale,
+    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
         }
-      })
-    : []
+      }
 
-  const availableVersions = config.versions
-    ? config.versions.versions.map((v) => ({
-        key: v.path as import('../../shared/types').BoltdocsVersion,
-        label: v.label,
-        isCurrent: v.path === currentVersion,
-      }))
-    : []
+      return true
+    })
+  }, [allRoutes, config, currentLocale, currentVersion, currentRoute])
 
   return {
     routes,
     allRoutes,
     currentRoute,
     currentLocale: currentLocale as import('../../shared/types').BoltdocsLocale,
-    currentLocaleLabel,
-    availableLocales,
-    currentVersion: currentVersion as import('../../shared/types').BoltdocsVersion,
-    currentVersionLabel,
-    availableVersions,
-    config,
+    currentVersion:
+      currentVersion as import('../../shared/types').BoltdocsVersion,
   }
 }

package/src/client/hooks/use-search-highlight.ts

@@ -0,0 +1,185 @@
+import { useEffect } from 'react'
+import { useLocation } from './use-location'
+
+/**
+ * Hook to highlight search terms based on the 'hl' query parameter.
+ */
+export function useSearchHighlight(
+  containerSelector: string = '.boltdocs-page',
+) {
+  const { search } = useLocation()
+  const query = new URLSearchParams(search).get('hl')
+
+  useEffect(() => {
+    if (!query) {
+      clearHighlights(containerSelector)
+      return
+    }
+
+    const container = document.querySelector(containerSelector)
+    if (!container) return
+
+    let rafId: number
+
+    // Observe changes to the content (e.g. navigation or lazy loading)
+    const observer = new MutationObserver((mutations) => {
+      const hasExternalChanges = mutations.some((m) => {
+        const addedNodes = Array.from(m.addedNodes)
+        const removedNodes = Array.from(m.removedNodes)
+
+        return (
+          addedNodes.some(
+            (n) =>
+              !(
+                n instanceof HTMLElement &&
+                n.hasAttribute('data-search-highlight')
+              ),
+          ) ||
+          removedNodes.some(
+            (n) =>
+              !(
+                n instanceof HTMLElement &&
+                n.hasAttribute('data-search-highlight')
+              ),
+          )
+        )
+      })
+
+      if (hasExternalChanges) {
+        run()
+      }
+    })
+
+    // Function to run highlighting
+    function run() {
+      cancelAnimationFrame(rafId)
+      rafId = requestAnimationFrame(() => {
+        // Disconnect to avoid observing our own cleanup/highlight cycle
+        observer.disconnect()
+        clearHighlights(containerSelector)
+
+        // Split query into individual words (minimum 2 chars)
+        const terms = query!
+          .split(/\s+/)
+          .map((t) => t.trim())
+          .filter((t) => t.length >= 2)
+
+        if (terms.length > 0) {
+          highlightTerms(container!, terms)
+        }
+
+        // Re-observe
+        observer.observe(container!, { childList: true, subtree: true })
+      })
+    }
+
+    // Initial run
+    run()
+
+    return () => {
+      cancelAnimationFrame(rafId)
+      observer.disconnect()
+      clearHighlights(containerSelector)
+    }
+  }, [query, search, containerSelector])
+}
+
+function clearHighlights(selector: string) {
+  const marks = document.querySelectorAll(
+    `${selector} mark[data-search-highlight]`,
+  )
+  marks.forEach((mark) => {
+    try {
+      const parent = mark.parentNode
+      if (parent && parent.contains(mark)) {
+        const text = mark.textContent || ''
+        parent.replaceChild(document.createTextNode(text), mark)
+      }
+    } catch (e) {
+      // Ignore DOM errors during cleanup
+    }
+  })
+}
+
+function highlightTerms(container: Element, terms: string[]) {
+  const walker = document.createTreeWalker(container, NodeFilter.SHOW_TEXT, {
+    acceptNode: (node) => {
+      const parent = node.parentElement
+      if (
+        parent &&
+        (parent.tagName === 'SCRIPT' ||
+          parent.tagName === 'STYLE' ||
+          parent.tagName === 'MARK' ||
+          parent.closest('pre') ||
+          parent.closest('code'))
+      ) {
+        return NodeFilter.FILTER_REJECT
+      }
+      return NodeFilter.FILTER_ACCEPT
+    },
+  })
+
+  const nodes: Text[] = []
+  let node: Node | null
+  while ((node = walker.nextNode())) {
+    nodes.push(node as Text)
+  }
+
+  // Create a combined regex for all terms
+  // Accent-insensitive helper: replaces 'a' with '[aáàä...]'
+  const accentMap: Record<string, string> = {
+    a: '[aáàäâã]',
+    e: '[eéèëê]',
+    i: '[iíìïî]',
+    o: '[oóòöôõ]',
+    u: '[uúùüû]',
+    n: '[nñ]',
+    c: '[cç]',
+  }
+
+  const prepareRegex = (term: string) => {
+    let pattern = term.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+    // Make it accent insensitive
+    pattern = pattern
+      .split('')
+      .map((char) => {
+        const lower = char.toLowerCase()
+        return accentMap[lower] || char
+      })
+      .join('')
+    return pattern
+  }
+
+  const combinedPattern = terms.map(prepareRegex).join('|')
+  const regex = new RegExp(`(${combinedPattern})`, 'gi')
+
+  const matchRegexes = terms.map((term) => {
+    const p = prepareRegex(term)
+    return new RegExp(`^${p}$`, 'i')
+  })
+
+  nodes.forEach((textNode) => {
+    const text = textNode.textContent
+    if (text && regex.test(text)) {
+      const fragment = document.createDocumentFragment()
+      const parts = text.split(regex)
+
+      parts.forEach((part) => {
+        const isMatch = matchRegexes.some((rx) => rx.test(part))
+
+        if (isMatch) {
+          const mark = document.createElement('mark')
+          mark.textContent = part
+          mark.setAttribute('data-search-highlight', 'true')
+          fragment.appendChild(mark)
+        } else if (part) {
+          fragment.appendChild(document.createTextNode(part))
+        }
+      })
+
+      if (textNode.parentNode) {
+        textNode.parentNode.replaceChild(fragment, textNode)
+      }
+    }
+  })
+}

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

@@ -2,7 +2,7 @@ import { useState, useMemo, useEffect } from 'react'
 import { Index } from 'flexsearch'
 import { useRoutes } from './use-routes'
 import type { ComponentRoute } from '../types'
-// @ts-ignore
+// @ts-expect-error
 import searchData from 'virtual:boltdocs-search'
 
 interface SearchDataItem {
@@ -40,6 +40,15 @@ export function useSearch(routes: ComponentRoute[]) {
     setIndex(newIndex)
   }, [isOpen, index])
 
+  // Pre-index searchData for O(1) lookups
+  const searchDataMap = useMemo(() => {
+    const map = new Map<string, SearchDataItem>()
+    for (const doc of searchData as SearchDataItem[]) {
+      map.set(doc.id, doc)
+    }
+    return map
+  }, [])
+
   const list = useMemo(() => {
     if (!query) {
       // Default results: just active routes
@@ -70,7 +79,7 @@ export function useSearch(routes: ComponentRoute[]) {
     const seen = new Set<string>()
 
     for (const id of searchResults) {
-      const doc = (searchData as SearchDataItem[]).find((d) => d.id === id)
+      const doc = searchDataMap.get(id as string)
       if (!doc) continue
 
       // Filter by locale and version
@@ -92,7 +101,7 @@ export function useSearch(routes: ComponentRoute[]) {
     }
 
     return results.slice(0, 10)
-  }, [query, index, currentLocale, currentVersion, routes])
+  }, [query, index, currentLocale, currentVersion, routes, searchDataMap])
 
   return {
     isOpen,