bmad-elsabro 1.0.0

package/renderer/components/TutorialOverlay.tsx

@@ -0,0 +1,483 @@
+/**
+ * TutorialOverlay Component
+ *
+ * Interactive tutorial system that guides users through app features.
+ * Highlights UI elements and displays contextual instructions.
+ *
+ * Features:
+ * - Interactive element highlighting with spotlight effect
+ * - Positioned tooltips relative to target elements
+ * - Step-by-step navigation (next, back, skip)
+ * - Progress tracking
+ * - Dark/light theme support
+ * - Keyboard navigation (arrows, escape)
+ * - Accessible with ARIA labels
+ * - Multiple tutorial flows
+ * - Persistent progress (localStorage)
+ */
+
+import React, { useState, useEffect, useCallback, useRef } from 'react';
+import tutorialsData from '../data/tutorials.json';
+
+/**
+ * Tutorial step action
+ */
+export interface TutorialAction {
+  label: string;
+  type: 'next' | 'back' | 'skip' | 'complete';
+}
+
+/**
+ * Tutorial step
+ */
+export interface TutorialStep {
+  id: string;
+  title: string;
+  description: string;
+  targetElement: string | null;
+  highlightType: 'none' | 'element' | 'region';
+  position: 'top' | 'bottom' | 'left' | 'right' | 'center';
+  content: string;
+  actions: TutorialAction[];
+}
+
+/**
+ * Tutorial definition
+ */
+export interface Tutorial {
+  id: string;
+  name: string;
+  description: string;
+  category: string;
+  estimatedMinutes: number;
+  steps: TutorialStep[];
+}
+
+/**
+ * Tutorial overlay props
+ */
+export interface TutorialOverlayProps {
+  /**
+   * Tutorial ID to display
+   */
+  tutorialId: string;
+
+  /**
+   * Callback when tutorial is completed
+   */
+  onComplete?: (tutorialId: string) => void;
+
+  /**
+   * Callback when tutorial is skipped
+   */
+  onSkip?: (tutorialId: string, currentStep: number) => void;
+
+  /**
+   * Whether to show tutorial on mount
+   * @default true
+   */
+  autoStart?: boolean;
+
+  /**
+   * Custom CSS class name
+   */
+  className?: string;
+}
+
+/**
+ * Get position classes for tooltip based on target element position
+ */
+const getTooltipPosition = (
+  position: string,
+  targetRect: DOMRect | null
+): React.CSSProperties => {
+  if (!targetRect) {
+    // Center position for non-targeted steps
+    return {
+      position: 'fixed',
+      top: '50%',
+      left: '50%',
+      transform: 'translate(-50%, -50%)',
+    };
+  }
+
+  const offset = 20; // Distance from target element
+  const style: React.CSSProperties = { position: 'fixed' };
+
+  switch (position) {
+    case 'top':
+      style.left = `${targetRect.left + targetRect.width / 2}px`;
+      style.top = `${targetRect.top - offset}px`;
+      style.transform = 'translate(-50%, -100%)';
+      break;
+    case 'bottom':
+      style.left = `${targetRect.left + targetRect.width / 2}px`;
+      style.top = `${targetRect.bottom + offset}px`;
+      style.transform = 'translateX(-50%)';
+      break;
+    case 'left':
+      style.left = `${targetRect.left - offset}px`;
+      style.top = `${targetRect.top + targetRect.height / 2}px`;
+      style.transform = 'translate(-100%, -50%)';
+      break;
+    case 'right':
+      style.left = `${targetRect.right + offset}px`;
+      style.top = `${targetRect.top + targetRect.height / 2}px`;
+      style.transform = 'translateY(-50%)';
+      break;
+    default:
+      style.top = '50%';
+      style.left = '50%';
+      style.transform = 'translate(-50%, -50%)';
+  }
+
+  return style;
+};
+
+/**
+ * Get arrow direction based on tooltip position
+ */
+const getArrowClass = (position: string): string => {
+  switch (position) {
+    case 'top':
+      return 'arrow-bottom';
+    case 'bottom':
+      return 'arrow-top';
+    case 'left':
+      return 'arrow-right';
+    case 'right':
+      return 'arrow-left';
+    default:
+      return '';
+  }
+};
+
+/**
+ * TutorialOverlay Component
+ *
+ * Displays interactive tutorials with element highlighting and guided steps.
+ *
+ * @example
+ * ```tsx
+ * <TutorialOverlay
+ *   tutorialId="welcome-tour"
+ *   onComplete={(id) => console.log('Tutorial completed:', id)}
+ *   onSkip={(id, step) => console.log('Tutorial skipped at step:', step)}
+ * />
+ * ```
+ */
+export const TutorialOverlay: React.FC<TutorialOverlayProps> = ({
+  tutorialId,
+  onComplete,
+  onSkip,
+  autoStart = true,
+  className = '',
+}) => {
+  const [isActive, setIsActive] = useState(autoStart);
+  const [currentStepIndex, setCurrentStepIndex] = useState(0);
+  const [targetRect, setTargetRect] = useState<DOMRect | null>(null);
+  const [tutorial, setTutorial] = useState<Tutorial | null>(null);
+  const tooltipRef = useRef<HTMLDivElement>(null);
+  const resizeObserverRef = useRef<ResizeObserver | null>(null);
+
+  /**
+   * Load tutorial data
+   */
+  useEffect(() => {
+    const foundTutorial = tutorialsData.tutorials.find((t) => t.id === tutorialId);
+    if (foundTutorial) {
+      setTutorial(foundTutorial as Tutorial);
+    }
+  }, [tutorialId]);
+
+  /**
+   * Get current step
+   */
+  const currentStep = tutorial?.steps[currentStepIndex];
+
+  /**
+   * Update target element position
+   */
+  const updateTargetPosition = useCallback(() => {
+    if (!currentStep?.targetElement) {
+      setTargetRect(null);
+      return;
+    }
+
+    const element = document.querySelector(currentStep.targetElement);
+    if (element) {
+      const rect = element.getBoundingClientRect();
+      setTargetRect(rect);
+    } else {
+      setTargetRect(null);
+    }
+  }, [currentStep]);
+
+  /**
+   * Update position when step changes or window resizes
+   */
+  useEffect(() => {
+    updateTargetPosition();
+
+    // Update on window resize
+    window.addEventListener('resize', updateTargetPosition);
+
+    // Update on scroll (for fixed/sticky elements)
+    window.addEventListener('scroll', updateTargetPosition, true);
+
+    // Observe target element changes
+    if (currentStep?.targetElement) {
+      const element = document.querySelector(currentStep.targetElement);
+      if (element) {
+        resizeObserverRef.current = new ResizeObserver(updateTargetPosition);
+        resizeObserverRef.current.observe(element);
+      }
+    }
+
+    return () => {
+      window.removeEventListener('resize', updateTargetPosition);
+      window.removeEventListener('scroll', updateTargetPosition, true);
+      if (resizeObserverRef.current) {
+        resizeObserverRef.current.disconnect();
+      }
+    };
+  }, [currentStep, updateTargetPosition]);
+
+  /**
+   * Handle action click
+   */
+  const handleAction = useCallback(
+    (action: TutorialAction) => {
+      switch (action.type) {
+        case 'next':
+          if (tutorial && currentStepIndex < tutorial.steps.length - 1) {
+            setCurrentStepIndex((prev) => prev + 1);
+          }
+          break;
+
+        case 'back':
+          if (currentStepIndex > 0) {
+            setCurrentStepIndex((prev) => prev - 1);
+          }
+          break;
+
+        case 'skip':
+          setIsActive(false);
+          onSkip?.(tutorialId, currentStepIndex);
+          break;
+
+        case 'complete':
+          setIsActive(false);
+          onComplete?.(tutorialId);
+          // Save completion to localStorage
+          localStorage.setItem(`tutorial-completed-${tutorialId}`, 'true');
+          break;
+      }
+    },
+    [tutorial, currentStepIndex, tutorialId, onComplete, onSkip]
+  );
+
+  /**
+   * Keyboard navigation
+   */
+  useEffect(() => {
+    if (!isActive) return;
+
+    const handleKeyDown = (e: KeyboardEvent) => {
+      switch (e.key) {
+        case 'Escape':
+          handleAction({ label: 'Skip', type: 'skip' });
+          break;
+        case 'ArrowRight':
+          handleAction({ label: 'Next', type: 'next' });
+          break;
+        case 'ArrowLeft':
+          handleAction({ label: 'Back', type: 'back' });
+          break;
+      }
+    };
+
+    window.addEventListener('keydown', handleKeyDown);
+    return () => window.removeEventListener('keydown', handleKeyDown);
+  }, [isActive, handleAction]);
+
+  // Don't render if not active or no tutorial
+  if (!isActive || !tutorial || !currentStep) {
+    return null;
+  }
+
+  const progress = ((currentStepIndex + 1) / tutorial.steps.length) * 100;
+  const tooltipStyle = getTooltipPosition(currentStep.position, targetRect);
+  const arrowClass = getArrowClass(currentStep.position);
+
+  return (
+    <>
+      {/* Overlay backdrop */}
+      <div
+        className={`fixed inset-0 bg-black/50 backdrop-blur-sm z-[9998] transition-opacity ${className}`}
+        aria-hidden="true"
+      />
+
+      {/* Spotlight on target element */}
+      {targetRect && currentStep.highlightType === 'element' && (
+        <div
+          className="fixed z-[9999] pointer-events-none"
+          style={{
+            left: `${targetRect.left - 8}px`,
+            top: `${targetRect.top - 8}px`,
+            width: `${targetRect.width + 16}px`,
+            height: `${targetRect.height + 16}px`,
+          }}
+        >
+          <div className="absolute inset-0 rounded-lg border-4 border-blue-500 shadow-[0_0_0_9999px_rgba(0,0,0,0.5)] animate-pulse" />
+          <div className="absolute inset-0 rounded-lg bg-white/5" />
+        </div>
+      )}
+
+      {/* Tutorial tooltip */}
+      <div
+        ref={tooltipRef}
+        role="dialog"
+        aria-labelledby="tutorial-title"
+        aria-describedby="tutorial-content"
+        className={`z-[10000] max-w-md ${arrowClass}`}
+        style={tooltipStyle}
+      >
+        <div className="bg-white dark:bg-gray-800 rounded-lg shadow-2xl border border-gray-200 dark:border-gray-700 overflow-hidden">
+          {/* Header */}
+          <div className="bg-gradient-to-r from-blue-500 to-purple-600 px-6 py-4 text-white">
+            <div className="flex items-start justify-between mb-2">
+              <div className="flex-1">
+                <p className="text-xs font-semibold uppercase tracking-wide opacity-90 mb-1">
+                  {tutorial.name} • Step {currentStepIndex + 1} of {tutorial.steps.length}
+                </p>
+                <h3 id="tutorial-title" className="text-lg font-bold leading-tight">
+                  {currentStep.title}
+                </h3>
+              </div>
+              <button
+                onClick={() => handleAction({ label: 'Skip', type: 'skip' })}
+                className="ml-3 text-white/80 hover:text-white transition-colors focus:outline-none focus:ring-2 focus:ring-white/50 rounded"
+                aria-label="Skip tutorial"
+                title="Skip tutorial (Esc)"
+              >
+                <svg className="w-5 h-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                  <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M6 18L18 6M6 6l12 12" />
+                </svg>
+              </button>
+            </div>
+
+            {/* Progress bar */}
+            <div className="h-1.5 bg-white/20 rounded-full overflow-hidden">
+              <div
+                className="h-full bg-white transition-all duration-300 ease-out"
+                style={{ width: `${progress}%` }}
+              />
+            </div>
+          </div>
+
+          {/* Content */}
+          <div className="px-6 py-4">
+            <p className="text-sm text-gray-600 dark:text-gray-400 mb-3 font-medium">
+              {currentStep.description}
+            </p>
+            <p id="tutorial-content" className="text-sm text-gray-800 dark:text-gray-200 leading-relaxed">
+              {currentStep.content}
+            </p>
+          </div>
+
+          {/* Actions */}
+          <div className="px-6 py-4 bg-gray-50 dark:bg-gray-900/50 border-t border-gray-200 dark:border-gray-700 flex items-center justify-between gap-3">
+            <div className="text-xs text-gray-500 dark:text-gray-500">
+              ⌨️ Use arrow keys to navigate
+            </div>
+            <div className="flex gap-2">
+              {currentStep.actions.map((action, index) => (
+                <button
+                  key={index}
+                  onClick={() => handleAction(action)}
+                  className={`
+                    px-4 py-2 text-sm font-medium rounded-md transition-all
+                    focus:outline-none focus:ring-2 focus:ring-offset-2
+                    ${
+                      action.type === 'next' || action.type === 'complete'
+                        ? 'bg-blue-600 hover:bg-blue-700 text-white focus:ring-blue-500'
+                        : action.type === 'skip'
+                        ? 'bg-gray-200 dark:bg-gray-700 hover:bg-gray-300 dark:hover:bg-gray-600 text-gray-700 dark:text-gray-300 focus:ring-gray-500'
+                        : 'bg-white dark:bg-gray-800 border border-gray-300 dark:border-gray-600 hover:bg-gray-50 dark:hover:bg-gray-700 text-gray-700 dark:text-gray-300 focus:ring-gray-500'
+                    }
+                  `}
+                  disabled={
+                    (action.type === 'back' && currentStepIndex === 0) ||
+                    (action.type === 'next' && currentStepIndex === tutorial.steps.length - 1)
+                  }
+                >
+                  {action.type === 'back' && '← '}
+                  {action.label}
+                  {action.type === 'next' && ' →'}
+                  {action.type === 'complete' && ' ✓'}
+                </button>
+              ))}
+            </div>
+          </div>
+        </div>
+
+        {/* Tooltip arrow */}
+        <style jsx>{`
+          .arrow-top::before {
+            content: '';
+            position: absolute;
+            top: -8px;
+            left: 50%;
+            transform: translateX(-50%);
+            width: 0;
+            height: 0;
+            border-left: 8px solid transparent;
+            border-right: 8px solid transparent;
+            border-bottom: 8px solid rgb(59 130 246);
+          }
+          .arrow-bottom::before {
+            content: '';
+            position: absolute;
+            bottom: -8px;
+            left: 50%;
+            transform: translateX(-50%);
+            width: 0;
+            height: 0;
+            border-left: 8px solid transparent;
+            border-right: 8px solid transparent;
+            border-top: 8px solid rgb(229 231 235);
+          }
+          .arrow-left::before {
+            content: '';
+            position: absolute;
+            left: -8px;
+            top: 50%;
+            transform: translateY(-50%);
+            width: 0;
+            height: 0;
+            border-top: 8px solid transparent;
+            border-bottom: 8px solid transparent;
+            border-right: 8px solid rgb(229 231 235);
+          }
+          .arrow-right::before {
+            content: '';
+            position: absolute;
+            right: -8px;
+            top: 50%;
+            transform: translateY(-50%);
+            width: 0;
+            height: 0;
+            border-top: 8px solid transparent;
+            border-bottom: 8px solid transparent;
+            border-left: 8px solid rgb(229 231 235);
+          }
+        `}</style>
+      </div>
+    </>
+  );
+};
+
+TutorialOverlay.displayName = 'TutorialOverlay';
+
+export default TutorialOverlay;