@12-apps/ui 1.0.0 → 1.3.1

package/src/components/feedback/TutorialOverlay/TutorialOverlay.tsx

@@ -1,27 +1,17 @@
-import {
-  CheckCircle as CompleteIcon,
-  Close as CloseIcon,
-  NavigateBefore as PrevIcon,
-  NavigateNext as NextIcon,
-  Refresh as RestartIcon,
-} from '@mui/icons-material';
 import {
   alpha,
   Box,
-  Button,
   Fade,
-  IconButton,
   keyframes,
   LinearProgress,
   Paper,
   Portal,
-  Stack,
-  styled,
-  Typography,
-} from '@mui/material';
+  styled } from '@mui/material';
 import type { FC} from 'react';
-import React, { useCallback,useEffect, useRef, useState } from 'react';
+import React, {  } from 'react';
 
+import { useTutorialOverlay } from './TutorialOverlay.hooks';
+import { TutorialStepBody } from './TutorialStepBody';
 import type { TutorialOverlayProps } from './TutorialOverlay.types';
 
 // Animation keyframes
@@ -48,8 +38,7 @@ const floatAnimation = keyframes`
 
 // Styled components
 const Overlay = styled(Box, {
-  shouldForwardProp: (prop) => prop !== 'allowClickThrough',
-})<{ allowClickThrough?: boolean }>(({ theme, allowClickThrough }) => ({
+  shouldForwardProp: (prop) => prop !== 'allowClickThrough' })<{ allowClickThrough?: boolean }>(({ theme, allowClickThrough }) => ({
   position: 'fixed',
   top: 0,
   left: 0,
@@ -57,8 +46,7 @@ const Overlay = styled(Box, {
   bottom: 0,
   zIndex: theme.zIndex.modal + 100,
   pointerEvents: allowClickThrough ? 'none' : 'auto',
-  transition: 'opacity 0.3s ease',
-}));
+  transition: 'opacity 0.3s ease' }));
 
 const Backdrop = styled(Box)(() => ({
   position: 'absolute',
@@ -67,12 +55,10 @@ const Backdrop = styled(Box)(() => ({
   right: 0,
   bottom: 0,
   background: alpha('#000', 0.7),
-  backdropFilter: 'blur(2px)',
-}));
+  backdropFilter: 'blur(2px)' }));
 
 const Spotlight = styled(Box, {
-  shouldForwardProp: (prop) => prop !== 'bounds' && prop !== 'padding',
-})<{ bounds: globalThis.DOMRect; padding: number }>(({ bounds, padding }) => ({
+  shouldForwardProp: (prop) => prop !== 'bounds' && prop !== 'padding' })<{ bounds: globalThis.DOMRect; padding: number }>(({ bounds, padding }) => ({
   position: 'absolute',
   top: bounds.top - padding,
   left: bounds.left - padding,
@@ -88,13 +74,10 @@ const Spotlight = styled(Box, {
     inset: -2,
     borderRadius: 8,
     background: 'transparent',
-    boxShadow: '0 0 0 9999px rgba(0, 0, 0, 0.7)',
-  },
-}));
+    boxShadow: '0 0 0 9999px rgba(0, 0, 0, 0.7)' } }));
 
 const TooltipContainer = styled(Paper, {
-  shouldForwardProp: (prop) => prop !== 'placement',
-})<{ placement: string }>(({ theme, placement }) => ({
+  shouldForwardProp: (prop) => prop !== 'placement' })<{ placement: string }>(({ theme, placement }) => ({
   position: 'absolute',
   maxWidth: 360,
   padding: theme.spacing(3),
@@ -119,31 +102,25 @@ const TooltipContainer = styled(Paper, {
       left: '50%',
       marginLeft: -6,
       borderTop: 'none',
-      borderLeft: 'none',
-    }),
+      borderLeft: 'none' }),
     ...(placement === 'bottom' && {
       top: -7,
       left: '50%',
       marginLeft: -6,
       borderBottom: 'none',
-      borderRight: 'none',
-    }),
+      borderRight: 'none' }),
     ...(placement === 'left' && {
       right: -7,
       top: '50%',
       marginTop: -6,
       borderLeft: 'none',
-      borderBottom: 'none',
-    }),
+      borderBottom: 'none' }),
     ...(placement === 'right' && {
       left: -7,
       top: '50%',
       marginTop: -6,
       borderRight: 'none',
-      borderTop: 'none',
-    }),
-  },
-}));
+      borderTop: 'none' }) } }));
 
 const ProgressBar = styled(LinearProgress)(({ theme }) => ({
   position: 'fixed',
@@ -153,229 +130,137 @@ const ProgressBar = styled(LinearProgress)(({ theme }) => ({
   height: 4,
   zIndex: theme.zIndex.modal + 102,
   '& .MuiLinearProgress-bar': {
-    background: `linear-gradient(90deg, ${theme.palette.primary.main} 0%, ${theme.palette.primary.light} 100%)`,
-  },
-}));
-
-const StepIndicator = styled(Box)(({ theme }) => ({
-  display: 'flex',
-  gap: theme.spacing(1),
-  marginTop: theme.spacing(2),
-  marginBottom: theme.spacing(2),
-}));
-
-const StepDot = styled(Box, {
-  shouldForwardProp: (prop) => prop !== 'active' && prop !== 'completed',
-})<{ active?: boolean; completed?: boolean }>(({ theme, active, completed }) => ({
-  width: 8,
-  height: 8,
-  borderRadius: '50%',
-  background: completed
-    ? theme.palette.success.main
-    : active
-      ? theme.palette.primary.main
-      : alpha(theme.palette.text.primary, 0.3),
-  transition: 'all 0.3s ease',
-  ...(active && {
-    transform: 'scale(1.5)',
-  }),
-}));
-
-// Helper function to get element bounds
-const getElementBounds = (selector: string): globalThis.DOMRect | null => {
-  const element = document.querySelector(selector);
-  if (!element) return null;
-  return element.getBoundingClientRect();
-};
-
-// Helper function to calculate tooltip position
-const calculateTooltipPosition = (
-  targetBounds: globalThis.DOMRect,
-  tooltipBounds: globalThis.DOMRect,
-  placement: string,
-  padding = 16,
-) => {
-  const viewport = {
-    width: window.innerWidth,
-    height: window.innerHeight,
-  };
-
-  let position = { top: 0, left: 0 };
-  let finalPlacement = placement;
-
-  if (placement === 'auto') {
-    // Determine best placement based on available space
-    const spaces = {
-      top: targetBounds.top,
-      bottom: viewport.height - targetBounds.bottom,
-      left: targetBounds.left,
-      right: viewport.width - targetBounds.right,
-    };
-    finalPlacement = Object.entries(spaces).reduce((a, b) => (b[1] > a[1] ? b : a))[0];
-  }
-
-  switch (finalPlacement) {
-    case 'top':
-      position = {
-        top: targetBounds.top - tooltipBounds.height - padding,
-        left: targetBounds.left + targetBounds.width / 2 - tooltipBounds.width / 2,
-      };
-      break;
-    case 'bottom':
-      position = {
-        top: targetBounds.bottom + padding,
-        left: targetBounds.left + targetBounds.width / 2 - tooltipBounds.width / 2,
-      };
-      break;
-    case 'left':
-      position = {
-        top: targetBounds.top + targetBounds.height / 2 - tooltipBounds.height / 2,
-        left: targetBounds.left - tooltipBounds.width - padding,
-      };
-      break;
-    case 'right':
-      position = {
-        top: targetBounds.top + targetBounds.height / 2 - tooltipBounds.height / 2,
-        left: targetBounds.right + padding,
-      };
-      break;
-  }
+    background: `linear-gradient(90deg, ${theme.palette.primary.main} 0%, ${theme.palette.primary.light} 100%)` } }));
+
+type TutorialDefaultedKeys =
+  | 'initialStep'
+  | 'active'
+  | 'showProgress'
+  | 'allowKeyboardNavigation'
+  | 'allowClickThrough'
+  | 'variant'
+  | 'allowSkip'
+  | 'animated';
+
+type ResolvedTutorialProps = TutorialOverlayProps &
+  Required<Pick<TutorialOverlayProps, TutorialDefaultedKeys>>;
+
+const TUTORIAL_DEFAULTS: Pick<TutorialOverlayProps, TutorialDefaultedKeys> = {
+  initialStep: 0,
+  active: true,
+  showProgress: true,
+  allowKeyboardNavigation: true,
+  allowClickThrough: false,
+  variant: 'tooltip',
+  allowSkip: false,
+  animated: true };
+
+// Strips explicitly-undefined props before the merge, so `prop={undefined}` still
+// falls back to the default exactly as a destructuring default would. Applied as
+// a merge rather than destructuring defaults, which would otherwise put eight
+// branches into the component's own complexity budget.
+const resolveProps = (props: TutorialOverlayProps): ResolvedTutorialProps =>
+  ({
+    ...TUTORIAL_DEFAULTS,
+    ...(Object.fromEntries(
+      Object.entries(props).filter(([, value]) => value !== undefined),
+    ) as Partial<TutorialOverlayProps>) }) as ResolvedTutorialProps;
+
+// The dimming layer and the cut-out over the highlighted element. Local because
+// Backdrop and Spotlight cannot cross a module boundary (TS2742).
+const TutorialLayers: React.FC<{
+  variant: string;
+  targetBounds: globalThis.DOMRect | null;
+  isVisible: boolean;
+  spotlightPadding?: number;
+}> = ({ variant, targetBounds, isVisible, spotlightPadding }) => {
+  const isSpotlight = variant === 'spotlight' || variant === 'highlight';
+  const dimmed = variant === 'modal' || isSpotlight;
 
-  // Ensure tooltip stays within viewport
-  position.top = Math.max(
-    padding,
-    Math.min(position.top, viewport.height - tooltipBounds.height - padding),
-  );
-  position.left = Math.max(
-    padding,
-    Math.min(position.left, viewport.width - tooltipBounds.width - padding),
+  return (
+    <>
+      {dimmed && <Backdrop />}
+      {targetBounds && isVisible && isSpotlight && (
+        <Spotlight
+          bounds={targetBounds}
+          padding={spotlightPadding || 8}
+          data-testid="tutorial-highlight"
+        />
+      )}
+    </>
   );
-
-  return { position, placement: finalPlacement };
 };
 
-// Main component
-export const TutorialOverlay: FC<TutorialOverlayProps> = ({
-  steps,
-  onComplete,
-  onSkip,
-  onStepComplete,
-  initialStep = 0,
-  active = true,
-  showProgress = true,
-  allowKeyboardNavigation = true,
-  allowClickThrough = false,
-  variant = 'tooltip',
-  allowSkip = false,
-  animated = true,
-}) => {
-  const [currentStep, setCurrentStep] = useState(initialStep);
-  const [targetBounds, setTargetBounds] = useState<globalThis.DOMRect | null>(null);
-  const [tooltipPosition, setTooltipPosition] = useState({ top: 0, left: 0 });
-  const [actualPlacement, setActualPlacement] = useState<string>('bottom');
-  const [isVisible, setIsVisible] = useState(false);
-  const tooltipRef = useRef<HTMLDivElement>(null);
-
-  const currentStepData = steps[currentStep];
-  const progress = ((currentStep + 1) / steps.length) * 100;
-  const isModal = variant === 'modal';
-  const isSpotlight = variant === 'spotlight' || variant === 'highlight';
-  const isLastStep = currentStep === steps.length - 1;
-  const requiresActionBeforeNext = currentStepData?.requiresAction && !isLastStep;
-
-  // Update target bounds when step changes
-  useEffect(() => {
-    if (!active || !currentStepData) return;
-
-    const updateBounds = () => {
-      const bounds = getElementBounds(currentStepData.target);
-      if (bounds) {
-        setTargetBounds(bounds);
-        setIsVisible(true);
-      } else {
-        setIsVisible(false);
-      }
-    };
-
-    // Initial update
-    updateBounds();
-
-    // Update on resize/scroll
-    const handleUpdate = () => updateBounds();
-    window.addEventListener('resize', handleUpdate);
-    window.addEventListener('scroll', handleUpdate, true);
-
-    return () => {
-      window.removeEventListener('resize', handleUpdate);
-      window.removeEventListener('scroll', handleUpdate, true);
-    };
-  }, [currentStep, currentStepData, active]);
-
-  // Calculate tooltip position
-  useEffect(() => {
-    if (!targetBounds || !tooltipRef.current || !isVisible || !currentStepData) return;
-
-    const tooltipBounds = tooltipRef.current.getBoundingClientRect();
-    const { position, placement } = calculateTooltipPosition(
-      targetBounds,
-      tooltipBounds,
-      currentStepData.position || 'auto',
-    );
-    setTooltipPosition(position);
-    setActualPlacement(placement);
-  }, [targetBounds, currentStepData, isVisible]);
-
-  // Handler functions
-  const handleNext = useCallback(() => {
-    const currentStepId = steps[currentStep]?.id;
-    if (currentStepId && onStepComplete) {
-      onStepComplete(currentStepId);
-    }
-
-    if (currentStep < steps.length - 1) {
-      setCurrentStep(currentStep + 1);
-    } else if (onComplete) {
-      onComplete();
-    }
-  }, [currentStep, steps, onComplete, onStepComplete]);
-
-  const handlePrev = useCallback(() => {
-    if (currentStep > 0) {
-      setCurrentStep(currentStep - 1);
-    }
-  }, [currentStep]);
-
-  const handleSkip = useCallback(() => {
-    if (onSkip) {
-      onSkip();
-    }
-  }, [onSkip]);
-
-  const handleRestart = useCallback(() => {
-    setCurrentStep(0);
-  }, []);
-
-  // Keyboard navigation
-  useEffect(() => {
-    if (!allowKeyboardNavigation || !active) return;
-
-    const handleKeyPress = (e: globalThis.KeyboardEvent) => {
-      switch (e.key) {
-        case 'ArrowLeft':
-          handlePrev();
-          break;
-        case 'ArrowRight':
-          handleNext();
-          break;
-        case 'Escape':
-          handleSkip();
-          break;
-      }
-    };
-
-    window.addEventListener('keydown', handleKeyPress);
-    return () => window.removeEventListener('keydown', handleKeyPress);
-  }, [active, allowKeyboardNavigation, handleNext, handlePrev, handleSkip]);
+// The positioned card. Local because TooltipContainer cannot cross a module
+// boundary (TS2742).
+const TutorialTooltip: React.FC<{
+  tutorial: ReturnType<typeof useTutorialOverlay> & {
+    currentStepData: TutorialOverlayProps['steps'][number];
+  };
+  steps: TutorialOverlayProps['steps'];
+  allowSkip: boolean;
+  showProgress: boolean;
+  animated: boolean;
+  requiresActionBeforeNext: boolean;
+}> = ({ tutorial, steps, allowSkip, showProgress, animated, requiresActionBeforeNext }) => (
+        <Fade in={tutorial.isVisible} timeout={300}>
+          <TooltipContainer
+            ref={tutorial.tooltipRef}
+            placement={tutorial.actualPlacement}
+            elevation={12}
+            style={{
+              top: tutorial.tooltipPosition.top,
+              left: tutorial.tooltipPosition.left,
+              animation: animated ? undefined : 'none' }}
+            role="dialog"
+            aria-labelledby={`tutorial-title-${tutorial.currentStep}`}
+            aria-describedby={`tutorial-content-${tutorial.currentStep}`}
+            data-testid={`tutorial-step-${tutorial.currentStep}`}
+          >
+            <TutorialStepBody
+              step={tutorial.currentStepData}
+              currentStep={tutorial.currentStep}
+              stepCount={steps.length}
+              progress={tutorial.progress}
+              isLastStep={tutorial.isLastStep}
+              allowSkip={allowSkip}
+              showProgress={showProgress}
+              requiresActionBeforeNext={requiresActionBeforeNext}
+              onNext={tutorial.handleNext}
+              onPrev={tutorial.handlePrev}
+              onSkip={tutorial.handleSkip}
+              onRestart={tutorial.handleRestart}
+            />
+          </TooltipContainer>
+        </Fade>
+);
+
+export const TutorialOverlay: FC<TutorialOverlayProps> = (componentProps) => {
+  const {
+    steps,
+    onComplete,
+    onSkip,
+    onStepComplete,
+    initialStep,
+    active,
+    showProgress,
+    allowKeyboardNavigation,
+    allowClickThrough,
+    variant,
+    allowSkip,
+    animated } = resolveProps(componentProps);
+
+  const tutorial = useTutorialOverlay({
+    steps,
+    initialStep,
+    active,
+    allowKeyboardNavigation,
+    onComplete,
+    onSkip,
+    onStepComplete });
+  const { currentStepData, isLastStep, isVisible, targetBounds, progress } = tutorial;
+
+  const requiresActionBeforeNext = Boolean(currentStepData?.requiresAction) && !isLastStep;
 
   if (!active || !currentStepData) return null;
 
@@ -387,164 +272,21 @@ export const TutorialOverlay: FC<TutorialOverlayProps> = ({
       <Overlay allowClickThrough={allowClickThrough} data-testid="tutorial-overlay">
         {showProgress && <ProgressBar variant="determinate" value={progress} />}
 
-        {(isModal || isSpotlight) && <Backdrop />}
-
-        {targetBounds && isVisible && isSpotlight && (
-          <Spotlight
-            bounds={targetBounds}
-            padding={currentStepData.spotlightPadding || 8}
-            data-testid="tutorial-highlight"
-          />
-        )}
-
-        <Fade in={isVisible} timeout={300}>
-          <TooltipContainer
-            ref={tooltipRef}
-            placement={actualPlacement}
-            elevation={12}
-            style={{
-              top: tooltipPosition.top,
-              left: tooltipPosition.left,
-              animation: animated ? undefined : 'none',
-            }}
-            role="dialog"
-            aria-labelledby={`tutorial-title-${currentStep}`}
-            aria-describedby={`tutorial-content-${currentStep}`}
-            data-testid={`tutorial-step-${currentStep}`}
-          >
-            <Stack spacing={2}>
-              <Box
-                sx={{ display: 'flex', justifyContent: 'space-between', alignItems: 'flex-start' }}
-              >
-                <Typography
-                  id={`tutorial-title-${currentStep}`}
-                  variant="h6"
-                  fontWeight="bold"
-                  sx={{ flex: 1 }}
-                  data-testid="tutorial-step-title"
-                >
-                  {currentStepData.title}
-                </Typography>
-                {allowSkip && (
-                  <IconButton
-                    size="small"
-                    onClick={handleSkip}
-                    sx={{ ml: 1, mt: -1, mr: -1 }}
-                    data-testid="tutorial-close-button"
-                  >
-                    <CloseIcon fontSize="small" />
-                  </IconButton>
-                )}
-              </Box>
-
-              <Typography
-                id={`tutorial-content-${currentStep}`}
-                variant="body2"
-                color="text.secondary"
-                data-testid="tutorial-step-content"
-              >
-                {currentStepData.content}
-              </Typography>
-
-              {showProgress && (
-                <Typography variant="caption" color="text.secondary" align="center">
-                  {currentStep + 1} of {steps.length}
-                </Typography>
-              )}
-
-              {currentStepData.action && (
-                <Button
-                  variant="contained"
-                  size="small"
-                  onClick={currentStepData.action.onClick}
-                  sx={{
-                    background: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',
-                    color: 'white',
-                  }}
-                >
-                  {currentStepData.action.label}
-                </Button>
-              )}
-
-              <StepIndicator data-testid="tutorial-step-indicators">
-                {steps.map((_, index) => (
-                  <StepDot
-                    key={index}
-                    active={index === currentStep}
-                    completed={index < currentStep}
-                    data-testid={`tutorial-indicator-${index}`}
-                  />
-                ))}
-              </StepIndicator>
-
-              <Stack
-                direction="row"
-                spacing={1}
-                justifyContent="space-between"
-                data-testid="tutorial-navigation"
-              >
-                <Stack direction="row" spacing={1}>
-                  {allowSkip && (
-                    <Button size="small" onClick={handleSkip} variant="text">
-                      Skip
-                    </Button>
-                  )}
-                  {steps.length > 1 && (
-                    <IconButton
-                      size="small"
-                      onClick={handleRestart}
-                      disabled={currentStep === 0}
-                      title="Restart"
-                    >
-                      <RestartIcon fontSize="small" />
-                    </IconButton>
-                  )}
-                </Stack>
-
-                <Stack direction="row" spacing={1}>
-                  {steps.length > 1 && currentStep > 0 && (
-                    <Button
-                      size="small"
-                      startIcon={<PrevIcon />}
-                      onClick={handlePrev}
-                      disabled={currentStep === 0}
-                      data-testid="tutorial-prev-button"
-                    >
-                      Previous
-                    </Button>
-                  )}
-
-                  {!isLastStep ? (
-                    <Button
-                      variant="contained"
-                      size="small"
-                      endIcon={<NextIcon />}
-                      onClick={handleNext}
-                      disabled={requiresActionBeforeNext}
-                      title={requiresActionBeforeNext ? 'Complete the required action first' : ''}
-                      data-testid="tutorial-next-button"
-                    >
-                      Next
-                    </Button>
-                  ) : (
-                    <Button
-                      variant="contained"
-                      size="small"
-                      endIcon={<CompleteIcon />}
-                      onClick={handleNext}
-                      sx={{
-                        background: 'linear-gradient(135deg, #84fab0 0%, #8fd3f4 100%)',
-                      }}
-                      data-testid="tutorial-finish-button"
-                    >
-                      {steps.length === 1 ? 'Complete' : 'Finish'}
-                    </Button>
-                  )}
-                </Stack>
-              </Stack>
-            </Stack>
-          </TooltipContainer>
-        </Fade>
+        <TutorialLayers
+          variant={variant}
+          targetBounds={targetBounds}
+          isVisible={isVisible}
+          spotlightPadding={currentStepData.spotlightPadding}
+        />
+
+        <TutorialTooltip
+          tutorial={{ ...tutorial, currentStepData }}
+          steps={steps}
+          allowSkip={allowSkip}
+          showProgress={showProgress}
+          animated={animated}
+          requiresActionBeforeNext={requiresActionBeforeNext}
+        />
       </Overlay>
     </Portal>
   );