boltdocs 1.10.1 → 1.11.0

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

@@ -0,0 +1,71 @@
+import { useState, useMemo } from 'react'
+import type { ComponentRoute } from '@client/types'
+
+export function useSearch(routes: ComponentRoute[]) {
+  const [isOpen, setIsOpen] = useState(false)
+  const [query, setQuery] = useState('')
+
+  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,
+      }))
+    }
+
+    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,
+            })
+          }
+        }
+      }
+    }
+
+    // Deduplicate by path
+    const seen = new Set()
+    return results
+      .filter((r) => {
+        if (seen.has(r.path)) return false
+        seen.add(r.path)
+        return true
+      })
+      .slice(0, 10)
+  }, [routes, query])
+
+  return {
+    isOpen,
+    setIsOpen,
+    query,
+    setQuery,
+    list,
+    input: {
+      value: query,
+      onChange: (e: any) => setQuery(e.target.value),
+    },
+  }
+}

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

@@ -0,0 +1,49 @@
+import { useLocation } from 'react-router-dom'
+import { useConfig } from '@client/app/config-context'
+import type { ComponentRoute } from '../types'
+
+export function useSidebar(routes: ComponentRoute[]) {
+  const config = useConfig()
+  const location = useLocation()
+
+  // Find active route and tab
+  const activeRoute = routes.find((r) => r.path === location.pathname)
+  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) {
+    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,
+        })
+      }
+      groupsMap.get(route.group)!.routes.push(route)
+    }
+  }
+
+  const groups = Array.from(groupsMap.values())
+
+  return {
+    groups,
+    ungrouped,
+    activeRoute,
+    activePath: location.pathname,
+    config,
+  }
+}

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

@@ -0,0 +1,43 @@
+import { useLocation } from 'react-router-dom'
+import { useEffect, useState, useRef } from 'react'
+import type { ComponentRoute, BoltdocsTab } from '@client/types'
+
+export function useTabs(
+  tabs: BoltdocsTab[] = [],
+  routes: ComponentRoute[] = [],
+) {
+  const location = useLocation()
+  const tabRefs = useRef<(HTMLAnchorElement | null)[]>([])
+  const [indicatorStyle, setIndicatorStyle] = useState<React.CSSProperties>({
+    opacity: 0,
+    transform: 'translateX(0) scaleX(0)',
+    width: 0,
+  })
+
+  const activeRoute = routes.find((r) => r.path === location.pathname)
+  const activeTabId = activeRoute?.tab?.toLowerCase()
+  const activeIndex = tabs.findIndex(
+    (tab) => tab.id.toLowerCase() === activeTabId,
+  )
+  const finalActiveIndex = activeIndex === -1 ? 0 : activeIndex
+
+  // biome-ignore lint/correctness/useExhaustiveDependencies: Updated pointer to the tab
+  useEffect(() => {
+    const activeTab = tabRefs.current[finalActiveIndex]
+    if (activeTab) {
+      setIndicatorStyle({
+        opacity: 1,
+        width: activeTab.offsetWidth,
+        transform: `translateX(${activeTab.offsetLeft}px)`,
+      })
+    }
+  }, [finalActiveIndex, tabs.length, location.pathname])
+
+  return {
+    tabs,
+    activeIndex: finalActiveIndex,
+    indicatorStyle,
+    tabRefs,
+    activeTabId,
+  }
+}

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

@@ -0,0 +1,78 @@
+import { useNavigate } from 'react-router-dom'
+import { getBaseFilePath } from '@client/utils/get-base-file-path'
+import { useRoutes } from './use-routes'
+
+export interface VersionOption {
+  key: string
+  label: string
+  value: string
+  isCurrent: boolean
+}
+
+export interface UseVersionReturn {
+  currentVersion: string | undefined
+  currentVersionLabel: string | undefined
+  availableVersions: VersionOption[]
+  handleVersionChange: (version: string) => void
+}
+
+/**
+ * Hook to manage and switch between different versions of the documentation.
+ */
+export function useVersion(): UseVersionReturn {
+  const navigate = useNavigate()
+  const routeContext = useRoutes()
+  const { allRoutes, currentRoute, currentVersion, currentLocale, config } =
+    routeContext
+  const versions = config.versions
+
+  const handleVersionChange = (version: string) => {
+    if (!versions || version === currentVersion) return
+
+    let targetPath = `/docs/${version}`
+
+    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.version || versions.defaultVersion) === version &&
+          (currentLocale ? r.locale === currentLocale : !r.locale),
+      )
+
+      if (targetRoute) {
+        targetPath = targetRoute.path
+      } else {
+        const versionIndexRoute = allRoutes.find(
+          (r) =>
+            getBaseFilePath(r.filePath, r.version, r.locale) === 'index.md' &&
+            (r.version || versions.defaultVersion) === version &&
+            (currentLocale ? r.locale === currentLocale : !r.locale),
+        )
+        targetPath = versionIndexRoute
+          ? versionIndexRoute.path
+          : `/docs/${version}${currentLocale ? `/${currentLocale}` : ''}`
+      }
+    }
+
+    navigate(targetPath)
+  }
+
+  const availableVersions = routeContext.availableVersions.map((v) => ({
+    ...v,
+    label: v.label as string,
+    value: v.key,
+  }))
+
+  return {
+    currentVersion,
+    currentVersionLabel: routeContext.currentVersionLabel,
+    availableVersions,
+    handleVersionChange,
+  }
+}

package/src/client/index.ts

@@ -1,19 +1,46 @@
-export type { BoltdocsConfig, BoltdocsThemeConfig } from "../node/config";
-export type { ComponentRoute, CreateBoltdocsAppOptions } from "./types";
-import { PackageManagerTabs } from "./theme/components/PackageManagerTabs";
-export { createBoltdocsApp } from "./app";
-export { ThemeLayout } from "./theme/ui/Layout";
-export { Navbar } from "./theme/ui/Navbar";
-export { Sidebar } from "./theme/ui/Sidebar";
-export { OnThisPage } from "./theme/ui/OnThisPage";
-export { Head } from "./theme/ui/Head";
-export { Breadcrumbs } from "./theme/ui/Breadcrumbs";
-export { BackgroundGradient } from "./theme/ui/BackgroundGradient";
-export { Playground } from "./theme/components/Playground";
-export { NotFound } from "./theme/ui/NotFound";
-export { Loading } from "./theme/ui/Loading";
-export { CodeBlock } from "./theme/components/CodeBlock";
-export { Video } from "./theme/components/Video";
+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'
+
+// Composable layout building blocks
+export { DocsLayout } from '@components/docs-layout'
+export { DefaultLayout } from '@components/default-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 { ProgressBar } from '@components/ui-base/progress-bar'
+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 {
+  defineSandbox,
+  openSandbox,
+  embedSandbox,
+} from '@integrations/codesandbox'
+
+export type {
+  SandboxOptions,
+  SandboxFile,
+  SandboxFiles,
+  SandboxEmbedOptions,
+} from './types'
 export {
   Button,
   Badge,
@@ -27,11 +54,17 @@ export {
   Warning,
   Danger,
   InfoBox,
+  ComponentProps,
+  ComponentPreview,
+  Important,
+  Caution,
   List,
   FileTree,
   Table,
   Field,
-} from "./theme/components/mdx";
+  Link,
+  Image,
+} from './components/mdx'
 export type {
   ButtonProps,
   BadgeProps,
@@ -40,8 +73,12 @@ export type {
   TabsProps,
   TabProps,
   AdmonitionProps,
+  ComponentPropsProps,
+  ComponentPreviewProps,
   ListProps,
   FileTreeProps,
   TableProps,
   FieldProps,
-} from "./theme/components/mdx";
+  LinkProps,
+  ImageProps,
+} from './components/mdx'

package/src/client/integrations/codesandbox.ts

@@ -0,0 +1,179 @@
+import { getParameters } from 'codesandbox/lib/api/define.js'
+import { SandboxOptions } from '../types'
+
+/**
+ * Build the files payload for the CodeSandbox Define API.
+ * Ensures every file conforms to the `{ content, isBinary }` shape
+ * required by the SDK, and auto-generates a `package.json` when one
+ * isn't explicitly provided.
+ */
+function buildSandboxFiles(options: SandboxOptions) {
+  const files = options.files || {}
+  const dependencies = options.dependencies || {}
+  const devDependencies = options.devDependencies || {}
+  const title = options.title || 'codesandbox-project'
+  const description = options.description || 'Generic Sandbox'
+
+  const finalFiles: Record<string, { content: string; isBinary: boolean }> = {}
+
+  for (const [path, file] of Object.entries(files)) {
+    const content =
+      typeof file.content === 'object'
+        ? JSON.stringify(file.content, null, 2)
+        : file.content
+    finalFiles[path] = { content, isBinary: file.isBinary ?? false }
+  }
+
+  if (!finalFiles['package.json']) {
+    const isVite =
+      options.template === 'vite' ||
+      !!devDependencies.vite ||
+      !!devDependencies['@vitejs/plugin-react']
+
+    const defaultScripts = isVite
+      ? {
+          dev: 'vite',
+          build: 'vite build',
+          preview: 'vite preview',
+        }
+      : {
+          start: 'node index.js',
+        }
+
+    finalFiles['package.json'] = {
+      content: JSON.stringify(
+        {
+          private: true,
+          name: title,
+          description,
+          type: 'module',
+          version: '1.0.0',
+          scripts: options.scripts || defaultScripts,
+          dependencies,
+          devDependencies,
+        },
+        null,
+        2,
+      ),
+      isBinary: false,
+    }
+  }
+
+  return finalFiles
+}
+
+/**
+ * Helper to define a sandbox and get a URL for the CodeSandbox Define API.
+ * Uses the official SDK `getParameters` for proper LZ-string compression.
+ */
+export function defineSandbox(options: SandboxOptions) {
+  const finalFiles = buildSandboxFiles(options)
+  const parameters = getParameters({ files: finalFiles })
+
+  // FIX: Agregar query params que forzan comportamiento correcto
+  const query = new URLSearchParams({
+    parameters,
+    // FIX: Forzar instalación de dependencias
+    installDependencies: 'true',
+  })
+
+  // FIX: Agregar file query para que abra el entry correcto
+  if (options.entry) {
+    query.set('file', `/${options.entry}`)
+  }
+
+  return {
+    parameters,
+    url: `https://codesandbox.io/api/v1/sandboxes/define?${query.toString()}`,
+    options,
+  }
+}
+
+/**
+ * CORE API: Open a CodeSandbox using a form POST to the Define API.
+ *
+ * Uses a hidden form + POST which avoids URL length limits and is the
+ * recommended approach from CodeSandbox documentation. The SDK's
+ * `getParameters` handles LZ-string compression internally.
+ */
+export function openSandbox(options: SandboxOptions) {
+  if (typeof window === 'undefined') return defineSandbox(options)
+
+  const finalFiles = buildSandboxFiles(options)
+  const parameters = getParameters({ files: finalFiles })
+  const entry = options.entry || 'src/App.tsx'
+
+  // Use form POST – the most reliable method for the Define API
+  const form = document.createElement('form')
+  form.method = 'POST'
+  form.target = '_blank'
+  form.action = 'https://codesandbox.io/api/v1/sandboxes/define'
+  form.style.display = 'none'
+
+  const addField = (name: string, value: string) => {
+    const input = document.createElement('input')
+    input.type = 'hidden'
+    input.name = name
+    input.value = value
+    form.appendChild(input)
+  }
+
+  const queryParams = new URLSearchParams({
+    file: `/${entry}`,
+    // FIX: Forzar vista de preview (no solo editor)
+    // FIX: Deshabilitar eslint que a veces bloquea
+    eslint: '0',
+    // FIX: Habilitar codemirror
+    codemirror: '1',
+    // FIX: Forzar instalación de deps
+    installDependencies: 'true',
+  })
+
+  addField('query', queryParams.toString())
+  addField('parameters', parameters)
+
+  document.body.appendChild(form)
+  form.submit()
+  document.body.removeChild(form)
+
+  return {
+    parameters,
+    url: `https://codesandbox.io/api/v1/sandboxes/define?parameters=${parameters}`,
+    options,
+  }
+}
+
+/**
+ * Generate an embeddable iframe URL for a CodeSandbox.
+ *
+ * This gives you more control than `openSandbox` — you can embed the sandbox
+ * inline on the page rather than opening a new tab. The returned URL can be
+ * used as the `src` of an `<iframe>`.
+ *
+ * @example
+ * ```tsx
+ * const url = embedSandbox({
+ *   files: { "index.js": { content: "console.log('hello')" } },
+ *   embed: { view: "editor", theme: "dark" },
+ * }).url;
+ * // url → "https://codesandbox.io/api/v1/sandboxes/define?parameters=…&embed=1&view=editor&theme=dark"
+ * ```
+ */
+export function embedSandbox(options: SandboxOptions) {
+  const finalFiles = buildSandboxFiles(options)
+  const parameters = getParameters({ files: finalFiles })
+  const embedOptions = options.embed || {}
+
+  const query = new URLSearchParams({ parameters, embed: '1' })
+
+  if (embedOptions.view) query.set('view', embedOptions.view)
+  if (embedOptions.theme) query.set('theme', embedOptions.theme)
+  if (embedOptions.hideNavigation) query.set('hidenavigation', '1')
+  if (options.entry) query.set('file', `/${options.entry}`)
+
+  return {
+    parameters,
+    url: `https://codesandbox.io/api/v1/sandboxes/define?${query.toString()}`,
+    options,
+  }
+}

package/src/client/ssr.tsx

@@ -1,25 +1,27 @@
-import React from "react";
-import ReactDOMServer from "react-dom/server";
-import { StaticRouter } from "react-router-dom/server";
-import { AppShell } from "./app";
-import { ComponentRoute } from "./types";
+import React from 'react'
+import ReactDOMServer from 'react-dom/server'
+import { StaticRouter } from 'react-router-dom/server'
+import { AppShell } from './app'
+import type { ComponentRoute } from './types'
 
 /**
  * Options for rendering the Boltdocs application on the server (SSG).
  */
 export interface RenderOptions {
   /** The URL path currently being rendered */
-  path: string;
+  path: string
   /** Initial routes generated by the Vite plugin (`virtual:boltdocs-routes`) */
-  routes: ComponentRoute[];
+  routes: ComponentRoute[]
   /** Site configuration (`virtual:boltdocs-config`) */
-  config: any;
+  config: any
   /** The name of the documentation directory (e.g. 'docs') */
-  docsDirName: string;
+  docsDirName: string
   /** Optional custom React component to render when visiting the root path ('/') */
-  homePage?: React.ComponentType;
+  homePage?: React.ComponentType
+  /** Custom external pages mapped by their route path */
+  externalPages?: Record<string, React.ComponentType<any>>
   /** Preloaded modules (since SSR cannot use dynamic imports easily) */
-  modules: Record<string, any>;
+  modules: Record<string, any>
 }
 
 /**
@@ -27,13 +29,21 @@ export interface RenderOptions {
  * This is called by the Node SSG script during the Vite build process.
  */
 export async function render(options: RenderOptions): Promise<string> {
-  const { path, routes, config, modules, homePage, docsDirName } = options;
+  const {
+    path,
+    routes,
+    config,
+    modules,
+    homePage,
+    externalPages,
+    docsDirName,
+  } = options
 
   // For SSR, we must resolve modules synchronously. We create a mock 'loader'
   // that instantly returns the module since the SSG script already loaded it.
-  const resolvedModules: Record<string, () => Promise<any>> = {};
+  const resolvedModules: Record<string, () => Promise<any>> = {}
   for (const [key, mod] of Object.entries(modules)) {
-    resolvedModules[key] = () => Promise.resolve(mod);
+    resolvedModules[key] = () => Promise.resolve(mod)
   }
 
   const html = ReactDOMServer.renderToString(
@@ -45,10 +55,11 @@ export async function render(options: RenderOptions): Promise<string> {
           docsDirName={docsDirName}
           modules={resolvedModules}
           homePage={homePage}
+          externalPages={externalPages}
         />
       </StaticRouter>
     </React.StrictMode>,
-  );
+  )
 
-  return html;
+  return html
 }