feat: Add react-joyride guided walkthrough for first-time users (#11)

- 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: claude[bot] <209825114+claude[bot]@users.noreply.github.com>
Co-authored-by: Nadim Tuhin <nadimtuhin@users.noreply.github.com>

Author: nadimtuhin

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",
     "sql-formatter": "^15.4.10",
@@ -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",

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,
+  };
+}

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>