From 59c7b84d2322dc8ec8d09975666ec967f3d5f76c Mon Sep 17 00:00:00 2001
From: "claude[bot]" <209825114+claude[bot]@users.noreply.github.com>
Date: Thu, 24 Jul 2025 06:15:28 +0000
Subject: [PATCH] feat: Add react-joyride guided walkthrough for first-time
 users
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add react-joyride dependency and TypeScript types
- Implement GuidedTour component with localStorage state management
- Add data-tour attributes to key UI elements (sidebar, search, shortcuts, tools list, main content)
- Integrate guided tour into main Layout component
- Add keyboard shortcut (⌘⇧?) to manually trigger tour
- Update KeyboardShortcuts component to show tour shortcut
- Tour automatically shows for first-time users and remembers completion state

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-authored-by: Nadim Tuhin <nadimtuhin@users.noreply.github.com>
---
 package.json                         |   2 +
 src/App.tsx                          |  23 ++++-
 src/components/GuidedTour.tsx        | 147 +++++++++++++++++++++++++++
 src/components/KeyboardShortcuts.tsx |   4 +
 4 files changed, 173 insertions(+), 3 deletions(-)
 create mode 100644 src/components/GuidedTour.tsx

diff --git a/package.json b/package.json
index 5cd95dc..1265bd3 100644
--- a/package.json
+++ b/package.json
@@ -38,6 +38,7 @@
     "prettier": "^3.4.2",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
+    "react-joyride": "^2.8.2",
     "react-markdown": "^9.0.3",
     "react-router-dom": "^7.5.2",
     "sharp": "^0.33.2",
@@ -64,6 +65,7 @@
     "@types/papaparse": "^5.3.14",
     "@types/react": "^18.3.5",
     "@types/react-dom": "^18.3.0",
+    "@types/react-joyride": "^2.0.5",
     "@types/sharp": "^0.32.0",
     "@types/uuid": "^9.0.8",
     "@vitejs/plugin-react": "^4.3.1",
diff --git a/src/App.tsx b/src/App.tsx
index 6ab9c90..d2b1bf4 100644
--- a/src/App.tsx
+++ b/src/App.tsx
@@ -90,6 +90,7 @@ import HtmlMinifyBeautify from "./components/HtmlMinifyBeautify";
 import SpotlightSearch from "./components/SpotlightSearch";
 import KeyboardShortcuts from "./components/KeyboardShortcuts";
 import Credits from "./components/Credits";
+import GuidedTour, { useShouldShowTour } from "./components/GuidedTour";
 import {
   DndContext,
   closestCenter,
@@ -197,6 +198,7 @@ function Layout({ tools: defaultTools }: { tools: Tool[] }) {
   const [isSpotlightOpen, setIsSpotlightOpen] = useState(false);
   const [isShortcutsOpen, setIsShortcutsOpen] = useState(false);
   const [isSidebarExpanded, setIsSidebarExpanded] = useState(true);
+  const { shouldShow: shouldShowTour, setShouldShow: setShowTour } = useShouldShowTour();
   const [tools, setTools] = useState<Tool[]>(() => {
     const savedOrder = localStorage.getItem("toolsOrder");
     if (savedOrder) {
@@ -236,6 +238,11 @@ function Layout({ tools: defaultTools }: { tools: Tool[] }) {
         e.preventDefault();
         setIsShortcutsOpen(true);
       }
+      // Command/Control + Shift + ? for tour
+      if ((e.metaKey || e.ctrlKey) && e.shiftKey && e.key === "?") {
+        e.preventDefault();
+        setShowTour(true);
+      }
     };
 
     document.addEventListener("keydown", handleKeyDown);
@@ -289,6 +296,7 @@ function Layout({ tools: defaultTools }: { tools: Tool[] }) {
               <RouterLink
                 to="/"
                 className="text-xl font-bold text-gray-800 no-underline"
+                data-tour="sidebar-brand"
               >
                 DevUtils
               </RouterLink>
@@ -308,6 +316,7 @@ function Layout({ tools: defaultTools }: { tools: Tool[] }) {
                     onClick={() => setIsSpotlightOpen(true)}
                     className="p-1.5 hover:bg-gray-100 rounded"
                     title="Search (⌘K)"
+                    data-tour="search-button"
                   >
                     <Search size={18} />
                   </button>
@@ -315,6 +324,7 @@ function Layout({ tools: defaultTools }: { tools: Tool[] }) {
                     onClick={() => setIsShortcutsOpen(true)}
                     className="p-1.5 hover:bg-gray-100 rounded"
                     title="Keyboard Shortcuts (⌘?)"
+                    data-tour="shortcuts-button"
                   >
                     <Keyboard size={18} />
                   </button>
@@ -322,6 +332,7 @@ function Layout({ tools: defaultTools }: { tools: Tool[] }) {
                     onClick={() => setIsSidebarExpanded(false)}
                     className="p-1.5 hover:bg-gray-100 rounded"
                     title="Collapse Sidebar"
+                    data-tour="sidebar-toggle"
                   >
                     <PanelLeftClose size={18} />
                   </button>
@@ -330,7 +341,7 @@ function Layout({ tools: defaultTools }: { tools: Tool[] }) {
             </div>
           </div>
           {isSidebarExpanded && (
-            <div className="flex space-x-2">
+            <div className="flex space-x-2" data-tour="github-links">
               <a
                 href="https://github.com/nadimtuhin/devutils"
                 target="_blank"
@@ -352,7 +363,7 @@ function Layout({ tools: defaultTools }: { tools: Tool[] }) {
             </div>
           )}
         </div>
-        <nav className="p-2 flex-1">
+        <nav className="p-2 flex-1" data-tour="tool-list">
           <DndContext
             sensors={sensors}
             collisionDetection={closestCenter}
@@ -380,7 +391,7 @@ function Layout({ tools: defaultTools }: { tools: Tool[] }) {
       </div>
 
       {/* Main Content */}
-      <div className="flex-1 overflow-auto">
+      <div className="flex-1 overflow-auto" data-tour="main-content">
         <div className="p-8">
           <Routes>
             <Route path="/" element={<Navigate to="/unix-time" replace />} />
@@ -415,6 +426,12 @@ function Layout({ tools: defaultTools }: { tools: Tool[] }) {
         isOpen={isShortcutsOpen}
         onClose={() => setIsShortcutsOpen(false)}
       />
+
+      {/* Guided Tour */}
+      <GuidedTour
+        isOpen={shouldShowTour}
+        onClose={() => setShowTour(false)}
+      />
     </div>
   );
 }
diff --git a/src/components/GuidedTour.tsx b/src/components/GuidedTour.tsx
new file mode 100644
index 0000000..c4c06de
--- /dev/null
+++ b/src/components/GuidedTour.tsx
@@ -0,0 +1,147 @@
+import React, { useState, useEffect } from 'react';
+import Joyride, { Step, CallBackProps, STATUS, EVENTS } from 'react-joyride';
+
+interface GuidedTourProps {
+  isOpen: boolean;
+  onClose: () => void;
+}
+
+const TOUR_STORAGE_KEY = 'devutils-tour-completed';
+
+const steps: Step[] = [
+  {
+    target: '[data-tour="sidebar-brand"]',
+    content: 'Welcome to DevUtils! This is your collection of handy development tools.',
+    placement: 'right',
+  },
+  {
+    target: '[data-tour="search-button"]',
+    content: 'Use the search button (⌘K) to quickly find any tool you need.',
+    placement: 'bottom',
+  },
+  {
+    target: '[data-tour="shortcuts-button"]',
+    content: 'View all keyboard shortcuts to speed up your workflow.',
+    placement: 'bottom',
+  },
+  {
+    target: '[data-tour="sidebar-toggle"]',
+    content: 'Toggle the sidebar to maximize your workspace when needed.',
+    placement: 'bottom',
+  },
+  {
+    target: '[data-tour="tool-list"]',
+    content: 'Browse all available tools here. You can drag to reorder them based on your preference!',
+    placement: 'right',
+  },
+  {
+    target: '[data-tour="main-content"]',
+    content: 'This is where the magic happens - each tool provides instant conversion and formatting capabilities.',
+    placement: 'left',
+  },
+  {
+    target: '[data-tour="github-links"]',
+    content: 'Don\'t forget to star the repository if you find DevUtils helpful!',
+    placement: 'right',
+  },
+];
+
+export default function GuidedTour({ isOpen, onClose }: GuidedTourProps) {
+  const [run, setRun] = useState(false);
+
+  useEffect(() => {
+    if (isOpen) {
+      setRun(true);
+    }
+  }, [isOpen]);
+
+  const handleJoyrideCallback = (data: CallBackProps) => {
+    const { status, type } = data;
+
+    if ([EVENTS.STEP_AFTER, EVENTS.TARGET_NOT_FOUND].includes(type)) {
+      // Update state to advance the tour
+    }
+
+    if ([STATUS.FINISHED, STATUS.SKIPPED].includes(status)) {
+      // Mark tour as completed
+      localStorage.setItem(TOUR_STORAGE_KEY, 'true');
+      setRun(false);
+      onClose();
+    }
+  };
+
+  return (
+    <Joyride
+      callback={handleJoyrideCallback}
+      continuous={true}
+      run={run}
+      scrollToFirstStep={true}
+      showProgress={true}
+      showSkipButton={true}
+      steps={steps}
+      styles={{
+        options: {
+          primaryColor: '#3b82f6',
+          width: 320,
+          zIndex: 1000,
+        },
+        spotlight: {
+          borderRadius: 8,
+        },
+        tooltip: {
+          borderRadius: 8,
+          fontSize: 14,
+        },
+        tooltipContainer: {
+          textAlign: 'left',
+        },
+        tooltipTitle: {
+          fontSize: 16,
+          fontWeight: 600,
+          marginBottom: 8,
+        },
+      }}
+      locale={{
+        back: 'Back',
+        close: 'Close',
+        last: 'Finish',
+        next: 'Next',
+        open: 'Open the dialog',
+        skip: 'Skip tour',
+      }}
+    />
+  );
+}
+
+// Hook to check if tour should be shown
+export function useShouldShowTour() {
+  const [shouldShow, setShouldShow] = useState(false);
+
+  useEffect(() => {
+    const hasCompletedTour = localStorage.getItem(TOUR_STORAGE_KEY);
+    if (!hasCompletedTour) {
+      // Show tour after a short delay to ensure UI is rendered
+      const timer = setTimeout(() => {
+        setShouldShow(true);
+      }, 1000);
+      return () => clearTimeout(timer);
+    }
+  }, []);
+
+  const markTourCompleted = () => {
+    localStorage.setItem(TOUR_STORAGE_KEY, 'true');
+    setShouldShow(false);
+  };
+
+  const resetTour = () => {
+    localStorage.removeItem(TOUR_STORAGE_KEY);
+    setShouldShow(true);
+  };
+
+  return {
+    shouldShow,
+    markTourCompleted,
+    resetTour,
+    setShouldShow,
+  };
+}
\ No newline at end of file
diff --git a/src/components/KeyboardShortcuts.tsx b/src/components/KeyboardShortcuts.tsx
index 20ed601..29b2682 100644
--- a/src/components/KeyboardShortcuts.tsx
+++ b/src/components/KeyboardShortcuts.tsx
@@ -32,6 +32,10 @@ const KeyboardShortcuts: React.FC<Props> = ({ isOpen, onClose }) => {
               <span>Show Keyboard Shortcuts</span>
               <kbd className="px-2 py-1 bg-gray-100 rounded">⌘ ?</kbd>
             </div>
+            <div className="flex justify-between items-center">
+              <span>Show Guided Tour</span>
+              <kbd className="px-2 py-1 bg-gray-100 rounded">⌘ ⇧ ?</kbd>
+            </div>
             <div className="flex justify-between items-center">
               <span>Navigate Tools</span>
               <kbd className="px-2 py-1 bg-gray-100 rounded">↑/↓</kbd>