diff --git a/apps/ui/src/components/shared/index.ts b/apps/ui/src/components/shared/index.ts index 2497d4092..5060ebd14 100644 --- a/apps/ui/src/components/shared/index.ts +++ b/apps/ui/src/components/shared/index.ts @@ -5,3 +5,17 @@ export { type UseModelOverrideOptions, type UseModelOverrideResult, } from './use-model-override'; + +// Onboarding Wizard Components +export { + OnboardingWizard, + useOnboardingWizard, + ONBOARDING_STORAGE_PREFIX, + ONBOARDING_TARGET_ATTRIBUTE, + ONBOARDING_ANALYTICS, + type OnboardingStep, + type OnboardingState, + type OnboardingWizardProps, + type UseOnboardingWizardOptions, + type UseOnboardingWizardResult, +} from './onboarding'; diff --git a/apps/ui/src/components/shared/onboarding/constants.ts b/apps/ui/src/components/shared/onboarding/constants.ts new file mode 100644 index 000000000..d001634ee --- /dev/null +++ b/apps/ui/src/components/shared/onboarding/constants.ts @@ -0,0 +1,55 @@ +/** + * Shared Onboarding Wizard Constants + * + * Layout, positioning, and timing constants for the onboarding wizard. + */ + +/** Storage key prefix for onboarding state */ +export const ONBOARDING_STORAGE_PREFIX = 'automaker:onboarding'; + +/** Padding around spotlight highlight elements (px) */ +export const SPOTLIGHT_PADDING = 8; + +/** Padding between target element and tooltip (px) */ +export const TOOLTIP_OFFSET = 16; + +/** Vertical offset from top of target to tooltip (px) */ +export const TOOLTIP_TOP_OFFSET = 40; + +/** Maximum tooltip width (px) */ +export const TOOLTIP_MAX_WIDTH = 400; + +/** Minimum safe margin from viewport edges (px) */ +export const VIEWPORT_SAFE_MARGIN = 16; + +/** Threshold for placing tooltip to the right of target (30% of viewport) */ +export const TOOLTIP_POSITION_RIGHT_THRESHOLD = 0.3; + +/** Threshold for placing tooltip to the left of target (70% of viewport) */ +export const TOOLTIP_POSITION_LEFT_THRESHOLD = 0.7; + +/** Threshold from bottom of viewport to trigger alternate positioning (px) */ +export const BOTTOM_THRESHOLD = 450; + +/** Debounce delay for resize handler (ms) */ +export const RESIZE_DEBOUNCE_MS = 100; + +/** Animation duration for step transitions (ms) */ +export const STEP_TRANSITION_DURATION = 200; + +/** ID for the wizard description element (for aria-describedby) */ +export const WIZARD_DESCRIPTION_ID = 'onboarding-wizard-description'; + +/** ID for the wizard title element (for aria-labelledby) */ +export const WIZARD_TITLE_ID = 'onboarding-wizard-title'; + +/** Data attribute name for targeting elements */ +export const ONBOARDING_TARGET_ATTRIBUTE = 'data-onboarding-target'; + +/** Analytics event names for onboarding tracking */ +export const ONBOARDING_ANALYTICS = { + STARTED: 'onboarding_started', + COMPLETED: 'onboarding_completed', + SKIPPED: 'onboarding_skipped', + STEP_VIEWED: 'onboarding_step_viewed', +} as const; diff --git a/apps/ui/src/components/shared/onboarding/index.ts b/apps/ui/src/components/shared/onboarding/index.ts new file mode 100644 index 000000000..26b117c32 --- /dev/null +++ b/apps/ui/src/components/shared/onboarding/index.ts @@ -0,0 +1,21 @@ +/** + * Shared Onboarding Components + * + * Generic onboarding wizard infrastructure for building + * interactive tutorials across different views. + */ + +export { OnboardingWizard } from './onboarding-wizard'; +export { useOnboardingWizard } from './use-onboarding-wizard'; +export type { + OnboardingStep, + OnboardingState, + OnboardingWizardProps, + UseOnboardingWizardOptions, + UseOnboardingWizardResult, +} from './types'; +export { + ONBOARDING_STORAGE_PREFIX, + ONBOARDING_TARGET_ATTRIBUTE, + ONBOARDING_ANALYTICS, +} from './constants'; diff --git a/apps/ui/src/components/shared/onboarding/onboarding-wizard.tsx b/apps/ui/src/components/shared/onboarding/onboarding-wizard.tsx new file mode 100644 index 000000000..70bbcb9bc --- /dev/null +++ b/apps/ui/src/components/shared/onboarding/onboarding-wizard.tsx @@ -0,0 +1,545 @@ +/** + * Generic Onboarding Wizard Component + * + * A multi-step wizard overlay that guides users through features + * with visual highlighting (spotlight effect) on target elements. + * + * Features: + * - Spotlight overlay targeting elements via data-onboarding-target + * - Responsive tooltip positioning (left/right/bottom) + * - Step navigation (keyboard & mouse) + * - Configurable children slot for view-specific content + * - Completion celebration animation + * - Full accessibility (ARIA, focus management) + */ + +import { useEffect, useRef, useCallback, useState } from 'react'; +import { createPortal } from 'react-dom'; +import { X, ChevronLeft, ChevronRight, CheckCircle2, PartyPopper, Sparkles } from 'lucide-react'; +import { Button } from '@/components/ui/button'; +import { cn } from '@/lib/utils'; +import { + SPOTLIGHT_PADDING, + TOOLTIP_OFFSET, + TOOLTIP_TOP_OFFSET, + TOOLTIP_MAX_WIDTH, + VIEWPORT_SAFE_MARGIN, + TOOLTIP_POSITION_RIGHT_THRESHOLD, + TOOLTIP_POSITION_LEFT_THRESHOLD, + BOTTOM_THRESHOLD, + RESIZE_DEBOUNCE_MS, + STEP_TRANSITION_DURATION, + WIZARD_DESCRIPTION_ID, + WIZARD_TITLE_ID, + ONBOARDING_TARGET_ATTRIBUTE, +} from './constants'; +import type { OnboardingWizardProps, OnboardingStep } from './types'; + +interface HighlightRect { + top: number; + left: number; + right: number; + bottom: number; + width: number; + height: number; +} + +export function OnboardingWizard({ + isVisible, + currentStep, + currentStepData, + totalSteps, + onNext, + onPrevious, + onSkip, + onComplete, + steps, + children, +}: OnboardingWizardProps) { + const [highlightRect, setHighlightRect] = useState(null); + const [tooltipPosition, setTooltipPosition] = useState<'left' | 'right' | 'bottom'>('bottom'); + const [isAnimating, setIsAnimating] = useState(false); + const [showCompletionCelebration, setShowCompletionCelebration] = useState(false); + + // Refs for focus management + const dialogRef = useRef(null); + const nextButtonRef = useRef(null); + + // Detect if user is on a touch device + const [isTouchDevice, setIsTouchDevice] = useState(false); + + useEffect(() => { + setIsTouchDevice('ontouchstart' in window || navigator.maxTouchPoints > 0); + }, []); + + // Lock scroll when wizard is visible + useEffect(() => { + if (!isVisible) return; + + const originalOverflow = document.body.style.overflow; + document.body.style.overflow = 'hidden'; + + return () => { + document.body.style.overflow = originalOverflow; + }; + }, [isVisible]); + + // Focus management - move focus to dialog when opened + useEffect(() => { + if (!isVisible) return; + + const timer = setTimeout(() => { + nextButtonRef.current?.focus(); + }, STEP_TRANSITION_DURATION); + + return () => clearTimeout(timer); + }, [isVisible]); + + // Animate step transitions + useEffect(() => { + if (!isVisible) return; + + setIsAnimating(true); + const timer = setTimeout(() => { + setIsAnimating(false); + }, STEP_TRANSITION_DURATION); + + return () => clearTimeout(timer); + }, [currentStep, isVisible]); + + // Find and highlight the target element + useEffect(() => { + if (!isVisible || !currentStepData) { + setHighlightRect(null); + return; + } + + const updateHighlight = () => { + // Find target element by data-onboarding-target attribute + const targetEl = document.querySelector( + `[${ONBOARDING_TARGET_ATTRIBUTE}="${currentStepData.targetId}"]` + ); + + if (targetEl) { + const rect = targetEl.getBoundingClientRect(); + setHighlightRect({ + top: rect.top, + left: rect.left, + right: rect.right, + bottom: rect.bottom, + width: rect.width, + height: rect.height, + }); + + // Determine tooltip position based on target position and available space + const viewportWidth = window.innerWidth; + const viewportHeight = window.innerHeight; + const targetCenter = rect.left + rect.width / 2; + const tooltipWidth = Math.min(TOOLTIP_MAX_WIDTH, viewportWidth - VIEWPORT_SAFE_MARGIN * 2); + + const spaceAtBottom = viewportHeight - rect.bottom - TOOLTIP_OFFSET; + const spaceAtRight = viewportWidth - rect.right - TOOLTIP_OFFSET; + const spaceAtLeft = rect.left - TOOLTIP_OFFSET; + + // For leftmost targets, prefer right position + if ( + targetCenter < viewportWidth * TOOLTIP_POSITION_RIGHT_THRESHOLD && + spaceAtRight >= tooltipWidth + ) { + setTooltipPosition('right'); + } + // For rightmost targets, prefer left position + else if ( + targetCenter > viewportWidth * TOOLTIP_POSITION_LEFT_THRESHOLD && + spaceAtLeft >= tooltipWidth + ) { + setTooltipPosition('left'); + } + // For middle targets, check if bottom position would work + else if (spaceAtBottom >= BOTTOM_THRESHOLD) { + setTooltipPosition('bottom'); + } + // Fallback logic + else if (spaceAtRight > spaceAtLeft && spaceAtRight >= tooltipWidth * 0.6) { + setTooltipPosition('right'); + } else if (spaceAtLeft >= tooltipWidth * 0.6) { + setTooltipPosition('left'); + } else { + setTooltipPosition('bottom'); + } + } + }; + + updateHighlight(); + + // Debounced resize handler + let resizeTimeout: ReturnType; + const handleResize = () => { + clearTimeout(resizeTimeout); + resizeTimeout = setTimeout(updateHighlight, RESIZE_DEBOUNCE_MS); + }; + + window.addEventListener('resize', handleResize); + return () => { + window.removeEventListener('resize', handleResize); + clearTimeout(resizeTimeout); + }; + }, [isVisible, currentStepData]); + + // Keyboard navigation + useEffect(() => { + if (!isVisible) return; + + const handleKeyDown = (e: KeyboardEvent) => { + if (e.key === 'Escape') { + onSkip(); + } else if (e.key === 'ArrowRight' || e.key === 'Enter') { + if (currentStep < totalSteps - 1) { + onNext(); + } else { + handleComplete(); + } + } else if (e.key === 'ArrowLeft') { + onPrevious(); + } + }; + + window.addEventListener('keydown', handleKeyDown); + return () => window.removeEventListener('keydown', handleKeyDown); + }, [isVisible, currentStep, totalSteps, onNext, onPrevious, onSkip]); + + // Calculate tooltip styles based on position and highlight rect + const getTooltipStyles = useCallback((): React.CSSProperties => { + if (!highlightRect) return {}; + + const viewportHeight = window.innerHeight; + const viewportWidth = window.innerWidth; + const tooltipWidth = Math.min(TOOLTIP_MAX_WIDTH, viewportWidth - VIEWPORT_SAFE_MARGIN * 2); + + switch (tooltipPosition) { + case 'right': { + const topPos = Math.max(VIEWPORT_SAFE_MARGIN, highlightRect.top + TOOLTIP_TOP_OFFSET); + const availableHeight = viewportHeight - topPos - VIEWPORT_SAFE_MARGIN; + return { + position: 'fixed', + top: topPos, + left: highlightRect.right + TOOLTIP_OFFSET, + width: tooltipWidth, + maxWidth: `calc(100vw - ${highlightRect.right + TOOLTIP_OFFSET * 2}px)`, + maxHeight: Math.max(200, availableHeight), + }; + } + case 'left': { + const topPos = Math.max(VIEWPORT_SAFE_MARGIN, highlightRect.top + TOOLTIP_TOP_OFFSET); + const availableHeight = viewportHeight - topPos - VIEWPORT_SAFE_MARGIN; + return { + position: 'fixed', + top: topPos, + right: viewportWidth - highlightRect.left + TOOLTIP_OFFSET, + width: tooltipWidth, + maxWidth: `calc(${highlightRect.left - TOOLTIP_OFFSET * 2}px)`, + maxHeight: Math.max(200, availableHeight), + }; + } + case 'bottom': + default: { + const idealTop = highlightRect.bottom + TOOLTIP_OFFSET; + const availableHeight = viewportHeight - idealTop - VIEWPORT_SAFE_MARGIN; + + const minTop = 100; + const topPos = + availableHeight < 250 + ? Math.max( + minTop, + viewportHeight - Math.max(300, availableHeight) - VIEWPORT_SAFE_MARGIN + ) + : idealTop; + + const idealLeft = highlightRect.left + highlightRect.width / 2 - tooltipWidth / 2; + const leftPos = Math.max( + VIEWPORT_SAFE_MARGIN, + Math.min(idealLeft, viewportWidth - tooltipWidth - VIEWPORT_SAFE_MARGIN) + ); + + return { + position: 'fixed', + top: topPos, + left: leftPos, + width: tooltipWidth, + maxHeight: Math.max(200, viewportHeight - topPos - VIEWPORT_SAFE_MARGIN), + }; + } + } + }, [highlightRect, tooltipPosition]); + + // Handle completion with celebration + const handleComplete = useCallback(() => { + setShowCompletionCelebration(true); + setTimeout(() => { + setShowCompletionCelebration(false); + onComplete(); + }, 1200); + }, [onComplete]); + + // Handle step indicator click for direct navigation + const handleStepClick = useCallback( + (stepIndex: number) => { + if (stepIndex === currentStep) return; + + if (stepIndex > currentStep) { + for (let i = currentStep; i < stepIndex; i++) { + onNext(); + } + } else { + for (let i = currentStep; i > stepIndex; i--) { + onPrevious(); + } + } + }, + [currentStep, onNext, onPrevious] + ); + + if (!isVisible || !currentStepData) return null; + + const StepIcon = currentStepData.icon || Sparkles; + const isLastStep = currentStep === totalSteps - 1; + const isFirstStep = currentStep === 0; + + const content = ( +
+ {/* Completion celebration overlay */} + {showCompletionCelebration && ( +
+
+ +

You're all set!

+
+
+ )} + + {/* Dark overlay with cutout for highlighted element */} + + + {/* Highlight border around the target element */} + {highlightRect && ( +
+ )} + + {/* Skip button - top right */} + + + {/* Tooltip card with step content */} +
+ {/* Header */} +
+
+ +
+
+

+ {currentStepData.title} +

+
+ + Step {currentStep + 1} of {totalSteps} + + {/* Step indicators - clickable for navigation */} + +
+
+
+ + {/* Description */} +

+ {currentStepData.description} +

+ + {/* Tip box */} + {currentStepData.tip && ( +
+

+ Tip: + {currentStepData.tip} +

+
+ )} + + {/* Custom content slot (e.g., Quick Start section) */} + {children} + + {/* Navigation buttons */} +
+ + + +
+ + {/* Keyboard hints - hidden on touch devices */} + {!isTouchDevice && ( + + )} +
+
+ ); + + // Render in a portal to ensure it's above everything + return createPortal(content, document.body); +} diff --git a/apps/ui/src/components/shared/onboarding/types.ts b/apps/ui/src/components/shared/onboarding/types.ts new file mode 100644 index 000000000..ce934778f --- /dev/null +++ b/apps/ui/src/components/shared/onboarding/types.ts @@ -0,0 +1,109 @@ +/** + * Shared Onboarding Wizard Types + * + * Generic types for building onboarding wizards across different views. + */ + +import type { ComponentType } from 'react'; + +/** + * Represents a single step in the onboarding wizard + */ +export interface OnboardingStep { + /** Unique identifier for this step */ + id: string; + /** Target element ID - matches data-onboarding-target attribute */ + targetId: string; + /** Step title displayed in the wizard */ + title: string; + /** Main description explaining this step */ + description: string; + /** Optional tip shown in a highlighted box */ + tip?: string; + /** Optional icon component for visual identification */ + icon?: ComponentType<{ className?: string }>; +} + +/** + * Persisted onboarding state structure + */ +export interface OnboardingState { + /** Whether the wizard has been completed */ + completed: boolean; + /** ISO timestamp when completed */ + completedAt?: string; + /** Whether the wizard has been skipped */ + skipped: boolean; + /** ISO timestamp when skipped */ + skippedAt?: string; +} + +/** + * Options for the useOnboardingWizard hook + */ +export interface UseOnboardingWizardOptions { + /** Unique storage key for localStorage persistence */ + storageKey: string; + /** Array of wizard steps to display */ + steps: OnboardingStep[]; + /** Optional callback when wizard is completed */ + onComplete?: () => void; + /** Optional callback when wizard is skipped */ + onSkip?: () => void; +} + +/** + * Return type for the useOnboardingWizard hook + */ +export interface UseOnboardingWizardResult { + /** Whether the wizard is currently visible */ + isVisible: boolean; + /** Current step index (0-based) */ + currentStep: number; + /** Current step data or null if not available */ + currentStepData: OnboardingStep | null; + /** Total number of steps */ + totalSteps: number; + /** Navigate to the next step */ + goToNextStep: () => void; + /** Navigate to the previous step */ + goToPreviousStep: () => void; + /** Navigate to a specific step by index */ + goToStep: (step: number) => void; + /** Start/show the wizard from the beginning */ + startWizard: () => void; + /** Complete the wizard and hide it */ + completeWizard: () => void; + /** Skip the wizard and hide it */ + skipWizard: () => void; + /** Whether the wizard has been completed */ + isCompleted: boolean; + /** Whether the wizard has been skipped */ + isSkipped: boolean; +} + +/** + * Props for the OnboardingWizard component + */ +export interface OnboardingWizardProps { + /** Whether the wizard is visible */ + isVisible: boolean; + /** Current step index */ + currentStep: number; + /** Current step data */ + currentStepData: OnboardingStep | null; + /** Total number of steps */ + totalSteps: number; + /** Handler for next step navigation */ + onNext: () => void; + /** Handler for previous step navigation */ + onPrevious: () => void; + /** Handler for skipping the wizard */ + onSkip: () => void; + /** Handler for completing the wizard */ + onComplete: () => void; + /** Array of all steps (for step indicator navigation) */ + steps: OnboardingStep[]; + /** Optional content to render before navigation buttons (e.g., Quick Start) */ + children?: React.ReactNode; +} diff --git a/apps/ui/src/components/shared/onboarding/use-onboarding-wizard.ts b/apps/ui/src/components/shared/onboarding/use-onboarding-wizard.ts new file mode 100644 index 000000000..a545f0912 --- /dev/null +++ b/apps/ui/src/components/shared/onboarding/use-onboarding-wizard.ts @@ -0,0 +1,216 @@ +/** + * Generic Onboarding Wizard Hook + * + * Manages the state and logic for interactive onboarding wizards. + * Can be used to create onboarding experiences for any view. + * + * Features: + * - Persists completion status to localStorage + * - Step navigation (next, previous, jump to step) + * - Analytics tracking hooks + * - No auto-show logic - wizard only shows via startWizard() + */ + +import { useState, useCallback, useEffect, useMemo } from 'react'; +import { createLogger } from '@automaker/utils/logger'; +import { getItem, setItem } from '@/lib/storage'; +import { ONBOARDING_STORAGE_PREFIX, ONBOARDING_ANALYTICS } from './constants'; +import type { + OnboardingState, + OnboardingStep, + UseOnboardingWizardOptions, + UseOnboardingWizardResult, +} from './types'; + +const logger = createLogger('OnboardingWizard'); + +/** Default state for new wizards */ +const DEFAULT_ONBOARDING_STATE: OnboardingState = { + completed: false, + skipped: false, +}; + +/** + * Load onboarding state from localStorage + */ +function loadOnboardingState(storageKey: string): OnboardingState { + try { + const fullKey = `${ONBOARDING_STORAGE_PREFIX}:${storageKey}`; + const stored = getItem(fullKey); + if (stored) { + return JSON.parse(stored) as OnboardingState; + } + } catch (error) { + logger.error('Failed to load onboarding state:', error); + } + return { ...DEFAULT_ONBOARDING_STATE }; +} + +/** + * Save onboarding state to localStorage + */ +function saveOnboardingState(storageKey: string, state: OnboardingState): void { + try { + const fullKey = `${ONBOARDING_STORAGE_PREFIX}:${storageKey}`; + setItem(fullKey, JSON.stringify(state)); + } catch (error) { + logger.error('Failed to save onboarding state:', error); + } +} + +/** + * Track analytics event (placeholder - integrate with actual analytics service) + */ +function trackAnalytics(event: string, data?: Record): void { + logger.debug(`[Analytics] ${event}`, data); +} + +/** + * Generic hook for managing onboarding wizard state. + * + * @example + * ```tsx + * const wizard = useOnboardingWizard({ + * storageKey: 'my-view-onboarding', + * steps: MY_WIZARD_STEPS, + * onComplete: () => console.log('Done!'), + * }); + * + * // Start the wizard when user clicks help button + * + * + * // Render the wizard + * + * ``` + */ +export function useOnboardingWizard({ + storageKey, + steps, + onComplete, + onSkip, +}: UseOnboardingWizardOptions): UseOnboardingWizardResult { + const [currentStep, setCurrentStep] = useState(0); + const [isWizardVisible, setIsWizardVisible] = useState(false); + const [onboardingState, setOnboardingState] = useState(DEFAULT_ONBOARDING_STATE); + + // Load persisted state on mount + useEffect(() => { + const state = loadOnboardingState(storageKey); + setOnboardingState(state); + }, [storageKey]); + + // Update persisted state helper + const updateState = useCallback( + (updates: Partial) => { + setOnboardingState((prev) => { + const newState = { ...prev, ...updates }; + saveOnboardingState(storageKey, newState); + return newState; + }); + }, + [storageKey] + ); + + // Current step data + const currentStepData = useMemo(() => steps[currentStep] || null, [steps, currentStep]); + const totalSteps = steps.length; + + // Navigation handlers + const goToNextStep = useCallback(() => { + if (currentStep < totalSteps - 1) { + const nextStep = currentStep + 1; + setCurrentStep(nextStep); + trackAnalytics(ONBOARDING_ANALYTICS.STEP_VIEWED, { + storageKey, + step: nextStep, + stepId: steps[nextStep]?.id, + }); + } + }, [currentStep, totalSteps, storageKey, steps]); + + const goToPreviousStep = useCallback(() => { + if (currentStep > 0) { + setCurrentStep(currentStep - 1); + } + }, [currentStep]); + + const goToStep = useCallback( + (step: number) => { + if (step >= 0 && step < totalSteps) { + setCurrentStep(step); + trackAnalytics(ONBOARDING_ANALYTICS.STEP_VIEWED, { + storageKey, + step, + stepId: steps[step]?.id, + }); + } + }, + [totalSteps, storageKey, steps] + ); + + // Wizard lifecycle handlers + const startWizard = useCallback(() => { + setCurrentStep(0); + setIsWizardVisible(true); + trackAnalytics(ONBOARDING_ANALYTICS.STARTED, { storageKey }); + }, [storageKey]); + + const completeWizard = useCallback(() => { + setIsWizardVisible(false); + setCurrentStep(0); + updateState({ + completed: true, + completedAt: new Date().toISOString(), + }); + trackAnalytics(ONBOARDING_ANALYTICS.COMPLETED, { storageKey }); + onComplete?.(); + }, [storageKey, updateState, onComplete]); + + const skipWizard = useCallback(() => { + setIsWizardVisible(false); + setCurrentStep(0); + updateState({ + skipped: true, + skippedAt: new Date().toISOString(), + }); + trackAnalytics(ONBOARDING_ANALYTICS.SKIPPED, { + storageKey, + skippedAtStep: currentStep, + }); + onSkip?.(); + }, [storageKey, currentStep, updateState, onSkip]); + + return { + // Visibility + isVisible: isWizardVisible, + + // Steps + currentStep, + currentStepData, + totalSteps, + + // Navigation + goToNextStep, + goToPreviousStep, + goToStep, + + // Actions + startWizard, + completeWizard, + skipWizard, + + // State + isCompleted: onboardingState.completed, + isSkipped: onboardingState.skipped, + }; +} diff --git a/apps/ui/src/components/views/board-view.tsx b/apps/ui/src/components/views/board-view.tsx index 2b1e35913..741ef5074 100644 --- a/apps/ui/src/components/views/board-view.tsx +++ b/apps/ui/src/components/views/board-view.tsx @@ -72,9 +72,11 @@ import { useBoardPersistence, useFollowUpState, useSelectionMode, + useBoardOnboarding, } from './board-view/hooks'; -import { SelectionActionBar } from './board-view/components'; +import { SelectionActionBar, BoardOnboardingWizard } from './board-view/components'; import { MassEditDialog } from './board-view/dialogs'; +import { generateSampleFeatures, isSampleFeature } from './board-view/constants'; // Stable empty array to avoid infinite loop in selector const EMPTY_WORKTREES: ReturnType['getWorktrees']> = []; @@ -186,6 +188,8 @@ export function BoardView() { const [searchQuery, setSearchQuery] = useState(''); // Plan approval loading state const [isPlanApprovalLoading, setIsPlanApprovalLoading] = useState(false); + // Quick start loading state for onboarding + const [isQuickStartLoading, setIsQuickStartLoading] = useState(false); // Derive spec creation state from store - check if current project is the one being created const isCreatingSpec = specCreatingForProject === currentProject?.path; const creatingSpecProjectPath = specCreatingForProject ?? undefined; @@ -1028,6 +1032,76 @@ export function BoardView() { currentProject, }); + // Use onboarding wizard hook - triggered manually via help button + const onboarding = useBoardOnboarding({ + projectPath: currentProject?.path || null, + }); + + // Handler for Quick Start - create sample features + const handleQuickStart = useCallback(async () => { + if (!currentProject) return; + + setIsQuickStartLoading(true); + try { + const api = getHttpApiClient(); + const sampleFeatures = generateSampleFeatures(); + + // Create each sample feature + for (const featureData of sampleFeatures) { + const result = await api.features.create(currentProject.path, featureData); + if (result.success && result.feature) { + useAppStore.getState().addFeature(result.feature); + } + } + + onboarding.markQuickStartUsed(); + toast.success('Sample tasks added!', { + description: 'Explore the board to see tasks at different stages.', + }); + + // Reload features to ensure state is in sync + loadFeatures(); + } catch (error) { + logger.error('Failed to create sample features:', error); + toast.error('Failed to add sample tasks'); + } finally { + setIsQuickStartLoading(false); + } + }, [currentProject, loadFeatures, onboarding]); + + // Handler for clearing sample data + const handleClearSampleData = useCallback(async () => { + if (!currentProject) return; + + const sampleFeatures = hookFeatures.filter((f) => isSampleFeature(f)); + if (sampleFeatures.length === 0) { + onboarding.setHasSampleData(false); + return; + } + + try { + const api = getHttpApiClient(); + const featureIds = sampleFeatures.map((f) => f.id); + const result = await api.features.bulkDelete(currentProject.path, featureIds); + + if (result.success || (result.results && result.results.some((r) => r.success))) { + // Remove from local state + const successfullyDeletedIds = + result.results?.filter((r) => r.success).map((r) => r.featureId) ?? featureIds; + successfullyDeletedIds.forEach((id) => { + useAppStore.getState().removeFeature(id); + }); + + onboarding.setHasSampleData(false); + toast.success('Sample tasks removed'); + loadFeatures(); + } + } catch (error) { + logger.error('Failed to clear sample data:', error); + toast.error('Failed to remove sample tasks'); + } + }, [currentProject, hookFeatures, loadFeatures, onboarding]); + // Find feature for pending plan approval const pendingApprovalFeature = useMemo(() => { if (!pendingPlanApproval) return null; @@ -1210,6 +1284,7 @@ export function BoardView() { onShowBoardBackground={() => setShowBoardBackgroundModal(true)} onShowCompletedModal={() => setShowCompletedModal(true)} completedCount={completedFeatures.length} + onStartTour={onboarding.startWizard} /> {/* Worktree Panel - conditionally rendered based on visibility setting */} @@ -1568,6 +1643,23 @@ export function BoardView() { setSelectedWorktreeForAction(null); }} /> + + {/* Board Onboarding Wizard */} +
); } diff --git a/apps/ui/src/components/views/board-view/board-controls.tsx b/apps/ui/src/components/views/board-view/board-controls.tsx index c4d7f3af8..9bc66f9ae 100644 --- a/apps/ui/src/components/views/board-view/board-controls.tsx +++ b/apps/ui/src/components/views/board-view/board-controls.tsx @@ -1,12 +1,14 @@ import { Button } from '@/components/ui/button'; import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '@/components/ui/tooltip'; -import { ImageIcon, Archive } from 'lucide-react'; +import { ImageIcon, Archive, HelpCircle } from 'lucide-react'; interface BoardControlsProps { isMounted: boolean; onShowBoardBackground: () => void; onShowCompletedModal: () => void; completedCount: number; + /** Callback to start the onboarding wizard tour */ + onStartTour?: () => void; } export function BoardControls({ @@ -14,12 +16,34 @@ export function BoardControls({ onShowBoardBackground, onShowCompletedModal, completedCount, + onStartTour, }: BoardControlsProps) { if (!isMounted) return null; return (
+ {/* Board Tour Button - always visible when handler is provided */} + {onStartTour && ( + + + + + +

Take a Board Tour

+ + + )} + {/* Board Background Button */} diff --git a/apps/ui/src/components/views/board-view/board-header.tsx b/apps/ui/src/components/views/board-view/board-header.tsx index 5a9b73029..700508247 100644 --- a/apps/ui/src/components/views/board-view/board-header.tsx +++ b/apps/ui/src/components/views/board-view/board-header.tsx @@ -31,6 +31,8 @@ interface BoardHeaderProps { onShowBoardBackground: () => void; onShowCompletedModal: () => void; completedCount: number; + // Tour/onboarding props + onStartTour?: () => void; } // Shared styles for header control containers @@ -53,6 +55,7 @@ export function BoardHeader({ onShowBoardBackground, onShowCompletedModal, completedCount, + onStartTour, }: BoardHeaderProps) { const [showAutoModeSettings, setShowAutoModeSettings] = useState(false); const apiKeys = useAppStore((state) => state.apiKeys); @@ -113,6 +116,7 @@ export function BoardHeader({ onShowBoardBackground={onShowBoardBackground} onShowCompletedModal={onShowCompletedModal} completedCount={completedCount} + onStartTour={onStartTour} />
diff --git a/apps/ui/src/components/views/board-view/components/board-onboarding-wizard.tsx b/apps/ui/src/components/views/board-view/components/board-onboarding-wizard.tsx new file mode 100644 index 000000000..6ac320986 --- /dev/null +++ b/apps/ui/src/components/views/board-view/components/board-onboarding-wizard.tsx @@ -0,0 +1,137 @@ +/** + * Board Onboarding Wizard Component + * + * Board-specific wrapper around the shared OnboardingWizard component. + * Adds Quick Start functionality to generate sample tasks. + */ + +import { Sparkles, CheckCircle2, Trash2, Loader2 } from 'lucide-react'; +import { Button } from '@/components/ui/button'; +import { cn } from '@/lib/utils'; +import { OnboardingWizard, type OnboardingStep } from '@/components/shared/onboarding'; + +interface BoardOnboardingWizardProps { + isVisible: boolean; + currentStep: number; + currentStepData: OnboardingStep | null; + totalSteps: number; + onNext: () => void; + onPrevious: () => void; + onSkip: () => void; + onComplete: () => void; + onQuickStart: () => void; + hasSampleData: boolean; + onClearSampleData: () => void; + isQuickStartLoading?: boolean; + steps: OnboardingStep[]; +} + +/** + * Quick Start section component - only shown on first step + */ +function QuickStartSection({ + onQuickStart, + hasSampleData, + onClearSampleData, + isQuickStartLoading = false, +}: { + onQuickStart: () => void; + hasSampleData: boolean; + onClearSampleData: () => void; + isQuickStartLoading?: boolean; +}) { + return ( +
+

+

+

+ Want to see the board in action? We can add some sample tasks to demonstrate the workflow. +

+
+ + {hasSampleData && ( + + )} +
+
+ ); +} + +export function BoardOnboardingWizard({ + isVisible, + currentStep, + currentStepData, + totalSteps, + onNext, + onPrevious, + onSkip, + onComplete, + onQuickStart, + hasSampleData, + onClearSampleData, + isQuickStartLoading = false, + steps, +}: BoardOnboardingWizardProps) { + const isFirstStep = currentStep === 0; + + return ( + + {/* Board-specific Quick Start section - only on first step */} + {isFirstStep && ( + + )} + + ); +} diff --git a/apps/ui/src/components/views/board-view/components/index.ts b/apps/ui/src/components/views/board-view/components/index.ts index 514e407d6..62692b9cb 100644 --- a/apps/ui/src/components/views/board-view/components/index.ts +++ b/apps/ui/src/components/views/board-view/components/index.ts @@ -1,3 +1,4 @@ export { KanbanCard } from './kanban-card/kanban-card'; export { KanbanColumn } from './kanban-column'; export { SelectionActionBar } from './selection-action-bar'; +export { BoardOnboardingWizard } from './board-onboarding-wizard'; diff --git a/apps/ui/src/components/views/board-view/components/kanban-column.tsx b/apps/ui/src/components/views/board-view/components/kanban-column.tsx index 4a1b62dd7..0a9db2d14 100644 --- a/apps/ui/src/components/views/board-view/components/kanban-column.tsx +++ b/apps/ui/src/components/views/board-view/components/kanban-column.tsx @@ -50,6 +50,7 @@ export const KanbanColumn = memo(function KanbanColumn({ )} style={widthStyle} data-testid={`kanban-column-${id}`} + data-onboarding-target={id} > {/* Background layer with opacity */}
): boolean { + // Check title prefix - this is the reliable marker that persists through the database + return feature.title?.startsWith(SAMPLE_FEATURE_PREFIX) ?? false; +} + +/** + * Generate sample feature data with unique IDs + * @returns Array of sample features ready to be created + */ +export function generateSampleFeatures(): Array> { + return SAMPLE_FEATURES.map((template) => ({ + title: template.title, + description: template.description, + category: template.category, + status: template.status, + priority: template.priority, + images: [], + imagePaths: [], + skipTests: true, + model: 'sonnet' as const, + thinkingLevel: 'none' as const, + planningMode: 'skip' as const, + requirePlanApproval: false, + // Mark as sample data in a way that persists + // We use the title prefix [DEMO] as the marker + })); +} diff --git a/apps/ui/src/components/views/board-view/hooks/index.ts b/apps/ui/src/components/views/board-view/hooks/index.ts index 272937f45..230311ced 100644 --- a/apps/ui/src/components/views/board-view/hooks/index.ts +++ b/apps/ui/src/components/views/board-view/hooks/index.ts @@ -8,3 +8,4 @@ export { useBoardBackground } from './use-board-background'; export { useBoardPersistence } from './use-board-persistence'; export { useFollowUpState } from './use-follow-up-state'; export { useSelectionMode } from './use-selection-mode'; +export { useBoardOnboarding } from './use-board-onboarding'; diff --git a/apps/ui/src/components/views/board-view/hooks/use-board-onboarding.ts b/apps/ui/src/components/views/board-view/hooks/use-board-onboarding.ts new file mode 100644 index 000000000..c21c2a89d --- /dev/null +++ b/apps/ui/src/components/views/board-view/hooks/use-board-onboarding.ts @@ -0,0 +1,275 @@ +/** + * Board Onboarding Hook + * + * Board-specific wrapper around the shared onboarding wizard hook. + * Manages board-specific features like sample data (Quick Start). + * + * Usage: + * - Wizard is triggered manually via startWizard() when user clicks help button + * - No auto-show logic - user controls when to see the wizard + */ + +import { useState, useCallback, useEffect } from 'react'; +import { createLogger } from '@automaker/utils/logger'; +import { getItem, setItem } from '@/lib/storage'; +import { + useOnboardingWizard, + ONBOARDING_TARGET_ATTRIBUTE, + type OnboardingStep, +} from '@/components/shared/onboarding'; +import { PlayCircle, Sparkles, Lightbulb, CheckCircle2, Settings2 } from 'lucide-react'; + +const logger = createLogger('BoardOnboarding'); + +// ============================================================================ +// CONSTANTS +// ============================================================================ + +/** Storage key prefix for board-specific onboarding data */ +const BOARD_ONBOARDING_STORAGE_KEY = 'automaker:board-onboarding-data'; + +/** Maximum length for project path hash in storage key */ +const PROJECT_PATH_HASH_MAX_LENGTH = 50; + +// Board-specific analytics events +export const BOARD_ONBOARDING_ANALYTICS = { + QUICK_START_USED: 'board_onboarding_quick_start_used', + SAMPLE_DATA_CLEARED: 'board_onboarding_sample_data_cleared', +} as const; + +// ============================================================================ +// WIZARD STEPS +// ============================================================================ + +/** + * Board wizard step definitions + * Each step targets a kanban column via data-onboarding-target + */ +export const BOARD_WIZARD_STEPS: OnboardingStep[] = [ + { + id: 'backlog', + targetId: 'backlog', + title: 'Backlog', + description: + 'This is where all your planned tasks live. Add new features, bug fixes, or improvements here. When you\'re ready to work on something, drag it to "In Progress" or click the play button.', + tip: 'Press N or click the + button to quickly add a new feature.', + icon: PlayCircle, + }, + { + id: 'in_progress', + targetId: 'in_progress', + title: 'In Progress', + description: + 'Tasks being actively worked on appear here. AI agents automatically pick up items from the backlog and move them here when processing begins.', + tip: 'You can run multiple tasks simultaneously using Auto Mode.', + icon: Sparkles, + }, + { + id: 'waiting_approval', + targetId: 'waiting_approval', + title: 'Waiting Approval', + description: + 'Completed work lands here for your review. Check the changes, run tests, and approve or send back for revisions.', + tip: 'Click "View Output" to see what the AI agent did.', + icon: Lightbulb, + }, + { + id: 'verified', + targetId: 'verified', + title: 'Verified', + description: + "Approved and verified tasks are ready for deployment! Archive them when you're done or move them back if changes are needed.", + tip: 'Click "Complete All" to archive all verified items at once.', + icon: CheckCircle2, + }, + { + id: 'custom_columns', + targetId: 'pipeline-settings', // Highlight the pipeline settings button icon + title: 'Custom Pipelines', + description: + 'You can create custom columns (called pipelines) to build your own workflow! Click this settings icon to add, rename, or configure pipeline steps.', + tip: 'Use pipelines to add code review, QA testing, or any custom stage to your workflow.', + icon: Settings2, + }, +]; + +// Re-export for backward compatibility +export type { OnboardingStep as WizardStep } from '@/components/shared/onboarding'; +export { ONBOARDING_TARGET_ATTRIBUTE }; + +// ============================================================================ +// BOARD-SPECIFIC STATE +// ============================================================================ + +interface BoardOnboardingData { + hasSampleData: boolean; + quickStartUsed: boolean; +} + +const DEFAULT_BOARD_DATA: BoardOnboardingData = { + hasSampleData: false, + quickStartUsed: false, +}; + +/** + * Sanitize project path to create a storage key + */ +function sanitizeProjectPath(projectPath: string): string { + return projectPath.replace(/[^a-zA-Z0-9]/g, '_').slice(0, PROJECT_PATH_HASH_MAX_LENGTH); +} + +/** + * Get storage key for board-specific data + */ +function getBoardDataStorageKey(projectPath: string): string { + const hash = sanitizeProjectPath(projectPath); + return `${BOARD_ONBOARDING_STORAGE_KEY}:${hash}`; +} + +/** + * Load board-specific onboarding data from localStorage + */ +function loadBoardData(projectPath: string): BoardOnboardingData { + try { + const key = getBoardDataStorageKey(projectPath); + const stored = getItem(key); + if (stored) { + return JSON.parse(stored) as BoardOnboardingData; + } + } catch (error) { + logger.error('Failed to load board onboarding data:', error); + } + return { ...DEFAULT_BOARD_DATA }; +} + +/** + * Save board-specific onboarding data to localStorage + */ +function saveBoardData(projectPath: string, data: BoardOnboardingData): void { + try { + const key = getBoardDataStorageKey(projectPath); + setItem(key, JSON.stringify(data)); + } catch (error) { + logger.error('Failed to save board onboarding data:', error); + } +} + +/** + * Track analytics event (placeholder) + */ +function trackAnalytics(event: string, data?: Record): void { + logger.debug(`[Analytics] ${event}`, data); +} + +// ============================================================================ +// HOOK +// ============================================================================ + +export interface UseBoardOnboardingOptions { + projectPath: string | null; +} + +export interface UseBoardOnboardingResult { + // From shared wizard hook + isWizardVisible: boolean; + currentStep: number; + currentStepData: OnboardingStep | null; + totalSteps: number; + goToNextStep: () => void; + goToPreviousStep: () => void; + goToStep: (step: number) => void; + startWizard: () => void; + completeWizard: () => void; + skipWizard: () => void; + isCompleted: boolean; + isSkipped: boolean; + + // Board-specific + hasSampleData: boolean; + setHasSampleData: (has: boolean) => void; + markQuickStartUsed: () => void; + + // Steps data for component + steps: OnboardingStep[]; +} + +export function useBoardOnboarding({ + projectPath, +}: UseBoardOnboardingOptions): UseBoardOnboardingResult { + // Board-specific state for sample data + const [boardData, setBoardData] = useState(DEFAULT_BOARD_DATA); + + // Create storage key from project path + const storageKey = projectPath ? `board:${sanitizeProjectPath(projectPath)}` : 'board:default'; + + // Use the shared onboarding wizard hook + const wizard = useOnboardingWizard({ + storageKey, + steps: BOARD_WIZARD_STEPS, + }); + + // Load board-specific data when project changes + useEffect(() => { + if (!projectPath) { + setBoardData(DEFAULT_BOARD_DATA); + return; + } + + const data = loadBoardData(projectPath); + setBoardData(data); + }, [projectPath]); + + // Update board data helper + const updateBoardData = useCallback( + (updates: Partial) => { + if (!projectPath) return; + + setBoardData((prev) => { + const newData = { ...prev, ...updates }; + saveBoardData(projectPath, newData); + return newData; + }); + }, + [projectPath] + ); + + // Sample data handlers + const setHasSampleData = useCallback( + (has: boolean) => { + updateBoardData({ hasSampleData: has }); + if (!has) { + trackAnalytics(BOARD_ONBOARDING_ANALYTICS.SAMPLE_DATA_CLEARED, { projectPath }); + } + }, + [projectPath, updateBoardData] + ); + + const markQuickStartUsed = useCallback(() => { + updateBoardData({ quickStartUsed: true, hasSampleData: true }); + trackAnalytics(BOARD_ONBOARDING_ANALYTICS.QUICK_START_USED, { projectPath }); + }, [projectPath, updateBoardData]); + + return { + // Spread shared wizard state and actions + isWizardVisible: wizard.isVisible, + currentStep: wizard.currentStep, + currentStepData: wizard.currentStepData, + totalSteps: wizard.totalSteps, + goToNextStep: wizard.goToNextStep, + goToPreviousStep: wizard.goToPreviousStep, + goToStep: wizard.goToStep, + startWizard: wizard.startWizard, + completeWizard: wizard.completeWizard, + skipWizard: wizard.skipWizard, + isCompleted: wizard.isCompleted, + isSkipped: wizard.isSkipped, + + // Board-specific + hasSampleData: boardData.hasSampleData, + setHasSampleData, + markQuickStartUsed, + + // Steps data + steps: BOARD_WIZARD_STEPS, + }; +} diff --git a/apps/ui/src/components/views/board-view/kanban-board.tsx b/apps/ui/src/components/views/board-view/kanban-board.tsx index 4601a70c5..ca055d532 100644 --- a/apps/ui/src/components/views/board-view/kanban-board.tsx +++ b/apps/ui/src/components/views/board-view/kanban-board.tsx @@ -173,6 +173,7 @@ export function KanbanBoard({ onClick={onOpenPipelineSettings} title="Pipeline Settings" data-testid="pipeline-settings-button" + data-onboarding-target="pipeline-settings" >