boltdocs 2.1.1 → 2.3.0

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

@@ -1,61 +1,98 @@
-import { useState, useMemo } from 'react'
+import { useState, useMemo, useEffect } from 'react'
+import { Index } from 'flexsearch'
+import { useRoutes } from './use-routes'
 import type { ComponentRoute } from '@client/types'
+// @ts-ignore
+import searchData from 'virtual:boltdocs-search'
+
+interface SearchDataItem {
+  id: string
+  title: string
+  content: string
+  url: string
+  display: string
+  locale?: string
+  version?: string
+}
 
 export function useSearch(routes: ComponentRoute[]) {
+  const { currentLocale, currentVersion } = useRoutes()
   const [isOpen, setIsOpen] = useState(false)
   const [query, setQuery] = useState('')
+  const [index, setIndex] = useState<Index | null>(null)
+
+  // Initialize FlexSearch index once
+  useEffect(() => {
+    if (!isOpen || index) return
+
+    const newIndex = new Index({
+      preset: 'match',
+      tokenize: 'full',
+      resolution: 9,
+      cache: true,
+    })
+
+    // Index all documents
+    for (const doc of searchData as SearchDataItem[]) {
+      newIndex.add(doc.id, `${doc.title} ${doc.content}`)
+    }
+
+    setIndex(newIndex)
+  }, [isOpen, index])
 
   const list = useMemo(() => {
     if (!query) {
-      return routes.slice(0, 10).map((r) => ({
-        id: r.path,
-        title: r.title,
-        path: r.path,
-        bio: r.description || '',
-        groupTitle: r.groupTitle,
-      }))
+      // Default results: just active routes
+      return routes
+        .filter((r) => {
+          const localeMatch = !currentLocale || r.locale === currentLocale
+          const versionMatch = !currentVersion || r.version === currentVersion
+          return localeMatch && versionMatch
+        })
+        .slice(0, 10)
+        .map((r) => ({
+          id: r.path,
+          title: r.title,
+          path: r.path,
+          bio: r.description || '',
+          groupTitle: r.groupTitle,
+        }))
     }
 
+    if (!index) return []
+
+    const searchResults = index.search(query, {
+      limit: 20,
+      suggest: true,
+    })
+
     const results: any[] = []
-    const lowerQuery = query.toLowerCase()
-
-    for (const route of routes) {
-      if (route.title?.toLowerCase().includes(lowerQuery)) {
-        results.push({
-          id: route.path,
-          title: route.title,
-          path: route.path,
-          bio: route.description || '',
-          groupTitle: route.groupTitle,
-        })
-      }
-
-      if (route.headings) {
-        for (const heading of route.headings) {
-          if (heading.text.toLowerCase().includes(lowerQuery)) {
-            results.push({
-              id: `${route.path}#${heading.id}`,
-              title: heading.text,
-              path: `${route.path}#${heading.id}`,
-              bio: `Heading in ${route.title}`,
-              groupTitle: route.title,
-              isHeading: true,
-            })
-          }
-        }
-      }
-    }
+    const seen = new Set<string>()
+
+    for (const id of searchResults) {
+      const doc = (searchData as SearchDataItem[]).find((d) => d.id === id)
+      if (!doc) continue
 
-    // Deduplicate by path
-    const seen = new Set()
-    return results
-      .filter((r) => {
-        if (seen.has(r.path)) return false
-        seen.add(r.path)
-        return true
+      // Filter by locale and version
+      const localeMatch = !currentLocale || doc.locale === currentLocale
+      const versionMatch = !currentVersion || doc.version === currentVersion
+      if (!localeMatch || !versionMatch) continue
+
+      if (seen.has(doc.url)) continue
+      seen.add(doc.url)
+
+      results.push({
+        id: doc.url,
+        title: doc.title,
+        path: doc.url,
+        bio: doc.display,
+        groupTitle: doc.display.split(' > ')[0],
+        isHeading: doc.url.includes('#'),
       })
-      .slice(0, 10)
-  }, [routes, query])
+    }
+
+    return results.slice(0, 10)
+  }, [query, index, currentLocale, currentVersion, routes])
 
   return {
     isOpen,
@@ -65,7 +102,8 @@ export function useSearch(routes: ComponentRoute[]) {
     list,
     input: {
       value: query,
-      onChange: (e: any) => setQuery(e.target.value),
+      onChange: (e: React.ChangeEvent<HTMLInputElement>) =>
+        setQuery(e.target.value),
     },
   }
 }

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

@@ -7,7 +7,11 @@ export function useSidebar(routes: ComponentRoute[]) {
   const location = useLocation()
 
   // Find active route and tab
-  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()
 
   // Filter routes by active tab if any
@@ -43,7 +47,7 @@ export function useSidebar(routes: ComponentRoute[]) {
     groups,
     ungrouped,
     activeRoute,
-    activePath: location.pathname,
+    activePath: currentPath,
     config,
   }
 }

package/src/client/hooks/use-version.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 VersionOption {
   key: string
@@ -25,10 +26,14 @@ export function useVersion(): UseVersionReturn {
   const { allRoutes, currentRoute, currentVersion, currentLocale, config } =
     routeContext
   const versions = config.versions
+  const setVersion = useBoltdocsStore((s) => s.setVersion)
 
   const handleVersionChange = (version: string) => {
     if (!versions || version === currentVersion) return
 
+    // Update store
+    setVersion(version)
+
     let targetPath = `/docs/${version}`
 
     if (currentRoute) {

package/src/client/integrations/index.ts

@@ -0,0 +1 @@
+export * from './codesandbox'

package/src/client/store/use-boltdocs-store.ts

@@ -0,0 +1,44 @@
+import { create } from 'zustand'
+import { persist, createJSONStorage } from 'zustand/middleware'
+
+interface BoltdocsState {
+  currentLocale: string | undefined
+  currentVersion: string | undefined
+  hasHydrated: boolean
+
+  // Actions
+  setLocale: (locale: string | undefined) => void
+  setVersion: (version: string | undefined) => void
+  setHasHydrated: (val: boolean) => void
+}
+
+/**
+ * Global store for Boltdocs documentation state.
+ * Uses localStorage persistence to remember user preferences across sessions.
+ */
+export const useBoltdocsStore = create<BoltdocsState>()(
+  persist(
+    (set) => ({
+      currentLocale: undefined,
+      currentVersion: undefined,
+      hasHydrated: false,
+
+      setLocale: (locale: string | undefined) => set({ currentLocale: locale }),
+      setVersion: (version: string | undefined) =>
+        set({ currentVersion: version }),
+      setHasHydrated: (val: boolean) => set({ hasHydrated: val }),
+    }),
+    {
+      name: 'boltdocs-storage',
+      storage: createJSONStorage(() => localStorage),
+      // Only persist identifying state
+      partialize: (state: BoltdocsState) => ({
+        currentLocale: state.currentLocale,
+        currentVersion: state.currentVersion,
+      }),
+      onRehydrateStorage: () => (state?: BoltdocsState) => {
+        state?.setHasHydrated(true)
+      },
+    },
+  ),
+)

package/src/client/theme/neutral.css

@@ -67,6 +67,35 @@
   --spacing-sidebar: 16rem;
   --spacing-toc: 14rem;
   --spacing-content-max: 48rem;
+
+  @keyframes pulse {
+    0%,
+    100% {
+      opacity: 1;
+    }
+    50% {
+      opacity: 0.5;
+    }
+  }
+
+  @keyframes fade-in {
+    from {
+      opacity: 0;
+      transform: translateY(10px);
+    }
+    to {
+      opacity: 1;
+      transform: translateY(0);
+    }
+  }
+}
+
+.animate-pulse {
+  animation: pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite;
+}
+
+.animate-fade-in {
+  animation: fade-in 0.5s ease-out forwards;
 }
 
 :root[data-theme="dark"],

package/src/client/types.ts

@@ -119,7 +119,8 @@ export interface SandboxEmbedOptions {
  */
 export interface BoltdocsTab {
   id: string
-  text: string
+  /** Text to display (can be a string or a map of translations) */
+  text: string | Record<string, string>
   icon?: string
 }
 
@@ -160,7 +161,8 @@ export interface LayoutProps {
  * Unified type for navbar links.
  */
 export interface NavbarLink {
-  label: string
+  /** Label to display (can be a string or a map of translations) */
+  label: string | Record<string, string>
   href: string
   active: boolean
   /** Optional icon or string for external link indication */

package/src/client/utils/i18n.ts

@@ -0,0 +1,23 @@
+/**
+ * Retrieves the correct translation from a value that can be either
+ * a simple string or a map of locale-specific strings.
+ *
+ * @param value - The text to translate
+ * @param locale - The current active locale (e.g., 'en', 'es')
+ * @returns The translated string
+ */
+export function getTranslated(
+  value: string | Record<string, string> | undefined,
+  locale?: string,
+): string {
+  if (!value) return ''
+  if (typeof value === 'string') return value
+
+  if (locale && value[locale]) {
+    return value[locale]
+  }
+
+  // Fallback: Use the first available translation or an empty string
+  const firstValue = Object.values(value)[0]
+  return firstValue || ''
+}

package/src/node/{cli.ts → cli/build.ts}

@@ -1,27 +1,16 @@
-import { createServer, build, preview } from 'vite'
-import { createViteConfig, resolveConfig } from './index'
-import { getHtmlTemplate } from './plugin/html'
+import { build, preview } from 'vite'
+import { createViteConfig, resolveConfig } from '../index'
+import { getHtmlTemplate } from '../plugin/html'
 import path from 'path'
 import fs from 'fs'
+import * as ui from './ui'
 
 /**
- * Core logic for the Boltdocs CLI commands.
- * These functions wrap Vite's JS API to provide a seamless experience.
+ * Logic for the `boltdocs build` command.
+ * Prepares the production bundle and handles dynamic index.html generation.
+ *
+ * @param root - The project root directory
  */
-
-export async function devAction(root: string = process.cwd()) {
-  try {
-    const viteConfig = await createViteConfig(root, 'development')
-    const server = await createServer(viteConfig)
-    await server.listen()
-    server.printUrls()
-    server.bindCLIShortcuts({ print: true })
-  } catch (e) {
-    console.error('[boltdocs] Failed to start dev server:', e)
-    process.exit(1)
-  }
-}
-
 export async function buildAction(root: string = process.cwd()) {
   let createdIndexHtml = false
   const indexPath = path.resolve(root, 'index.html')
@@ -35,9 +24,9 @@ export async function buildAction(root: string = process.cwd()) {
 
     const viteConfig = await createViteConfig(root, 'production')
     await build(viteConfig)
-    console.log('[boltdocs] Build completed successfully.')
+    ui.success('Build completed successfully.')
   } catch (e) {
-    console.error('[boltdocs] Build failed:', e)
+    ui.error('Build failed:', e)
     process.exit(1)
   } finally {
     if (createdIndexHtml && fs.existsSync(indexPath)) {
@@ -46,14 +35,19 @@ export async function buildAction(root: string = process.cwd()) {
   }
 }
 
+/**
+ * Logic for the `boltdocs preview` command.
+ * Serves the production build from the disk.
+ *
+ * @param root - The project root directory
+ */
 export async function previewAction(root: string = process.cwd()) {
   try {
     const viteConfig = await createViteConfig(root, 'production')
     const previewServer = await preview(viteConfig)
     previewServer.printUrls()
   } catch (e) {
-    console.error('[boltdocs] Failed to start preview server:', e)
+    ui.error('Failed to start preview server:', e)
     process.exit(1)
   }
 }
-

package/src/node/cli/dev.ts

@@ -0,0 +1,22 @@
+import { createServer } from 'vite'
+import { createViteConfig } from '../index'
+import * as ui from './ui'
+
+/**
+ * Logic for the `boltdocs dev` command.
+ * Starts a Vite development server and sets up HMR.
+ *
+ * @param root - The project root directory
+ */
+export async function devAction(root: string = process.cwd()) {
+  try {
+    const viteConfig = await createViteConfig(root, 'development')
+    const server = await createServer(viteConfig)
+    await server.listen()
+    server.printUrls()
+    server.bindCLIShortcuts({ print: true })
+  } catch (e) {
+    ui.error('Failed to start dev server:', e)
+    process.exit(1)
+  }
+}

package/src/node/cli/doctor.ts

@@ -0,0 +1,243 @@
+import path from 'path'
+import fs from 'fs'
+import fastGlob from 'fast-glob'
+import { resolveConfig } from '../config'
+import { parseFrontmatter, normalizePath } from '../utils'
+import * as ui from './ui'
+
+/**
+ * Interface representing a documentation hygiene issue.
+ */
+interface Issue {
+  level: 'high' | 'warning' | 'low'
+  message: string
+  suggestion?: string
+}
+
+/**
+ * Logic for the `boltdocs doctor` command.
+ * Scans the documentation directory for broken links, missing frontmatter,
+ * and orphaned translations.
+ *
+ * @param root - The project root directory
+ */
+export async function doctorAction(root: string = process.cwd()) {
+  const { colors } = ui
+  ui.info(
+    `${colors.bold}Running documentation health check...${colors.reset}\n`,
+  )
+  const start = performance.now()
+
+  try {
+    const config = await resolveConfig('docs', root)
+    const docsDir = path.resolve(root, 'docs')
+
+    if (!fs.existsSync(docsDir)) {
+      ui.error(`Documentation directory not found at ${docsDir}`)
+      process.exit(1)
+    }
+
+    const files = await fastGlob(['**/*.md', '**/*.mdx'], {
+      cwd: docsDir,
+      absolute: true,
+      suppressErrors: true,
+    })
+
+    let highCount = 0
+    let warningCount = 0
+    let lowCount = 0
+    const issuesMap = new Map<string, Issue[]>()
+
+    const addIssue = (file: string, issue: Issue) => {
+      const relPath = path.relative(docsDir, file)
+      let issues = issuesMap.get(relPath)
+      if (!issues) {
+        issues = []
+        issuesMap.set(relPath, issues)
+      }
+      issues.push(issue)
+      if (issue.level === 'high') highCount++
+      else if (issue.level === 'warning') warningCount++
+      else if (issue.level === 'low') lowCount++
+    }
+
+    const basePath = '/docs'
+
+    // 1. Scan for Frontmatter, Links, and Content Issues
+    for (const file of files) {
+      const { data, content } = parseFrontmatter(file)
+
+      // Frontmatter Validation
+      if (!data.title) {
+        addIssue(file, {
+          level: 'warning',
+          message: 'Missing "title" in frontmatter.',
+          suggestion:
+            'Add `title: Your Title` to the YAML frontmatter at the top of the file.',
+        })
+      }
+
+      if (!data.description) {
+        addIssue(file, {
+          level: 'low',
+          message: 'Missing "description" in frontmatter.',
+          suggestion:
+            'Adding a description helps with SEO and search previews.',
+        })
+      }
+
+      // Link Validation
+      const linkRegex = /\[.*?\]\((.*?)\)/g
+      const htmlLinkRegex = /<a\s+[^>]*href=["']([^"']+)["'][^>]*>/g
+      const links = [
+        ...content.matchAll(linkRegex),
+        ...content.matchAll(htmlLinkRegex),
+      ]
+
+      for (const match of links) {
+        let link = match[1]
+        if (
+          !link ||
+          link.startsWith('http') ||
+          link.startsWith('https') ||
+          link.startsWith('#') ||
+          link.startsWith('mailto:') ||
+          link.startsWith('tel:')
+        ) {
+          continue
+        }
+
+        link = link.split('#')[0]
+        if (!link) continue
+
+        let targetPath: string
+        if (link.startsWith('/')) {
+          let pathAfterBase = link
+          if (link.startsWith(basePath + '/') || link === basePath) {
+            pathAfterBase = link.substring(basePath.length)
+          }
+          targetPath = path.join(docsDir, pathAfterBase)
+        } else {
+          targetPath = path.resolve(path.dirname(file), link)
+        }
+
+        const extensions = ['', '.md', '.mdx', '/index.md', '/index.mdx']
+        let exists = false
+        for (const ext of extensions) {
+          const finalPath = targetPath + ext
+          if (fs.existsSync(finalPath) && fs.statSync(finalPath).isFile()) {
+            exists = true
+            break
+          }
+        }
+
+        if (!exists) {
+          addIssue(file, {
+            level: 'high',
+            message: `Broken internal link: "${link}"`,
+            suggestion: `Ensure the file exists at "${targetPath}". If it's a directory, ensure it has an "index.md" or "index.mdx".`,
+          })
+        }
+      }
+    }
+
+    // 2. Scan for Orphaned Translations
+    if (config.i18n) {
+      const { defaultLocale, locales } = config.i18n
+      const otherLocales = Object.keys(locales).filter(
+        (l) => l !== defaultLocale,
+      )
+
+      for (const file of files) {
+        const relPath = normalizePath(path.relative(docsDir, file))
+        const parts = relPath.split('/')
+
+        if (parts[0] === defaultLocale) {
+          const pathAfterLocale = parts.slice(1).join('/')
+          for (const locale of otherLocales) {
+            const localeParts = [locale, ...parts.slice(1)]
+            const targetLocaleFile = path.join(docsDir, ...localeParts)
+
+            if (!fs.existsSync(targetLocaleFile)) {
+              addIssue(file, {
+                level: 'warning',
+                message: `Missing translation for locale "${locale}"`,
+                suggestion: `Create a translated version of this file at "${locale}/${pathAfterLocale}".`,
+              })
+            }
+          }
+        }
+      }
+    }
+
+    // Final Reporting
+    if (issuesMap.size === 0) {
+      ui.success('All documentation files are healthy!\n')
+    } else {
+      for (const [file, issues] of issuesMap.entries()) {
+        console.log(`📄 ${colors.bold}${file}${colors.reset}`)
+
+        const sortedIssues = issues.sort((a, b) => {
+          const order = { high: 1, warning: 2, low: 3 }
+          return order[a.level] - order[b.level]
+        })
+
+        for (const issue of sortedIssues) {
+          let prefix = ''
+          let color = ''
+          if (issue.level === 'high') {
+            prefix = '❌'
+            color = colors.red
+          } else if (issue.level === 'warning') {
+            prefix = '⚠️'
+            color = colors.yellow
+          } else {
+            prefix = 'ℹ️'
+            color = colors.cyan
+          }
+
+          console.log(
+            `   ${color}${prefix} ${issue.level.toUpperCase()}:${colors.reset} ${issue.message}`,
+          )
+          if (issue.suggestion) {
+            console.log(
+              `      ${colors.gray}💡 Suggestion: ${issue.suggestion}${colors.reset}`,
+            )
+          }
+        }
+        console.log('')
+      }
+
+      console.log(`${colors.bold}Summary:${colors.reset}`)
+      console.log(
+        `   ${colors.red}${highCount} high-level errors${colors.reset}`,
+      )
+      console.log(`   ${colors.yellow}${warningCount} warnings${colors.reset}`)
+      console.log(
+        `   ${colors.cyan}${lowCount} minor improvements${colors.reset}\n`,
+      )
+
+      if (highCount > 0) {
+        ui.error(
+          'HIGH ERROR: Fix these to ensure your documentation builds correctly.',
+        )
+      }
+      if (warningCount > 0 || lowCount > 0) {
+        ui.info(
+          'TIP: Address warnings and suggestions for premium quality docs.',
+        )
+      }
+      console.log('')
+    }
+
+    const duration = performance.now() - start
+    ui.info(`Finished in ${duration.toFixed(2)}ms\n`)
+
+    if (highCount > 0) {
+      process.exit(1)
+    }
+  } catch (e) {
+    ui.error('Failed to run doctor check:', e)
+    process.exit(1)
+  }
+}

package/src/node/cli/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Boltdocs CLI Actions Module.
+ * This module exports all command-line actions used by the Boltdocs tool.
+ */
+
+export * from './dev'
+export * from './build'
+export * from './doctor'
+export * from './ui'