boltdocs 2.1.1 → 2.3.0

package/src/client/components/ui-base/sidebar.tsx

@@ -8,7 +8,8 @@ import type { BoltdocsConfig } from '@node/config'
 
 function getIcon(iconName?: string): React.ElementType | undefined {
   if (!iconName) return undefined
-  const IconComponent = (LucideIcons as Record<string, any>)[iconName]
+  const icons = LucideIcons as unknown as Record<string, React.ElementType>
+  const IconComponent = icons[iconName]
   return IconComponent || undefined
 }
 
@@ -45,16 +46,21 @@ function CollapsibleSidebarGroup({
       isOpen={isOpen}
       onToggle={() => setIsOpen(!isOpen)}
     >
-      {group.routes.map((route: ComponentRoute) => (
-        <SidebarPrimitive.SidebarLink
-          key={route.path}
-          label={route.title}
-          href={route.path}
-          active={activePath === route.path}
-          icon={getIcon(route.icon)}
-          badge={route.badge}
-        />
-      ))}
+      {group.routes.map((route: ComponentRoute) => {
+        const isCurrent =
+          activePath ===
+          (route.path.endsWith('/') ? route.path.slice(0, -1) : route.path)
+        return (
+          <SidebarPrimitive.SidebarLink
+            key={route.path}
+            label={route.title}
+            href={route.path}
+            active={isCurrent}
+            icon={getIcon(route.icon)}
+            badge={route.badge}
+          />
+        )
+      })}
     </SidebarPrimitive.SidebarGroup>
   )
 }
@@ -67,22 +73,27 @@ export function Sidebar({
   config: BoltdocsConfig
 }) {
   const { groups, ungrouped, activePath } = useSidebar(routes)
-  const themeConfig = config.theme || config.themeConfig || {}
+  const themeConfig = config.theme || {}
 
   return (
     <SidebarPrimitive.SidebarRoot>
       {ungrouped.length > 0 && (
         <SidebarPrimitive.SidebarGroup className="mb-6">
-          {ungrouped.map((route) => (
-            <SidebarPrimitive.SidebarLink
-              key={route.path}
-              label={route.title}
-              href={route.path}
-              active={activePath === route.path}
-              icon={getIcon(route.icon)}
-              badge={route.badge}
-            />
-          ))}
+          {ungrouped.map((route) => {
+            const isCurrent =
+              activePath ===
+              (route.path.endsWith('/') ? route.path.slice(0, -1) : route.path)
+            return (
+              <SidebarPrimitive.SidebarLink
+                key={route.path}
+                label={route.title}
+                href={route.path}
+                active={isCurrent}
+                icon={getIcon(route.icon)}
+                badge={route.badge}
+              />
+            )
+          })}
         </SidebarPrimitive.SidebarGroup>
       )}
 

package/src/client/components/ui-base/tabs.tsx

@@ -3,6 +3,8 @@ import T from '@components/primitives/tabs'
 import { Link } from '@components/primitives/link'
 import type { BoltdocsTab, ComponentRoute } from '@client/types'
 import * as Icons from 'lucide-react'
+import { getTranslated } from '@client/utils/i18n'
+import { useRoutes } from '@hooks/use-routes'
 
 export function Tabs({
   tabs,
@@ -11,6 +13,7 @@ export function Tabs({
   tabs: BoltdocsTab[]
   routes: ComponentRoute[]
 }) {
+  const { currentLocale } = useRoutes()
   const { indicatorStyle, tabRefs, activeIndex } = useTabsHook(tabs, routes)
 
   const renderTabIcon = (iconName?: string) => {
@@ -54,7 +57,7 @@ export function Tabs({
               }`}
             >
               {renderTabIcon(tab.icon)}
-              <span>{tab.text}</span>
+              <span>{getTranslated(tab.text, currentLocale)}</span>
             </Link>
           )
         })}

package/src/client/components/ui-base/theme-toggle.tsx

@@ -1,10 +1,11 @@
 import { useEffect, useState } from 'react'
-import { Sun, Moon } from 'lucide-react'
+import { Sun, Moon, Monitor } from 'lucide-react'
 import { useTheme } from '@client/app/theme-context'
-import { ToggleButton } from 'react-aria-components'
+import { Button } from 'react-aria-components'
+import { Menu, MenuItem, MenuTrigger } from '@components/primitives/menu'
 
 export function ThemeToggle() {
-  const { theme, toggleTheme } = useTheme()
+  const { theme, setTheme } = useTheme()
   const [mounted, setMounted] = useState(false)
 
   useEffect(() => {
@@ -15,18 +16,37 @@ export function ThemeToggle() {
     return <div className="h-9 w-9" />
   }
 
+  const Icon = theme === 'system' ? Monitor : theme === 'dark' ? Moon : Sun
+
   return (
-    <ToggleButton
-      onChange={toggleTheme}
-      className="flex h-9 w-9 items-center justify-center rounded-md text-text-muted transition-colors hover:bg-bg-surface hover:text-text-main"
-      aria-label="Toggle theme"
-      isSelected={theme === 'dark'}
-    >
-      {theme === 'dark' ? (
-        <Sun size={20} className="animate-in fade-in zoom-in duration-300" />
-      ) : (
-        <Moon size={20} className="animate-in fade-in zoom-in duration-300" />
-      )}
-    </ToggleButton>
+    <MenuTrigger placement="bottom right">
+      <Button
+        className="flex h-9 w-9 items-center justify-center rounded-md text-text-muted transition-colors hover:bg-bg-surface hover:text-text-main outline-none focus-visible:ring-2 focus-visible:ring-primary-500"
+        aria-label="Selection theme"
+      >
+        <Icon size={20} className="animate-in fade-in zoom-in duration-300" />
+      </Button>
+      <Menu
+        selectionMode="single"
+        selectedKeys={[theme]}
+        onSelectionChange={(keys) => {
+          const newTheme = Array.from(keys)[0] as 'light' | 'dark' | 'system'
+          setTheme(newTheme)
+        }}
+      >
+        <MenuItem id="light">
+          <Sun size={16} />
+          <span>Light</span>
+        </MenuItem>
+        <MenuItem id="dark">
+          <Moon size={16} />
+          <span>Dark</span>
+        </MenuItem>
+        <MenuItem id="system">
+          <Monitor size={16} />
+          <span>System</span>
+        </MenuItem>
+      </Menu>
+    </MenuTrigger>
   )
 }

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

@@ -1,6 +1,7 @@
 import { useNavigate } from 'react-router-dom'
 import { getBaseFilePath } from '@client/utils/get-base-file-path'
 import { useRoutes } from './use-routes'
+import { useBoltdocsStore } from '../store/use-boltdocs-store'
 
 export interface LocaleOption {
   key: string
@@ -24,10 +25,14 @@ export function useI18n(): UseI18nReturn {
   const routeContext = useRoutes()
   const { allRoutes, currentRoute, currentLocale, config } = routeContext
   const i18n = config.i18n
+  const setLocale = useBoltdocsStore((s) => s.setLocale)
 
   const handleLocaleChange = (locale: string) => {
     if (!i18n || locale === currentLocale) return
 
+    // Update store
+    setLocale(locale)
+
     let targetPath = '/'
 
     if (currentRoute) {
@@ -63,21 +68,47 @@ export function useI18n(): UseI18nReturn {
               : `/${locale}`
       }
     } else {
-      targetPath = locale === i18n.defaultLocale ? '/' : `/${locale}`
+      // 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
+      const targetRoute = allRoutes.find(
+        (r) =>
+          (r.filePath === 'index.mdx' || r.filePath === 'index.md') &&
+          (r.locale || i18n.defaultLocale) === locale &&
+          !r.version, // Prefer non-versioned root
+      )
+
+      if (targetRoute) {
+        targetPath = targetRoute.path
+      } else {
+        targetPath = locale === i18n.defaultLocale ? '/' : `/${locale}`
+      }
     }
 
     navigate(targetPath)
   }
 
-  const availableLocales = routeContext.availableLocales.map((l) => ({
-    ...l,
-    label: l.label as string,
-    value: l.key,
-  }))
+  const currentLocaleConfig =
+    config.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,
+        }
+      })
+    : []
 
   return {
     currentLocale,
-    currentLocaleLabel: routeContext.currentLocaleLabel,
+    currentLocaleLabel,
     availableLocales,
     handleLocaleChange,
   }

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

@@ -1,95 +1,73 @@
-import { useLocation } from 'react-router-dom'
 import { useConfig } from '@client/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 within the /docs path preserves the active version and language.
+ * It ensures that navigation preserves the active version and language across the entire site.
  */
 export function useLocalizedTo(to: RouterLinkProps['to']) {
-  const location = useLocation()
   const config = useConfig()
+  const { currentLocale: activeLocale, currentVersion: activeVersion } =
+    useRoutes()
 
   if (!config || typeof to !== 'string') return to
-  if (!config.i18n && !config.versions) return to
-
-  const basePath = '/docs'
-  if (!to.startsWith(basePath)) return to
-
-  // 1. Detect current context from location
-  const curSub = location.pathname.substring(basePath.length)
-  const curParts = curSub.split('/').filter(Boolean)
-
-  let currentVersion = config.versions?.defaultVersion
-  let currentLocale = config.i18n?.defaultLocale
-
-  let cIdx = 0
-  if (
-    config.versions &&
-    curParts.length > cIdx &&
-    config.versions.versions[curParts[cIdx]]
-  ) {
-    currentVersion = curParts[cIdx]
-    cIdx++
-  }
-  if (
-    config.i18n &&
-    curParts.length > cIdx &&
-    config.i18n.locales[curParts[cIdx]]
-  ) {
-    currentLocale = curParts[cIdx]
-  }
 
-  // 2. Parse the target `to` path
-  const toSub = to.substring(basePath.length)
-  const toParts = toSub.split('/').filter(Boolean)
-
-  let tIdx = 0
-  let hasVersion = false
-  let hasLocale = false
-
-  if (
-    config.versions &&
-    toParts.length > tIdx &&
-    config.versions.versions[toParts[tIdx]]
-  ) {
-    hasVersion = true
-    tIdx++
-  }
-  if (
-    config.i18n &&
-    toParts.length > tIdx &&
-    config.i18n.locales[toParts[tIdx]]
-  ) {
-    hasLocale = true
-    tIdx++
+  // External or absolute links don't need localization
+  if (to.startsWith('http') || to.startsWith('//')) return to
+
+  const i18n = config.i18n
+  const versions = config.versions
+
+  if (!i18n && !versions) return to
+
+  // 1. Identify the input intent
+  const isDocLink = to.startsWith('/docs')
+
+  // 3. Clean the 'to' path of ANY existing prefixes to avoid stacking
+  const parts = to.split('/').filter(Boolean)
+  let pIdx = 0
+
+  // Strip '/docs' if present at start
+  if (parts[pIdx] === 'docs') pIdx++
+
+  // Strip versions if present
+  if (versions && parts.length > pIdx) {
+    const vMatch = versions.versions.find((v) => v.path === parts[pIdx])
+    if (vMatch) pIdx++
   }
 
-  // Extract just the actual route parts
-  const routeParts = toParts.slice(tIdx)
+  // Strip locales if present
+  if (i18n && parts.length > pIdx && i18n.locales[parts[pIdx]]) pIdx++
+
+  // The actual relative route remaining
+  const routeContent = parts.slice(pIdx)
+
+  // 4. Reconstruct strictly from base
+  const resultParts: string[] = []
 
-  // Reconstruct path
-  const finalParts = []
-  if (config.versions) {
-    if (hasVersion) {
-      finalParts.push(toParts[0])
-    } else if (currentVersion) {
-      finalParts.push(currentVersion)
+  if (isDocLink) {
+    resultParts.push('docs')
+    if (versions && activeVersion) {
+      resultParts.push(activeVersion)
     }
   }
-  if (config.i18n) {
-    if (hasLocale) {
-      finalParts.push(toParts[hasVersion ? 1 : 0])
-    } else if (currentLocale) {
-      finalParts.push(currentLocale)
+
+  if (i18n && activeLocale) {
+    // Only prefix if it's NOT the default locale (cleaner URLs)
+    if (activeLocale !== i18n.defaultLocale) {
+      resultParts.push(activeLocale)
     }
   }
 
-  finalParts.push(...routeParts)
+  resultParts.push(...routeContent)
+
+  const finalPath = `/${resultParts.join('/')}`
 
-  let finalPath = `${basePath}/${finalParts.join('/')}`
-  if (finalPath.endsWith('/')) {
-    finalPath = finalPath.slice(0, -1)
+  // Cleanup trailing slashes unless it's just root
+  if (finalPath.length > 1 && finalPath.endsWith('/')) {
+    return finalPath.slice(0, -1)
   }
-  return finalPath === basePath ? basePath : finalPath
+
+  return finalPath || '/'
 }

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

@@ -2,14 +2,17 @@ import { useLocation } from 'react-router-dom'
 import { useConfig } from '@client/app/config-context'
 import { useTheme } from '@client/app/theme-context'
 import type { NavbarLink } from '@client/types'
+import { getTranslated } from '@client/utils/i18n'
+import { useRoutes } from './use-routes'
 
 export function useNavbar() {
   const config = useConfig()
   const { theme } = useTheme()
   const location = useLocation()
+  const { currentLocale } = useRoutes()
 
-  const themeConfig = config.theme || config.themeConfig || {}
-  const title = themeConfig.title || 'Boltdocs'
+  const themeConfig = config.theme || {}
+  const title = getTranslated(themeConfig.title, currentLocale) || 'Boltdocs'
   const rawLinks = themeConfig.navbar || []
   const socialLinks = themeConfig.socialLinks || []
   const githubRepo = themeConfig.githubRepo
@@ -18,13 +21,17 @@ export function useNavbar() {
   const links: NavbarLink[] = rawLinks.map((item: any) => {
     const href = item.href || item.to || item.link || ''
     return {
-      label: item.label || item.text || '',
+      label: getTranslated(item.label || item.text, currentLocale),
       href,
       active: location.pathname === href,
       to:
         href.startsWith('http') || href.startsWith('//')
           ? 'external'
           : undefined,
+      items: item.items?.map((sub: any) => ({
+        label: getTranslated(sub.label || sub.text, currentLocale),
+        href: sub.href || sub.link || sub.to || '',
+      })),
     }
   })
 

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

@@ -1,18 +1,39 @@
+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 } = useRoutes()
-  const currentPath = window.location.pathname
+  const { routes, currentRoute } = useRoutes()
+  const location = useLocation()
 
-  const currentIndex = routes.findIndex((r) => r.path === currentPath)
-  const currentRoute = routes[currentIndex]
+  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 ? routes[currentIndex - 1] : null
+  const prevPage = currentIndex > 0 ? contextRoutes[currentIndex - 1] : null
   const nextPage =
-    currentIndex < routes.length - 1 ? routes[currentIndex + 1] : null
+    currentIndex !== -1 && currentIndex < contextRoutes.length - 1
+      ? contextRoutes[currentIndex + 1]
+      : null
 
   return {
     prevPage,

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

@@ -1,6 +1,7 @@
 import { useLocation } from 'react-router-dom'
 import { useConfig } from '@client/app/config-context'
 import { usePreload } from '@client/app/preload'
+import { useBoltdocsStore } from '../store/use-boltdocs-store'
 
 /**
  * Hook to access the framework's routing state.
@@ -12,16 +13,26 @@ export function useRoutes() {
   const config = useConfig()
   const location = useLocation()
 
-  // Find the current route exactly matching the pathname
+  // Use Zustand store for active state
+  const currentLocaleStore = useBoltdocsStore((s) => s.currentLocale)
+  const currentVersionStore = useBoltdocsStore((s) => s.currentVersion)
+  const hasHydrated = useBoltdocsStore((s) => s.hasHydrated)
+
+  // Find the current route matching the pathname
   const currentRoute = allRoutes.find((r) => r.path === location.pathname)
 
-  // Derive current locale and version from the route or defaults
+  // Derive current locale and version
+  // Priority: URL (currentRoute) > Zustand Store (Persistence) > Config Default
   const currentLocale = config.i18n
-    ? currentRoute?.locale || config.i18n.defaultLocale
+    ? currentRoute?.locale ||
+      (hasHydrated ? currentLocaleStore : undefined) ||
+      config.i18n.defaultLocale
     : undefined
 
   const currentVersion = config.versions
-    ? currentRoute?.version || config.versions.defaultVersion
+    ? currentRoute?.version ||
+      (hasHydrated ? currentVersionStore : undefined) ||
+      config.versions.defaultVersion
     : undefined
 
   // Filter routes to those matching the current version and locale
@@ -32,28 +43,62 @@ export function useRoutes() {
     const versionMatch = config.versions
       ? (r.version || config.versions.defaultVersion) === currentVersion
       : true
-    return localeMatch && versionMatch
+
+    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
+      }
+    }
+
+    return true
   })
 
   // Labels and lists for UI convenience
+  const currentLocaleConfig =
+    config.i18n?.localeConfigs?.[currentLocale as string]
   const currentLocaleLabel =
-    config.i18n?.locales[currentLocale as string] || currentLocale
-  const currentVersionLabel =
-    config.versions?.versions[currentVersion as string] || currentVersion
+    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, label]) => ({
-        key,
-        label,
-        isCurrent: key === currentLocale,
-      }))
+    ? Object.entries(config.i18n.locales).map(([key, defaultLabel]) => {
+        const localeConfig = config.i18n?.localeConfigs?.[key]
+        return {
+          key,
+          label: localeConfig?.label || defaultLabel,
+          isCurrent: key === currentLocale,
+        }
+      })
     : []
 
   const availableVersions = config.versions
-    ? Object.entries(config.versions.versions).map(([key, label]) => ({
-        key,
-        label,
-        isCurrent: key === currentVersion,
+    ? config.versions.versions.map((v) => ({
+        key: v.path,
+        label: v.label,
+        isCurrent: v.path === currentVersion,
       }))
     : []