boltdocs 1.0.0

package/src/client/theme/ui/SearchDialog/search.css

@@ -0,0 +1,152 @@
+/* ═══════════════════════════════════════════════════════════
+   SEARCH MODAL
+   ═══════════════════════════════════════════════════════════ */
+.boltdocs-search-overlay {
+  position: fixed;
+  top: 0;
+  left: 0;
+  right: 0;
+  bottom: 0;
+  background-color: rgba(0, 0, 0, 0.6);
+  backdrop-filter: blur(4px);
+  -webkit-backdrop-filter: blur(4px);
+  z-index: 999;
+  display: flex;
+  justify-content: center;
+  align-items: flex-start;
+  padding-top: 10vh;
+}
+
+.boltdocs-search-modal {
+  width: 100%;
+  max-width: 560px;
+  background-color: var(--ld-bg-main);
+  border: 1px solid var(--ld-border-subtle);
+  border-radius: var(--ld-radius-lg);
+  box-shadow: 0 16px 64px rgba(0, 0, 0, 0.4);
+  overflow: hidden;
+  display: flex;
+  flex-direction: column;
+  animation: boltdocs-search-appear 0.15s ease-out forwards;
+}
+
+@keyframes boltdocs-search-appear {
+  from {
+    opacity: 0;
+    transform: scale(0.96) translateY(-10px);
+  }
+  to {
+    opacity: 1;
+    transform: scale(1) translateY(0);
+  }
+}
+
+.boltdocs-search-header {
+  display: flex;
+  align-items: center;
+  padding: 1rem 1.25rem;
+  border-bottom: 1px solid transparent; /* Seamless header */
+  background-color: transparent;
+  gap: 0.75rem;
+}
+
+.boltdocs-search-header svg {
+  width: 18px;
+  height: 18px;
+  color: var(--ld-color-primary);
+  opacity: 0.8;
+}
+
+.boltdocs-search-header input {
+  flex: 1;
+  background: transparent;
+  border: none;
+  color: var(--ld-text-main);
+  font-size: 1.05rem;
+  font-weight: 500;
+  font-family: var(--ld-font-sans);
+  outline: none;
+  box-shadow: none;
+}
+
+.boltdocs-search-header input::placeholder {
+  color: var(--ld-text-dim);
+}
+
+.boltdocs-search-close {
+  background: var(--ld-bg-mute);
+  border: 1px solid var(--ld-border-subtle);
+  color: var(--ld-text-dim);
+  font-size: 0.6875rem;
+  padding: 0.2rem 0.4rem;
+  border-radius: 4px;
+  cursor: pointer;
+  font-family: var(--ld-font-sans);
+  transition: all 0.2s;
+}
+
+.boltdocs-search-close:hover {
+  background: var(--ld-border-strong);
+  color: var(--ld-text-main);
+}
+
+.boltdocs-search-results {
+  max-height: 50vh;
+  overflow-y: auto;
+  padding: 0.5rem;
+}
+
+.boltdocs-search-results::-webkit-scrollbar {
+  width: 6px;
+}
+.boltdocs-search-results::-webkit-scrollbar-thumb {
+  background: var(--ld-bg-mute);
+  border-radius: 4px;
+}
+
+.boltdocs-search-result-item {
+  display: flex;
+  flex-direction: column;
+  padding: 0.75rem 1rem;
+  border-radius: var(--ld-radius-md);
+  text-decoration: none;
+  transition: background-color 0.15s;
+  margin-bottom: 2px;
+}
+
+.boltdocs-search-result-item.is-heading {
+  padding-left: 2rem;
+  border-left: 2px solid transparent;
+}
+
+.heading-indicator {
+  color: var(--ld-text-muted);
+  font-weight: 500;
+  margin-right: 0.35rem;
+  font-family: var(--ld-font-mono);
+}
+
+.boltdocs-search-result-item:hover,
+.boltdocs-search-result-item:focus {
+  background-color: var(--ld-bg-mute);
+  outline: none;
+}
+
+.boltdocs-search-result-title {
+  color: var(--ld-text-main);
+  font-weight: 500;
+  font-size: 0.95rem;
+}
+
+.boltdocs-search-result-group {
+  color: var(--ld-text-muted);
+  font-size: 0.75rem;
+  margin-top: 0.15rem;
+}
+
+.boltdocs-search-empty {
+  padding: 2rem;
+  text-align: center;
+  color: var(--ld-text-dim);
+  font-size: 0.9rem;
+}

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

@@ -0,0 +1,200 @@
+import React, { 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 } from "lucide-react";
+
+interface RouteItem {
+  path: string;
+  title: string;
+  group?: string;
+  groupTitle?: string;
+  sidebarPosition?: number;
+  badge?: string | { text: string; expires?: string };
+}
+
+interface SidebarGroup {
+  slug: string;
+  title: string;
+  routes: RouteItem[];
+}
+
+/**
+ * Renders a small badge next to sidebar items if one exists and hasn't expired.
+ */
+function renderBadge(badgeRaw: RouteItem["badge"]) {
+  if (!badgeRaw) return null;
+
+  let text = "";
+  let expires = "";
+
+  if (typeof badgeRaw === "string") {
+    text = badgeRaw;
+  } else {
+    text = badgeRaw.text;
+    expires = badgeRaw.expires || "";
+  }
+
+  // Check expiration
+  if (expires) {
+    const expireDate = new Date(expires);
+    const now = new Date();
+    // Reset time components for accurate day comparison
+    expireDate.setHours(0, 0, 0, 0);
+    now.setHours(0, 0, 0, 0);
+    if (now > expireDate) {
+      return null;
+    }
+  }
+
+  if (!text) return null;
+
+  if (!text) return null;
+
+  let typeClass = "badge-default";
+  const lowerText = text.toLowerCase();
+  if (lowerText === "new") {
+    typeClass = "badge-new";
+  } else if (lowerText === "experimental") {
+    typeClass = "badge-experimental";
+  } else if (lowerText === "updated") {
+    typeClass = "badge-updated";
+  }
+
+  return <span className={`sidebar-badge ${typeClass}`}>{text}</span>;
+}
+
+/**
+ * The sidebar navigation component.
+ * Groups documentation routes logically based on the `group` property.
+ * Highlights the active link based on the current URL path.
+ *
+ * @param routes - Array of all generated routes to be displayed
+ * @param config - Global configuration (which can contain sidebar overrides)
+ */
+export function Sidebar({
+  routes,
+  config,
+  onCollapse,
+}: {
+  routes: RouteItem[];
+  config: BoltdocsConfig;
+  onCollapse?: () => void;
+}) {
+  const location = useLocation();
+
+  const ungrouped: RouteItem[] = [];
+  const groupMap = new Map<string, SidebarGroup>();
+
+  for (const route of routes) {
+    if (!route.group) {
+      ungrouped.push(route);
+    } else {
+      if (!groupMap.has(route.group)) {
+        groupMap.set(route.group, {
+          slug: route.group,
+          title: route.groupTitle || route.group,
+          routes: [],
+        });
+      }
+      groupMap.get(route.group)!.routes.push(route);
+    }
+  }
+
+  const groups = Array.from(groupMap.values());
+
+  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">
+          <button
+            className="sidebar-collapse-btn"
+            onClick={onCollapse}
+            aria-label="Collapse Sidebar"
+            title="Collapse Sidebar"
+          >
+            <ChevronLeft size={16} />
+            <span>Collapse Sidebar</span>
+          </button>
+        </div>
+      )}
+
+      {config.themeConfig?.poweredBy !== false && <PoweredBy />}
+    </aside>
+  );
+}
+
+function SidebarGroupSection({
+  group,
+  currentPath,
+}: {
+  group: SidebarGroup;
+  currentPath: string;
+}) {
+  const isActive = group.routes.some((r) => currentPath === r.path);
+  const [open, setOpen] = useState(true);
+
+  return (
+    <div className="sidebar-group">
+      <button
+        className={`sidebar-group-header ${isActive ? "active" : ""}`}
+        onClick={() => setOpen(!open)}
+        aria-expanded={open}
+        aria-controls={`sidebar-group-${group.slug}`}
+      >
+        <span className="sidebar-group-title">{group.title}</span>
+        <span className={`sidebar-group-chevron ${open ? "open" : ""}`}>
+          <ChevronRight size={16} />
+        </span>
+      </button>
+      {open && (
+        <ul className="sidebar-group-list" id={`sidebar-group-${group.slug}`}>
+          {group.routes.map((route) => (
+            <li key={route.path}>
+              <Link
+                to={route.path === "" ? "/" : route.path}
+                className={`sidebar-link sidebar-link-nested ${currentPath === route.path ? "active" : ""}`}
+                aria-current={currentPath === route.path ? "page" : undefined}
+              >
+                <div className="sidebar-link-content">
+                  <span>{route.title}</span>
+                  {renderBadge(route.badge)}
+                </div>
+              </Link>
+            </li>
+          ))}
+        </ul>
+      )}
+    </div>
+  );
+}

package/src/client/theme/ui/Sidebar/index.ts

@@ -0,0 +1 @@
+export { Sidebar } from "./Sidebar";

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

@@ -0,0 +1,269 @@
+/* ═══════════════════════════════════════════════════════════
+   SIDEBAR
+   ═══════════════════════════════════════════════════════════ */
+.boltdocs-sidebar {
+  width: var(--ld-sidebar-width);
+  flex-shrink: 0;
+  background-color: var(--ld-sidebar-bg);
+  backdrop-filter: blur(var(--ld-sidebar-blur));
+  -webkit-backdrop-filter: blur(var(--ld-sidebar-blur));
+  border-right: 1px solid var(--ld-border-subtle);
+  padding: 1rem 0.6rem;
+  overflow-y: auto;
+  position: sticky;
+  top: var(--ld-navbar-height);
+  height: calc(100vh - var(--ld-navbar-height));
+  scrollbar-width: thin;
+  scrollbar-color: var(--ld-bg-mute) transparent;
+  display: flex;
+  flex-direction: column;
+  transition:
+    width 0.3s cubic-bezier(0.16, 1, 0.3, 1),
+    padding 0.3s cubic-bezier(0.16, 1, 0.3, 1),
+    opacity 0.2s ease;
+}
+
+.boltdocs-sidebar > nav {
+  flex: 1;
+}
+
+/* ─── 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;
+  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);
+  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);
+}
+
+.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);
+}
+
+.sidebar-collapse-btn {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  width: 100%;
+  padding: 0.5rem 0.75rem;
+  background: none;
+  border: none;
+  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;
+}
+
+.sidebar-collapse-btn:hover {
+  background-color: var(--ld-bg-soft);
+  color: var(--ld-color-primary);
+}
+
+.boltdocs-sidebar::-webkit-scrollbar {
+  width: 4px;
+}
+
+.boltdocs-sidebar::-webkit-scrollbar-track {
+  background: transparent;
+}
+
+.boltdocs-sidebar::-webkit-scrollbar-thumb {
+  background: var(--ld-bg-mute);
+  border-radius: 4px;
+}
+
+.sidebar-list {
+  list-style: none;
+  padding: 0;
+  margin: 0 0 0.5rem;
+}
+
+.sidebar-list li {
+  margin-bottom: 1px;
+}
+
+.sidebar-link {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 0.45rem 0.75rem;
+  color: var(--ld-text-muted);
+  text-decoration: none;
+  border-radius: var(--ld-radius-md);
+  font-size: 0.875rem;
+  font-weight: 500;
+  transition: all 0.2s ease;
+  margin: 0.15rem 0;
+}
+
+.sidebar-link-content {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  width: 100%;
+  gap: 0.5rem;
+}
+
+.sidebar-link-content > span:first-child {
+  flex: 1;
+  word-wrap: break-word;
+}
+
+.sidebar-badge {
+  font-size: 0.45rem;
+  font-weight: 500;
+  padding: 0.1rem 0.3rem;
+  border-radius: 9999px;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  white-space: nowrap;
+  line-height: 1;
+  display: inline-flex;
+  align-items: center;
+  flex-shrink: 0;
+}
+
+.sidebar-badge.badge-new {
+  color: #38bdf8;
+  background-color: rgba(56, 189, 248, 0.15);
+  border: 1px solid rgba(56, 189, 248, 0.25);
+}
+
+.sidebar-badge.badge-experimental {
+  color: #eab308; /* Yellow */
+  background-color: rgba(234, 179, 8, 0.15);
+  border: 1px solid rgba(234, 179, 8, 0.25);
+}
+
+.sidebar-badge.badge-updated {
+  color: #a1a1aa; /* Grey / Zinc 400 */
+  background-color: rgba(161, 161, 170, 0.15);
+  border: 1px solid rgba(161, 161, 170, 0.25);
+}
+
+.sidebar-badge.badge-default {
+  color: var(--ld-text-muted);
+  background-color: var(--ld-bg-mute);
+  border: 1px solid var(--ld-border-subtle);
+}
+
+.sidebar-link:hover {
+  color: var(--ld-color-primary-hover);
+}
+
+.sidebar-link.active {
+  color: var(--ld-color-primary);
+  font-weight: 600;
+}
+
+/* ─── Sidebar Groups ─────────────────────────────────────── */
+.sidebar-group {
+  margin-top: 1.25rem;
+}
+
+.sidebar-group:first-child {
+  margin-top: 0;
+}
+
+.sidebar-group-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  width: 100%;
+  padding: 0.35rem 0.75rem;
+  background: none;
+  border: none;
+  border-radius: var(--ld-radius-md);
+  color: var(--ld-text-dim);
+  font-family: var(--ld-font-sans);
+  font-size: 0.6875rem;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+  cursor: pointer;
+  transition:
+    color 0.2s,
+    background-color 0.2s;
+}
+
+.sidebar-group-header:hover {
+  color: var(--ld-text-muted);
+  background-color: rgba(255, 255, 255, 0.03);
+}
+
+.sidebar-group-header.active {
+  color: var(--ld-color-primary);
+}
+
+.sidebar-group-chevron {
+  display: inline-flex;
+  align-items: center;
+  transition: transform 0.25s ease;
+  font-size: 0.75rem;
+  line-height: 1;
+}
+
+.sidebar-group-chevron.open {
+  transform: rotate(90deg);
+}
+
+.sidebar-group-list {
+  list-style: none;
+  padding: 0;
+  margin: 0.35rem 0 0;
+  overflow: hidden;
+}
+
+.sidebar-group-list li {
+  margin-bottom: 1px;
+}
+
+.sidebar-link-nested {
+  padding-left: 1.25rem;
+}

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

@@ -0,0 +1,69 @@
+import React, { useEffect, useState } from "react";
+import { Sun, Moon } from "lucide-react";
+
+export function ThemeToggle() {
+  const [theme, setTheme] = useState("dark");
+  const [mounted, setMounted] = useState(false);
+
+  useEffect(() => {
+    setMounted(true);
+    // On mount, read from localStorage or matchMedia
+    const stored = localStorage.getItem("boltdocs-theme");
+    if (stored === "light" || stored === "dark") {
+      setTheme(stored);
+    } else {
+      const prefersDark = window.matchMedia(
+        "(prefers-color-scheme: dark)",
+      ).matches;
+      setTheme(prefersDark ? "dark" : "light");
+    }
+
+    // Listen to system changes if no localStorage is set
+    const mediaQuery = window.matchMedia("(prefers-color-scheme: dark)");
+    const handleChange = (e: MediaQueryListEvent) => {
+      if (!localStorage.getItem("boltdocs-theme")) {
+        setTheme(e.matches ? "dark" : "light");
+      }
+    };
+    mediaQuery.addEventListener("change", handleChange);
+    return () => mediaQuery.removeEventListener("change", handleChange);
+  }, []);
+
+  useEffect(() => {
+    if (!mounted) return;
+    const root = document.documentElement;
+    if (theme === "light") {
+      root.classList.add("theme-light");
+      root.dataset.theme = "light";
+    } else {
+      root.classList.remove("theme-light");
+      root.dataset.theme = "dark";
+    }
+  }, [theme, mounted]);
+
+  const toggleTheme = () => {
+    const newTheme = theme === "dark" ? "light" : "dark";
+    setTheme(newTheme);
+    localStorage.setItem("boltdocs-theme", newTheme);
+  };
+
+  // Prevent hydration mismatch by rendering a placeholder with same layout
+  if (!mounted) {
+    return (
+      <button className="navbar-icon-btn" aria-label="Toggle theme" disabled>
+        <span style={{ width: 20, height: 20, display: "inline-block" }}></span>
+      </button>
+    );
+  }
+
+  return (
+    <button
+      className="navbar-icon-btn"
+      onClick={toggleTheme}
+      aria-label="Toggle theme"
+      title={`Switch to ${theme === "dark" ? "light" : "dark"} theme`}
+    >
+      {theme === "dark" ? <Sun size={20} /> : <Moon size={20} />}
+    </button>
+  );
+}

package/src/client/theme/ui/ThemeToggle/index.ts

@@ -0,0 +1 @@
+export { ThemeToggle } from "./ThemeToggle";