boltdocs 2.5.6 → 2.6.1

package/src/client/components/ui-base/on-this-page.tsx

@@ -3,10 +3,10 @@ import {
   AnchorProvider,
   ScrollProvider,
   useActiveAnchor,
-} from '@components/primitives/on-this-page'
-import React, { useRef, useEffect, useState, useCallback } from 'react'
-import { useOnThisPage } from '@hooks/use-onthispage'
-import type { OnThisPageProps } from '@client/types'
+} from '../primitives/on-this-page'
+import { useRef, useEffect, useState, useCallback, useMemo } from 'react'
+import { useOnThisPage } from '../../hooks/use-onthispage'
+import type { OnThisPageProps } from '../../types'
 import { Pencil, CircleHelp, TextAlignStart } from 'lucide-react'
 
 export function OnThisPage({
@@ -17,7 +17,7 @@ export function OnThisPage({
 }: OnThisPageProps) {
   const { headings } = useOnThisPage(rawHeadings)
 
-  const toc = React.useMemo(
+  const toc = useMemo(
     () =>
       headings.map((h) => ({ title: h.text, url: `#${h.id}`, depth: h.level })),
     [headings],
@@ -115,7 +115,7 @@ function OnThisPageInner({
 
       {(editLink || communityHelp) && (
         <div className="mt-8 pt-8 border-t border-border-subtle space-y-4">
-          <p className="text-xs font-bold uppercase tracking-wider text-text-main">
+          <p className="text-xs font-bold uppercase text-text-main">
             Need help?
           </p>
           <ul className="space-y-3">

package/src/client/components/ui-base/page-nav.tsx

@@ -1,5 +1,5 @@
-import { usePageNav } from '@hooks/use-page-nav'
-import { PageNav as PageNavPrimitive } from '@components/primitives/page-nav'
+import { usePageNav } from '../../hooks/use-page-nav'
+import { PageNav as PageNavPrimitive } from '../primitives/page-nav'
 
 /**
  * Component to display the previous and next page navigation buttons.
@@ -14,9 +14,7 @@ export function PageNav() {
     <PageNavPrimitive.Root className="animate-in fade-in slide-in-from-bottom-4 duration-700">
       {prevPage ? (
         <PageNavPrimitive.Link to={prevPage.path} direction="prev">
-          <PageNavPrimitive.Title>
-            Previous
-          </PageNavPrimitive.Title>
+          <PageNavPrimitive.Title>Previous</PageNavPrimitive.Title>
           <PageNavPrimitive.Description>
             {prevPage.title}
           </PageNavPrimitive.Description>
@@ -27,9 +25,7 @@ export function PageNav() {
 
       {nextPage && (
         <PageNavPrimitive.Link to={nextPage.path} direction="next">
-          <PageNavPrimitive.Title>
-            Next
-          </PageNavPrimitive.Title>
+          <PageNavPrimitive.Title>Next</PageNavPrimitive.Title>
           <PageNavPrimitive.Description>
             {nextPage.title}
           </PageNavPrimitive.Description>

package/src/client/components/ui-base/search-dialog.tsx

@@ -1,11 +1,9 @@
 import { useEffect, useCallback } from 'react'
-import { useSearch } from '@hooks/use-search'
-import {
-  SearchDialog as SearchDialogPrimitive,
-} from '@components/primitives/search-dialog'
-import Navbar from '@components/primitives/navbar'
+import { useSearch } from '../../hooks/use-search'
+import { SearchDialog as SearchDialogPrimitive } from '../primitives/search-dialog'
+import Navbar from '../primitives/navbar'
 import { useNavigate } from 'react-router-dom'
-import type { ComponentRoute } from '@client/types'
+import type { ComponentRoute } from '../../types'
 interface SearchResult {
   id: string
   title: string
@@ -73,8 +71,12 @@ export function SearchDialog({ routes }: { routes: ComponentRoute[] }) {
               >
                 <SearchDialogPrimitive.Item.Icon isHeading={item.isHeading} />
                 <div className="flex flex-col justify-center gap-0.5">
-                  <SearchDialogPrimitive.Item.Title>{item.title}</SearchDialogPrimitive.Item.Title>
-                  <SearchDialogPrimitive.Item.Bio>{item.bio}</SearchDialogPrimitive.Item.Bio>
+                  <SearchDialogPrimitive.Item.Title>
+                    {item.title}
+                  </SearchDialogPrimitive.Item.Title>
+                  <SearchDialogPrimitive.Item.Bio>
+                    {item.bio}
+                  </SearchDialogPrimitive.Item.Bio>
                 </div>
               </SearchDialogPrimitive.Item>
             )}

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

@@ -1,52 +1,105 @@
 import { useState, useEffect, useMemo } from 'react'
-import { useSidebar } from '@hooks/use-sidebar'
-import { Sidebar as SidebarPrimitive } from '@components/primitives/sidebar'
+import { useSidebar } from '../../hooks/use-sidebar'
+import { Sidebar as SidebarPrimitive } from '../primitives/sidebar'
 import { PoweredBy } from './powered-by'
 import * as LucideIcons from 'lucide-react'
-import type { ComponentRoute } from '@client/types'
-import type { BoltdocsConfig } from '@node/config'
+import virtualIcons from 'virtual:boltdocs-icons'
+import type { ComponentRoute } from '../../types'
+import type { BoltdocsConfig } from '../../../shared/types'
 
 function getIcon(iconName?: string): React.ElementType | undefined {
   if (!iconName) return undefined
-  const icons = LucideIcons as unknown as Record<string, React.ElementType>
-  const IconComponent = icons[iconName]
+  const icons = { ...LucideIcons, ...virtualIcons } as unknown as Record<
+    string,
+    React.ElementType
+  >
+  const IconComponent = icons[iconName] || icons[iconName + 'Icon']
   return IconComponent || undefined
 }
 
-function CollapsibleSidebarGroup({
-  group,
+function SidebarSubRouteGroup({
+  route,
   activePath,
   getIcon,
 }: {
-  group: {
-    slug: string
-    title: string
-    routes: ComponentRoute[]
-    icon?: string
-  }
+  route: ComponentRoute
   activePath: string
   getIcon: (iconName?: string) => React.ElementType | undefined
 }) {
-  const hasActiveRoute = useMemo(
-    () => group.routes.some((r) => r.path === activePath),
-    [group.routes, activePath],
+  const isCurrent =
+    activePath ===
+    (route.path.endsWith('/') ? route.path.slice(0, -1) : route.path)
+
+  const hasActiveSubRoute = useMemo(
+    () => route.subRoutes?.some((r) => r.path === activePath),
+    [route.subRoutes, activePath],
   )
 
-  const [isOpen, setIsOpen] = useState(true)
+  const [isOpen, setIsOpen] = useState(hasActiveSubRoute || isCurrent)
 
   useEffect(() => {
-    if (hasActiveRoute) {
+    if (hasActiveSubRoute || isCurrent) {
       setIsOpen(true)
     }
-  }, [hasActiveRoute])
+  }, [hasActiveSubRoute, isCurrent])
 
   return (
-    <SidebarPrimitive.Group
-      title={group.title}
+    <SidebarPrimitive.SubGroup
+      label={route.title}
+      href={route.path}
+      active={isCurrent}
+      icon={getIcon(route.icon)}
+      badge={route.badge}
       isOpen={isOpen}
       onToggle={() => setIsOpen(!isOpen)}
     >
+      {route.subRoutes?.map((subRoute: ComponentRoute) => {
+        const isSubCurrent =
+          activePath ===
+          (subRoute.path.endsWith('/') ? subRoute.path.slice(0, -1) : subRoute.path)
+        return (
+          <SidebarPrimitive.Link
+            key={subRoute.path}
+            label={subRoute.title}
+            href={subRoute.path}
+            active={isSubCurrent}
+            icon={getIcon(subRoute.icon)}
+            badge={subRoute.badge}
+          />
+        )
+      })}
+    </SidebarPrimitive.SubGroup>
+  )
+}
+
+function SidebarGroupSection({
+  group,
+  activePath,
+  getIcon,
+}: {
+  group: {
+    slug: string
+    title: string
+    routes: ComponentRoute[]
+    icon?: string
+  }
+  activePath: string
+  getIcon: (iconName?: string) => React.ElementType | undefined
+}) {
+  return (
+    <SidebarPrimitive.Group title={group.title} icon={getIcon(group.icon)}>
       {group.routes.map((route: ComponentRoute) => {
+        if (route.subRoutes && route.subRoutes.length > 0) {
+          return (
+            <SidebarSubRouteGroup
+              key={route.path}
+              route={route}
+              activePath={activePath}
+              getIcon={getIcon}
+            />
+          )
+        }
+
         const isCurrent =
           activePath ===
           (route.path.endsWith('/') ? route.path.slice(0, -1) : route.path)
@@ -98,7 +151,7 @@ export function Sidebar({
       )}
 
       {groups.map((group) => (
-        <CollapsibleSidebarGroup
+        <SidebarGroupSection
           key={group.slug}
           group={group}
           activePath={activePath}

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

@@ -1,10 +1,10 @@
-import { useTabs as useTabsHook } from '@hooks/use-tabs'
-import { Tabs as T } from '@components/primitives/tabs'
-import { Link } from '@components/primitives/link'
-import type { BoltdocsTab, ComponentRoute } from '@client/types'
+import { useTabs as useTabsHook } from '../../hooks/use-tabs'
+import { Tabs as T } from '../primitives/tabs'
+import { Link } from '../primitives/link'
+import type { BoltdocsTab, ComponentRoute } from '../../types'
 import * as Icons from 'lucide-react'
-import { getTranslated } from '@client/utils/i18n'
-import { useRoutes } from '@hooks/use-routes'
+import { getTranslated } from '../../utils/i18n'
+import { useRoutes } from '../../hooks/use-routes'
 
 export function Tabs({
   tabs,
@@ -50,10 +50,11 @@ export function Tabs({
               ref={(el: HTMLAnchorElement | null) => {
                 tabRefs.current[index] = el
               }}
-              className={`relative flex items-center gap-2 px-4 py-3 text-sm font-medium transition-colors outline-none ${isActive
+              className={`relative flex items-center gap-2 px-4 py-3 text-sm font-medium transition-colors outline-none ${
+                isActive
                   ? 'text-primary-500'
                   : 'text-text-muted hover:text-text-main'
-                }`}
+              }`}
             >
               {renderTabIcon(tab.icon)}
               <span>{getTranslated(tab.text, currentLocale)}</span>

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

@@ -1,8 +1,8 @@
 import { useEffect, useState } from 'react'
 import { Sun, Moon, Monitor } from 'lucide-react'
-import { useTheme } from '@client/app/theme-context'
+import { useTheme } from '../../app/theme-context'
 import { Button } from 'react-aria-components'
-import { Menu } from '@components/primitives/menu'
+import { Menu } from '../primitives/menu'
 
 export function ThemeToggle() {
   const { theme, setTheme } = useTheme()

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

@@ -1,7 +1,7 @@
 import { useNavigate } from 'react-router-dom'
-import { getBaseFilePath } from '@client/utils/get-base-file-path'
+import { getBaseFilePath } from '../utils/get-base-file-path'
 import { useRoutes } from './use-routes'
-import { useBoltdocsStore } from '../store/boltdocs-context'
+import { useBoltdocsContext } from '../store/boltdocs-context'
 
 export interface LocaleOption {
   key: string
@@ -25,7 +25,7 @@ export function useI18n(): UseI18nReturn {
   const routeContext = useRoutes()
   const { allRoutes, currentRoute, currentLocale, config } = routeContext
   const i18n = config.i18n
-  const setLocale = useBoltdocsStore((s) => s.setLocale)
+  const { setLocale } = useBoltdocsContext()
 
   const handleLocaleChange = (locale: string) => {
     if (!i18n || locale === currentLocale) return

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

@@ -1,4 +1,4 @@
-import { useConfig } from '@client/app/config-context'
+import { useConfig } from '../app/config-context'
 import type { LinkProps as RouterLinkProps } from 'react-router-dom'
 import { useRoutes } from './use-routes'
 

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

@@ -1,13 +1,13 @@
 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 { 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 } = useTheme()
+  const { theme, resolvedTheme } = useTheme()
   const location = useLocation()
   const { currentLocale } = useRoutes()
 
@@ -67,11 +67,13 @@ export function useNavbar() {
   })
 
   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
-      : theme === 'dark'
+      : resolvedTheme === 'dark'
         ? (logo as any).dark
         : (logo as any).light
 

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

@@ -1,7 +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/boltdocs-context'
+import { useConfig } from '../app/config-context'
+import { useRoutesContext } from '../app/routes-context'
+import { useBoltdocsContext } from '../store/boltdocs-context'
 
 /**
  * Hook to access the framework's routing state.
@@ -9,17 +9,25 @@ import { useBoltdocsStore } from '../store/boltdocs-context'
  * version and locale.
  */
 export function useRoutes() {
-  const { routes: allRoutes } = usePreload()
+  const { routes: allRoutes } = useRoutesContext()
   const config = useConfig()
   const location = useLocation()
 
   // Use Zustand store for active state
-  const currentLocaleStore = useBoltdocsStore((s) => s.currentLocale)
-  const currentVersionStore = useBoltdocsStore((s) => s.currentVersion)
-  const hasHydrated = useBoltdocsStore((s) => s.hasHydrated)
+  const {
+    hasHydrated,
+    currentLocale: currentLocaleStore,
+    currentVersion: currentVersionStore,
+  } = useBoltdocsContext()
+
+  const normalize = (p: string) =>
+    p.endsWith('/') && p.length > 1 ? p.slice(0, -1) : p
+  const currentPath = normalize(location.pathname)
 
   // Find the current route matching the pathname
-  const currentRoute = allRoutes.find((r) => r.path === location.pathname)
+  const currentRoute = allRoutes?.find?.(
+    (r) => normalize(r.path) === currentPath,
+  )
 
   // Derive current locale and version
   // Priority: URL (currentRoute) > Zustand Store (Persistence) > Config Default
@@ -36,7 +44,7 @@ export function useRoutes() {
     : undefined
 
   // Filter routes to those matching the current version and locale
-  const routes = allRoutes.filter((r) => {
+  const routes = allRoutes?.filter?.((r) => {
     const localeMatch = config.i18n
       ? (r.locale || config.i18n.defaultLocale) === currentLocale
       : true
@@ -53,7 +61,7 @@ export function useRoutes() {
       const isCurrentRoutePrefixed = !!currentRoute?.locale
       const isRoutePrefixed = !!r.locale
 
-      const hasAlternate = allRoutes.some(
+      const hasAlternate = allRoutes?.some?.(
         (alt) =>
           alt !== r &&
           alt.filePath === r.filePath &&
@@ -78,7 +86,7 @@ export function useRoutes() {
     config.i18n?.locales[currentLocale as string] ||
     currentLocale
 
-  const currentVersionConfig = config.versions?.versions.find(
+  const currentVersionConfig = config.versions?.versions?.find?.(
     (v) => v.path === currentVersion,
   )
   const currentVersionLabel = currentVersionConfig?.label || currentVersion

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

@@ -1,7 +1,7 @@
 import { useState, useMemo, useEffect } from 'react'
 import { Index } from 'flexsearch'
 import { useRoutes } from './use-routes'
-import type { ComponentRoute } from '@client/types'
+import type { ComponentRoute } from '../types'
 // @ts-ignore
 import searchData from 'virtual:boltdocs-search'
 

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

@@ -1,5 +1,5 @@
 import { useLocation } from 'react-router-dom'
-import { useConfig } from '@client/app/config-context'
+import { useConfig } from '../app/config-context'
 import type { ComponentRoute } from '../types'
 
 export function useSidebar(routes: ComponentRoute[]) {
@@ -41,7 +41,53 @@ export function useSidebar(routes: ComponentRoute[]) {
     }
   }
 
-  const groups = Array.from(groupsMap.values())
+  const groups = Array.from(groupsMap.values()).map((group) => {
+    const subRouteParents = new Map<string, ComponentRoute>()
+    const subRouteChildren = new Map<string, ComponentRoute[]>()
+
+    // First pass: Categorize as parent or child
+    for (const route of group.routes) {
+      if (route.subRouteGroup) {
+        const isParent =
+          route.path.endsWith(`/${route.subRouteGroup}`) ||
+          route.path.endsWith(`/${route.subRouteGroup}/`)
+
+        if (isParent && !subRouteParents.has(route.subRouteGroup)) {
+          subRouteParents.set(route.subRouteGroup, route)
+        } else {
+          if (!subRouteChildren.has(route.subRouteGroup)) {
+            subRouteChildren.set(route.subRouteGroup, [])
+          }
+          subRouteChildren.get(route.subRouteGroup)!.push(route)
+        }
+      }
+    }
+
+    const finalRoutes: ComponentRoute[] = []
+    const seenSubGroups = new Set<string>()
+
+    // Second pass: Assemble maintaining mostly original order
+    for (const route of group.routes) {
+      if (route.subRouteGroup) {
+        if (!seenSubGroups.has(route.subRouteGroup)) {
+          seenSubGroups.add(route.subRouteGroup)
+          const parent = subRouteParents.get(route.subRouteGroup)
+          const children = subRouteChildren.get(route.subRouteGroup) || []
+
+          if (parent) {
+            finalRoutes.push({ ...parent, subRoutes: children })
+          } else {
+            // Fallback
+            finalRoutes.push(...children)
+          }
+        }
+      } else {
+        finalRoutes.push(route)
+      }
+    }
+
+    return { ...group, routes: finalRoutes }
+  })
 
   return {
     groups,

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

@@ -1,6 +1,6 @@
 import { useLocation } from 'react-router-dom'
 import { useEffect, useState, useRef } from 'react'
-import type { ComponentRoute, BoltdocsTab } from '@client/types'
+import type { ComponentRoute, BoltdocsTab } from '../types'
 
 export function useTabs(
   tabs: BoltdocsTab[] = [],
@@ -14,7 +14,11 @@ export function useTabs(
     width: 0,
   })
 
-  const activeRoute = routes.find((r) => r.path === location.pathname)
+  const normalize = (p: string) =>
+    p.endsWith('/') && p.length > 1 ? p.slice(0, -1) : p
+  const currentPath = normalize(location.pathname)
+
+  const activeRoute = routes.find((r) => normalize(r.path) === currentPath)
   const activeTabId = activeRoute?.tab?.toLowerCase()
   const activeIndex = tabs.findIndex(
     (tab) => tab.id.toLowerCase() === activeTabId,

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

@@ -1,7 +1,7 @@
 import { useNavigate } from 'react-router-dom'
-import { getBaseFilePath } from '@client/utils/get-base-file-path'
+import { getBaseFilePath } from '../utils/get-base-file-path'
 import { useRoutes } from './use-routes'
-import { useBoltdocsStore } from '../store/boltdocs-context'
+import { useBoltdocsContext } from '../store/boltdocs-context'
 
 export interface VersionOption {
   key: string
@@ -26,7 +26,7 @@ export function useVersion(): UseVersionReturn {
   const { allRoutes, currentRoute, currentVersion, currentLocale, config } =
     routeContext
   const versions = config.versions
-  const setVersion = useBoltdocsStore((s) => s.setVersion)
+  const { setVersion } = useBoltdocsContext()
 
   const handleVersionChange = (version: string) => {
     if (!versions || version === currentVersion) return

package/src/client/index.ts

@@ -1,35 +1,32 @@
-export type { BoltdocsConfig, BoltdocsThemeConfig } from '../node/config'
 export type {
   ComponentRoute,
-  CreateBoltdocsAppOptions,
   LayoutProps,
 } from './types'
-export { createBoltdocsApp } from './app'
-export { useConfig } from '@client/app/config-context'
-export { useTheme } from '@client/app/theme-context'
-export { useRoutes } from '@client/hooks/use-routes'
-export { useMdxComponents } from '@client/app/mdx-components-context'
+export * from './ssg'
+export { useConfig } from './app/config-context'
+export { useTheme } from './app/theme-context'
+export { useRoutes } from './hooks/use-routes'
+export { useMdxComponents } from './app/mdx-components-context'
 
 // Hooks
-export * from '@hooks/index'
+export * from './hooks/index'
 // Composable layout building blocks
-export { DocsLayout } from '@components/docs-layout'
-export { DefaultLayout } from '@components/default-layout'
+export { DocsLayout } from './components/docs-layout'
 
 // Default UI components (for use in custom layout.tsx)
-export { Navbar } from '@components/ui-base/navbar'
-export { Sidebar } from '@components/ui-base/sidebar'
-export { OnThisPage } from '@components/ui-base/on-this-page'
-export { Head } from '@components/ui-base/head'
-export { Breadcrumbs } from '@components/ui-base/breadcrumbs'
-export { PageNav } from '@components/ui-base/page-nav'
-export { ErrorBoundary } from '@components/ui-base/error-boundary'
-export { CopyMarkdown } from '@components/ui-base/copy-markdown'
+export { Navbar } from './components/ui-base/navbar'
+export { Sidebar } from './components/ui-base/sidebar'
+export { OnThisPage } from './components/ui-base/on-this-page'
+export { Head } from './components/ui-base/head'
+export { Breadcrumbs } from './components/ui-base/breadcrumbs'
+export { PageNav } from './components/ui-base/page-nav'
+export { ErrorBoundary } from './components/ui-base/error-boundary'
+export { CopyMarkdown } from './components/ui-base/copy-markdown'
 
-export { NotFound } from '@components/ui-base/not-found'
-export { Loading } from '@components/ui-base/loading'
-export { CodeBlock } from '@components/mdx/code-block'
-export { Video } from '@components/mdx/video'
+export { NotFound } from './components/ui-base/not-found'
+export { Loading } from './components/ui-base/loading'
+export { CodeBlock } from './components/mdx/code-block'
+export { Video } from './components/mdx/video'
 
 // MDX Components
 export {
@@ -104,3 +101,4 @@ export { Skeleton as PrimitiveSkeleton } from './components/primitives/skeleton'
 
 // Utilities
 export { cn } from './utils/cn'
+export { getTranslated } from './utils/i18n'