boltdocs 1.0.0

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

@@ -0,0 +1,202 @@
+import React from "react";
+import {
+  Link as RouterLink,
+  NavLink as RouterNavLink,
+  LinkProps as RouterLinkProps,
+  NavLinkProps as RouterNavLinkProps,
+  useLocation,
+} from "react-router-dom";
+import { usePreload } from "../../../app/preload";
+import { useConfig } from "../../../app";
+
+function useLocalizedTo(to: RouterLinkProps["to"]) {
+  const location = useLocation();
+  const config = useConfig();
+  if (!config || typeof to !== "string") return to;
+  if (!config.i18n && !config.versions) return to;
+
+  const basePath = "/docs";
+  if (!to.startsWith(basePath)) return to;
+
+  // 1. Detect current context from location
+  const curSub = location.pathname.substring(basePath.length);
+  const curParts = curSub.split("/").filter(Boolean);
+
+  let currentVersion = config.versions?.defaultVersion;
+  let currentLocale = config.i18n?.defaultLocale;
+
+  let cIdx = 0;
+  if (
+    config.versions &&
+    curParts.length > cIdx &&
+    config.versions.versions[curParts[cIdx]]
+  ) {
+    currentVersion = curParts[cIdx];
+    cIdx++;
+  }
+  if (
+    config.i18n &&
+    curParts.length > cIdx &&
+    config.i18n.locales[curParts[cIdx]]
+  ) {
+    currentLocale = curParts[cIdx];
+  }
+
+  // 2. Parse the target `to` path
+  const toSub = to.substring(basePath.length);
+  const toParts = toSub.split("/").filter(Boolean);
+
+  let tIdx = 0;
+  let hasVersion = false;
+  let hasLocale = false;
+
+  if (
+    config.versions &&
+    toParts.length > tIdx &&
+    config.versions.versions[toParts[tIdx]]
+  ) {
+    hasVersion = true;
+    tIdx++;
+  }
+  if (
+    config.i18n &&
+    toParts.length > tIdx &&
+    config.i18n.locales[toParts[tIdx]]
+  ) {
+    hasLocale = true;
+    tIdx++;
+  }
+
+  // Extract just the actual route parts
+  const routeParts = toParts.slice(tIdx);
+
+  // Reconstruct path
+  const finalParts = [];
+  if (config.versions) {
+    if (hasVersion) {
+      finalParts.push(toParts[0]);
+    } else if (currentVersion) {
+      finalParts.push(currentVersion);
+    }
+  }
+  if (config.i18n) {
+    if (hasLocale) {
+      finalParts.push(toParts[hasVersion ? 1 : 0]);
+    } else if (currentLocale) {
+      finalParts.push(currentLocale);
+    }
+  }
+
+  finalParts.push(...routeParts);
+
+  let finalPath = `${basePath}/${finalParts.join("/")}`;
+  if (finalPath.endsWith("/")) {
+    finalPath = finalPath.slice(0, -1);
+  }
+  return finalPath === basePath ? basePath : finalPath;
+}
+
+export interface LinkProps extends Omit<RouterLinkProps, "prefetch"> {
+  /** Should prefetch the page on hover? Options: 'hover' | 'none'. Default 'hover' */
+  boltdocsPrefetch?: "hover" | "none";
+}
+
+export const Link = React.forwardRef<HTMLAnchorElement, LinkProps>(
+  (props, ref) => {
+    const {
+      boltdocsPrefetch = "hover",
+      onMouseEnter,
+      onFocus,
+      to,
+      ...rest
+    } = props;
+    const localizedTo = useLocalizedTo(to);
+    const { preload } = usePreload();
+
+    const handleMouseEnter = (e: React.MouseEvent<HTMLAnchorElement>) => {
+      onMouseEnter?.(e);
+      if (
+        boltdocsPrefetch === "hover" &&
+        typeof localizedTo === "string" &&
+        localizedTo.startsWith("/")
+      ) {
+        preload(localizedTo);
+      }
+    };
+
+    const handleFocus = (e: React.FocusEvent<HTMLAnchorElement>) => {
+      onFocus?.(e);
+      if (
+        boltdocsPrefetch === "hover" &&
+        typeof localizedTo === "string" &&
+        localizedTo.startsWith("/")
+      ) {
+        preload(localizedTo);
+      }
+    };
+
+    return (
+      <RouterLink
+        ref={ref}
+        to={localizedTo}
+        onMouseEnter={handleMouseEnter}
+        onFocus={handleFocus}
+        {...rest}
+      />
+    );
+  },
+);
+Link.displayName = "Link";
+
+export interface NavLinkProps extends Omit<RouterNavLinkProps, "prefetch"> {
+  /** Should prefetch the page on hover? Options: 'hover' | 'none'. Default 'hover' */
+  boltdocsPrefetch?: "hover" | "none";
+}
+
+export const NavLink = React.forwardRef<HTMLAnchorElement, NavLinkProps>(
+  (props, ref) => {
+    const {
+      boltdocsPrefetch = "hover",
+      onMouseEnter,
+      onFocus,
+      to,
+      ...rest
+    } = props;
+
+    const localizedTo = useLocalizedTo(to);
+    const { preload } = usePreload();
+
+    const handleMouseEnter = (e: React.MouseEvent<HTMLAnchorElement>) => {
+      onMouseEnter?.(e);
+      if (
+        boltdocsPrefetch === "hover" &&
+        typeof localizedTo === "string" &&
+        localizedTo.startsWith("/")
+      ) {
+        preload(localizedTo);
+      }
+    };
+
+    const handleFocus = (e: React.FocusEvent<HTMLAnchorElement>) => {
+      onFocus?.(e);
+      if (
+        boltdocsPrefetch === "hover" &&
+        typeof localizedTo === "string" &&
+        localizedTo.startsWith("/")
+      ) {
+        preload(localizedTo);
+      }
+    };
+
+    return (
+      <RouterNavLink
+        ref={ref}
+        to={localizedTo}
+        onMouseEnter={handleMouseEnter}
+        onFocus={handleFocus}
+        {...rest}
+      />
+    );
+  },
+);
+NavLink.displayName = "NavLink";

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

@@ -0,0 +1,2 @@
+export { Link, NavLink } from "./Link";
+export type { LinkProps, NavLinkProps } from "./Link";

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

@@ -0,0 +1,10 @@
+import React from 'react';
+
+export function Loading() {
+  return (
+    <div className="boltdocs-loading">
+      <div className="loading-spinner" />
+      <p className="loading-text">Loading...</p>
+    </div>
+  );
+}

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

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

package/src/client/theme/ui/Loading/loading.css

@@ -0,0 +1,30 @@
+/* ─── Loading ─────────────────────────────────────────────── */
+.boltdocs-loading {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  min-height: 40vh;
+  gap: 1rem;
+}
+
+.loading-spinner {
+  width: 2.5rem;
+  height: 2.5rem;
+  border: 3px solid var(--ld-border-subtle);
+  border-top-color: var(--ld-color-primary);
+  border-radius: 50%;
+  animation: boltdocs-spin 0.7s linear infinite;
+}
+
+@keyframes boltdocs-spin {
+  to {
+    transform: rotate(360deg);
+  }
+}
+
+.loading-text {
+  font-size: 0.875rem;
+  color: var(--ld-text-dim);
+  margin: 0;
+}

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

@@ -0,0 +1,27 @@
+import { useEffect, useState } from "react";
+import { GitHub } from "../../icons/github";
+import { getStarsRepo } from "../../../utils";
+
+export function GithubStars({ repo }: { repo: string }) {
+  const [stars, setStars] = useState<string | null>(null);
+
+  useEffect(() => {
+    if (repo) {
+      getStarsRepo(repo)
+        .then((stars) => setStars(stars))
+        .catch(() => setStars("0"));
+    }
+  }, [repo]);
+
+  return (
+    <a
+      href={`https://github.com/${repo}`}
+      target="_blank"
+      rel="noopener noreferrer"
+      className="navbar-github-stars"
+    >
+      <GitHub />
+      {stars && <span>{stars}</span>}
+    </a>
+  );
+}

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

@@ -0,0 +1,145 @@
+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 { LanguageSwitcher } from "../LanguageSwitcher";
+import { VersionSwitcher } from "../VersionSwitcher";
+import { ThemeToggle } from "../ThemeToggle";
+import { getStarsRepo } from "../../../utils";
+import { Discord } from "../../icons/discord";
+import { XformerlyTwitter } from "../../icons/twitter";
+import { GithubStars } from "./GithubStars";
+
+const SearchDialog = React.lazy(() =>
+  import("../SearchDialog").then((m) => ({ default: m.SearchDialog })),
+);
+
+const ICON_MAP: Record<string, React.FC> = {
+  discord: Discord,
+  x: XformerlyTwitter,
+};
+
+function formatStars(stars: number) {
+  if (stars >= 1000) {
+    return (stars / 1000).toFixed(1) + "K";
+  }
+  return stars.toString();
+}
+
+/**
+ * The top navigation bar of the documentation site.
+ */
+export function Navbar({
+  config,
+  routes,
+  allRoutes,
+  currentLocale,
+  currentVersion,
+}: {
+  config: BoltdocsConfig;
+  routes?: ComponentRoute[];
+  allRoutes?: ComponentRoute[];
+  currentLocale?: string;
+  currentVersion?: string;
+}) {
+  const title = config.themeConfig?.title || "Boltdocs";
+  const navItems = config.themeConfig?.navbar || [];
+  const socialLinks = config.themeConfig?.socialLinks || [];
+
+  return (
+    <header className="boltdocs-navbar">
+      <div className="navbar-container">
+        {/* LEFT SECTION */}
+        <div className="navbar-left">
+          <div className="navbar-logo">
+            <Link to="/">
+              {config.themeConfig?.logo ? (
+                config.themeConfig.logo.trim().startsWith("<svg") ? (
+                  <span
+                    className="navbar-logo-svg"
+                    dangerouslySetInnerHTML={{
+                      __html: config.themeConfig.logo,
+                    }}
+                  />
+                ) : (
+                  <img
+                    src={config.themeConfig.logo}
+                    alt={title}
+                    className="navbar-logo-img"
+                  />
+                )
+              ) : null}
+              {title}
+            </Link>
+          </div>
+
+          {config.versions && currentVersion && allRoutes ? (
+            <VersionSwitcher
+              versions={config.versions}
+              currentVersion={currentVersion}
+              currentLocale={currentLocale}
+              allRoutes={allRoutes}
+            />
+          ) : config.themeConfig?.version ? (
+            <div className="navbar-version">
+              {config.themeConfig.version} <ChevronDown size={14} />
+            </div>
+          ) : null}
+
+          <nav className="navbar-links" aria-label="Top Navigation">
+            {navItems.map((item, i) => (
+              <Link key={i} to={item.link}>
+                {item.text}
+              </Link>
+            ))}
+          </nav>
+        </div>
+
+        {/* RIGHT SECTION */}
+        <div className="navbar-right">
+          <React.Suspense
+            fallback={<div className="navbar-search-placeholder" />}
+          >
+            <SearchDialog routes={routes || []} />
+          </React.Suspense>
+
+          {config.i18n && currentLocale && allRoutes && (
+            <LanguageSwitcher
+              i18n={config.i18n}
+              currentLocale={currentLocale}
+              allRoutes={allRoutes}
+            />
+          )}
+
+          <ThemeToggle />
+
+          {config.themeConfig?.githubRepo && (
+            <GithubStars repo={config.themeConfig.githubRepo} />
+          )}
+
+          {/* Optional Divider if both groups have items */}
+          {socialLinks.length > 0 && <div className="navbar-divider" />}
+
+          <div className="navbar-icons">
+            {socialLinks.map((link, i) => {
+              const IconComp = ICON_MAP[link.icon.toLowerCase()];
+              return (
+                <a
+                  key={i}
+                  href={link.link}
+                  target="_blank"
+                  rel="noopener noreferrer"
+                  className="navbar-icon-btn"
+                  aria-label={link.icon}
+                >
+                  {IconComp ? <IconComp /> : <span>{link.icon}</span>}
+                </a>
+              );
+            })}
+          </div>
+        </div>
+      </div>
+    </header>
+  );
+}

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

@@ -0,0 +1,2 @@
+export { Navbar } from "./Navbar";
+export { GithubStars } from "./GithubStars";

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

@@ -0,0 +1,233 @@
+/* ═══════════════════════════════════════════════════════════
+   NAVBAR
+   ═══════════════════════════════════════════════════════════ */
+.boltdocs-navbar {
+  display: flex;
+  align-items: center;
+  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;
+}
+
+.navbar-container {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  width: 100%;
+  max-width: 1440px;
+  margin: 0 auto;
+  padding: 0 1.5rem; /* Aligned exactly with main-container */
+}
+
+.navbar-logo {
+  flex: 1;
+}
+
+.navbar-logo a {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  font-weight: 700;
+  font-size: 1.15rem;
+  color: var(--ld-text-main);
+  text-decoration: none;
+  letter-spacing: -0.01em;
+}
+
+.navbar-logo a:hover {
+  color: var(--ld-text-main);
+}
+
+.navbar-logo-img {
+  height: 20px;
+  width: auto;
+  object-fit: contain;
+  display: block;
+}
+
+.navbar-logo-svg {
+  display: flex;
+  align-items: center;
+}
+
+.navbar-logo-svg svg {
+  height: 36px;
+  width: auto;
+  fill: currentColor;
+  display: block;
+}
+
+.navbar-left {
+  display: flex;
+  align-items: center;
+  gap: 1.25rem;
+}
+
+.navbar-version {
+  display: flex;
+  align-items: center;
+  gap: 0.2rem;
+  font-size: 0.75rem;
+  font-weight: 500;
+  color: var(--ld-text-muted);
+  background-color: var(--ld-bg-soft);
+  padding: 0.25rem 0.5rem;
+  border-radius: var(--ld-radius-md);
+  border: 1px solid var(--ld-border-subtle);
+  cursor: pointer;
+  transition: all 0.2s;
+}
+
+.navbar-version:hover {
+  background-color: var(--ld-bg-mute);
+  color: var(--ld-text-main);
+  border-color: var(--ld-border-strong);
+}
+
+.navbar-right {
+  display: flex;
+  align-items: center;
+  gap: 0.75rem;
+}
+
+.navbar-links {
+  display: flex;
+  align-items: center;
+  gap: 0.25rem;
+}
+
+.navbar-links a {
+  position: relative;
+  padding: 0.4rem 0.75rem;
+  color: var(--ld-text-muted);
+  text-decoration: none;
+  font-weight: 500;
+  font-size: 0.875rem;
+  border-radius: var(--ld-radius-md);
+  transition:
+    color 0.2s,
+    background-color 0.2s;
+}
+
+.navbar-links a:hover {
+  color: var(--ld-text-main);
+  background-color: var(--ld-color-primary-muted);
+}
+
+.navbar-links a.active {
+  color: var(--ld-color-primary);
+}
+
+.navbar-search {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  padding: 0.35rem 0.75rem;
+  background-color: transparent; /* Cleaner flat base */
+  border: 1px solid transparent; /* Invisible border initially */
+  border-radius: var(--ld-radius-full);
+  backdrop-filter: blur(12px);
+  -webkit-backdrop-filter: blur(12px);
+  color: var(--ld-text-dim);
+  font-size: 0.8125rem;
+  min-width: 220px;
+  cursor: pointer;
+  transition: all 0.2s;
+}
+
+.navbar-search:hover {
+  background-color: var(--ld-bg-mute);
+  color: var(--ld-text-muted);
+}
+
+.navbar-search svg {
+  width: 15px;
+  height: 15px;
+  opacity: 0.7;
+}
+
+.navbar-search kbd {
+  margin-left: auto;
+  padding: 0.15rem 0.4rem;
+  font-family: var(--ld-font-sans);
+  font-weight: 500;
+  font-size: 0.65rem;
+  background-color: var(--ld-bg-mute);
+  border: 1px solid var(--ld-border-strong);
+  border-radius: var(--ld-radius-md);
+  color: var(--ld-text-dim);
+}
+
+/* ─── Github Stars Pill ────────────────────────────────── */
+.navbar-github-stars {
+  display: flex;
+  align-items: center;
+  gap: 0.35rem;
+  padding: 0.3rem 0.65rem;
+  border-radius: var(--ld-radius-full);
+  border: 1px solid var(--ld-border-subtle);
+  background: var(--ld-bg-soft);
+  color: var(--ld-text-muted);
+  text-decoration: none;
+  font-size: 0.8rem;
+  font-weight: 500;
+  transition: all 0.2s;
+}
+
+.navbar-github-stars:hover {
+  color: var(--ld-text-main);
+  background: var(--ld-bg-mute);
+  border-color: var(--ld-border-strong);
+}
+
+.navbar-github-stars svg {
+  width: 15px;
+  height: 15px;
+}
+
+.navbar-divider {
+  width: 1px;
+  height: 18px;
+  background-color: var(--ld-border-subtle);
+  margin: 0 0.25rem;
+}
+
+.navbar-icons {
+  display: flex;
+  align-items: center;
+  gap: 0.25rem;
+}
+
+.navbar-icon-btn {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 2.15rem;
+  height: 2.15rem;
+  background: transparent;
+  border: none;
+  cursor: pointer;
+  border-radius: var(--ld-radius-full);
+  color: var(--ld-text-muted);
+  text-decoration: none;
+  transition:
+    color 0.2s,
+    background-color 0.2s;
+}
+
+.navbar-icon-btn:hover {
+  color: var(--ld-text-main);
+  background-color: var(--ld-bg-mute);
+}
+
+.navbar-icon-btn svg {
+  width: 18px;
+  height: 18px;
+}

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

@@ -0,0 +1,20 @@
+import React from "react";
+import { Link } from "../Link";
+import { ArrowLeft } from "lucide-react";
+
+export function NotFound() {
+  return (
+    <div className="boltdocs-not-found">
+      <div className="not-found-content">
+        <span className="not-found-code">404</span>
+        <h1 className="not-found-title">Page Not Found</h1>
+        <p className="not-found-text">
+          The page you're looking for doesn't exist or has been moved.
+        </p>
+        <Link to="/" className="not-found-link">
+          <ArrowLeft size={16} /> Go to Home
+        </Link>
+      </div>
+    </div>
+  );
+}

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

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