boltdocs 2.6.2 → 2.7.0

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

@@ -1,102 +1,205 @@
+import { useMemo } from 'react'
 import { useLocation } from 'react-router-dom'
 import { useConfig } from '../app/config-context'
 import type { ComponentRoute } from '../types'
+import { normalizePath } from '../utils/path'
 
 export function useSidebar(routes: ComponentRoute[]) {
   const config = useConfig()
   const location = useLocation()
 
-  // Find active route and tab
-  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()
-
-  // Filter routes by active tab if any
-  const filteredRoutes = activeTabId
-    ? routes.filter((r) => !r.tab || r.tab.toLowerCase() === activeTabId)
-    : routes
-
-  const ungrouped: ComponentRoute[] = []
-  const groupsMap = new Map<
-    string,
-    { slug: string; title: string; routes: ComponentRoute[]; icon?: string }
-  >()
-
-  for (const route of filteredRoutes) {
-    // Skip home pages or external pages from the sidebar if they are not explicitly grouped
-    if (!route.filePath && !route.group) continue
-
-    if (!route.group) {
-      ungrouped.push(route)
-    } else {
-      if (!groupsMap.has(route.group)) {
-        groupsMap.set(route.group, {
-          slug: route.group,
-          title: route.groupTitle || route.group,
-          routes: [],
-          icon: route.groupIcon,
-        })
+  const currentPath = normalizePath(location.pathname)
+
+  return useMemo(() => {
+    const activeRoute = routes.find(
+      (r) => normalizePath(r.path) === currentPath,
+    )
+    const activeTabId = activeRoute?.tab?.toLowerCase()
+
+    const filteredRoutes = activeTabId
+      ? routes.filter((r) => !r.tab || r.tab.toLowerCase() === activeTabId)
+      : routes
+
+    const directoryMeta: Record<string, any> = {}
+    if (config.directoryMeta) {
+      for (const [key, value] of Object.entries(config.directoryMeta)) {
+        const cleanKey = key
+          .split('/')
+          .filter((part) => !part.startsWith('(') || !part.endsWith(')'))
+          .map((part) => part.replace(/^\d+-/, ''))
+          .join('/')
+        directoryMeta[cleanKey === '' ? '.' : cleanKey] = value
       }
-      groupsMap.get(route.group)!.routes.push(route)
     }
-  }
-
-  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, [])
+
+    // 1. Helper to format labels
+    const capitalize = (str: string) =>
+      str.charAt(0).toUpperCase() + str.slice(1).replace(/-/g, ' ')
+
+    // 2. Define recursive tree builder
+    const rootNodesMap = new Map<string, ComponentRoute>()
+    const ungrouped: ComponentRoute[] = []
+
+    // Helper to find or create nested folders recursively
+    const getOrCreateNode = (
+      parts: string[],
+      rootStore: Map<string, ComponentRoute>,
+    ) => {
+      let currentMap = rootStore
+      let parentPath = ''
+      let lastNode: ComponentRoute | null = null
+
+      for (let i = 0; i < parts.length; i++) {
+        const segment = parts[i]
+        const currentRelPath = parentPath ? `${parentPath}/${segment}` : segment
+
+        if (!currentMap.has(segment)) {
+          const meta = directoryMeta[currentRelPath] || {}
+          const newNode: ComponentRoute = {
+            path: '#', // Placeholder
+            title: meta.title || capitalize(segment),
+            componentPath: '',
+            filePath: '',
+            icon: meta.icon,
+            groupPosition: typeof meta.order === 'number' ? meta.order : 999,
+            subRoutes: [],
           }
-          subRouteChildren.get(route.subRouteGroup)!.push(route)
+          currentMap.set(segment, newNode)
         }
+
+        lastNode = currentMap.get(segment)!
+
+        // Create inner subRoutes mapping helper
+        if (!(lastNode as any)._subMap) {
+          ;(lastNode as any)._subMap = new Map<string, ComponentRoute>()
+        }
+        currentMap = (lastNode as any)._subMap as Map<string, ComponentRoute>
+        parentPath = currentRelPath
       }
+      return lastNode
     }
 
-    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)
-          }
+    // 3. Sort input routes initially by their internal position/ordering
+    const sortedRoutes = [...filteredRoutes].sort((a, b) => {
+      const posA = a.sidebarPosition ?? a.order ?? 999
+      const posB = b.sidebarPosition ?? b.order ?? 999
+      return posA - posB
+    })
+
+    // 4. Distribute routes into tree
+    for (const route of sortedRoutes) {
+      if (route.sidebarHidden) continue
+
+      const parts = route.slugParts || []
+      const fileName = route.filePath.split('/').pop() || ''
+      const isIndex = /^index\.mdx?$/.test(fileName)
+
+      if (parts.length === 0) {
+        // Top level route (not in subfolder)
+        if (route.filePath) ungrouped.push(route)
+        continue
+      }
+
+      if (isIndex) {
+        // Index files populate the CONTAINER object itself
+        const containerNode = getOrCreateNode(parts, rootNodesMap)
+        if (containerNode) {
+          // Merge properties onto the container so it becomes clickable
+          containerNode.path = route.path
+          containerNode.title = route.title || containerNode.title
+          containerNode.icon = route.icon || containerNode.icon
+          containerNode.badge = route.badge
+          containerNode.sidebarPosition = route.sidebarPosition
+          containerNode.frontmatter = route.frontmatter
         }
       } else {
-        finalRoutes.push(route)
+        // Normal leaf file nested under path
+        const parentNode = getOrCreateNode(parts, rootNodesMap)
+        if (parentNode) {
+          parentNode.subRoutes!.push(route)
+        }
       }
     }
 
-    return { ...group, routes: finalRoutes }
-  })
+    // 5. Recursive sorting and cleanup helper
+    const finalizeTree = (
+      nodes: ComponentRoute[],
+      currentPathPrefix: string = '',
+    ): ComponentRoute[] => {
+      nodes.forEach((node) => {
+        // 1. Pull child nodes from internal Map store into subRoutes
+        if ((node as any)._subMap) {
+          const childDirs = Array.from(
+            ((node as any)._subMap as Map<string, ComponentRoute>).values(),
+          )
+          node.subRoutes = [...(node.subRoutes || []), ...childDirs]
+          delete (node as any)._subMap
+        }
+
+        // 2. Recursively process grandchildren
+        if (node.subRoutes && node.subRoutes.length > 0) {
+          node.subRoutes = finalizeTree(node.subRoutes)
+        }
+      })
+
+      // 3. Sort this specific depth layer
+      return nodes.sort((a, b) => {
+        // Position ordering
+        const posA = a.sidebarPosition ?? a.groupPosition ?? 999
+        const posB = b.sidebarPosition ?? b.groupPosition ?? 999
+
+        if (posA !== posB) return posA - posB
+
+        // Fallback alphabetical
+        return a.title.localeCompare(b.title)
+      })
+    }
+
+    // Finalize top-level groups
+    const rawGroups = Array.from(rootNodesMap.values())
+    const finalizedTopNodes = finalizeTree(rawGroups)
+
+    // Map finalized top nodes to expected format [{ title, routes }]
+    const groups = finalizedTopNodes.map((node) => {
+      // To match current primitives expectations, a 'group' is the top-level container.
+      // If the top node is already structured as a ComponentRoute, we wrap it.
+      return {
+        slug: node.title.toLowerCase().replace(/\s+/g, '-'),
+        title: node.title,
+        icon: node.icon,
+        routes: [node], // The primitives sidebar renderer iterates topGroup.routes and recurses inside.
+      }
+    })
+
+    // Wait, actually the legacy Sidebar.tsx treats "groups" as visual wrappers with headers,
+    // and "routes" inside as the start of items. If we want top-level direct items, they map to 'ungrouped'.
+    // Let's return grouped items natively.
 
-  return {
-    groups,
-    ungrouped,
-    activeRoute,
-    activePath: currentPath,
-    config,
-  }
+    // RE-DESIGN LEGACY COMPATIBILITY:
+    // If user wants strict backwards layout, we unwrap the very top layer!
+    const legacyCompatibleGroups = finalizedTopNodes
+      .map((node) => {
+        // Check if it's a container with subitems. If it is, make IT the group header!
+        if (node.subRoutes && node.subRoutes.length > 0) {
+          return {
+            slug: node.title.toLowerCase().replace(/\s+/g, '-'),
+            title: node.title,
+            icon: node.icon,
+            routes: node.subRoutes, // Unwrap children as top-level list underneath the visual group title!
+          }
+        }
+        // If it's standalone, send it to ungrouped
+        ungrouped.push(node)
+        return null
+      })
+      .filter(Boolean) as any[]
+
+    return {
+      groups: legacyCompatibleGroups,
+      ungrouped: finalizeTree(ungrouped),
+      activeRoute,
+      activePath: currentPath,
+      config,
+    }
+  }, [routes, config, currentPath])
 }

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

@@ -1,6 +1,7 @@
 import { useLocation } from 'react-router-dom'
 import { useEffect, useState, useRef } from 'react'
 import type { ComponentRoute, BoltdocsTab } from '../types'
+import { normalizePath } from '../utils/path'
 
 export function useTabs(
   tabs: BoltdocsTab[] = [],
@@ -14,11 +15,9 @@ export function useTabs(
     width: 0,
   })
 
-  const normalize = (p: string) =>
-    p.endsWith('/') && p.length > 1 ? p.slice(0, -1) : p
-  const currentPath = normalize(location.pathname)
+  const currentPath = normalizePath(location.pathname)
 
-  const activeRoute = routes.find((r) => normalize(r.path) === currentPath)
+  const activeRoute = routes.find((r) => normalizePath(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,6 +1,8 @@
+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 { BoltdocsVersion } from '../../shared/types'
 
@@ -23,9 +25,8 @@ export interface UseVersionReturn {
  */
 export function useVersion(): UseVersionReturn {
   const navigate = useNavigate()
-  const routeContext = useRoutes()
-  const { allRoutes, currentRoute, currentVersion, currentLocale, config } =
-    routeContext
+  const config = useConfig()
+  const { allRoutes, currentRoute, currentVersion, currentLocale } = useRoutes()
   const versions = config.versions
   const { setVersion } = useBoltdocsContext()
 
@@ -35,21 +36,12 @@ export function useVersion(): UseVersionReturn {
     // Update store
     setVersion(version)
 
-    // If we are on the home page or a path that doesn't belong to the documentation,
-    // we stay on the current page.
-    const localePaths = config.i18n ? Object.keys(config.i18n.locales).map(l => `/${l}`) : []
-    const isHome = !currentRoute || 
-                   currentRoute.path === '/' || 
-                   currentRoute.path === config.base || 
-                   currentRoute.path === '' ||
-                   localePaths.includes(currentRoute.path)
-    
-    if (isHome) {
-      return
-    }
+    // 3. Attempt derivation or deployment of navigation target
+    const base = config.base || '/docs'
+    const safeBase = base.replace(/\/$/, '')
+    let targetPath = `${safeBase}/${version}${currentLocale ? `/${currentLocale}` : ''}`
 
     if (currentRoute) {
-      let targetPath = `/docs/${version}`
       const baseFile = getBaseFilePath(
         currentRoute.filePath,
         currentRoute.version,
@@ -60,7 +52,8 @@ export function useVersion(): UseVersionReturn {
         (r) =>
           getBaseFilePath(r.filePath, r.version, r.locale) === baseFile &&
           (r.version || versions.defaultVersion) === version &&
-          (currentLocale ? r.locale === currentLocale : !r.locale),
+          (!config.i18n ||
+            (r.locale || config.i18n.defaultLocale) === currentLocale),
       )
 
       if (targetRoute) {
@@ -70,26 +63,48 @@ export function useVersion(): UseVersionReturn {
           (r) =>
             getBaseFilePath(r.filePath, r.version, r.locale) === 'index.md' &&
             (r.version || versions.defaultVersion) === version &&
-            (currentLocale ? r.locale === currentLocale : !r.locale),
+            (!config.i18n ||
+              (r.locale || config.i18n.defaultLocale) === currentLocale),
         )
-        targetPath = versionIndexRoute
-          ? versionIndexRoute.path
-          : `/docs/${version}${currentLocale ? `/${currentLocale}` : ''}`
+        if (versionIndexRoute) {
+          targetPath = versionIndexRoute.path
+        }
+      }
+    } else {
+      // Recovery mode: if currently on a 404, attempt to find ANY document in the target version
+      const fallbackRoute = allRoutes.find(
+        (r) =>
+          (r.version || versions.defaultVersion) === version &&
+          (!config.i18n ||
+            (r.locale || config.i18n.defaultLocale) === currentLocale),
+      )
+      if (fallbackRoute) {
+        targetPath = fallbackRoute.path
       }
-      
-      navigate(targetPath)
     }
+
+    navigate(targetPath)
   }
 
-  const availableVersions = routeContext.availableVersions.map((v) => ({
-    ...v,
-    label: v.label as string,
-    value: v.key,
-  }))
+  const currentVersionConfig = versions?.versions?.find?.(
+    (v) => v.path === currentVersion,
+  )
+  const currentVersionLabel = currentVersionConfig?.label || currentVersion
+
+  const availableVersions = useMemo(() => {
+    return versions
+      ? versions.versions.map((v) => ({
+          key: v.path as BoltdocsVersion,
+          label: v.label,
+          value: v.path,
+          isCurrent: v.path === currentVersion,
+        }))
+      : []
+  }, [versions, currentVersion])
 
   return {
     currentVersion,
-    currentVersionLabel: routeContext.currentVersionLabel,
+    currentVersionLabel,
     availableVersions,
     handleVersionChange,
   }

package/src/client/index.ts

@@ -1,105 +1,31 @@
+export type * from './types'
 export type {
-  ComponentRoute,
-  LayoutProps,
-} from './types'
-export type { BoltdocsLocale, BoltdocsVersion, BoltdocsTypes } from '../shared/types'
+  BoltdocsLocale,
+  BoltdocsVersion,
+  BoltdocsTypes,
+} from '../shared/types'
 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 { useUI } from './app/ui-context'
 export * from './hooks/index'
-// Composable layout building blocks
-export { DocsLayout } from './components/docs-layout'
-
-// Default UI components (for use in custom layout.tsx)
+export { DocsLayout } from './components/docs-layout-default'
 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 { SearchDialog } from './components/ui-base/search-dialog'
 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 {
-  Button,
-  Badge,
-  Card,
-  Cards,
-  Tabs,
-  Tab,
-  Admonition,
-  Note,
-  Tip,
-  Warning,
-  Danger,
-  InfoBox,
-  ComponentProps,
-  ComponentPreview,
-  Important,
-  Caution,
-  List,
-  FileTree,
-  Table,
-  Field,
-  Link,
-  Image,
-} from './components/mdx'
-
-export type {
-  ButtonProps,
-  BadgeProps,
-  CardProps,
-  CardsProps,
-  TabsProps,
-  TabProps,
-  AdmonitionProps,
-  ComponentPropsProps,
-  ComponentPreviewProps,
-  ListProps,
-  FileTreeProps,
-  TableProps,
-  FieldProps,
-  LinkProps,
-  ImageProps,
-} from './components/mdx'
-
-// Primitives
-export { Navbar as PrimitiveNavbar } from './components/primitives/navbar'
-export { NavigationMenu as PrimitiveNavigationMenu } from './components/primitives/navigation-menu'
-export { SearchDialog as SearchDialogPrimitive } from './components/primitives/search-dialog'
-export {
-  OnThisPage as PrimitiveOnThisPage,
-  AnchorProvider,
-  ScrollProvider,
-  useActiveAnchor,
-  useActiveAnchors,
-  useItems,
-} from './components/primitives/on-this-page'
-export { PageNav as PrimitivePageNav } from './components/primitives/page-nav'
-export { Tabs as PrimitiveTabs } from './components/primitives/tabs'
-export { Sidebar as PrimitiveSidebar } from './components/primitives/sidebar'
-export { Breadcrumbs as PrimitiveBreadcrumbs } from './components/primitives/breadcrumbs'
-export { Button as PrimitiveButton } from './components/primitives/button'
-export { ButtonGroup } from './components/primitives/button-group'
-export { Menu as PrimitiveMenu } from './components/primitives/menu'
-export { Popover as PrimitivePopover } from './components/primitives/popover'
-export { Tooltip as PrimitiveTooltip } from './components/primitives/tooltip'
-export {
-  Link as PrimitiveLink,
-  NavLink as PrimitiveNavLink,
-} from './components/primitives/link'
-export { Skeleton as PrimitiveSkeleton } from './components/primitives/skeleton'
+export { Card } from './components/mdx/card'
+export { Cards } from './components/mdx/cards'
 
 // Utilities
 export { cn } from './utils/cn'
 export { getTranslated } from './utils/i18n'
+export { reactToText } from './utils/react-to-text'
+export { copyToClipboard } from './utils/copy-clipboard'
+export { getStarsRepo } from './utils/github'

package/src/client/mdx.ts

@@ -0,0 +1,2 @@
+import { mdx_components_default as Mdx } from './components/mdx'
+export default Mdx

package/src/client/primitives.ts

@@ -0,0 +1,19 @@
+export * from './components/primitives/docs-layout'
+export * from './components/primitives/button-group'
+export * from './components/primitives/tabs'
+export * from './components/primitives/sidebar'
+export * from './components/primitives/on-this-page'
+export * from './components/primitives/code-block'
+export * from './components/primitives/button'
+export * from './components/primitives/popover'
+export * from './components/primitives/tooltip'
+export * from './components/primitives/link'
+export * from './components/primitives/error-boundary'
+export * from './components/primitives/heading'
+export * from './components/primitives/image'
+export * from './components/primitives/menu'
+export * from './components/primitives/page-nav'
+export * from './components/primitives/search-dialog'
+export * from './components/primitives/skeleton'
+export * from './components/primitives/breadcrumbs'
+export * from './components/primitives/navbar'