From dc046febb7e856aff110d507c64efb25bd5b80cc Mon Sep 17 00:00:00 2001
From: Thomas <thomas.whyyou@gmail.com>
Date: Tue, 24 Mar 2026 18:50:22 -0400
Subject: [PATCH 1/3] add a keybinding on ctrl to toggle the isCollapsed state

---
 .../guide/components/Toolbar/V2/V2.tsx        | 27 +++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/packages/react/src/modules/guide/components/Toolbar/V2/V2.tsx b/packages/react/src/modules/guide/components/Toolbar/V2/V2.tsx
index 096daaeab..88d0285bc 100644
--- a/packages/react/src/modules/guide/components/Toolbar/V2/V2.tsx
+++ b/packages/react/src/modules/guide/components/Toolbar/V2/V2.tsx
@@ -105,6 +105,33 @@ export const V2 = () => {
     };
   }, [runConfig, client, setDisplayOption]);
 
+  // Toggle collapsed state when Ctrl is pressed and released alone
+  // (without combining with another key), similar to Vercel's toolbar.
+  React.useEffect(() => {
+    let ctrlUsedInCombo = false;
+
+    const handleKeyDown = (e: KeyboardEvent) => {
+      if (e.key === "Control") {
+        ctrlUsedInCombo = false;
+      } else if (e.ctrlKey) {
+        ctrlUsedInCombo = true;
+      }
+    };
+
+    const handleKeyUp = (e: KeyboardEvent) => {
+      if (e.key === "Control" && !ctrlUsedInCombo) {
+        setIsCollapsed((prev) => !prev);
+      }
+    };
+
+    window.addEventListener("keydown", handleKeyDown);
+    window.addEventListener("keyup", handleKeyUp);
+    return () => {
+      window.removeEventListener("keydown", handleKeyDown);
+      window.removeEventListener("keyup", handleKeyUp);
+    };
+  }, []);
+
   const containerRef = React.useRef<HTMLDivElement>(null);
   const { position, isDragging, handlePointerDown, hasDraggedRef } =
     useDraggable({

From e55eb348119c9b13eea37fb1173072e225a30772 Mon Sep 17 00:00:00 2001
From: Thomas <thomas.whyyou@gmail.com>
Date: Wed, 25 Mar 2026 11:03:39 -0400
Subject: [PATCH 2/3] add animation effect for guide toolbar v2 when collapse
 and expand

---
 .../guide/components/Toolbar/V2/V2.tsx        |  2 ++
 .../guide/components/Toolbar/styles.css       | 22 +++++++++++++++++++
 2 files changed, 24 insertions(+)

diff --git a/packages/react/src/modules/guide/components/Toolbar/V2/V2.tsx b/packages/react/src/modules/guide/components/Toolbar/V2/V2.tsx
index 88d0285bc..017b8a907 100644
--- a/packages/react/src/modules/guide/components/Toolbar/V2/V2.tsx
+++ b/packages/react/src/modules/guide/components/Toolbar/V2/V2.tsx
@@ -169,6 +169,7 @@ export const V2 = () => {
             cursor: isDragging ? "grabbing" : "grab",
             touchAction: "none",
             userSelect: "none",
+            animation: "toolbar-collapse-fade-in 150ms ease-out",
           }}
         >
           <Box
@@ -197,6 +198,7 @@ export const V2 = () => {
           style={{
             width: TOOLBAR_WIDTH,
             boxShadow: "0 8px 32px var(--tgph-gray-5)",
+            animation: "toolbar-expand-fade-in 150ms ease-out",
           }}
         >
           {/* Header — also acts as drag handle area */}
diff --git a/packages/react/src/modules/guide/components/Toolbar/styles.css b/packages/react/src/modules/guide/components/Toolbar/styles.css
index 504afefe7..de3d2c23d 100644
--- a/packages/react/src/modules/guide/components/Toolbar/styles.css
+++ b/packages/react/src/modules/guide/components/Toolbar/styles.css
@@ -1,2 +1,24 @@
 @telegraph tokens;
 @telegraph components;
+
+/* Animation effect for toolbar V2 when expanding and collapsing. */
+@keyframes toolbar-collapse-fade-in {
+  from {
+    opacity: 0;
+    transform: scale(0.8);
+  }
+  to {
+    opacity: 1;
+    transform: scale(1);
+  }
+}
+@keyframes toolbar-expand-fade-in {
+  from {
+    opacity: 0;
+    transform: scale(0.95);
+  }
+  to {
+    opacity: 1;
+    transform: scale(1);
+  }
+}

From b74abb9f06aca24a18a2aff802e2447fbe8b18a6 Mon Sep 17 00:00:00 2001
From: Thomas <thomas.whyyou@gmail.com>
Date: Wed, 25 Mar 2026 12:35:21 -0400
Subject: [PATCH 3/3] add tooltip for the guide toolbar V2 expand/collapse
 hotkey

---
 .../guide/components/Toolbar/V2/V2.tsx        | 80 ++++++++++++-------
 1 file changed, 53 insertions(+), 27 deletions(-)

diff --git a/packages/react/src/modules/guide/components/Toolbar/V2/V2.tsx b/packages/react/src/modules/guide/components/Toolbar/V2/V2.tsx
index 017b8a907..2f97e0844 100644
--- a/packages/react/src/modules/guide/components/Toolbar/V2/V2.tsx
+++ b/packages/react/src/modules/guide/components/Toolbar/V2/V2.tsx
@@ -32,6 +32,22 @@ import {
 
 const TOOLBAR_WIDTH = "540px";
 
+const Kbd = ({ children }: { children: React.ReactNode }) => {
+  return (
+    <kbd
+      style={{
+        display: "inline-block",
+        padding: "1px 4px",
+        borderRadius: "var(--tgph-rounded-2)",
+        border: "1px solid rgba(255, 255, 255, 0.3)",
+        backgroundColor: "rgba(255, 255, 255, 0.15)",
+      }}
+    >
+      {children}
+    </kbd>
+  );
+};
+
 type DisplayOption = "all-guides" | "only-eligible" | "only-displayable";
 
 const GuidesList = ({
@@ -156,38 +172,48 @@ export const V2 = () => {
       }}
     >
       {isCollapsed ? (
-        <Stack
-          border="px"
-          rounded="4"
-          align="center"
-          justify="center"
-          w="10"
-          h="10"
-          onPointerDown={handlePointerDown}
-          backgroundColor="surface-1"
-          style={{
-            cursor: isDragging ? "grabbing" : "grab",
-            touchAction: "none",
-            userSelect: "none",
-            animation: "toolbar-collapse-fade-in 150ms ease-out",
-          }}
+        <Tooltip
+          side="left"
+          delayDuration={500}
+          label={
+            <Text as="span" size="1">
+              Guide Toolbar <Kbd>ctrl</Kbd>
+            </Text>
+          }
         >
-          <Box
+          <Stack
+            border="px"
+            rounded="4"
+            align="center"
+            justify="center"
+            w="10"
+            h="10"
+            onPointerDown={handlePointerDown}
+            backgroundColor="surface-1"
             style={{
-              transform: "scale(0.7)",
-              transformOrigin: "center center",
+              cursor: isDragging ? "grabbing" : "grab",
+              touchAction: "none",
+              userSelect: "none",
+              animation: "toolbar-collapse-fade-in 150ms ease-out",
             }}
           >
-            <KnockButton
-              onClick={() => {
-                if (!hasDraggedRef.current) {
-                  setIsCollapsed(false);
-                }
+            <Box
+              style={{
+                transform: "scale(0.7)",
+                transformOrigin: "center center",
               }}
-              positioned={false}
-            />
-          </Box>
-        </Stack>
+            >
+              <KnockButton
+                onClick={() => {
+                  if (!hasDraggedRef.current) {
+                    setIsCollapsed(false);
+                  }
+                }}
+                positioned={false}
+              />
+            </Box>
+          </Stack>
+        </Tooltip>
       ) : (
         <Stack
           direction="column"