From 1cc93da83dc3d87fc88e5f1fc2366df640edf98b Mon Sep 17 00:00:00 2001
From: Camiel van Schoonhoven <camiel.vanschoonhoven@shopify.com>
Date: Mon, 29 Sep 2025 17:18:44 -0700
Subject: [PATCH] Add debug mode for viewing ReactFlow Node ids

---
 .env.example                                  |  5 +-
 .../ReactFlow/FlowCanvas/IONode/IONode.tsx    | 38 ++++++--
 .../TaskNode/TaskNodeCard/Handles.tsx         | 89 ++++++++++++-------
 .../TaskNode/TaskNodeCard/TaskNodeCard.tsx    | 60 ++++++++-----
 src/components/ui/tooltip.tsx                 |  6 ++
 src/utils/constants.ts                        |  3 +
 6 files changed, 136 insertions(+), 65 deletions(-)

diff --git a/.env.example b/.env.example
index ae9807efa..7e618dd4f 100644
--- a/.env.example
+++ b/.env.example
@@ -17,4 +17,7 @@ VITE_ENABLE_GOOGLE_CLOUD_SUBMITTER=<boolean>
 
 # Github
 VITE_REQUIRE_AUTHORIZATION=<boolean>
-VITE_GITHUB_CLIENT_ID=<string>
\ No newline at end of file
+VITE_GITHUB_CLIENT_ID=<string>
+
+# Dev Tools
+VITE_ENABLE_DEBUG_MODE=<boolean>
\ No newline at end of file
diff --git a/src/components/shared/ReactFlow/FlowCanvas/IONode/IONode.tsx b/src/components/shared/ReactFlow/FlowCanvas/IONode/IONode.tsx
index aae6b9336..5a2b7ae3f 100644
--- a/src/components/shared/ReactFlow/FlowCanvas/IONode/IONode.tsx
+++ b/src/components/shared/ReactFlow/FlowCanvas/IONode/IONode.tsx
@@ -6,6 +6,11 @@ import { OutputNameEditor } from "@/components/Editor/IOEditor/OutputNameEditor"
 import { getOutputConnectedDetails } from "@/components/Editor/utils/getOutputConnectedDetails";
 import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
 import { BlockStack, InlineStack } from "@/components/ui/layout";
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipTrigger,
+} from "@/components/ui/tooltip";
 import { Paragraph } from "@/components/ui/typography";
 import { useNodeManager } from "@/hooks/useNodeManager";
 import { cn } from "@/lib/utils";
@@ -13,6 +18,7 @@ import { useComponentSpec } from "@/providers/ComponentSpecProvider";
 import { useContextPanel } from "@/providers/ContextPanelProvider";
 import type { IONodeData } from "@/types/nodes";
 import { isInputSpec, typeSpecToString } from "@/utils/componentSpec";
+import { ENABLE_DEBUG_MODE } from "@/utils/constants";
 
 interface IONodeProps {
   type: "input" | "output";
@@ -24,7 +30,7 @@ interface IONodeProps {
 const IONode = ({ type, data, selected = false }: IONodeProps) => {
   const { currentGraphSpec, currentSubgraphSpec } = useComponentSpec();
   const { setContent, clearContent } = useContextPanel();
-  const { getHandleNodeId } = useNodeManager();
+  const { getNodeId, getHandleNodeId } = useNodeManager();
 
   const { spec, readOnly } = data;
 
@@ -51,6 +57,7 @@ const IONode = ({ type, data, selected = false }: IONodeProps) => {
     [currentSubgraphSpec.outputs, spec.name],
   );
 
+  const nodeId = getNodeId(spec.name, type);
   const handleNodeType = isInput ? "handle-out" : "handle-in";
   const nodeHandleId = getHandleNodeId(spec.name, spec.name, handleNodeType);
 
@@ -107,6 +114,11 @@ const IONode = ({ type, data, selected = false }: IONodeProps) => {
     <Card className={cn("border-2 max-w-[300px] p-0", borderColor)}>
       <CardHeader className="px-2 py-2.5">
         <CardTitle className="break-words">{spec.name}</CardTitle>
+        {ENABLE_DEBUG_MODE && (
+          <Paragraph size="xs" tone="subdued">
+            Node Id: {nodeId}
+          </Paragraph>
+        )}
       </CardHeader>
       <CardContent className="p-2 max-w-[250px]">
         <BlockStack gap="2">
@@ -141,12 +153,24 @@ const IONode = ({ type, data, selected = false }: IONodeProps) => {
             </Paragraph>
           </InlineStack>
         </BlockStack>
-        <Handle
-          id={nodeHandleId}
-          type={handleType}
-          position={handlePosition}
-          className={cn(handleDefaultClassName, handleClassName)}
-        />
+        <Tooltip>
+          <TooltipTrigger asChild>
+            <Handle
+              id={nodeHandleId}
+              type={handleType}
+              position={handlePosition}
+              className={cn(handleDefaultClassName, handleClassName)}
+            />
+          </TooltipTrigger>
+          <TooltipContent disabled={!ENABLE_DEBUG_MODE}>
+            <div className="capitalize">
+              {type} Name: {spec.name}
+            </div>
+            <div>Handle Name: {spec.name}</div>
+            <div>parentNodeId: {nodeId}</div>
+            <div>handleNodeId: {nodeHandleId}</div>
+          </TooltipContent>
+        </Tooltip>
       </CardContent>
     </Card>
   );
diff --git a/src/components/shared/ReactFlow/FlowCanvas/TaskNode/TaskNodeCard/Handles.tsx b/src/components/shared/ReactFlow/FlowCanvas/TaskNode/TaskNodeCard/Handles.tsx
index 2a04b8f10..26aaa51bd 100644
--- a/src/components/shared/ReactFlow/FlowCanvas/TaskNode/TaskNodeCard/Handles.tsx
+++ b/src/components/shared/ReactFlow/FlowCanvas/TaskNode/TaskNodeCard/Handles.tsx
@@ -15,6 +15,7 @@ import { useNodeManager } from "@/hooks/useNodeManager";
 import { cn } from "@/lib/utils";
 import { useTaskNode } from "@/providers/TaskNodeProvider";
 import type { InputSpec, OutputSpec } from "@/utils/componentSpec";
+import { ENABLE_DEBUG_MODE } from "@/utils/constants";
 
 type InputHandleProps = {
   input: InputSpec;
@@ -34,7 +35,7 @@ export const InputHandle = ({
   onHandleSelectionChange,
 }: InputHandleProps) => {
   const { getInputHandleNodeId } = useNodeManager();
-  const { taskId, nodeId, state } = useTaskNode();
+  const { taskId, nodeId, state, name } = useTaskNode();
 
   const fromHandle = useConnection((connection) => connection.fromHandle?.id);
   const toHandle = useConnection((connection) => connection.toHandle?.id);
@@ -131,23 +132,33 @@ export const InputHandle = ({
       data-active={active}
     >
       <div className="absolute -translate-x-6 flex items-center h-3 w-3">
-        <Handle
-          ref={handleRef}
-          type="target"
-          id={handleId}
-          position={Position.Left}
-          isConnectable={true}
-          className={cn(
-            "border-0! h-full! w-full! transform-none!",
-            missing,
-            (selected || active) && "bg-blue-500!",
-            highlight && "bg-green-500!",
-            state.readOnly && "cursor-pointer!",
-          )}
-          onClick={handleHandleClick}
-          data-invalid={invalid}
-          data-testid={`input-handle-${input.name}`}
-        />
+        <Tooltip>
+          <TooltipTrigger asChild>
+            <Handle
+              ref={handleRef}
+              type="target"
+              id={handleId}
+              position={Position.Left}
+              isConnectable={true}
+              className={cn(
+                "border-0! h-full! w-full! transform-none!",
+                missing,
+                (selected || active) && "bg-blue-500!",
+                highlight && "bg-green-500!",
+                state.readOnly && "cursor-pointer!",
+              )}
+              onClick={handleHandleClick}
+              data-invalid={invalid}
+              data-testid={`input-handle-${input.name}`}
+            />
+          </TooltipTrigger>
+          <TooltipContent disabled={!ENABLE_DEBUG_MODE}>
+            <div>Task Name: {name}</div>
+            <div>Handle Name: {input.name}</div>
+            <div>parentNodeId: {nodeId}</div>
+            <div>handleNodeId: {handleId}</div>
+          </TooltipContent>
+        </Tooltip>
       </div>
       <div
         className={cn(
@@ -221,7 +232,7 @@ export const OutputHandle = ({
   onHandleSelectionChange,
 }: OutputHandleProps) => {
   const { getOutputHandleNodeId } = useNodeManager();
-  const { taskId, nodeId, state } = useTaskNode();
+  const { taskId, nodeId, state, name } = useTaskNode();
 
   const fromHandle = useConnection((connection) => connection.fromHandle?.id);
   const toHandle = useConnection((connection) => connection.toHandle?.id);
@@ -339,21 +350,31 @@ export const OutputHandle = ({
           </div>
         )}
       </div>
-      <Handle
-        ref={handleRef}
-        type="source"
-        id={handleId}
-        position={Position.Right}
-        isConnectable={true}
-        onClick={handleHandleClick}
-        className={cn(
-          "relative! border-0! !w-[12px] !h-[12px] transform-none! translate-x-6 cursor-pointer bg-gray-500!",
-          (selected || active) && "bg-blue-500!",
-          highlight && "bg-green-500!",
-          state.readOnly && "cursor-pointer!",
-        )}
-        data-testid={`output-handle-${output.name}`}
-      />
+      <Tooltip>
+        <TooltipTrigger asChild>
+          <Handle
+            ref={handleRef}
+            type="source"
+            id={handleId}
+            position={Position.Right}
+            isConnectable={true}
+            onClick={handleHandleClick}
+            className={cn(
+              "relative! border-0! !w-[12px] !h-[12px] transform-none! translate-x-6 cursor-pointer bg-gray-500!",
+              (selected || active) && "bg-blue-500!",
+              highlight && "bg-green-500!",
+              state.readOnly && "cursor-pointer!",
+            )}
+            data-testid={`output-handle-${output.name}`}
+          />
+        </TooltipTrigger>
+        <TooltipContent disabled={!ENABLE_DEBUG_MODE}>
+          <div>Task Name: {name}</div>
+          <div>Handle Name: {output.name}</div>
+          <div>parentNodeId: {nodeId}</div>
+          <div>handleNodeId: {handleId}</div>
+        </TooltipContent>
+      </Tooltip>
     </div>
   );
 };
diff --git a/src/components/shared/ReactFlow/FlowCanvas/TaskNode/TaskNodeCard/TaskNodeCard.tsx b/src/components/shared/ReactFlow/FlowCanvas/TaskNode/TaskNodeCard/TaskNodeCard.tsx
index e76d6a1f4..bc3f9f655 100644
--- a/src/components/shared/ReactFlow/FlowCanvas/TaskNode/TaskNodeCard/TaskNodeCard.tsx
+++ b/src/components/shared/ReactFlow/FlowCanvas/TaskNode/TaskNodeCard/TaskNodeCard.tsx
@@ -17,6 +17,7 @@ import { useComponentSpec } from "@/providers/ComponentSpecProvider";
 import { useContextPanel } from "@/providers/ContextPanelProvider";
 import { useTaskNode } from "@/providers/TaskNodeProvider";
 import { isCacheDisabled } from "@/utils/cache";
+import { ENABLE_DEBUG_MODE } from "@/utils/constants";
 import { getSubgraphDescription, isSubgraph } from "@/utils/subgraphUtils";
 
 import {
@@ -254,25 +255,40 @@ const TaskNodeCard = () => {
         ref={nodeRef}
         onDoubleClick={handleDoubleClick}
       >
-        <CardHeader className="border-b border-slate-200 px-2 py-2.5 flex flex-row justify-between items-start">
+        <CardHeader className="border-b border-slate-200 px-2 py-2.5 items-start">
           <BlockStack>
-            <InlineStack gap="2" blockAlign="center" wrap="nowrap">
-              {isSubgraphNode && isSubgraphNavigationEnabled && (
-                <QuickTooltip content={`Subgraph: ${subgraphDescription}`}>
-                  <Icon name="Workflow" size="sm" className="text-blue-600" />
-                </QuickTooltip>
+            <InlineStack
+              gap="2"
+              align="space-between"
+              blockAlign="start"
+              wrap="nowrap"
+              className="w-full"
+            >
+              <InlineStack gap="2" blockAlign="center" wrap="nowrap">
+                {isSubgraphNode && isSubgraphNavigationEnabled && (
+                  <QuickTooltip content={`Subgraph: ${subgraphDescription}`}>
+                    <Icon name="Workflow" size="sm" className="text-blue-600" />
+                  </QuickTooltip>
+                )}
+                {disabledCache && !readOnly && (
+                  <QuickTooltip
+                    content="Cache Disabled"
+                    className="whitespace-nowrap"
+                  >
+                    <Icon name="ZapOff" size="sm" className="text-orange-400" />
+                  </QuickTooltip>
+                )}
+                <CardTitle className="break-words text-left text-xs text-slate-900">
+                  {name}
+                </CardTitle>
+              </InlineStack>
+              {isRemoteComponentLibrarySearchEnabled ? (
+                <PublishedComponentBadge componentRef={taskSpec.componentRef}>
+                  {digestMarkup}
+                </PublishedComponentBadge>
+              ) : (
+                digestMarkup
               )}
-              {disabledCache && !readOnly && (
-                <QuickTooltip
-                  content="Cache Disabled"
-                  className="whitespace-nowrap"
-                >
-                  <Icon name="ZapOff" size="sm" className="text-orange-400" />
-                </QuickTooltip>
-              )}
-              <CardTitle className="break-words text-left text-xs text-slate-900">
-                {name}
-              </CardTitle>
             </InlineStack>
             {taskId &&
               taskId !== name &&
@@ -283,12 +299,10 @@ const TaskNodeCard = () => {
               )}
           </BlockStack>
 
-          {isRemoteComponentLibrarySearchEnabled ? (
-            <PublishedComponentBadge componentRef={taskSpec.componentRef}>
-              {digestMarkup}
-            </PublishedComponentBadge>
-          ) : (
-            digestMarkup
+          {ENABLE_DEBUG_MODE && (
+            <Text size="xs" tone="subdued">
+              Node Id: {nodeId}
+            </Text>
           )}
         </CardHeader>
         <CardContent className="p-2 flex flex-col gap-2">
diff --git a/src/components/ui/tooltip.tsx b/src/components/ui/tooltip.tsx
index d84b451a3..ff0f2579e 100644
--- a/src/components/ui/tooltip.tsx
+++ b/src/components/ui/tooltip.tsx
@@ -40,6 +40,7 @@ function TooltipTrigger({
 interface TooltipContentProps
   extends React.ComponentProps<typeof TooltipPrimitive.Content> {
   arrowClassName?: string;
+  disabled?: boolean;
 }
 
 function TooltipContent({
@@ -47,8 +48,13 @@ function TooltipContent({
   sideOffset = 0,
   children,
   arrowClassName,
+  disabled,
   ...props
 }: TooltipContentProps) {
+  if (disabled) {
+    return null;
+  }
+
   return (
     <TooltipPrimitive.Portal>
       <TooltipPrimitive.Content
diff --git a/src/utils/constants.ts b/src/utils/constants.ts
index 411d96183..911c2d253 100644
--- a/src/utils/constants.ts
+++ b/src/utils/constants.ts
@@ -1,4 +1,7 @@
 /* Environment Config */
+export const ENABLE_DEBUG_MODE =
+  import.meta.env.VITE_ENABLE_DEBUG_MODE === "true";
+
 export const ABOUT_URL =
   import.meta.env.VITE_ABOUT_URL || "https://cloud-pipelines.net/";