boltdocs 1.0.1 → 1.3.0

package/src/client/app/index.tsx

@@ -11,6 +11,7 @@ import { ThemeLayout } from "../theme/ui/Layout";
 import { NotFound } from "../theme/ui/NotFound";
 import { Loading } from "../theme/ui/Loading";
 import { MDXProvider } from "@mdx-js/react";
+import { ComponentRoute, CreateBoltdocsAppOptions } from "../types";
 import {
   createContext,
   useContext,
@@ -39,27 +40,6 @@ const PackageManagerTabs = lazy(() =>
     default: m.PackageManagerTabs,
   })),
 );
-const Playground = lazy(() =>
-  import("../theme/components/Playground").then((m) => ({
-    default: m.Playground,
-  })),
-);
-
-import {
-  Button,
-  Badge,
-  Card,
-  Cards,
-  Tabs,
-  Tab,
-  Admonition,
-  Note,
-  Tip,
-  Warning,
-  Danger,
-  InfoBox,
-  List,
-} from "../theme/components/mdx";
 declare global {
   interface ImportMeta {
     env: Record<string, any>;
@@ -114,75 +94,8 @@ const mdxComponents = {
       <PackageManagerTabs {...props} />
     </Suspense>
   ),
-  Playground: (props: any) => (
-    <Suspense fallback={<div className="playground-skeleton" />}>
-      <Playground {...props} />
-    </Suspense>
-  ),
-  Button,
-  Badge,
-  Card,
-  Cards,
-  Tabs,
-  Tab,
-  Admonition,
-  Note,
-  Tip,
-  Warning,
-  Danger,
-  InfoBox,
-  List,
 };
 
-/**
- * Metadata provided by the server for a specific route.
- * Maps closely to the `RouteMeta` type in the Node environment.
- */
-export interface ComponentRoute {
-  /** The final URL path */
-  path: string;
-  /** The absolute filesystem path of the source file */
-  componentPath: string;
-  /** The page title */
-  title: string;
-  /** Explicit order in the sidebar */
-  sidebarPosition?: number;
-  /** The relative path from the docs directory */
-  filePath: string;
-  /** The group directory name */
-  group?: string;
-  /** The display title of the group */
-  groupTitle?: string;
-  /** Explicit order of the group in the sidebar */
-  groupPosition?: number;
-  /** Extracted markdown headings for search indexing */
-  headings?: { level: number; text: string; id: string }[];
-  /** The locale this route belongs to, if i18n is configured */
-  locale?: string;
-  /** The version this route belongs to, if versioning is configured */
-  version?: string;
-}
-
-/**
- * Configuration options for initializing the Boltdocs client app.
- */
-export interface CreateBoltdocsAppOptions {
-  /** CSS selector for the DOM element where the app should mount (e.g. '#root') */
-  target: string;
-  /** Initial routes generated by the Vite plugin (`virtual:boltdocs-routes`) */
-  routes: ComponentRoute[];
-  /** Site configuration (`virtual:boltdocs-config`) */
-  config: any;
-  /** Dynamic import mapping from `import.meta.glob` for the documentation pages */
-  modules: Record<string, () => Promise<any>>;
-  /** The `import.meta.hot` instance necessary for fast refresh/HMR updates */
-  hot?: any;
-  /** Optional custom React component to render when visiting the root path ('/') */
-  homePage?: React.ComponentType;
-  /** Optional custom MDX components provided by plugins */
-  components?: Record<string, React.ComponentType<any>>;
-}
-
 export function AppShell({
   initialRoutes,
   initialConfig,
@@ -200,20 +113,9 @@ export function AppShell({
 }) {
   const [routesInfo, setRoutesInfo] = useState<ComponentRoute[]>(initialRoutes);
   const [config] = useState(initialConfig);
-  const [resolvedRoutes, setResolvedRoutes] = useState<any[]>([]);
-
-  // Subscribe to HMR events
-  useEffect(() => {
-    if (hot) {
-      hot.on("boltdocs:routes-update", (newRoutes: ComponentRoute[]) => {
-        setRoutesInfo(newRoutes);
-      });
-    }
-  }, [hot]);
 
-  // Resolve MDX components
-  useEffect(() => {
-    const mapped = routesInfo
+  const resolveRoutes = (infos: ComponentRoute[]) => {
+    return infos
       .filter(
         (route) => !(HomePage && (route.path === "/" || route.path === "")),
       )
@@ -232,8 +134,24 @@ export function AppShell({
           }),
         };
       });
+  };
+
+  const [resolvedRoutes, setResolvedRoutes] = useState<any[]>(() =>
+    resolveRoutes(initialRoutes),
+  );
+
+  // Subscribe to HMR events
+  useEffect(() => {
+    if (hot) {
+      hot.on("boltdocs:routes-update", (newRoutes: ComponentRoute[]) => {
+        setRoutesInfo(newRoutes);
+      });
+    }
+  }, [hot]);
 
-    setResolvedRoutes(mapped);
+  // Sync resolved routes when info or modules change
+  useEffect(() => {
+    setResolvedRoutes(resolveRoutes(routesInfo));
   }, [routesInfo, modules]);
 
   return (
@@ -261,7 +179,10 @@ export function AppShell({
           )}
 
           {/* Documentation pages WITH sidebar + TOC layout */}
-          <Route element={<DocsLayout config={config} routes={routesInfo} />}>
+          <Route
+            key="docs-layout"
+            element={<DocsLayout config={config} routes={routesInfo} />}
+          >
             {resolvedRoutes.map((route: any) => (
               <Route
                 key={route.path}
@@ -303,6 +224,8 @@ function ScrollHandler() {
   const { pathname, hash } = useLocation();
 
   useLayoutEffect(() => {
+    // Only scroll if we are not in a pending transition state (if we were using useTransition)
+    // For now, we ensure the scroll happens.
     if (hash) {
       const id = hash.replace("#", "");
       const element = document.getElementById(id);
@@ -412,11 +335,10 @@ export function createBoltdocsApp(options: CreateBoltdocsAppOptions) {
     </React.StrictMode>
   );
 
-  // In production (built app), the HTML is pre-rendered by SSG, so we hydrate.
-  // In development, the root is empty, so we createRoot.
-  if (import.meta.env.PROD && container.innerHTML.trim() !== "") {
-    ReactDOM.hydrateRoot(container as HTMLElement, app);
-  } else {
-    ReactDOM.createRoot(container as HTMLElement).render(app);
-  }
+  // SSG pre-renders a shell with mock components for SEO crawlers.
+  // We always use createRoot because the SSG output doesn't match the
+  // real client-side component tree (components are lazy/dynamic).
+  // Clear any SSG placeholder content before mounting.
+  container.innerHTML = "";
+  ReactDOM.createRoot(container as HTMLElement).render(app);
 }

package/src/client/app/preload.tsx

@@ -1,5 +1,5 @@
 import React, { createContext, useContext, useCallback } from "react";
-import { ComponentRoute } from "./index";
+import { ComponentRoute } from "../types";
 
 interface PreloadContextType {
   preload: (path: string) => void;

package/src/client/index.ts

@@ -1,5 +1,5 @@
 export type { BoltdocsConfig, BoltdocsThemeConfig } from "../node/config";
-export type { ComponentRoute, CreateBoltdocsAppOptions } from "./app";
+export type { ComponentRoute, CreateBoltdocsAppOptions } from "./types";
 export { createBoltdocsApp } from "./app";
 export { ThemeLayout } from "./theme/ui/Layout";
 export { Navbar } from "./theme/ui/Navbar";

package/src/client/ssr.tsx

@@ -1,7 +1,8 @@
 import React from "react";
 import ReactDOMServer from "react-dom/server";
 import { StaticRouter } from "react-router-dom/server";
-import { AppShell, ComponentRoute } from "./app";
+import { AppShell } from "./app";
+import { ComponentRoute } from "./types";
 
 /**
  * Options for rendering the Boltdocs application on the server (SSG).

package/src/client/theme/components/Playground/Playground.tsx

@@ -7,17 +7,52 @@ interface PlaygroundProps {
   children?: string | React.ReactNode;
   scope?: Record<string, any>;
   readonly?: boolean;
+  noInline?: boolean;
+}
+
+/**
+ * Transforms code that uses `export default` into a format compatible
+ * with react-live's `noInline` mode by stripping the export and
+ * appending a `render(<ComponentName />)` call.
+ */
+function prepareCode(raw: string): { code: string; noInline: boolean } {
+  const trimmed = raw.trim();
+
+  // Match: export default function Name(...)
+  const fnMatch = trimmed.match(/export\s+default\s+function\s+(\w+)/);
+  if (fnMatch) {
+    const name = fnMatch[1];
+    const code =
+      trimmed.replace(/export\s+default\s+/, "") + `\n\nrender(<${name} />);`;
+    return { code, noInline: true };
+  }
+
+  // Match: export default ComponentName  (at the end)
+  const varMatch = trimmed.match(/export\s+default\s+(\w+)\s*;?\s*$/);
+  if (varMatch) {
+    const name = varMatch[1];
+    const code =
+      trimmed.replace(/export\s+default\s+\w+\s*;?\s*$/, "") +
+      `\nrender(<${name} />);`;
+    return { code, noInline: true };
+  }
+
+  // No export default — use inline mode (simple JSX expression)
+  return { code: trimmed, noInline: false };
 }
 
 /**
  * A live React playground component.
  * Features a split layout with a live editor and a preview section.
+ *
+ * Supports `export default function App()` style code out of the box.
  */
 export function Playground({
   code,
   children,
   scope = {},
   readonly = false,
+  noInline: forceNoInline,
 }: PlaygroundProps) {
   // Extract code from either `code` prop or `children`
   let initialCode = code || "";
@@ -25,8 +60,11 @@ export function Playground({
     initialCode = children;
   }
 
+  const prepared = prepareCode(initialCode);
+  const useNoInline = forceNoInline ?? prepared.noInline;
+
   const [copied, setCopied] = useState(false);
-  const [activeCode, setActiveCode] = useState(initialCode.trim());
+  const [activeCode, setActiveCode] = useState(prepared.code);
 
   const handleCopy = () => {
     navigator.clipboard.writeText(activeCode);
@@ -43,7 +81,7 @@ export function Playground({
         code={activeCode}
         scope={extendedScope}
         theme={undefined}
-        noInline={false}
+        noInline={useNoInline}
       >
         <div className="playground-split-container">
           {/* Editor Side */}

package/src/client/theme/components/mdx/mdx-components.css

@@ -6,54 +6,77 @@
 
 /* ─── Button ──────────────────────────────────────────────── */
 .ld-btn {
+  /* Total Reset */
+  all: unset;
+  box-sizing: border-box !important;
   display: inline-flex;
   align-items: center;
-  gap: 0.4rem;
+  justify-content: center;
+  gap: 0.5rem;
+
+  /* Typography */
+  font-family: var(--ld-font-sans);
   font-weight: 600;
+  font-size: 0.9375rem;
+  line-height: normal; /* Essential for flex centering */
+  letter-spacing: -0.01em;
+  text-align: center;
+  text-decoration: none !important;
+  white-space: nowrap;
+
+  /* Appearance */
   border-radius: var(--ld-radius-md);
   cursor: pointer;
-  transition: all 300ms cubic-bezier(0.16, 1, 0.3, 1);
-  font-family: var(--ld-font-sans);
+  transition: all 250ms cubic-bezier(0.4, 0, 0.2, 1);
   border: 1px solid transparent;
-  line-height: 1;
-  letter-spacing: -0.01em;
+  user-select: none;
+  position: relative;
 }
 
 .ld-btn:hover {
-  transform: scale(1.05);
+  transform: translateY(-1px);
 }
 
 .ld-btn:active {
-  transform: scale(0.95);
+  transform: translateY(0) scale(0.98);
 }
 
 /* sizes */
 .ld-btn--sm {
-  padding: 0.45rem 1.1rem;
+  min-height: 2rem;
+  padding: 0 1rem;
   font-size: 0.8125rem;
   border-radius: var(--ld-radius-md);
 }
 .ld-btn--md {
-  padding: 0.7rem 1.6rem;
+  min-height: 2.625rem;
+  padding: 0 1.6rem;
   font-size: 0.9375rem;
 }
 .ld-btn--lg {
-  padding: 0.85rem 2.1rem;
+  min-height: 3.25rem;
+  padding: 0 2.2rem;
   font-size: 1.05rem;
 }
 
 /* variants */
 .ld-btn--primary {
-  background-color: var(--ld-ui-btn-primary-bg, var(--ld-btn-primary-bg));
+  background-color: var(
+    --ld-ui-btn-primary-bg,
+    var(--ld-btn-primary-bg)
+  ) !important;
   color: var(--ld-ui-btn-primary-text, var(--ld-btn-primary-text)) !important;
+  box-shadow: 0 1px 2px rgba(0, 0, 0, 0.1);
 }
 .ld-btn--primary:hover {
-  opacity: 0.92;
-  color: var(--ld-ui-btn-primary-text, var(--ld-btn-primary-text)) !important;
+  filter: brightness(1.1);
 }
 
 .ld-btn--secondary {
-  background-color: var(--ld-ui-btn-secondary-bg, var(--ld-btn-secondary-bg));
+  background-color: var(
+    --ld-ui-btn-secondary-bg,
+    var(--ld-btn-secondary-bg)
+  ) !important;
   color: var(
     --ld-ui-btn-secondary-text,
     var(--ld-btn-secondary-text)
@@ -63,14 +86,10 @@
 .ld-btn--secondary:hover {
   background-color: var(--ld-bg-mute);
   border-color: var(--ld-border-strong);
-  color: var(
-    --ld-ui-btn-secondary-text,
-    var(--ld-btn-secondary-text)
-  ) !important;
 }
 
 .ld-btn--outline {
-  background: transparent;
+  background: transparent !important;
   color: var(--ld-text-main) !important;
   border-color: var(--ld-border-strong);
 }
@@ -80,7 +99,7 @@
 }
 
 .ld-btn--ghost {
-  background: transparent;
+  background: transparent !important;
   color: var(--ld-text-muted) !important;
 }
 .ld-btn--ghost:hover {

package/src/client/theme/styles/markdown.css

@@ -265,12 +265,12 @@
 }
 
 .code-block-wrapper pre > code {
-  padding: 1.25rem !important;
-  display: block !important;
+  display: grid !important;
+  padding: 1.25rem 1rem !important;
 }
 
 .code-block-wrapper pre > code .line {
-  padding: 0;
+  padding: 0 1.25rem;
 }
 
 /* Default pre (without wrapper) */
@@ -288,7 +288,7 @@
 
 .boltdocs-page pre > code {
   display: grid;
-  padding: 1rem 0;
+  padding: 1rem 1rem;
   background-color: transparent;
   border: none;
   color: inherit;

package/src/client/theme/styles.css

@@ -27,7 +27,6 @@
 @import "./ui/Layout/pagination.css";
 
 /* Pages */
-@import "./styles/home.css";
 @import "./ui/NotFound/not-found.css";
 @import "./ui/Loading/loading.css";
 

package/src/client/theme/ui/Breadcrumbs/Breadcrumbs.tsx

@@ -2,7 +2,7 @@ import React from "react";
 import { useLocation } from "react-router-dom";
 import { Link } from "../Link";
 import { Home, ChevronRight } from "lucide-react";
-import { ComponentRoute } from "../../../app";
+import { ComponentRoute } from "../../../types";
 import { BoltdocsConfig } from "../../../../node/config";
 
 export interface BreadcrumbsProps {

package/src/client/theme/ui/LanguageSwitcher/LanguageSwitcher.tsx

@@ -2,7 +2,7 @@ import React, { useState, useRef, useEffect } from "react";
 import { Globe, ChevronDown } from "lucide-react";
 import { useNavigate, useLocation } from "react-router-dom";
 import { BoltdocsI18nConfig } from "../../../../node/config";
-import { ComponentRoute } from "../../../app";
+import { ComponentRoute } from "../../../types";
 
 function getBaseFilePath(
   filePath: string,

package/src/client/theme/ui/Layout/Layout.tsx

@@ -4,7 +4,7 @@ import { Link } from "../Link";
 import { ChevronLeft, ChevronRight, Menu } from "lucide-react";
 import { usePreload } from "../../../app/preload";
 import { BoltdocsConfig } from "../../../../node/config";
-import { ComponentRoute } from "../../../app";
+import { ComponentRoute } from "../../../types";
 export { Navbar } from "../Navbar";
 export { Sidebar } from "../Sidebar";
 export { OnThisPage } from "../OnThisPage";
@@ -139,22 +139,11 @@ export function ThemeLayout({
           <Sidebar
             routes={filteredRoutes}
             config={config}
-            onCollapse={() => setIsSidebarOpen(false)}
+            isCollapsed={!isSidebarOpen}
+            onToggle={() => setIsSidebarOpen(!isSidebarOpen)}
           />
         )}
 
-        {/* Floating Expand Button when Sidebar is Collapsed */}
-        {sidebar === undefined && (
-          <button
-            className="sidebar-toggle-floating"
-            onClick={() => setIsSidebarOpen(true)}
-            aria-label="Expand Sidebar"
-            title="Expand Sidebar"
-          >
-            <Menu size={20} />
-          </button>
-        )}
-
         <main className="boltdocs-content">
           {breadcrumbs !== undefined ? (
             breadcrumbs

package/src/client/theme/ui/Layout/responsive.css

@@ -12,10 +12,6 @@
     display: none;
   }
 
-  .sidebar-toggle-floating {
-    display: none !important;
-  }
-
   .boltdocs-content {
     padding: 1.5rem 1rem 3rem;
   }

package/src/client/theme/ui/Link/Link.tsx

@@ -5,6 +5,7 @@ import {
   LinkProps as RouterLinkProps,
   NavLinkProps as RouterNavLinkProps,
   useLocation,
+  useNavigate,
 } from "react-router-dom";
 import { usePreload } from "../../../app/preload";
 import { useConfig } from "../../../app";
@@ -107,11 +108,13 @@ export const Link = React.forwardRef<HTMLAnchorElement, LinkProps>(
       boltdocsPrefetch = "hover",
       onMouseEnter,
       onFocus,
+      onClick,
       to,
       ...rest
     } = props;
     const localizedTo = useLocalizedTo(to);
     const { preload } = usePreload();
+    const navigate = useNavigate();
 
     const handleMouseEnter = (e: React.MouseEvent<HTMLAnchorElement>) => {
       onMouseEnter?.(e);
@@ -135,12 +138,38 @@ export const Link = React.forwardRef<HTMLAnchorElement, LinkProps>(
       }
     };
 
+    const handleClick = (e: React.MouseEvent<HTMLAnchorElement>) => {
+      // Allow user onClick to handle defaults or custom logic
+      onClick?.(e);
+
+      // If default prevented or not a simple left click, don't handle
+      if (
+        e.defaultPrevented ||
+        e.button !== 0 ||
+        e.metaKey ||
+        e.ctrlKey ||
+        e.shiftKey ||
+        e.altKey
+      ) {
+        return;
+      }
+
+      // Intercept navigation to wrap in startTransition
+      if (typeof localizedTo === "string" && !localizedTo.startsWith("http")) {
+        e.preventDefault();
+        React.startTransition(() => {
+          navigate(localizedTo);
+        });
+      }
+    };
+
     return (
       <RouterLink
         ref={ref}
         to={localizedTo}
         onMouseEnter={handleMouseEnter}
         onFocus={handleFocus}
+        onClick={handleClick}
         {...rest}
       />
     );
@@ -159,12 +188,14 @@ export const NavLink = React.forwardRef<HTMLAnchorElement, NavLinkProps>(
       boltdocsPrefetch = "hover",
       onMouseEnter,
       onFocus,
+      onClick,
       to,
       ...rest
     } = props;
 
     const localizedTo = useLocalizedTo(to);
     const { preload } = usePreload();
+    const navigate = useNavigate();
 
     const handleMouseEnter = (e: React.MouseEvent<HTMLAnchorElement>) => {
       onMouseEnter?.(e);
@@ -188,12 +219,33 @@ export const NavLink = React.forwardRef<HTMLAnchorElement, NavLinkProps>(
       }
     };
 
+    const handleClick = (e: React.MouseEvent<HTMLAnchorElement>) => {
+      onClick?.(e);
+      if (
+        e.defaultPrevented ||
+        e.button !== 0 ||
+        e.metaKey ||
+        e.ctrlKey ||
+        e.shiftKey ||
+        e.altKey
+      ) {
+        return;
+      }
+      if (typeof localizedTo === "string" && !localizedTo.startsWith("http")) {
+        e.preventDefault();
+        React.startTransition(() => {
+          navigate(localizedTo);
+        });
+      }
+    };
+
     return (
       <RouterNavLink
         ref={ref}
         to={localizedTo}
         onMouseEnter={handleMouseEnter}
         onFocus={handleFocus}
+        onClick={handleClick}
         {...rest}
       />
     );

package/src/client/theme/ui/Navbar/Navbar.tsx

@@ -2,7 +2,7 @@ import React, { useEffect, useState } from "react";
 import { Link } from "../Link";
 import { Book, ChevronDown } from "lucide-react";
 import { BoltdocsConfig } from "../../../../node/config";
-import { ComponentRoute } from "../../../app";
+import { ComponentRoute } from "../../../types";
 import { LanguageSwitcher } from "../LanguageSwitcher";
 import { VersionSwitcher } from "../VersionSwitcher";
 import { ThemeToggle } from "../ThemeToggle";

package/src/client/theme/ui/NotFound/NotFound.tsx

@@ -1,4 +1,3 @@
-import React from "react";
 import { Link } from "../Link";
 import { ArrowLeft } from "lucide-react";