boltdocs 1.0.1 → 1.3.0

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

@@ -70,7 +70,6 @@ export function OnThisPage({
 
       if (visibleEntries.length > 0) {
         // If we have visible entries, find the one closest to the top of the viewport
-        // But with a priority for ones that just entered from the top
         const closest = visibleEntries.reduce((prev, curr) => {
           return Math.abs(curr.boundingClientRect.top - 100) <
             Math.abs(prev.boundingClientRect.top - 100)
@@ -98,15 +97,59 @@ export function OnThisPage({
     // Initial observation
     observeHeadings();
 
-    // Re-observe if content changes (e.g. after some delay to ensure rendering)
+    // Re-observe if content changes
     const timeoutId = setTimeout(observeHeadings, 1000);
 
+    // Scroll listener to detect bottom of page
+    const handleScroll = () => {
+      const scrollPosition = window.innerHeight + window.pageYOffset;
+      const bodyHeight = document.documentElement.scrollHeight;
+
+      // If we're within 50px of the bottom, activate the last heading
+      if (scrollPosition >= bodyHeight - 50) {
+        setActiveId(headings[headings.length - 1].id);
+      }
+    };
+
+    window.addEventListener("scroll", handleScroll, { passive: true });
+
     return () => {
       observerRef.current?.disconnect();
       clearTimeout(timeoutId);
+      window.removeEventListener("scroll", handleScroll);
     };
   }, [headings, location.pathname]);
 
+  // Autoscroll TOC list when activeId changes
+  useEffect(() => {
+    if (!activeId || !listRef.current) return;
+
+    const activeLink = listRef.current.querySelector(
+      `a[href="#${activeId}"]`,
+    ) as HTMLElement;
+
+    if (activeLink) {
+      const container = listRef.current.closest(
+        ".boltdocs-on-this-page",
+      ) as HTMLElement;
+      if (!container) return;
+
+      const linkRect = activeLink.getBoundingClientRect();
+      const containerRect = container.getBoundingClientRect();
+
+      const isVisible =
+        linkRect.top >= containerRect.top &&
+        linkRect.bottom <= containerRect.bottom;
+
+      if (!isVisible) {
+        activeLink.scrollIntoView({
+          behavior: "smooth",
+          block: "nearest",
+        });
+      }
+    }
+  }, [activeId]);
+
   const handleClick = useCallback(
     (e: React.MouseEvent<HTMLAnchorElement>, id: string) => {
       e.preventDefault();

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

@@ -2,7 +2,7 @@ import React, { useState, useEffect, useRef } from "react";
 import { createPortal } from "react-dom";
 import { Link } from "../Link";
 import { Search } from "lucide-react";
-import { ComponentRoute } from "../../../app";
+import { ComponentRoute } from "../../../types";
 
 interface SearchResult {
   title: string;

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

@@ -3,7 +3,7 @@ import { useLocation } from "react-router-dom";
 import { Link } from "../Link";
 import { BoltdocsConfig } from "../../../../node/config";
 import { PoweredBy } from "../PoweredBy";
-import { ChevronRight, ChevronLeft } from "lucide-react";
+import { ChevronRight, ChevronLeft, PanelLeft } from "lucide-react";
 
 interface RouteItem {
   path: string;
@@ -76,11 +76,13 @@ function renderBadge(badgeRaw: RouteItem["badge"]) {
 export function Sidebar({
   routes,
   config,
-  onCollapse,
+  isCollapsed,
+  onToggle,
 }: {
   routes: RouteItem[];
   config: BoltdocsConfig;
-  onCollapse?: () => void;
+  isCollapsed?: boolean;
+  onToggle?: () => void;
 }) {
   const location = useLocation();
 
@@ -106,50 +108,52 @@ export function Sidebar({
 
   return (
     <aside className="boltdocs-sidebar">
-      <nav aria-label="Main Navigation">
-        <ul className="sidebar-list">
-          {ungrouped.map((route) => (
-            <li key={route.path}>
-              <Link
-                to={route.path === "" ? "/" : route.path}
-                className={`sidebar-link ${location.pathname === route.path ? "active" : ""}`}
-                aria-current={
-                  location.pathname === route.path ? "page" : undefined
-                }
-              >
-                <div className="sidebar-link-content">
-                  <span>{route.title}</span>
-                  {renderBadge(route.badge)}
-                </div>
-              </Link>
-            </li>
-          ))}
-        </ul>
-
-        {groups.map((group) => (
-          <SidebarGroupSection
-            key={group.slug}
-            group={group}
-            currentPath={location.pathname}
-          />
-        ))}
-      </nav>
-
-      {onCollapse && (
-        <div className="sidebar-footer">
+      {onToggle && (
+        <div className="sidebar-collapse">
           <button
             className="sidebar-collapse-btn"
-            onClick={onCollapse}
-            aria-label="Collapse Sidebar"
-            title="Collapse Sidebar"
+            onClick={onToggle}
+            aria-label={isCollapsed ? "Expand Sidebar" : "Collapse Sidebar"}
+            title={isCollapsed ? "Expand Sidebar" : "Collapse Sidebar"}
           >
-            <ChevronLeft size={16} />
-            <span>Collapse Sidebar</span>
+            <PanelLeft size={18} />
           </button>
         </div>
       )}
 
-      {config.themeConfig?.poweredBy !== false && <PoweredBy />}
+      {!isCollapsed && (
+        <>
+          <nav aria-label="Main Navigation">
+            <ul className="sidebar-list">
+              {ungrouped.map((route) => (
+                <li key={route.path}>
+                  <Link
+                    to={route.path === "" ? "/" : route.path}
+                    className={`sidebar-link ${location.pathname === route.path ? "active" : ""}`}
+                    aria-current={
+                      location.pathname === route.path ? "page" : undefined
+                    }
+                  >
+                    <div className="sidebar-link-content">
+                      <span>{route.title}</span>
+                      {renderBadge(route.badge)}
+                    </div>
+                  </Link>
+                </li>
+              ))}
+            </ul>
+
+            {groups.map((group) => (
+              <SidebarGroupSection
+                key={group.slug}
+                group={group}
+                currentPath={location.pathname}
+              />
+            ))}
+          </nav>
+          {config.themeConfig?.poweredBy !== false && <PoweredBy />}
+        </>
+      )}
     </aside>
   );
 }

package/src/client/theme/ui/Sidebar/sidebar.css

@@ -29,80 +29,47 @@
 
 /* ─── Collapsible Sidebar ────────────────────────────────── */
 .boltdocs-main-container.sidebar-collapsed .boltdocs-sidebar {
-  width: 0;
-  padding-left: 0;
-  padding-right: 0;
-  border-right-color: transparent;
-  opacity: 0;
-  pointer-events: none;
+  width: 54px;
+  padding: 1rem 0;
+  border-right: 1px solid var(--ld-border-subtle);
+  opacity: 1;
+  pointer-events: auto;
   overflow: hidden;
 }
 
-.sidebar-toggle-floating {
-  position: fixed;
-  bottom: 2rem;
-  left: 2rem;
-  width: 2.75rem;
-  height: 2.75rem;
-  border-radius: 50%;
-  background-color: var(--ld-surface);
-  border: 1px solid var(--ld-border-strong);
-  color: var(--ld-text-muted);
+.sidebar-collapse {
+  width: 100%;
   display: flex;
   align-items: center;
-  justify-content: center;
-  cursor: pointer;
-  z-index: 100;
-  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.1);
-  transition: all 0.3s cubic-bezier(0.16, 1, 0.3, 1);
-  opacity: 0;
-  pointer-events: none;
-  transform: translateY(20px) scale(0.9);
+  justify-content: flex-end;
+  padding: 0 0.75rem 1rem;
+  transition: justify-content 0.3s ease;
 }
 
-.sidebar-toggle-floating:hover {
-  background-color: var(--ld-bg-soft);
-  color: var(--ld-text-main);
-  transform: translateY(0px) scale(1.05);
-  border-color: var(--ld-color-primary);
-}
-
-.sidebar-toggle-floating:active {
-  transform: translateY(0px) scale(0.95);
-}
-
-.boltdocs-main-container.sidebar-collapsed .sidebar-toggle-floating {
-  opacity: 1;
-  pointer-events: auto;
-  transform: translateY(0) scale(1);
-}
-
-.sidebar-footer {
-  margin-top: 2rem;
-  padding-top: 1rem;
-  border-top: 1px solid var(--ld-border-subtle);
+.boltdocs-main-container.sidebar-collapsed .sidebar-collapse {
+  justify-content: center;
+  padding: 0 0 1rem;
 }
 
 .sidebar-collapse-btn {
+  color: var(--ld-text-muted);
+  border: none;
+  box-shadow: none;
+  background-color: transparent;
+  cursor: pointer;
   display: flex;
   align-items: center;
-  gap: 0.5rem;
-  width: 100%;
-  padding: 0.5rem 0.75rem;
-  background: none;
-  border: none;
+  justify-content: center;
+  width: 32px;
+  height: 32px;
   border-radius: var(--ld-radius-md);
-  color: var(--ld-text-muted);
-  font-family: var(--ld-font-sans);
-  font-size: 0.8125rem;
-  font-weight: 500;
-  cursor: pointer;
-  transition: all 0.2s ease;
+  transition: all 0.2s cubic-bezier(0.16, 1, 0.3, 1);
 }
 
 .sidebar-collapse-btn:hover {
-  background-color: var(--ld-bg-soft);
-  color: var(--ld-color-primary);
+  background-color: var(--ld-bg-mute);
+  color: var(--ld-text-main);
+  transform: scale(1.05);
 }
 
 .boltdocs-sidebar::-webkit-scrollbar {

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

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

package/src/client/types.ts

@@ -0,0 +1,50 @@
+import React from "react";
+
+/**
+ * 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>>;
+}