boltdocs 1.6.0 → 1.7.0

package/src/client/theme/ui/Navbar/navbar.css

@@ -3,19 +3,25 @@
    ═══════════════════════════════════════════════════════════ */
 .boltdocs-navbar {
   display: flex;
-  align-items: center;
+  flex-direction: column;
   justify-content: center;
-  height: var(--ld-navbar-height);
-  padding: 0; /* Padding moved to container */
   background-color: var(--ld-navbar-bg);
-  backdrop-filter: blur(var(--ld-navbar-blur));
-  -webkit-backdrop-filter: blur(var(--ld-navbar-blur));
   border-bottom: 1px solid var(--ld-border-subtle);
   position: sticky;
   top: 0;
   z-index: 100;
 }
 
+.boltdocs-navbar.has-tabs {
+  --ld-header-height: 102px !important;
+  height: 102px;
+}
+
+.boltdocs-navbar:not(.has-tabs) {
+  --ld-header-height: var(--ld-navbar-height);
+  height: var(--ld-navbar-height);
+}
+
 .navbar-container {
   display: flex;
   align-items: center;
@@ -114,6 +120,16 @@
   transition:
     color 0.2s,
     background-color 0.2s;
+  display: flex;
+  align-items: center;
+  gap: 0.35rem;
+}
+
+.navbar-external-icon {
+  display: inline-flex;
+  align-items: center;
+  opacity: 0.6;
+  margin-top: 1px;
 }
 
 .navbar-links a:hover {
@@ -231,3 +247,93 @@
   width: 18px;
   height: 18px;
 }
+
+/* Tabs Styles */
+.boltdocs-tabs-container {
+  border-bottom: 1px solid var(--ld-border-subtle);
+  background: var(--ld-navbar-bg);
+  padding: 0;
+  height: 46px; /* 102px total = 56px navbar + 46px tabs */
+}
+
+.boltdocs-tabs {
+  max-width: 1440px;
+  margin: 0 auto;
+  display: flex;
+  gap: 2rem;
+  overflow-x: auto;
+  scrollbar-width: none;
+  padding: 0 1.5rem;
+}
+
+.boltdocs-tabs::-webkit-scrollbar {
+  display: none;
+}
+
+.boltdocs-tab-item {
+  padding: 0.85rem 0;
+  padding-bottom: calc(0.85rem + 1px); /* avoid clipping the indicator */
+  font-size: 0.875rem;
+  font-weight: 500;
+  color: var(--ld-text-muted);
+  text-decoration: none;
+  position: relative;
+  transition: all 0.25s cubic-bezier(0.4, 0, 0.2, 1);
+  white-space: nowrap;
+  display: flex;
+  align-items: center;
+  gap: 0.6rem;
+  opacity: 0.7;
+}
+
+.boltdocs-tab-item:hover {
+  color: var(--ld-text-main);
+  opacity: 1;
+}
+
+.tab-icon {
+  flex-shrink: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  transition: transform 0.2s ease;
+}
+
+.boltdocs-tab-item:hover .tab-icon {
+  transform: translateY(-1px);
+}
+
+.tab-icon.lucide-icon,
+.tab-icon.svg-icon svg {
+  width: 18px;
+  height: 18px;
+  stroke-width: 2.25px;
+}
+
+.boltdocs-tab-item.active {
+  color: var(--ld-text-main);
+  font-weight: 600;
+  opacity: 1;
+  text-shadow: 0 0 10px rgba(255, 255, 255, 0.2);
+}
+
+.boltdocs-tab-item::after {
+  content: "";
+  position: absolute;
+  bottom: 0px;
+  left: 0;
+  right: 0;
+  height: 3px;
+  background: var(--ld-primary);
+  border-radius: 2px 2px 0 0;
+  box-shadow: 0 0 12px rgba(var(--ld-primary-rgb), 0.6);
+  opacity: 0;
+  transform: scaleX(0);
+  transition: all 0.35s cubic-bezier(0.4, 0, 0.2, 1);
+  z-index: 10;
+}
+
+.boltdocs-tab-item.active::after {
+  opacity: 1;
+  transform: scaleX(1);
+}

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

@@ -1,6 +1,6 @@
 import React, { useEffect, useState, useRef, useCallback } from "react";
 import { useLocation } from "react-router-dom";
-import { Pencil, CircleHelp } from "lucide-react";
+import { Pencil, CircleHelp, TextAlignStart } from "lucide-react";
 
 interface TocHeading {
   id: string;
@@ -19,16 +19,16 @@ export function OnThisPage({
   communityHelp?: string;
   filePath?: string;
 }) {
-  const [activeId, setActiveId] = useState<string>("");
+  const [activeId, setActiveId] = useState<string | null>(null);
   const [indicatorStyle, setIndicatorStyle] = useState<React.CSSProperties>({});
   const observerRef = useRef<IntersectionObserver | null>(null);
   const location = useLocation();
   const listRef = useRef<HTMLUListElement>(null);
+  const visibleIdsRef = useRef<Set<string>>(new Set());
 
   // Reset active ID when path changes
   useEffect(() => {
     if (headings.length > 0) {
-      // Check if there's a hash in the URL
       const hash = window.location.hash.substring(1);
       if (hash && headings.some((h) => h.id === hash)) {
         setActiveId(hash);
@@ -38,19 +38,21 @@ export function OnThisPage({
     }
   }, [location.pathname, headings]);
 
-  // Update indicator position
+  // Update indicator position for the single active ID
   useEffect(() => {
     if (!activeId || !listRef.current) return;
 
-    const activeElement = listRef.current.querySelector(
+    const activeLink = listRef.current.querySelector(
       `a[href="#${activeId}"]`,
     ) as HTMLElement;
 
-    if (activeElement) {
-      const { offsetTop, offsetHeight } = activeElement;
+    if (activeLink) {
+      const top = activeLink.offsetTop;
+      const height = activeLink.offsetHeight;
+
       setIndicatorStyle({
-        transform: `translateY(${offsetTop}px)`,
-        height: `${offsetHeight}px`,
+        transform: `translateY(${top}px)`,
+        height: `${height}px`,
         opacity: 1,
       });
     }
@@ -60,30 +62,49 @@ export function OnThisPage({
   useEffect(() => {
     if (headings.length === 0) return;
 
+    // Reset visible tracking on re-run
+    visibleIdsRef.current.clear();
+
     if (observerRef.current) {
       observerRef.current.disconnect();
     }
 
     const callback: IntersectionObserverCallback = (entries) => {
-      // Find all entries that are intersecting
-      const visibleEntries = entries.filter((entry) => entry.isIntersecting);
-
-      if (visibleEntries.length > 0) {
-        // If we have visible entries, find the one closest to the top of the viewport
-        const closest = visibleEntries.reduce((prev, curr) => {
-          return Math.abs(curr.boundingClientRect.top - 100) <
-            Math.abs(prev.boundingClientRect.top - 100)
-            ? curr
-            : prev;
-        });
-        setActiveId(closest.target.id);
+      entries.forEach((entry) => {
+        if (entry.isIntersecting) {
+          visibleIdsRef.current.add(entry.target.id);
+        } else {
+          visibleIdsRef.current.delete(entry.target.id);
+        }
+      });
+
+      // Selection logic: first visible heading in document order
+      const firstVisible = headings.find((h) => visibleIdsRef.current.has(h.id));
+
+      if (firstVisible) {
+        setActiveId(firstVisible.id);
+      } else {
+        // Fallback: If nothing is visible, determine if we are at the top or bottom
+        const firstEl = document.getElementById(headings[0].id);
+        if (firstEl) {
+          const rect = firstEl.getBoundingClientRect();
+          if (rect.top > 200) {
+            setActiveId(headings[0].id);
+            return;
+          }
+        }
+        
+        // If we are deep in the doc, don't change it (keep previous)
       }
     };
 
-    observerRef.current = new IntersectionObserver(callback, {
-      rootMargin: "-100px 0px -70% 0px",
+    const observerOptions: IntersectionObserverInit = {
+      root: document.querySelector(".boltdocs-content"),
+      rootMargin: "-20% 0px -70% 0px",
       threshold: [0, 1],
-    });
+    };
+
+    observerRef.current = new IntersectionObserver(callback, observerOptions);
 
     const observeHeadings = () => {
       headings.forEach(({ id }) => {
@@ -94,18 +115,13 @@ export function OnThisPage({
       });
     };
 
-    // Initial observation
     observeHeadings();
-
-    // 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);
       }
@@ -120,7 +136,7 @@ export function OnThisPage({
     };
   }, [headings, location.pathname]);
 
-  // Autoscroll TOC list when activeId changes
+  // Autoscroll TOC list when the activeId changes
   useEffect(() => {
     if (!activeId || !listRef.current) return;
 
@@ -129,9 +145,7 @@ export function OnThisPage({
     ) as HTMLElement;
 
     if (activeLink) {
-      const container = listRef.current.closest(
-        ".boltdocs-on-this-page",
-      ) as HTMLElement;
+      const container = listRef.current.parentElement as HTMLElement;
       if (!container) return;
 
       const linkRect = activeLink.getBoundingClientRect();
@@ -143,7 +157,7 @@ export function OnThisPage({
 
       if (!isVisible) {
         activeLink.scrollIntoView({
-          behavior: "smooth",
+          behavior: "auto",
           block: "nearest",
         });
       }
@@ -179,21 +193,23 @@ export function OnThisPage({
     <nav className="boltdocs-on-this-page" aria-label="Table of contents">
       <p className="on-this-page-title">On this page</p>
       <div className="on-this-page-container">
-        <div className="toc-indicator" style={indicatorStyle} />
-        <ul className="on-this-page-list" ref={listRef}>
-          {headings.map((h) => (
-            <li key={h.id} className={h.level === 3 ? "toc-indent" : ""}>
-              <a
-                href={`#${h.id}`}
-                className={`toc-link ${activeId === h.id ? "active" : ""}`}
-                aria-current={activeId === h.id ? "true" : undefined}
-                onClick={(e) => handleClick(e, h.id)}
-              >
-                {h.text}
-              </a>
-            </li>
-          ))}
-        </ul>
+        <div className="on-this-page-list-container">
+          <div className="toc-indicator" style={indicatorStyle} />
+          <ul className="on-this-page-list" ref={listRef}>
+            {headings.map((h) => (
+              <li key={h.id} className={h.level === 3 ? "toc-indent" : ""}>
+                <a
+                  href={`#${h.id}`}
+                  className={`toc-link ${activeId === h.id ? "active" : ""}`}
+                  aria-current={activeId === h.id ? "true" : undefined}
+                  onClick={(e) => handleClick(e, h.id)}
+                >
+                  {h.text}
+                </a>
+              </li>
+            ))}
+          </ul>
+        </div>
       </div>
 
       {/* Need help? section */}

package/src/client/theme/ui/OnThisPage/toc.css

@@ -5,12 +5,12 @@
   width: var(--ld-toc-width);
   flex-shrink: 0;
   padding: 1.5rem 1rem;
-  position: sticky;
-  top: var(--ld-navbar-height);
-  height: calc(100vh - var(--ld-navbar-height));
-  overflow-y: auto;
-  scrollbar-width: thin;
-  scrollbar-color: var(--ld-bg-mute) transparent;
+  height: 100%;
+  display: flex;
+  flex-direction: column;
+  /* Hardware acceleration */
+  transform: translate3d(0, 0, 0);
+  backface-visibility: hidden;
 }
 
 .on-this-page-title {
@@ -21,11 +21,28 @@
   color: var(--ld-text-dim);
   margin: 0 0 0.75rem;
   padding-left: 0.75rem;
+  flex-shrink: 0;
 }
 
 .on-this-page-container {
   position: relative;
   padding-left: 2px;
+  flex: 0 1 auto;
+  min-height: 0; /* Important for children overflow */
+  display: flex;
+  flex-direction: column;
+}
+
+.on-this-page-list-container {
+  overflow-y: auto;
+  max-height: 50vh; /* Constrain height for large docs */
+  flex: 0 1 auto;
+  position: relative;
+  scrollbar-width: none;
+}
+
+.on-this-page-list-container::-webkit-scrollbar {
+  display: none;
 }
 
 .on-this-page-list {
@@ -67,7 +84,9 @@
   border-left: 2px solid transparent;
   margin-left: -2px;
   line-height: 1.4;
-  transition: color 0.2s;
+  transition:
+    color 0.2s,
+    font-weight 0.2s;
 }
 
 .toc-link:hover {
@@ -81,9 +100,10 @@
 
 /* ─── Need Help Section ──────────────────────────────────── */
 .toc-help {
-  margin-top: 2rem;
+  margin-top: 1.5rem;
   padding-top: 1rem;
   border-top: 1px solid var(--ld-border-subtle);
+  flex-shrink: 0;
 }
 
 .toc-help-title {
@@ -121,8 +141,8 @@
 }
 
 .toc-help-link:hover {
-  color: var(--ld-text-muted);
-  background-color: rgba(255, 255, 255, 0.03);
+  color: var(--ld-text-main);
+  background-color: var(--ld-bg-mute);
 }
 
 .toc-help-link svg {

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

@@ -1,9 +1,10 @@
-import React, { useState } from "react";
+import { useState } from "react";
 import { useLocation } from "react-router-dom";
 import { Link } from "../Link";
 import { BoltdocsConfig } from "../../../../node/config";
 import { PoweredBy } from "../PoweredBy";
-import { ChevronRight, ChevronLeft, PanelLeft } from "lucide-react";
+import { ChevronRight } from "lucide-react";
+import * as LucideIcons from "lucide-react";
 
 interface RouteItem {
   path: string;
@@ -12,12 +13,16 @@ interface RouteItem {
   groupTitle?: string;
   sidebarPosition?: number;
   badge?: string | { text: string; expires?: string };
+  icon?: string;
+  tab?: string;
+  groupIcon?: string;
 }
 
 interface SidebarGroup {
   slug: string;
   title: string;
   routes: RouteItem[];
+  icon?: string;
 }
 
 /**
@@ -50,8 +55,6 @@ function renderBadge(badgeRaw: RouteItem["badge"]) {
 
   if (!text) return null;
 
-  if (!text) return null;
-
   let typeClass = "badge-default";
   const lowerText = text.toLowerCase();
   if (lowerText === "new") {
@@ -65,6 +68,43 @@ function renderBadge(badgeRaw: RouteItem["badge"]) {
   return <span className={`sidebar-badge ${typeClass}`}>{text}</span>;
 }
 
+/**
+ * Renders an icon from a string (Lucide name or SVG).
+ */
+function renderIcon(iconName?: string, size = 16) {
+  if (!iconName) return null;
+
+  const trimmed = iconName.trim();
+
+  // Check if it's a raw SVG
+  if (trimmed.startsWith("<svg") || trimmed.includes("http")) {
+    if (trimmed.startsWith("<svg")) {
+      return (
+        <span
+          className="sidebar-icon svg-icon"
+          dangerouslySetInnerHTML={{ __html: trimmed }}
+        />
+      );
+    }
+    return (
+      <img
+        src={trimmed}
+        className="sidebar-icon"
+        style={{ width: size, height: size }}
+        alt=""
+      />
+    );
+  }
+
+  // Check if it's a Lucide icon
+  const IconComponent = (LucideIcons as any)[iconName];
+  if (IconComponent) {
+    return <IconComponent size={size} className="sidebar-icon lucide-icon" />;
+  }
+
+  return null;
+}
+
 /**
  * The sidebar navigation component.
  * Groups documentation routes logically based on the `group` property.
@@ -76,20 +116,28 @@ function renderBadge(badgeRaw: RouteItem["badge"]) {
 export function Sidebar({
   routes,
   config,
-  isCollapsed,
-  onToggle,
 }: {
   routes: RouteItem[];
   config: BoltdocsConfig;
-  isCollapsed?: boolean;
-  onToggle?: () => void;
 }) {
   const location = useLocation();
 
+  // Find active tab based on the current route's metadata
+  const currentRoute = routes.find((r) => r.path === location.pathname);
+  const activeTabId = currentRoute?.tab?.toLowerCase();
+
+  // Filter routes by active tab if any tab is active
+  const filteredRoutes = activeTabId
+    ? routes.filter((r) => {
+        if (!r.tab) return true; // Fallback for untabbed routes
+        return r.tab.toLowerCase() === activeTabId;
+      })
+    : routes;
+
   const ungrouped: RouteItem[] = [];
-  const groupMap = new Map<string, SidebarGroup>();
+  const groupMap = new Map<string, SidebarGroup & { icon?: string }>();
 
-  for (const route of routes) {
+  for (const route of filteredRoutes) {
     if (!route.group) {
       ungrouped.push(route);
     } else {
@@ -98,6 +146,7 @@ export function Sidebar({
           slug: route.group,
           title: route.groupTitle || route.group,
           routes: [],
+          icon: (route as any).groupIcon,
         });
       }
       groupMap.get(route.group)!.routes.push(route);
@@ -108,52 +157,38 @@ export function Sidebar({
 
   return (
     <aside className="boltdocs-sidebar">
-      {onToggle && (
-        <div className="sidebar-collapse">
-          <button
-            className="sidebar-collapse-btn"
-            onClick={onToggle}
-            aria-label={isCollapsed ? "Expand Sidebar" : "Collapse Sidebar"}
-            title={isCollapsed ? "Expand Sidebar" : "Collapse Sidebar"}
-          >
-            <PanelLeft size={18} />
-          </button>
-        </div>
-      )}
+      <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">
+                  <div className="sidebar-link-title-container">
+                    {renderIcon((route as any).icon)}
+                    <span>{route.title}</span>
+                  </div>
+                  {renderBadge(route.badge)}
+                </div>
+              </Link>
+            </li>
+          ))}
+        </ul>
 
-      {!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 />}
-        </>
-      )}
+        {groups.map((group) => (
+          <SidebarGroupSection
+            key={group.slug}
+            group={group}
+            currentPath={location.pathname}
+          />
+        ))}
+      </nav>
+      {config.themeConfig?.poweredBy !== false && <PoweredBy />}
     </aside>
   );
 }
@@ -176,7 +211,9 @@ function SidebarGroupSection({
         aria-expanded={open}
         aria-controls={`sidebar-group-${group.slug}`}
       >
-        <span className="sidebar-group-title">{group.title}</span>
+        <div className="sidebar-group-header-content">
+          <span className="sidebar-group-title">{group.title}</span>
+        </div>
         <span className={`sidebar-group-chevron ${open ? "open" : ""}`}>
           <ChevronRight size={16} />
         </span>
@@ -191,7 +228,10 @@ function SidebarGroupSection({
                 aria-current={currentPath === route.path ? "page" : undefined}
               >
                 <div className="sidebar-link-content">
-                  <span>{route.title}</span>
+                  <div className="sidebar-link-title-container">
+                    {renderIcon((route as any).icon)}
+                    <span>{route.title}</span>
+                  </div>
                   {renderBadge(route.badge)}
                 </div>
               </Link>