boltdocs 1.4.1 → 1.6.0

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

@@ -97,25 +97,44 @@ function useLocalizedTo(to: RouterLinkProps["to"]) {
   return finalPath === basePath ? basePath : finalPath;
 }
 
+import { LinkPreview } from "./LinkPreview";
+
 export interface LinkProps extends Omit<RouterLinkProps, "prefetch"> {
   /** Should prefetch the page on hover? Options: 'hover' | 'none'. Default 'hover' */
   boltdocsPrefetch?: "hover" | "none";
+  /** Should show a preview tooltip on hover? Default true */
+  boltdocsPreview?: boolean;
 }
 
 export const Link = React.forwardRef<HTMLAnchorElement, LinkProps>(
   (props, ref) => {
     const {
       boltdocsPrefetch = "hover",
+      boltdocsPreview = true,
       onMouseEnter,
+      onMouseLeave,
       onFocus,
+      onBlur,
       onClick,
       to,
       ...rest
     } = props;
     const localizedTo = useLocalizedTo(to);
-    const { preload } = usePreload();
+    const { preload, routes } = usePreload();
+    const config = useConfig();
     const navigate = useNavigate();
 
+    const shouldShowPreview =
+      boltdocsPreview && config?.themeConfig?.linkPreview !== false;
+
+    const [preview, setPreview] = React.useState<{
+      visible: boolean;
+      x: number;
+      y: number;
+      title: string;
+      summary?: string;
+    }>({ visible: false, x: 0, y: 0, title: "" });
+
     const handleMouseEnter = (e: React.MouseEvent<HTMLAnchorElement>) => {
       onMouseEnter?.(e);
       if (
@@ -125,6 +144,37 @@ export const Link = React.forwardRef<HTMLAnchorElement, LinkProps>(
       ) {
         preload(localizedTo);
       }
+
+      if (
+        shouldShowPreview &&
+        typeof localizedTo === "string" &&
+        localizedTo.startsWith("/")
+      ) {
+        const cleanPath = localizedTo.split("#")[0].split("?")[0];
+        const route = routes.find(
+          (r) => r.path === cleanPath || (cleanPath === "/" && r.path === ""),
+        );
+        if (route) {
+          setPreview({
+            visible: true,
+            x: e.clientX,
+            y: e.clientY,
+            title: route.title,
+            summary: route.description,
+          });
+        }
+      }
+    };
+
+    const handleMouseMove = (e: React.MouseEvent<HTMLAnchorElement>) => {
+      if (preview.visible) {
+        setPreview((prev) => ({ ...prev, x: e.clientX, y: e.clientY }));
+      }
+    };
+
+    const handleMouseLeave = (e: React.MouseEvent<HTMLAnchorElement>) => {
+      onMouseLeave?.(e);
+      setPreview((prev) => ({ ...prev, visible: false }));
     };
 
     const handleFocus = (e: React.FocusEvent<HTMLAnchorElement>) => {
@@ -138,9 +188,15 @@ export const Link = React.forwardRef<HTMLAnchorElement, LinkProps>(
       }
     };
 
+    const handleBlur = (e: React.FocusEvent<HTMLAnchorElement>) => {
+      onBlur?.(e);
+      setPreview((prev) => ({ ...prev, visible: false }));
+    };
+
     const handleClick = (e: React.MouseEvent<HTMLAnchorElement>) => {
       // Allow user onClick to handle defaults or custom logic
       onClick?.(e);
+      setPreview((prev) => ({ ...prev, visible: false }));
 
       // If default prevented or not a simple left click, don't handle
       if (
@@ -164,14 +220,28 @@ export const Link = React.forwardRef<HTMLAnchorElement, LinkProps>(
     };
 
     return (
-      <RouterLink
-        ref={ref}
-        to={localizedTo}
-        onMouseEnter={handleMouseEnter}
-        onFocus={handleFocus}
-        onClick={handleClick}
-        {...rest}
-      />
+      <>
+        <RouterLink
+          ref={ref}
+          to={localizedTo}
+          onMouseEnter={handleMouseEnter}
+          onMouseMove={handleMouseMove}
+          onMouseLeave={handleMouseLeave}
+          onFocus={handleFocus}
+          onBlur={handleBlur}
+          onClick={handleClick}
+          {...rest}
+        />
+        {shouldShowPreview && (
+          <LinkPreview
+            isVisible={preview.visible}
+            title={preview.title}
+            summary={preview.summary}
+            x={preview.x}
+            y={preview.y}
+          />
+        )}
+      </>
     );
   },
 );
@@ -180,23 +250,40 @@ Link.displayName = "Link";
 export interface NavLinkProps extends Omit<RouterNavLinkProps, "prefetch"> {
   /** Should prefetch the page on hover? Options: 'hover' | 'none'. Default 'hover' */
   boltdocsPrefetch?: "hover" | "none";
+  /** Should show a preview tooltip on hover? Default true */
+  boltdocsPreview?: boolean;
 }
 
 export const NavLink = React.forwardRef<HTMLAnchorElement, NavLinkProps>(
   (props, ref) => {
     const {
       boltdocsPrefetch = "hover",
+      boltdocsPreview = true,
       onMouseEnter,
+      onMouseLeave,
       onFocus,
+      onBlur,
       onClick,
       to,
       ...rest
     } = props;
 
     const localizedTo = useLocalizedTo(to);
-    const { preload } = usePreload();
+    const { preload, routes } = usePreload();
+    const config = useConfig();
     const navigate = useNavigate();
 
+    const shouldShowPreview =
+      boltdocsPreview && config?.themeConfig?.linkPreview !== false;
+
+    const [preview, setPreview] = React.useState<{
+      visible: boolean;
+      x: number;
+      y: number;
+      title: string;
+      summary?: string;
+    }>({ visible: false, x: 0, y: 0, title: "" });
+
     const handleMouseEnter = (e: React.MouseEvent<HTMLAnchorElement>) => {
       onMouseEnter?.(e);
       if (
@@ -206,6 +293,37 @@ export const NavLink = React.forwardRef<HTMLAnchorElement, NavLinkProps>(
       ) {
         preload(localizedTo);
       }
+
+      if (
+        shouldShowPreview &&
+        typeof localizedTo === "string" &&
+        localizedTo.startsWith("/")
+      ) {
+        const cleanPath = localizedTo.split("#")[0].split("?")[0];
+        const route = routes.find(
+          (r) => r.path === cleanPath || (cleanPath === "/" && r.path === ""),
+        );
+        if (route) {
+          setPreview({
+            visible: true,
+            x: e.clientX,
+            y: e.clientY,
+            title: route.title,
+            summary: route.description,
+          });
+        }
+      }
+    };
+
+    const handleMouseMove = (e: React.MouseEvent<HTMLAnchorElement>) => {
+      if (preview.visible) {
+        setPreview((prev) => ({ ...prev, x: e.clientX, y: e.clientY }));
+      }
+    };
+
+    const handleMouseLeave = (e: React.MouseEvent<HTMLAnchorElement>) => {
+      onMouseLeave?.(e);
+      setPreview((prev) => ({ ...prev, visible: false }));
     };
 
     const handleFocus = (e: React.FocusEvent<HTMLAnchorElement>) => {
@@ -219,8 +337,14 @@ export const NavLink = React.forwardRef<HTMLAnchorElement, NavLinkProps>(
       }
     };
 
+    const handleBlur = (e: React.FocusEvent<HTMLAnchorElement>) => {
+      onBlur?.(e);
+      setPreview((prev) => ({ ...prev, visible: false }));
+    };
+
     const handleClick = (e: React.MouseEvent<HTMLAnchorElement>) => {
       onClick?.(e);
+      setPreview((prev) => ({ ...prev, visible: false }));
       if (
         e.defaultPrevented ||
         e.button !== 0 ||
@@ -240,14 +364,28 @@ export const NavLink = React.forwardRef<HTMLAnchorElement, NavLinkProps>(
     };
 
     return (
-      <RouterNavLink
-        ref={ref}
-        to={localizedTo}
-        onMouseEnter={handleMouseEnter}
-        onFocus={handleFocus}
-        onClick={handleClick}
-        {...rest}
-      />
+      <>
+        <RouterNavLink
+          ref={ref}
+          to={localizedTo}
+          onMouseEnter={handleMouseEnter}
+          onMouseMove={handleMouseMove}
+          onMouseLeave={handleMouseLeave}
+          onFocus={handleFocus}
+          onBlur={handleBlur}
+          onClick={handleClick}
+          {...rest}
+        />
+        {shouldShowPreview && (
+          <LinkPreview
+            isVisible={preview.visible}
+            title={preview.title}
+            summary={preview.summary}
+            x={preview.x}
+            y={preview.y}
+          />
+        )}
+      </>
     );
   },
 );

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

@@ -0,0 +1,64 @@
+import { useEffect, useState, useRef } from "react";
+import { createPortal } from "react-dom";
+import "./link-preview.css";
+
+interface LinkPreviewProps {
+  isVisible: boolean;
+  title: string;
+  summary?: string;
+  x: number;
+  y: number;
+}
+
+export function LinkPreview({
+  isVisible,
+  title,
+  summary,
+  x,
+  y,
+}: LinkPreviewProps) {
+  const [mounted, setMounted] = useState(false);
+  const ref = useRef<HTMLDivElement>(null);
+  const [position, setPosition] = useState({ top: 0, left: 0 });
+
+  useEffect(() => {
+    setMounted(true);
+  }, []);
+
+  useEffect(() => {
+    if (isVisible && ref.current) {
+      const rect = ref.current.getBoundingClientRect();
+      const padding = 15;
+
+      let top = y + padding;
+      let left = x + padding;
+
+      // Keep within viewport
+      if (left + rect.width > window.innerWidth) {
+        left = x - rect.width - padding;
+      }
+      if (top + rect.height > window.innerHeight) {
+        top = y - rect.height - padding;
+      }
+
+      setPosition({ top, left });
+    }
+  }, [isVisible, x, y]);
+
+  if (!mounted) return null;
+
+  return createPortal(
+    <div
+      ref={ref}
+      className={`boltdocs-link-preview ${isVisible ? "is-visible" : ""}`}
+      style={{
+        top: position.top,
+        left: position.left,
+      }}
+    >
+      <span className="boltdocs-link-preview-title">{title}</span>
+      {summary && <p className="boltdocs-link-preview-summary">{summary}</p>}
+    </div>,
+    document.body,
+  );
+}

package/src/client/theme/ui/Link/link-preview.css

@@ -0,0 +1,64 @@
+.boltdocs-link-preview {
+  position: fixed;
+  z-index: 1000;
+  width: 320px;
+  padding: 1rem;
+  background-color: var(--ld-navbar-bg);
+  backdrop-filter: blur(var(--ld-navbar-blur));
+  -webkit-backdrop-filter: blur(var(--ld-navbar-blur));
+  border: 1px solid var(--ld-border-subtle);
+  border-radius: var(--ld-radius-md);
+  box-shadow:
+    0 10px 25px -5px rgba(0, 0, 0, 0.1),
+    0 8px 10px -6px rgba(0, 0, 0, 0.1);
+  pointer-events: none;
+  opacity: 0;
+  transform: translateY(10px) scale(0.95);
+  transition:
+    opacity 0.2s cubic-bezier(0.4, 0, 0.2, 1),
+    transform 0.2s cubic-bezier(0.4, 0, 0.2, 1);
+  font-family: var(--ld-font-sans);
+}
+
+.boltdocs-link-preview.is-visible {
+  opacity: 1;
+  transform: translateY(0) scale(1);
+}
+
+.boltdocs-link-preview-title {
+  display: block;
+  font-weight: 600;
+  font-size: 0.95rem;
+  color: var(--ld-text-main);
+  margin-bottom: 0.5rem;
+  line-height: 1.4;
+}
+
+.boltdocs-link-preview-summary {
+  display: block;
+  font-size: 0.85rem;
+  color: var(--ld-text-muted);
+  line-height: 1.5;
+  display: -webkit-box;
+  -webkit-line-clamp: 4;
+  line-clamp: 4;
+  -webkit-box-orient: vertical;
+  overflow: hidden;
+}
+
+/* Dark mode adjustments */
+[data-theme="dark"] .boltdocs-link-preview {
+  background-color: var(--ld-navbar-bg);
+  border-color: var(--ld-border-subtle);
+  box-shadow:
+    0 20px 25px -5px rgba(0, 0, 0, 0.3),
+    0 10px 10px -5px rgba(0, 0, 0, 0.2);
+}
+
+[data-theme="dark"] .boltdocs-link-preview-title {
+  color: #f8fafc;
+}
+
+[data-theme="dark"] .boltdocs-link-preview-summary {
+  color: #94a3b8;
+}

package/src/client/types.ts

@@ -23,6 +23,8 @@ export interface ComponentRoute {
   groupPosition?: number;
   /** Extracted markdown headings for search indexing */
   headings?: { level: number; text: string; id: string }[];
+  /** The page summary or description */
+  description?: string;
   /** The locale this route belongs to, if i18n is configured */
   locale?: string;
   /** The version this route belongs to, if versioning is configured */

package/src/node/config.ts

@@ -53,6 +53,8 @@ export interface BoltdocsThemeConfig {
   githubRepo?: string;
   /** Whether to show the 'Powered by LiteDocs' badge in the sidebar (default: true) */
   poweredBy?: boolean;
+  /** Whether to show a preview tooltip on internal links hover (default: true) */
+  linkPreview?: boolean;
   /** Granular layout customization props */
   layoutProps?: {
     navbar?: any;

package/src/node/routes/parser.ts

@@ -122,9 +122,22 @@ export function parseDocFile(
   }
 
   const sanitizedTitle = data.title ? escapeHtml(data.title) : inferredTitle;
-  const sanitizedDescription = data.description
+  let sanitizedDescription = data.description
     ? escapeHtml(data.description)
     : "";
+
+  // If no description is provided, extract a summary from the content
+  if (!sanitizedDescription && content) {
+    const summary = content
+      .replace(/^#+.*$/gm, "") // Remove headers
+      .replace(/\[([^\]]+)\]\([^\)]+\)/g, "$1") // Simplify links
+      .replace(/[_*`]/g, "") // Remove formatting
+      .replace(/\n+/g, " ") // Normalize whitespace
+      .trim()
+      .slice(0, 160);
+    sanitizedDescription = escapeHtml(summary);
+  }
+
   const sanitizedBadge = data.badge ? escapeHtml(data.badge) : undefined;
 
   return {

package/dist/CodeBlock-QYIKJMEB.mjs

@@ -1,7 +0,0 @@
-import {
-  CodeBlock
-} from "./chunk-KS5B3O6W.mjs";
-import "./chunk-FMTOYQLO.mjs";
-export {
-  CodeBlock
-};

package/dist/chunk-KS5B3O6W.mjs

@@ -1,43 +0,0 @@
-import {
-  copyToClipboard
-} from "./chunk-FMTOYQLO.mjs";
-
-// src/client/theme/components/CodeBlock/CodeBlock.tsx
-import React, { useState, useRef, useCallback } from "react";
-import { Copy, Check } from "lucide-react";
-import { jsx, jsxs } from "react/jsx-runtime";
-function CodeBlock({ children, ...props }) {
-  const [copied, setCopied] = useState(false);
-  const preRef = useRef(null);
-  let language = "";
-  if (React.isValidElement(children)) {
-    const childProps = children.props;
-    language = childProps?.["data-language"] || "";
-    if (!language && childProps?.className) {
-      const match = childProps.className.match(/language-(\w+)/);
-      if (match) language = match[1];
-    }
-  }
-  const handleCopy = useCallback(async () => {
-    const code = preRef.current?.textContent || "";
-    copyToClipboard(code);
-    setCopied(true);
-    setTimeout(() => setCopied(false), 2e3);
-  }, []);
-  return /* @__PURE__ */ jsxs("div", { className: "code-block-wrapper", children: [
-    /* @__PURE__ */ jsx(
-      "button",
-      {
-        className: `code-block-copy ${copied ? "copied" : ""}`,
-        onClick: handleCopy,
-        "aria-label": "Copy code",
-        children: copied ? /* @__PURE__ */ jsx(Check, { size: 16 }) : /* @__PURE__ */ jsx(Copy, { size: 16 })
-      }
-    ),
-    /* @__PURE__ */ jsx("pre", { ref: preRef, ...props, children })
-  ] });
-}
-
-export {
-  CodeBlock
-};

package/src/client/theme/icons/yarn.tsx

@@ -1,16 +0,0 @@
-import type { SVGProps } from "react";
-
-const Yarn = (props: SVGProps<SVGSVGElement>) => (
-  <svg {...props} viewBox="0 0 256 256">
-    <path
-      fill="#2C8EBB"
-      d="M128 0C57.307 0 0 57.307 0 128s57.307 128 128 128 128-57.307 128-128S198.693 0 128 0zm0 234.667C69.195 234.667 21.333 186.805 21.333 128S69.195 21.333 128 21.333 234.667 69.195 234.667 128 186.805 234.667 128 234.667z"
-    />
-    <path
-      fill="#2C8EBB"
-      d="M173.045 74.053c-4.632-4.632-12.144-4.632-16.776 0L128 102.323l-28.269-28.27c-4.632-4.632-12.144-4.632-16.776 0-4.632 4.632-4.632 12.144 0 16.776L111.224 119.1l-28.269 28.269c-4.632 4.632-4.632 12.144 0 16.776 2.316 2.316 5.352 3.474 8.388 3.474s6.072-1.158 8.388-3.474L128 135.877l28.269 28.268c2.316 2.316 5.352 3.474 8.388 3.474s6.072-1.158 8.388-3.474c4.632-4.632 4.632-12.144 0-16.776L144.776 119.1l28.269-28.271 c4.632-4.632 4.632-12.144 0-16.776z"
-    />
-  </svg>
-);
-
-export { Yarn };