boltdocs 1.10.2 → 1.11.0

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

@@ -0,0 +1,82 @@
+import { useEffect, useCallback } from 'react'
+import { useSearch } from '@hooks/use-search'
+import {
+  SearchDialogAutocomplete,
+  SearchDialogInput,
+  SearchDialogItemBio,
+  SearchDialogItemIcon,
+  SearchDialogItemRoot,
+  SearchDialogItemTitle,
+  SearchDialogList,
+  SearchDialogRoot,
+} from '@components/primitives/search-dialog'
+import Navbar from '@components/primitives/navbar'
+import { useNavigate } from 'react-router-dom'
+
+export function SearchDialog({ routes }: { routes: any[] }) {
+  const { isOpen, setIsOpen, query, setQuery, list } = useSearch(routes)
+  const navigate = useNavigate()
+
+  useEffect(() => {
+    const handleKeyDown = (e: KeyboardEvent) => {
+      const isMac = /Mac/.test(navigator.userAgent)
+      const isMeta = isMac ? e.metaKey : e.ctrlKey
+
+      if (isMeta && (e.key === 'k' || e.key === 'j')) {
+        e.preventDefault()
+        setIsOpen((prev) => !prev)
+      }
+    }
+    window.addEventListener('keydown', handleKeyDown)
+    return () => window.removeEventListener('keydown', handleKeyDown)
+  }, [setIsOpen])
+
+  const handleSelect = useCallback(
+    (key: React.Key) => {
+      const path = String(key)
+      setIsOpen(false)
+
+      if (path.includes('#')) {
+        const [p, id] = path.split('#')
+        navigate(p)
+        setTimeout(() => {
+          const el = document.getElementById(id)
+          if (el) el.scrollIntoView({ behavior: 'smooth' })
+        }, 100)
+      } else {
+        navigate(path)
+      }
+    },
+    [navigate, setIsOpen],
+  )
+
+  return (
+    <>
+      <Navbar.SearchTrigger onPress={() => setIsOpen(true)} />
+
+      <SearchDialogRoot isOpen={isOpen} onOpenChange={setIsOpen}>
+        <SearchDialogAutocomplete onSelectionChange={handleSelect}>
+          <SearchDialogInput
+            value={query}
+            onChange={(e: any) => setQuery(e.target.value)}
+          />
+          <SearchDialogList items={list}>
+            {(item: any) => (
+              <SearchDialogItemRoot
+                key={item.id}
+                onPress={() => handleSelect(item.id)}
+                textValue={item.title}
+              >
+                <SearchDialogItemIcon isHeading={item.isHeading} />
+                <div className="flex flex-col justify-center gap-0.5">
+                  <SearchDialogItemTitle>{item.title}</SearchDialogItemTitle>
+                  <SearchDialogItemBio>{item.groupTitle}</SearchDialogItemBio>
+                </div>
+              </SearchDialogItemRoot>
+            )}
+          </SearchDialogList>
+        </SearchDialogAutocomplete>
+      </SearchDialogRoot>
+    </>
+  )
+}

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

@@ -0,0 +1,104 @@
+import { useState, useEffect, useMemo } from 'react'
+import { useSidebar } from '@hooks/use-sidebar'
+import SidebarPrimitive from '@components/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'
+
+function getIcon(iconName?: string): React.ElementType | undefined {
+  if (!iconName) return undefined
+  const IconComponent = (LucideIcons as Record<string, any>)[iconName]
+  return IconComponent || undefined
+}
+
+function CollapsibleSidebarGroup({
+  group,
+  activePath,
+  getIcon,
+}: {
+  group: {
+    slug: string
+    title: string
+    routes: ComponentRoute[]
+    icon?: string
+  }
+  activePath: string
+  getIcon: (iconName?: string) => React.ElementType | undefined
+}) {
+  const hasActiveRoute = useMemo(
+    () => group.routes.some((r) => r.path === activePath),
+    [group.routes, activePath],
+  )
+
+  const [isOpen, setIsOpen] = useState(true)
+
+  useEffect(() => {
+    if (hasActiveRoute) {
+      setIsOpen(true)
+    }
+  }, [hasActiveRoute])
+
+  return (
+    <SidebarPrimitive.SidebarGroup
+      title={group.title}
+      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}
+        />
+      ))}
+    </SidebarPrimitive.SidebarGroup>
+  )
+}
+
+export function Sidebar({
+  routes,
+  config,
+}: {
+  routes: ComponentRoute[]
+  config: BoltdocsConfig
+}) {
+  const { groups, ungrouped, activePath } = useSidebar(routes)
+
+  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}
+            />
+          ))}
+        </SidebarPrimitive.SidebarGroup>
+      )}
+
+      {groups.map((group) => (
+        <CollapsibleSidebarGroup
+          key={group.slug}
+          group={group}
+          activePath={activePath}
+          getIcon={getIcon}
+        />
+      ))}
+
+      {config.themeConfig?.poweredBy && (
+        <div className="mt-auto pt-8">
+          <PoweredBy />
+        </div>
+      )}
+    </SidebarPrimitive.SidebarRoot>
+  )
+}

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

@@ -0,0 +1,65 @@
+import { useTabs as useTabsHook } from '@hooks/use-tabs'
+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'
+
+export function Tabs({
+  tabs,
+  routes,
+}: {
+  tabs: BoltdocsTab[]
+  routes: ComponentRoute[]
+}) {
+  const { indicatorStyle, tabRefs, activeIndex } = useTabsHook(tabs, routes)
+
+  const renderTabIcon = (iconName?: string) => {
+    if (!iconName) return null
+    if (iconName.trim().startsWith('<svg')) {
+      return (
+        <span
+          className="h-4 w-4"
+          dangerouslySetInnerHTML={{ __html: iconName }}
+        />
+      )
+    }
+    const LucideIcon = (Icons as Record<string, any>)[iconName]
+    if (LucideIcon) {
+      return <LucideIcon size={16} />
+    }
+    return <img src={iconName} alt="" className="h-4 w-4 object-contain" />
+  }
+
+  return (
+    <div className="mx-auto max-w-(--breakpoint-3xl) px-4 md:px-6">
+      <T.TabsList className="border-none py-0">
+        {tabs.map((tab, index) => {
+          const isActive = index === activeIndex
+          const firstRoute = routes.find(
+            (r) => r.tab && r.tab.toLowerCase() === tab.id.toLowerCase(),
+          )
+          const linkTo = firstRoute ? firstRoute.path : '#'
+
+          return (
+            <Link
+              key={tab.id}
+              href={linkTo}
+              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
+                  ? 'text-primary-500'
+                  : 'text-text-muted hover:text-text-main'
+              }`}
+            >
+              {renderTabIcon(tab.icon)}
+              <span>{tab.text}</span>
+            </Link>
+          )
+        })}
+        <T.TabsIndicator style={indicatorStyle} />
+      </T.TabsList>
+    </div>
+  )
+}

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

@@ -0,0 +1,32 @@
+import { useEffect, useState } from 'react'
+import { Sun, Moon } from 'lucide-react'
+import { useTheme } from '@client/app/theme-context'
+import { ToggleButton } from 'react-aria-components'
+
+export function ThemeToggle() {
+  const { theme, toggleTheme } = useTheme()
+  const [mounted, setMounted] = useState(false)
+
+  useEffect(() => {
+    setMounted(true)
+  }, [])
+
+  if (!mounted) {
+    return <div className="h-9 w-9" />
+  }
+
+  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>
+  )
+}

package/src/client/hooks/index.ts

@@ -0,0 +1,12 @@
+export * from './use-navbar'
+export * from './use-sidebar'
+export * from './use-search'
+export * from './use-onthispage'
+export * from './use-tabs'
+export * from './use-version'
+export * from './use-i18n'
+export * from './use-page-nav'
+export * from './use-breadcrumbs'
+export * from './use-routes'
+export * from './use-localized-to'
+export * from './use-location'

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

@@ -0,0 +1,22 @@
+import { useRoutes } from './use-routes'
+
+/**
+ * Hook to generate breadcrumbs based on the current active route.
+ */
+export function useBreadcrumbs() {
+  const { currentRoute: activeRoute } = useRoutes()
+
+  const crumbs: Array<{ label: string; href?: string }> = []
+
+  if (activeRoute) {
+    if (activeRoute.groupTitle) {
+      crumbs.push({ label: activeRoute.groupTitle })
+    }
+    crumbs.push({ label: activeRoute.title, href: activeRoute.path })
+  }
+
+  return {
+    crumbs,
+    activeRoute,
+  }
+}

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

@@ -0,0 +1,84 @@
+import { useNavigate } from 'react-router-dom'
+import { getBaseFilePath } from '@client/utils/get-base-file-path'
+import { useRoutes } from './use-routes'
+
+export interface LocaleOption {
+  key: string
+  label: string
+  value: string
+  isCurrent: boolean
+}
+
+export interface UseI18nReturn {
+  currentLocale: string | undefined
+  currentLocaleLabel: string | undefined
+  availableLocales: LocaleOption[]
+  handleLocaleChange: (locale: string) => void
+}
+
+/**
+ * Hook to manage and switch between different locales (languages) of the documentation.
+ */
+export function useI18n(): UseI18nReturn {
+  const navigate = useNavigate()
+  const routeContext = useRoutes()
+  const { allRoutes, currentRoute, currentLocale, config } = routeContext
+  const i18n = config.i18n
+
+  const handleLocaleChange = (locale: string) => {
+    if (!i18n || locale === currentLocale) return
+
+    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,
+      )
+
+      if (targetRoute) {
+        targetPath = targetRoute.path
+      } else {
+        const defaultIndexRoute = allRoutes.find(
+          (r) =>
+            getBaseFilePath(r.filePath, r.version, r.locale) === 'index.md' &&
+            (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}`
+      }
+    } else {
+      targetPath = locale === i18n.defaultLocale ? '/' : `/${locale}`
+    }
+
+    navigate(targetPath)
+  }
+
+  const availableLocales = routeContext.availableLocales.map((l) => ({
+    ...l,
+    label: l.label as string,
+    value: l.key,
+  }))
+
+  return {
+    currentLocale,
+    currentLocaleLabel: routeContext.currentLocaleLabel,
+    availableLocales,
+    handleLocaleChange,
+  }
+}

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

@@ -0,0 +1,95 @@
+import { useLocation } from 'react-router-dom'
+import { useConfig } from '@client/app/config-context'
+import type { LinkProps as RouterLinkProps } from 'react-router-dom'
+
+/**
+ * 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.
+ */
+export function useLocalizedTo(to: RouterLinkProps['to']) {
+  const location = useLocation()
+  const config = useConfig()
+
+  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++
+  }
+
+  // Extract just the actual route parts
+  const routeParts = toParts.slice(tIdx)
+
+  // Reconstruct path
+  const finalParts = []
+  if (config.versions) {
+    if (hasVersion) {
+      finalParts.push(toParts[0])
+    } else if (currentVersion) {
+      finalParts.push(currentVersion)
+    }
+  }
+  if (config.i18n) {
+    if (hasLocale) {
+      finalParts.push(toParts[hasVersion ? 1 : 0])
+    } else if (currentLocale) {
+      finalParts.push(currentLocale)
+    }
+  }
+
+  finalParts.push(...routeParts)
+
+  let finalPath = `${basePath}/${finalParts.join('/')}`
+  if (finalPath.endsWith('/')) {
+    finalPath = finalPath.slice(0, -1)
+  }
+  return finalPath === basePath ? basePath : finalPath
+}

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

@@ -0,0 +1,5 @@
+import { useLocation as useReactLocation } from 'react-router-dom'
+
+export const useLocation = () => {
+  return useReactLocation()
+}

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

@@ -0,0 +1,60 @@
+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'
+
+export function useNavbar() {
+  const config = useConfig()
+  const { theme } = useTheme()
+  const location = useLocation()
+
+  const themeConfig = config.themeConfig || {}
+  const title = themeConfig.title || 'Boltdocs'
+  const rawLinks = themeConfig.navbar || []
+  const socialLinks = themeConfig.socialLinks || []
+  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 || ''
+    return {
+      label: item.label || item.text || '',
+      href,
+      active: location.pathname === href,
+      to:
+        href.startsWith('http') || href.startsWith('//')
+          ? 'external'
+          : undefined,
+    }
+  })
+
+  const logo = themeConfig.logo
+  const logoSrc = !logo
+    ? null
+    : typeof logo === 'string'
+      ? logo
+      : theme === 'dark'
+        ? (logo as any).dark
+        : (logo as any).light
+
+  const logoProps = {
+    alt:
+      (logo && typeof logo === 'object' ? (logo as any).alt : undefined) ||
+      title,
+    width: logo && typeof logo === 'object' ? (logo as any).width : undefined,
+    height: logo && typeof logo === 'object' ? (logo as any).height : undefined,
+  }
+
+  const github = githubRepo ? `https://github.com/${githubRepo}` : null
+
+  return {
+    links,
+    title,
+    logo: logoSrc,
+    logoProps,
+    github,
+    social: socialLinks,
+    config,
+    theme,
+  }
+}

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

@@ -0,0 +1,23 @@
+import { useState } from 'react'
+
+interface Heading {
+  id: string
+  text: string
+  level: number
+}
+
+/**
+ * Hook to manage and provide current page headings for the OnThisPage component.
+ */
+export function useOnThisPage(headings: Heading[] = []) {
+  const [activeId, setActiveId] = useState<string | null>(null)
+
+  // We keep the signature the same for backward compatibility,
+  // but the activeId tracking is now handled by AnchorProvider in the primitives.
+
+  return {
+    headings,
+    activeId,
+    setActiveId,
+  }
+}

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

@@ -0,0 +1,22 @@
+import { useRoutes } from './use-routes'
+
+/**
+ * Hook to manage the previous and next button functionality for documentation pages.
+ */
+export function usePageNav() {
+  const { routes } = useRoutes()
+  const currentPath = window.location.pathname
+
+  const currentIndex = routes.findIndex((r) => r.path === currentPath)
+  const currentRoute = routes[currentIndex]
+
+  const prevPage = currentIndex > 0 ? routes[currentIndex - 1] : null
+  const nextPage =
+    currentIndex < routes.length - 1 ? routes[currentIndex + 1] : null
+
+  return {
+    prevPage,
+    nextPage,
+    currentRoute,
+  }
+}

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

@@ -0,0 +1,72 @@
+import { useLocation } from 'react-router-dom'
+import { useConfig } from '@client/app/config-context'
+import { usePreload } from '@client/app/preload'
+
+/**
+ * Hook to access the framework's routing state.
+ * Returns both the complete set of routes and a filtered list based on the current
+ * version and locale.
+ */
+export function useRoutes() {
+  const { routes: allRoutes } = usePreload()
+  const config = useConfig()
+  const location = useLocation()
+
+  // Find the current route exactly matching the pathname
+  const currentRoute = allRoutes.find((r) => r.path === location.pathname)
+
+  // Derive current locale and version from the route or defaults
+  const currentLocale = config.i18n
+    ? currentRoute?.locale || config.i18n.defaultLocale
+    : undefined
+
+  const currentVersion = config.versions
+    ? currentRoute?.version || 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
+    return localeMatch && versionMatch
+  })
+
+  // Labels and lists for UI convenience
+  const currentLocaleLabel =
+    config.i18n?.locales[currentLocale as string] || currentLocale
+  const currentVersionLabel =
+    config.versions?.versions[currentVersion as string] || currentVersion
+
+  const availableLocales = config.i18n
+    ? Object.entries(config.i18n.locales).map(([key, label]) => ({
+        key,
+        label,
+        isCurrent: key === currentLocale,
+      }))
+    : []
+
+  const availableVersions = config.versions
+    ? Object.entries(config.versions.versions).map(([key, label]) => ({
+        key,
+        label,
+        isCurrent: key === currentVersion,
+      }))
+    : []
+
+  return {
+    routes,
+    allRoutes,
+    currentRoute,
+    currentLocale,
+    currentLocaleLabel,
+    availableLocales,
+    currentVersion,
+    currentVersionLabel,
+    availableVersions,
+    config,
+  }
+}