portosaurus 3.0.2 → 4.0.0

package/src/theme/components/Preview/hooks/useAdaptiveSizing.js

@@ -0,0 +1,115 @@
+import { useEffect, useRef } from "react";
+
+/**
+ * Hook for managing responsive sizing, positioning, and adaptive anchoring.
+ * Handles the 3-tier layout logic (Phone, Tablet, Desktop) and window management.
+ */
+export function useAdaptiveSizing({
+  mode,
+  windowWidth,
+  floatingState,
+  dockWidth,
+  peekHeight,
+  setFloatingState,
+}) {
+  // --- Layout calculations (3-Tier Adaptive) ---
+  const isPhone = windowWidth <= 480;
+  const isMobile = windowWidth <= 768;
+  const isTablet = windowWidth > 480 && windowWidth <= 996;
+  const isDesktop = windowWidth > 996;
+
+  const isPopupMode = mode === "popup";
+  const isDockMode = mode === "dock" && isDesktop;
+  const showAsPeek = mode === "dock" && !isDesktop;
+  const isPipMode = mode === "pip";
+
+  // --- Adaptive Positioning (stick to right on resize) ---
+  const prevWidthRef = useRef(windowWidth);
+  useEffect(() => {
+    if (floatingState.x !== null && !isDockMode && !isMobile) {
+      const wasOnRight = floatingState.x > prevWidthRef.current / 2;
+      if (wasOnRight) {
+        const delta = windowWidth - prevWidthRef.current;
+        setFloatingState((prev) => ({ ...prev, x: prev.x + delta }));
+      }
+    }
+    prevWidthRef.current = windowWidth;
+  }, [windowWidth, isDockMode, isMobile, floatingState.x, setFloatingState]);
+
+  // --- Sizing math ---
+  const vh =
+    typeof window !== "undefined" ? document.documentElement.clientHeight : 800;
+
+  // PiP sizing logic
+  const pipWidth = isPhone
+    ? windowWidth
+    : isTablet
+      ? Math.min(600, windowWidth - 60)
+      : floatingState.width;
+
+  const pipHeight = isPhone
+    ? Math.min(floatingState.height, vh * 0.7)
+    : isTablet
+      ? Math.min(450, vh * 0.6)
+      : floatingState.height;
+
+  // Positioning logic
+  const marginX = isPhone ? 0 : 20;
+  const marginY = isPhone ? 0 : 20;
+
+  const defaultPipX = isTablet
+    ? (windowWidth - pipWidth) / 2
+    : isPhone
+      ? 0
+      : Math.max(16, windowWidth - pipWidth - marginX);
+
+  const defaultPipY = isPhone
+    ? vh - pipHeight
+    : Math.max(16, vh - pipHeight - marginY);
+
+  let rndX = floatingState.x ?? defaultPipX;
+  let rndY = floatingState.y ?? defaultPipY;
+
+  // Safety clamping for floating windows (PiP)
+  if (!isDockMode && !isPhone && floatingState.x !== null) {
+    rndX = Math.min(rndX, windowWidth - pipWidth - 10);
+    rndX = Math.max(10, rndX);
+    rndY = Math.min(rndY, vh - pipHeight - 10);
+    rndY = Math.max(10, rndY);
+  }
+
+  const rndPosition = isDockMode
+    ? { x: windowWidth - dockWidth, y: 0 }
+    : showAsPeek
+      ? { x: 0, y: Math.max(0, vh - peekHeight) }
+      : { x: rndX, y: rndY };
+
+  const rndSize = isDockMode
+    ? { width: dockWidth, height: vh }
+    : showAsPeek
+      ? { width: windowWidth, height: peekHeight }
+      : { width: pipWidth, height: pipHeight };
+
+  const rndBounds = isPhone
+    ? { left: 0, top: 0, right: windowWidth, bottom: vh }
+    : isDockMode
+      ? { left: 0, top: 0, right: windowWidth, bottom: vh }
+      : "parent";
+
+  return {
+    isPhone,
+    isMobile,
+    isTablet,
+    isDesktop,
+    isPopupMode,
+    isDockMode,
+    showAsPeek,
+    isPipMode,
+    rndPosition,
+    rndSize,
+    rndBounds,
+    pipWidth,
+    pipHeight,
+    vh,
+  };
+}

package/src/theme/components/Preview/hooks/useDeepLinkHash.js

@@ -1,38 +1,33 @@
-import { useEffect, useRef } from "react";
+import { useEffect } from "react";
 import { generatePvSlug, generatePvHash } from "../utils";
 
 /**
  * Syncs the URL hash with the active preview tab.
  * Also scrolls the active tab element into view.
  */
-export function useDeepLinkHash(
-  isOpen,
-  sources,
-  activeIndex,
-  tabRefs,
-  isDocked,
-) {
+export function useDeepLinkHash(isOpen, sources, activeIndex, mode, baseSlug) {
   useEffect(() => {
     if (!isOpen) return;
 
-    const src = sources[activeIndex];
-    if (src) {
-      const slug = generatePvSlug(src.label, src.path);
-      const newHash = generatePvHash(slug, isDocked);
+    let slug = baseSlug;
+    if (sources && sources.length > 1) {
+      const src = sources[activeIndex];
+      if (src) {
+        // For multi-tab previews, we append a slugified version of the tab's
+        // specific label or filename so each tab has a unique deep link
+        const rawLabel =
+          src.label ||
+          (src.path ? src.path.split(/[?#]/)[0].split("/").pop() : "tab");
+        const tabSlug = generatePvSlug(rawLabel);
+        slug = baseSlug ? `${baseSlug}-${tabSlug}` : tabSlug;
+      }
+    }
 
+    if (slug) {
+      const newHash = generatePvHash(slug, mode);
       if (window.location.hash !== `#${newHash}`) {
         window.history.replaceState(null, "", `#${newHash}`);
       }
     }
-
-    // Scroll active tab into view
-    const activeTabEl = tabRefs.current?.[activeIndex];
-    if (activeTabEl) {
-      activeTabEl.scrollIntoView({
-        behavior: "smooth",
-        block: "nearest",
-        inline: "center",
-      });
-    }
-  }, [activeIndex, isOpen, sources, isDocked]);
+  }, [activeIndex, isOpen, sources, mode, baseSlug]);
 }

package/src/theme/components/Preview/hooks/useDockLayout.js

@@ -7,17 +7,28 @@ import { useEffect, useRef } from "react";
  * - Collapses/expands the Docusaurus sidebar
  * - Tracks navbar height for dock top offset
  */
-export function useDockLayout(isOpen, isDocked, dockWidth) {
+export function useDockLayout({
+  isOpen,
+  isPopupMode,
+  isSidebarDock,
+  isPeekDock,
+  dockWidth,
+  peekHeight,
+}) {
   const weCollapsedSidebar = useRef(false);
 
   useEffect(() => {
     if (typeof document === "undefined") return;
 
-    const isMobile = window.innerWidth <= 768;
-    const desktopDockActive = isOpen && isDocked && !isMobile;
+    // --- Popup scroll lock ---
+    if (isOpen && isPopupMode) {
+      document.body.style.overflow = "hidden";
+    } else {
+      document.body.style.overflow = "";
+    }
 
     // --- Body classes & CSS vars ---
-    if (desktopDockActive) {
+    if (isSidebarDock) {
       document.body.classList.add("pv-dock-active");
       document.body.style.setProperty("--pv-dock-width", `${dockWidth}px`);
     } else {
@@ -25,6 +36,17 @@ export function useDockLayout(isOpen, isDocked, dockWidth) {
       document.body.style.setProperty("--pv-dock-width", "0px");
     }
 
+    if (isPeekDock) {
+      document.body.classList.add("pv-peek-active");
+      document.body.style.setProperty(
+        "--mobile-peek-height",
+        `${peekHeight}px`,
+      );
+    } else {
+      document.body.classList.remove("pv-peek-active");
+      document.body.style.setProperty("--mobile-peek-height", "0px");
+    }
+
     // --- Docusaurus sidebar auto-collapse ---
     const sidebarToggleBtn = document.querySelector(
       '[class*="collapseSidebarButton"]',
@@ -33,7 +55,7 @@ export function useDockLayout(isOpen, isDocked, dockWidth) {
       '[aria-label="Expand sidebar"]',
     );
 
-    if (desktopDockActive) {
+    if (isSidebarDock) {
       if (sidebarToggleBtn && !isCollapsed) {
         weCollapsedSidebar.current = true;
         sidebarToggleBtn.click();
@@ -56,15 +78,33 @@ export function useDockLayout(isOpen, isDocked, dockWidth) {
       }
     };
 
-    if (desktopDockActive) {
+    if (isSidebarDock) {
       updateNavOffset();
       window.addEventListener("resize", updateNavOffset, { passive: true });
     }
 
     return () => {
       document.body.classList.remove("pv-dock-active");
-      document.documentElement.style.removeProperty("--dock-top-offset");
+      document.body.classList.remove("pv-peek-active");
+      document.body.style.overflow = "";
+      document.body.style.removeProperty("--pv-dock-width");
+      document.body.style.removeProperty("--mobile-peek-height");
+
+      // Explicitly restore sidebar if we were the ones who collapsed it
+      // This prevents Docusaurus from "remembering" the collapsed state after reload
+      if (weCollapsedSidebar.current) {
+        const sidebarToggleBtn = document.querySelector(
+          '[class*="collapseSidebarButton"]',
+        );
+        const isCollapsed = !!document.querySelector(
+          '[aria-label="Expand sidebar"]',
+        );
+        if (sidebarToggleBtn && isCollapsed) {
+          sidebarToggleBtn.click();
+        }
+        weCollapsedSidebar.current = false;
+      }
       window.removeEventListener("resize", updateNavOffset);
     };
-  }, [isOpen, isDocked, dockWidth]);
+  }, [isOpen, isPopupMode, isSidebarDock, isPeekDock, dockWidth, peekHeight]);
 }

package/src/theme/components/Preview/hooks/useTouchZoom.js

@@ -0,0 +1,118 @@
+import { useEffect } from "react";
+import styles from "../styles.module.css";
+
+/**
+ * Hook for managing touch interactions:
+ * - Pinch-to-zoom (touch)
+ * - Trackpad zooming (ctrl + wheel)
+ * - Click-and-drag panning
+ */
+export function useTouchZoom({
+  containerRef,
+  isOpen,
+  zoomLevel,
+  setZoomLevel,
+}) {
+  useEffect(() => {
+    const el = containerRef.current;
+    if (!el || !isOpen) return;
+
+    let initialDistance = null;
+    let initialZoom = zoomLevel;
+
+    const getDistance = (touches) => {
+      return Math.hypot(
+        touches[0].clientX - touches[1].clientX,
+        touches[0].clientY - touches[1].clientY,
+      );
+    };
+
+    const handleWheel = (e) => {
+      if (e.ctrlKey) {
+        e.preventDefault();
+        const delta = -e.deltaY * 0.01;
+        setZoomLevel((prev) => Math.min(Math.max(0.5, prev + delta), 3.0));
+      }
+    };
+
+    const handleTouchStart = (e) => {
+      if (e.touches.length === 2) {
+        initialDistance = getDistance(e.touches);
+        setZoomLevel((prev) => {
+          initialZoom = prev;
+          return prev;
+        });
+      }
+    };
+
+    const handleTouchMove = (e) => {
+      if (e.touches.length === 2 && initialDistance) {
+        e.preventDefault();
+        const currentDistance = getDistance(e.touches);
+        const ratio = currentDistance / initialDistance;
+        setZoomLevel(Math.min(Math.max(0.5, initialZoom * ratio), 3.0));
+      }
+    };
+
+    const handleTouchEnd = (e) => {
+      if (e.touches.length < 2) {
+        initialDistance = null;
+      }
+    };
+
+    // --- Mouse Click-and-Drag Panning ---
+    let isPanning = false;
+    let startX = 0;
+    let startY = 0;
+    let initialScrollLeft = 0;
+    let initialScrollTop = 0;
+
+    const handleMouseDown = (e) => {
+      if (e.button !== 0) return;
+      isPanning = true;
+      startX = e.pageX;
+      startY = e.pageY;
+      initialScrollLeft = el.scrollLeft;
+      initialScrollTop = el.scrollTop;
+      el.classList.add(styles.isPanning);
+      document.body.classList.add(styles.isPanning);
+    };
+
+    const handleMouseMove = (e) => {
+      if (!isPanning) return;
+      e.preventDefault();
+      const x = e.pageX;
+      const y = e.pageY;
+      const walkX = (x - startX) * 1;
+      const walkY = (y - startY) * 1;
+      el.scrollLeft = initialScrollLeft - walkX;
+      el.scrollTop = initialScrollTop - walkY;
+    };
+
+    const handleMouseUpOrLeave = () => {
+      isPanning = false;
+      el.classList.remove(styles.isPanning);
+      document.body.classList.remove(styles.isPanning);
+    };
+
+    el.addEventListener("wheel", handleWheel, { passive: false });
+    el.addEventListener("touchstart", handleTouchStart, { passive: false });
+    el.addEventListener("touchmove", handleTouchMove, { passive: false });
+    el.addEventListener("touchend", handleTouchEnd);
+    el.addEventListener("mousedown", handleMouseDown);
+    el.addEventListener("mousemove", handleMouseMove);
+    el.addEventListener("mouseup", handleMouseUpOrLeave);
+    el.addEventListener("mouseleave", handleMouseUpOrLeave);
+
+    return () => {
+      el.removeEventListener("wheel", handleWheel);
+      el.removeEventListener("touchstart", handleTouchStart);
+      el.removeEventListener("touchmove", handleTouchMove);
+      el.removeEventListener("touchend", handleTouchEnd);
+      el.removeEventListener("mousedown", handleMouseDown);
+      el.removeEventListener("mousemove", handleMouseMove);
+      el.removeEventListener("mouseup", handleMouseUpOrLeave);
+      el.removeEventListener("mouseleave", handleMouseUpOrLeave);
+    };
+  }, [isOpen, setZoomLevel, containerRef, zoomLevel]);
+}

package/src/theme/components/Preview/renderers/CodeRenderer.js

@@ -5,8 +5,9 @@ import { Highlight } from "prism-react-renderer";
 /**
  * Self-contained code highlighter using prism-react-renderer.
  * Reads the Prism theme directly from Docusaurus site config.
+ * Safe to use in Root.js because it doesn't depend on Docusaurus context providers.
  */
-export default function CodeRenderer({ code, language }) {
+export default function CodeRenderer({ code, language, zoomLevel = 1.0 }) {
   const { siteConfig } = useDocusaurusContext();
   const isDark =
     typeof document !== "undefined" &&
@@ -15,8 +16,18 @@ export default function CodeRenderer({ code, language }) {
   const prismConfig = siteConfig?.themeConfig?.prism || {};
   const prismTheme = isDark ? prismConfig.darkTheme : prismConfig.theme;
 
+  // Normalize language (Prism uses 'diff' for both .diff and .patch)
+  const normalizedLanguage = language === "patch" ? "diff" : language || "text";
+
   return (
-    <Highlight code={code} language={language || "text"} theme={prismTheme}>
+    <Highlight
+      code={code}
+      language={normalizedLanguage}
+      theme={prismTheme}
+      {...(typeof window !== "undefined" && window.Prism
+        ? { prism: window.Prism }
+        : {})}
+    >
       {({ className, style, tokens, getLineProps, getTokenProps }) => (
         <pre
           className={className}
@@ -25,37 +36,65 @@ export default function CodeRenderer({ code, language }) {
             margin: 0,
             borderRadius: 0,
             padding: "14px 0",
-            fontSize: "0.85rem",
+            fontSize: `calc(0.85rem * ${zoomLevel})`,
             lineHeight: 1.6,
             minHeight: "100%",
             background: "var(--ifm-background-color)",
           }}
         >
-          {tokens.map((line, i) => (
-            <div
-              key={i}
-              {...getLineProps({ line })}
-              style={{ display: "flex" }}
-            >
-              <span
+          {tokens.map((line, i) => {
+            const lineProps = getLineProps({ line });
+            const lineContent = line.map((t) => t.content).join("");
+
+            // --- Robust Diff Highlighting ---
+            let diffStyle = {};
+            if (normalizedLanguage === "diff") {
+              if (lineContent.startsWith("+")) {
+                diffStyle = {
+                  background: "rgba(var(--ifm-color-success-rgb), 0.15)",
+                  borderLeft: "3px solid var(--ifm-color-success)",
+                };
+              } else if (lineContent.startsWith("-")) {
+                diffStyle = {
+                  background: "rgba(var(--ifm-color-danger-rgb), 0.15)",
+                  borderLeft: "3px solid var(--ifm-color-danger)",
+                };
+              }
+            }
+
+            return (
+              <div
+                key={i}
+                {...lineProps}
                 style={{
-                  display: "inline-block",
-                  width: "3em",
-                  paddingLeft: "14px",
-                  userSelect: "none",
-                  opacity: 0.4,
-                  flexShrink: 0,
+                  ...lineProps.style,
+                  ...diffStyle,
+                  display: "flex",
+                  paddingLeft: diffStyle.borderLeft ? "0px" : "3px",
                 }}
               >
-                {i + 1}
-              </span>
-              <span style={{ paddingRight: "14px" }}>
-                {line.map((token, key) => (
-                  <span key={key} {...getTokenProps({ token })} />
-                ))}
-              </span>
-            </div>
-          ))}
+                <span
+                  style={{
+                    display: "inline-block",
+                    width: "1.7em",
+                    textAlign: "right",
+                    marginRight: "12px",
+                    userSelect: "none",
+                    opacity: 0.35,
+                    flexShrink: 0,
+                    fontFamily: "var(--ifm-font-family-monospace)",
+                  }}
+                >
+                  {i + 1}
+                </span>
+                <span style={{ paddingRight: "14px", flex: 1 }}>
+                  {line.map((token, key) => (
+                    <span key={key} {...getTokenProps({ token })} />
+                  ))}
+                </span>
+              </div>
+            );
+          })}
         </pre>
       )}
     </Highlight>

package/src/theme/components/Preview/state/index.js

@@ -2,14 +2,14 @@ import { createContext, useContext, useReducer, useCallback } from "react";
 
 const PreviewContext = createContext(null);
 
-const DEFAULT_SIZE = { width: 720, height: 500 };
+const DEFAULT_SIZE = { width: 720, height: 400 };
 const DEFAULT_DOCK_PERCENTAGE = 0.42; // 42% of viewport width
 
 function getInitialState() {
   if (typeof window === "undefined") {
     return {
       isOpen: false,
-      isDocked: false,
+      mode: "popup",
       dockWidth: 420,
     };
   }
@@ -26,10 +26,13 @@ function getInitialState() {
 
   return {
     isOpen: false,
-    isDocked: false,
+    mode: "popup",
     dockWidth: defaultDockWidth,
+    peekHeight: typeof window !== "undefined" ? window.innerHeight * 0.42 : 400,
     sources: [],
     activeIndex: 0,
+    baseSlug: null,
+    modeSwitch: true,
     floatingState: {
       width: DEFAULT_SIZE.width,
       height: DEFAULT_SIZE.height,
@@ -45,22 +48,40 @@ function reducer(state, action) {
       return {
         ...state,
         isOpen: true,
+        mode: action.mode || "popup",
         sources: action.sources,
         activeIndex: action.index ?? 0,
+        baseSlug: action.baseSlug,
+        modeSwitch: action.modeSwitch ?? true,
       };
     case "CLOSE":
-      return { ...state, isOpen: false, isDocked: false };
-    case "SET_DOCKED":
-      return { ...state, isDocked: action.value };
+      return {
+        ...state,
+        isOpen: false,
+        mode: "popup",
+        baseSlug: null,
+        modeSwitch: true,
+      };
+    case "SET_MODE":
+      return { ...state, mode: action.mode };
     case "SET_ACTIVE_INDEX":
       return { ...state, activeIndex: action.index };
     case "SET_DOCK_WIDTH":
       return { ...state, dockWidth: action.width };
+    case "SET_PEEK_HEIGHT":
+      return { ...state, peekHeight: action.height };
     case "SET_FLOATING_STATE":
       return {
         ...state,
         floatingState: { ...state.floatingState, ...action.state },
       };
+    case "TOGGLE_MODE": {
+      let nextMode = "popup";
+      if (state.mode === "popup") nextMode = "dock";
+      else if (state.mode === "dock") nextMode = "pip";
+      else if (state.mode === "pip") nextMode = "dock";
+      return { ...state, mode: nextMode };
+    }
     default:
       return state;
   }
@@ -69,12 +90,29 @@ function reducer(state, action) {
 export function PreviewProvider({ children }) {
   const [state, dispatch] = useReducer(reducer, undefined, getInitialState);
 
-  const openPreview = useCallback((sources, index = 0, hashId = null) => {
-    if (hashId && typeof window !== "undefined") {
-      window.history.replaceState(null, null, "#" + hashId);
-    }
-    dispatch({ type: "OPEN", sources, index });
-  }, []);
+  const openPreview = useCallback(
+    (
+      sources,
+      index = 0,
+      hashId = null,
+      mode = "popup",
+      baseSlug = null,
+      modeSwitch = true,
+    ) => {
+      if (hashId && typeof window !== "undefined") {
+        window.history.replaceState(null, null, "#" + hashId);
+      }
+      dispatch({
+        type: "OPEN",
+        sources,
+        index,
+        mode,
+        baseSlug,
+        modeSwitch,
+      });
+    },
+    [],
+  );
 
   const closePreview = useCallback(() => {
     if (typeof window !== "undefined") {
@@ -87,8 +125,8 @@ export function PreviewProvider({ children }) {
     dispatch({ type: "CLOSE" });
   }, []);
 
-  const setDocked = useCallback((val) => {
-    dispatch({ type: "SET_DOCKED", value: val });
+  const setMode = useCallback((mode) => {
+    dispatch({ type: "SET_MODE", mode });
   }, []);
 
   const setActiveIndex = useCallback((index) => {
@@ -99,20 +137,30 @@ export function PreviewProvider({ children }) {
     dispatch({ type: "SET_DOCK_WIDTH", width });
   }, []);
 
+  const setPeekHeight = useCallback((height) => {
+    dispatch({ type: "SET_PEEK_HEIGHT", height });
+  }, []);
+
   const setFloatingState = useCallback((newState) => {
     dispatch({ type: "SET_FLOATING_STATE", state: newState });
   }, []);
 
+  const toggleMode = useCallback(() => {
+    dispatch({ type: "TOGGLE_MODE" });
+  }, []);
+
   return (
     <PreviewContext.Provider
       value={{
         ...state,
         openPreview,
         closePreview,
-        setDocked,
+        setMode,
         setActiveIndex,
         setDockWidth,
+        setPeekHeight,
         setFloatingState,
+        toggleMode,
       }}
     >
       {children}
@@ -122,17 +170,22 @@ export function PreviewProvider({ children }) {
 
 const DEFAULT_CTX = {
   isOpen: false,
-  isDocked: false,
+  mode: "popup",
   dockWidth: 420,
+  peekHeight: 400,
   sources: [],
   activeIndex: 0,
+  baseSlug: null,
+  modeSwitch: true,
   floatingState: { x: null, y: null, width: 800, height: 600 },
   openPreview: () => {},
   closePreview: () => {},
-  setDocked: () => {},
+  setMode: () => {},
   setActiveIndex: () => {},
   setDockWidth: () => {},
+  setPeekHeight: () => {},
   setFloatingState: () => {},
+  toggleMode: () => {},
 };
 
 export function usePreview() {