mirror of
https://github.com/AutoMaker-Org/automaker.git
synced 2026-01-30 22:32:04 +00:00
feat: implement onboarding wizard for board view
- Added a new onboarding wizard to guide users through the board features. - Integrated sample feature generation for quick start onboarding. - Enhanced BoardView component to manage onboarding state and actions. - Updated BoardControls and BoardHeader to include tour functionality. - Introduced utility functions for sample feature management in constants. - Improved user experience with toast notifications for onboarding actions.
This commit is contained in:
Shirone
@@ -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<ReturnType<typeof useAppStore.getState>['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,84 @@ export function BoardView() {
|
||||
currentProject,
|
||||
});
|
||||
|
||||
// Use onboarding wizard hook - check if board is empty (no non-sample features)
|
||||
const nonSampleFeatureCount = useMemo(
|
||||
() => hookFeatures.filter((f) => !isSampleFeature(f)).length,
|
||||
[hookFeatures]
|
||||
);
|
||||
const onboarding = useBoardOnboarding({
|
||||
projectPath: currentProject?.path || null,
|
||||
isEmpty: nonSampleFeatureCount === 0 && !isLoading,
|
||||
totalFeatureCount: hookFeatures.length,
|
||||
// Don't show wizard when spec generation is happening (for new projects)
|
||||
isSpecDialogOpen: isCreatingSpec,
|
||||
});
|
||||
|
||||
// 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 +1292,8 @@ export function BoardView() {
|
||||
onShowBoardBackground={() => setShowBoardBackgroundModal(true)}
|
||||
onShowCompletedModal={() => setShowCompletedModal(true)}
|
||||
completedCount={completedFeatures.length}
|
||||
onShowTour={onboarding.retriggerWizard}
|
||||
canShowTour={onboarding.canRetrigger}
|
||||
/>
|
||||
|
||||
{/* Worktree Panel - conditionally rendered based on visibility setting */}
|
||||
@@ -1568,6 +1652,22 @@ export function BoardView() {
|
||||
setSelectedWorktreeForAction(null);
|
||||
}}
|
||||
/>
|
||||
|
||||
{/* Board Onboarding Wizard */}
|
||||
<BoardOnboardingWizard
|
||||
isVisible={onboarding.isWizardVisible}
|
||||
currentStep={onboarding.currentStep}
|
||||
currentStepData={onboarding.currentStepData}
|
||||
totalSteps={onboarding.totalSteps}
|
||||
onNext={onboarding.goToNextStep}
|
||||
onPrevious={onboarding.goToPreviousStep}
|
||||
onSkip={onboarding.skipWizard}
|
||||
onComplete={onboarding.completeWizard}
|
||||
onQuickStart={handleQuickStart}
|
||||
hasSampleData={onboarding.hasSampleData}
|
||||
onClearSampleData={handleClearSampleData}
|
||||
isQuickStartLoading={isQuickStartLoading}
|
||||
/>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
|
||||
@@ -1,12 +1,16 @@
|
||||
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 show the onboarding wizard tour */
|
||||
onShowTour?: () => void;
|
||||
/** Whether the tour can be shown (wizard was previously completed/skipped) */
|
||||
canShowTour?: boolean;
|
||||
}
|
||||
|
||||
export function BoardControls({
|
||||
@@ -14,12 +18,35 @@ export function BoardControls({
|
||||
onShowBoardBackground,
|
||||
onShowCompletedModal,
|
||||
completedCount,
|
||||
onShowTour,
|
||||
canShowTour = false,
|
||||
}: BoardControlsProps) {
|
||||
if (!isMounted) return null;
|
||||
|
||||
return (
|
||||
<TooltipProvider>
|
||||
<div className="flex items-center gap-2">
|
||||
{/* Board Tour Button - only show if tour can be retriggered */}
|
||||
{canShowTour && onShowTour && (
|
||||
<Tooltip>
|
||||
<TooltipTrigger asChild>
|
||||
<Button
|
||||
variant="outline"
|
||||
size="sm"
|
||||
onClick={onShowTour}
|
||||
className="h-8 px-2 min-w-[32px] focus-visible:ring-2 focus-visible:ring-primary"
|
||||
data-testid="board-tour-button"
|
||||
aria-label="Take a board tour - learn how to use the kanban board"
|
||||
>
|
||||
<HelpCircle className="w-4 h-4" aria-hidden="true" />
|
||||
</Button>
|
||||
</TooltipTrigger>
|
||||
<TooltipContent>
|
||||
<p>Take a Board Tour</p>
|
||||
</TooltipContent>
|
||||
</Tooltip>
|
||||
)}
|
||||
|
||||
{/* Board Background Button */}
|
||||
<Tooltip>
|
||||
<TooltipTrigger asChild>
|
||||
|
||||
@@ -31,6 +31,9 @@ interface BoardHeaderProps {
|
||||
onShowBoardBackground: () => void;
|
||||
onShowCompletedModal: () => void;
|
||||
completedCount: number;
|
||||
// Tour/onboarding props
|
||||
onShowTour?: () => void;
|
||||
canShowTour?: boolean;
|
||||
}
|
||||
|
||||
// Shared styles for header control containers
|
||||
@@ -53,6 +56,8 @@ export function BoardHeader({
|
||||
onShowBoardBackground,
|
||||
onShowCompletedModal,
|
||||
completedCount,
|
||||
onShowTour,
|
||||
canShowTour,
|
||||
}: BoardHeaderProps) {
|
||||
const [showAutoModeSettings, setShowAutoModeSettings] = useState(false);
|
||||
const apiKeys = useAppStore((state) => state.apiKeys);
|
||||
@@ -113,6 +118,8 @@ export function BoardHeader({
|
||||
onShowBoardBackground={onShowBoardBackground}
|
||||
onShowCompletedModal={onShowCompletedModal}
|
||||
completedCount={completedCount}
|
||||
onShowTour={onShowTour}
|
||||
canShowTour={canShowTour}
|
||||
/>
|
||||
</div>
|
||||
<div className="flex gap-2 items-center">
|
||||
|
||||
@@ -0,0 +1,678 @@
|
||||
/**
|
||||
* Board Onboarding Wizard Component
|
||||
*
|
||||
* A multi-step wizard overlay that guides new users through the Kanban board
|
||||
* workflow with visual highlighting (spotlight effect) on each column.
|
||||
*
|
||||
* Features:
|
||||
* - Spotlight/overlay effect to focus attention on each column
|
||||
* - Step navigation (Next, Previous, Skip)
|
||||
* - Quick Start button to generate sample cards
|
||||
* - Responsive design for mobile, tablet, and desktop
|
||||
* - Keyboard navigation support
|
||||
*/
|
||||
|
||||
import { useEffect, useRef, useCallback, useState } from 'react';
|
||||
import { createPortal } from 'react-dom';
|
||||
import {
|
||||
X,
|
||||
ChevronLeft,
|
||||
ChevronRight,
|
||||
Sparkles,
|
||||
PlayCircle,
|
||||
Lightbulb,
|
||||
CheckCircle2,
|
||||
Trash2,
|
||||
Loader2,
|
||||
PartyPopper,
|
||||
Settings2,
|
||||
} from 'lucide-react';
|
||||
import { Button } from '@/components/ui/button';
|
||||
import { cn } from '@/lib/utils';
|
||||
import { WIZARD_STEPS, type WizardStep } from '../hooks/use-board-onboarding';
|
||||
|
||||
// ============================================================================
|
||||
// CONSTANTS
|
||||
// ============================================================================
|
||||
|
||||
/** Threshold for placing tooltip to the right of column (30% of viewport) */
|
||||
const TOOLTIP_POSITION_RIGHT_THRESHOLD = 0.3;
|
||||
|
||||
/** Threshold for placing tooltip to the left of column (70% of viewport) */
|
||||
const TOOLTIP_POSITION_LEFT_THRESHOLD = 0.7;
|
||||
|
||||
/** Padding around tooltip and highlight elements (px) */
|
||||
const SPOTLIGHT_PADDING = 8;
|
||||
|
||||
/** Padding between column and tooltip (px) */
|
||||
const TOOLTIP_OFFSET = 16;
|
||||
|
||||
/** Vertical offset from top of column to tooltip (px) */
|
||||
const TOOLTIP_TOP_OFFSET = 40;
|
||||
|
||||
/** Maximum tooltip width (px) */
|
||||
const TOOLTIP_MAX_WIDTH = 400;
|
||||
|
||||
/** Minimum safe margin from viewport edges (px) */
|
||||
const VIEWPORT_SAFE_MARGIN = 16;
|
||||
|
||||
/** Threshold from bottom of viewport to trigger alternate positioning (px) */
|
||||
const BOTTOM_THRESHOLD = 450;
|
||||
|
||||
/** Debounce delay for resize handler (ms) */
|
||||
const RESIZE_DEBOUNCE_MS = 100;
|
||||
|
||||
/** Animation duration for step transitions (ms) */
|
||||
const STEP_TRANSITION_DURATION = 200;
|
||||
|
||||
/** ID for the wizard description element (for aria-describedby) */
|
||||
const WIZARD_DESCRIPTION_ID = 'wizard-step-description';
|
||||
|
||||
/** ID for the wizard title element (for aria-labelledby) */
|
||||
const WIZARD_TITLE_ID = 'wizard-step-title';
|
||||
|
||||
interface BoardOnboardingWizardProps {
|
||||
isVisible: boolean;
|
||||
currentStep: number;
|
||||
currentStepData: WizardStep | null;
|
||||
totalSteps: number;
|
||||
onNext: () => void;
|
||||
onPrevious: () => void;
|
||||
onSkip: () => void;
|
||||
onComplete: () => void;
|
||||
onQuickStart: () => void;
|
||||
hasSampleData: boolean;
|
||||
onClearSampleData: () => void;
|
||||
isQuickStartLoading?: boolean;
|
||||
}
|
||||
|
||||
// Icons for each column/step
|
||||
const STEP_ICONS: Record<string, React.ComponentType<{ className?: string }>> = {
|
||||
backlog: PlayCircle,
|
||||
in_progress: Sparkles,
|
||||
waiting_approval: Lightbulb,
|
||||
verified: CheckCircle2,
|
||||
custom_columns: Settings2,
|
||||
};
|
||||
|
||||
export function BoardOnboardingWizard({
|
||||
isVisible,
|
||||
currentStep,
|
||||
currentStepData,
|
||||
totalSteps,
|
||||
onNext,
|
||||
onPrevious,
|
||||
onSkip,
|
||||
onComplete,
|
||||
onQuickStart,
|
||||
hasSampleData,
|
||||
onClearSampleData,
|
||||
isQuickStartLoading = false,
|
||||
}: BoardOnboardingWizardProps) {
|
||||
// Store rect as simple object to avoid DOMRect type issues
|
||||
const [highlightRect, setHighlightRect] = useState<{
|
||||
top: number;
|
||||
left: number;
|
||||
right: number;
|
||||
bottom: number;
|
||||
width: number;
|
||||
height: number;
|
||||
} | null>(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<HTMLDivElement>(null);
|
||||
const nextButtonRef = useRef<HTMLButtonElement>(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;
|
||||
|
||||
// Prevent body scroll while wizard is open
|
||||
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;
|
||||
|
||||
// Focus the next button when wizard opens for keyboard accessibility
|
||||
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 current column
|
||||
useEffect(() => {
|
||||
if (!isVisible || !currentStepData) {
|
||||
setHighlightRect(null);
|
||||
return;
|
||||
}
|
||||
|
||||
// Helper to update highlight rect and tooltip position
|
||||
const updateHighlight = () => {
|
||||
const columnEl = document.querySelector(
|
||||
`[data-testid="kanban-column-${currentStepData.columnId}"]`
|
||||
);
|
||||
|
||||
if (columnEl) {
|
||||
const rect = columnEl.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 column position and available space
|
||||
const viewportWidth = window.innerWidth;
|
||||
const viewportHeight = window.innerHeight;
|
||||
const columnCenter = rect.left + rect.width / 2;
|
||||
const tooltipWidth = Math.min(TOOLTIP_MAX_WIDTH, viewportWidth - VIEWPORT_SAFE_MARGIN * 2);
|
||||
|
||||
// Check if there's enough space at the bottom
|
||||
const spaceAtBottom = viewportHeight - rect.bottom - TOOLTIP_OFFSET;
|
||||
const spaceAtRight = viewportWidth - rect.right - TOOLTIP_OFFSET;
|
||||
const spaceAtLeft = rect.left - TOOLTIP_OFFSET;
|
||||
|
||||
// For leftmost columns, prefer right position
|
||||
if (
|
||||
columnCenter < viewportWidth * TOOLTIP_POSITION_RIGHT_THRESHOLD &&
|
||||
spaceAtRight >= tooltipWidth
|
||||
) {
|
||||
setTooltipPosition('right');
|
||||
}
|
||||
// For rightmost columns, prefer left position
|
||||
else if (
|
||||
columnCenter > viewportWidth * TOOLTIP_POSITION_LEFT_THRESHOLD &&
|
||||
spaceAtLeft >= tooltipWidth
|
||||
) {
|
||||
setTooltipPosition('left');
|
||||
}
|
||||
// For middle columns, check if bottom position would work
|
||||
else if (spaceAtBottom >= BOTTOM_THRESHOLD) {
|
||||
setTooltipPosition('bottom');
|
||||
}
|
||||
// If bottom doesn't have enough space, try left or right based on which has more space
|
||||
else if (spaceAtRight > spaceAtLeft && spaceAtRight >= tooltipWidth * 0.6) {
|
||||
setTooltipPosition('right');
|
||||
} else if (spaceAtLeft >= tooltipWidth * 0.6) {
|
||||
setTooltipPosition('left');
|
||||
}
|
||||
// Fallback to bottom with scrollable content
|
||||
else {
|
||||
setTooltipPosition('bottom');
|
||||
}
|
||||
}
|
||||
};
|
||||
|
||||
// Initial update
|
||||
updateHighlight();
|
||||
|
||||
// Debounced resize handler for performance
|
||||
let resizeTimeout: ReturnType<typeof setTimeout>;
|
||||
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 {
|
||||
onComplete();
|
||||
}
|
||||
} else if (e.key === 'ArrowLeft') {
|
||||
onPrevious();
|
||||
}
|
||||
};
|
||||
|
||||
window.addEventListener('keydown', handleKeyDown);
|
||||
return () => window.removeEventListener('keydown', handleKeyDown);
|
||||
}, [isVisible, currentStep, totalSteps, onNext, onPrevious, onSkip, onComplete]);
|
||||
|
||||
// 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: {
|
||||
// Calculate available space at bottom
|
||||
const idealTop = highlightRect.bottom + TOOLTIP_OFFSET;
|
||||
const availableHeight = viewportHeight - idealTop - VIEWPORT_SAFE_MARGIN;
|
||||
|
||||
// If not enough space, position higher but ensure tooltip stays below header
|
||||
const minTop = 100; // Minimum distance from top of viewport
|
||||
const topPos =
|
||||
availableHeight < 250
|
||||
? Math.max(
|
||||
minTop,
|
||||
viewportHeight - Math.max(300, availableHeight) - VIEWPORT_SAFE_MARGIN
|
||||
)
|
||||
: idealTop;
|
||||
|
||||
// Center tooltip under column but keep within viewport bounds
|
||||
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);
|
||||
// Show celebration briefly before completing
|
||||
setTimeout(() => {
|
||||
setShowCompletionCelebration(false);
|
||||
onComplete();
|
||||
}, 1200);
|
||||
}, [onComplete]);
|
||||
|
||||
// Handle step indicator click for direct navigation
|
||||
const handleStepClick = useCallback(
|
||||
(stepIndex: number) => {
|
||||
if (stepIndex === currentStep) return;
|
||||
|
||||
// Use onNext/onPrevious to properly track analytics
|
||||
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 = STEP_ICONS[currentStepData.id] || Sparkles;
|
||||
const isLastStep = currentStep === totalSteps - 1;
|
||||
const isFirstStep = currentStep === 0;
|
||||
|
||||
const content = (
|
||||
<div
|
||||
ref={dialogRef}
|
||||
className="fixed inset-0 z-[100]"
|
||||
role="dialog"
|
||||
aria-modal="true"
|
||||
aria-labelledby={WIZARD_TITLE_ID}
|
||||
aria-describedby={WIZARD_DESCRIPTION_ID}
|
||||
>
|
||||
{/* Completion celebration overlay */}
|
||||
{showCompletionCelebration && (
|
||||
<div className="absolute inset-0 z-[102] flex items-center justify-center pointer-events-none">
|
||||
<div className="animate-in zoom-in-50 fade-in duration-300 flex flex-col items-center gap-4 text-white">
|
||||
<PartyPopper className="w-16 h-16 text-yellow-400 animate-bounce" />
|
||||
<p className="text-2xl font-bold">You're all set!</p>
|
||||
</div>
|
||||
</div>
|
||||
)}
|
||||
|
||||
{/* Dark overlay with cutout for highlighted column */}
|
||||
<svg
|
||||
className="absolute inset-0 w-full h-full pointer-events-none"
|
||||
xmlns="http://www.w3.org/2000/svg"
|
||||
aria-hidden="true"
|
||||
>
|
||||
<defs>
|
||||
<mask id="spotlight-mask">
|
||||
{/* White = visible, black = hidden */}
|
||||
<rect x="0" y="0" width="100%" height="100%" fill="white" />
|
||||
{highlightRect && (
|
||||
<rect
|
||||
x={highlightRect.left - SPOTLIGHT_PADDING}
|
||||
y={highlightRect.top - SPOTLIGHT_PADDING}
|
||||
width={highlightRect.width + SPOTLIGHT_PADDING * 2}
|
||||
height={highlightRect.height + SPOTLIGHT_PADDING * 2}
|
||||
rx="16"
|
||||
fill="black"
|
||||
/>
|
||||
)}
|
||||
</mask>
|
||||
</defs>
|
||||
<rect
|
||||
x="0"
|
||||
y="0"
|
||||
width="100%"
|
||||
height="100%"
|
||||
fill="rgba(0, 0, 0, 0.75)"
|
||||
mask="url(#spotlight-mask)"
|
||||
className="transition-all duration-300"
|
||||
/>
|
||||
</svg>
|
||||
|
||||
{/* Highlight border around the column */}
|
||||
{highlightRect && (
|
||||
<div
|
||||
className="absolute pointer-events-none transition-all duration-300 ease-out"
|
||||
style={{
|
||||
left: highlightRect.left - SPOTLIGHT_PADDING,
|
||||
top: highlightRect.top - SPOTLIGHT_PADDING,
|
||||
width: highlightRect.width + SPOTLIGHT_PADDING * 2,
|
||||
height: highlightRect.height + SPOTLIGHT_PADDING * 2,
|
||||
borderRadius: '16px',
|
||||
border: '2px solid hsl(var(--primary))',
|
||||
boxShadow:
|
||||
'0 0 20px 4px hsl(var(--primary) / 0.3), inset 0 0 20px 4px hsl(var(--primary) / 0.1)',
|
||||
}}
|
||||
/>
|
||||
)}
|
||||
|
||||
{/* Skip button - top right with accessible touch target */}
|
||||
<Button
|
||||
variant="ghost"
|
||||
size="sm"
|
||||
className={cn(
|
||||
'fixed top-4 right-4 z-[101]',
|
||||
'text-white/70 hover:text-white hover:bg-white/10',
|
||||
'focus-visible:ring-2 focus-visible:ring-white focus-visible:ring-offset-2 focus-visible:ring-offset-transparent',
|
||||
'min-h-[44px] min-w-[44px] px-3' // Ensure minimum touch target size
|
||||
)}
|
||||
onClick={onSkip}
|
||||
aria-label="Skip the onboarding tour"
|
||||
>
|
||||
<X className="w-4 h-4 mr-1.5" aria-hidden="true" />
|
||||
<span>Skip Tour</span>
|
||||
</Button>
|
||||
|
||||
{/* Tooltip/Card with step content */}
|
||||
<div
|
||||
className={cn(
|
||||
'z-[101] bg-popover/95 backdrop-blur-xl rounded-xl shadow-2xl border border-border/50',
|
||||
'p-6 animate-in fade-in-0 slide-in-from-bottom-4 duration-300',
|
||||
'max-h-[calc(100vh-100px)] overflow-y-auto',
|
||||
// Step transition animation
|
||||
isAnimating && 'opacity-90 scale-[0.98]',
|
||||
'transition-all duration-200 ease-out'
|
||||
)}
|
||||
style={getTooltipStyles()}
|
||||
>
|
||||
{/* Header */}
|
||||
<div className="flex items-start gap-4 mb-4">
|
||||
<div className="flex items-center justify-center w-12 h-12 rounded-xl bg-primary/10 border border-primary/20 shrink-0">
|
||||
<StepIcon className="w-6 h-6 text-primary" />
|
||||
</div>
|
||||
<div className="flex-1 min-w-0">
|
||||
<h3 id={WIZARD_TITLE_ID} className="text-lg font-semibold text-foreground truncate">
|
||||
{currentStepData.title}
|
||||
</h3>
|
||||
<div className="flex items-center gap-2 mt-1.5">
|
||||
<span className="text-xs text-muted-foreground" aria-live="polite">
|
||||
Step {currentStep + 1} of {totalSteps}
|
||||
</span>
|
||||
{/* Step indicators - clickable for navigation */}
|
||||
<nav aria-label="Wizard steps" className="flex items-center gap-1">
|
||||
{Array.from({ length: totalSteps }).map((_, i) => (
|
||||
<button
|
||||
key={i}
|
||||
type="button"
|
||||
onClick={() => handleStepClick(i)}
|
||||
className={cn(
|
||||
'relative flex items-center justify-center',
|
||||
'w-6 h-6', // Touch target size
|
||||
'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary focus-visible:ring-offset-1 focus-visible:rounded-full',
|
||||
'transition-transform duration-200 hover:scale-110'
|
||||
)}
|
||||
aria-label={`Go to step ${i + 1}: ${WIZARD_STEPS[i]?.title}`}
|
||||
aria-current={i === currentStep ? 'step' : undefined}
|
||||
>
|
||||
{/* Visual dot indicator */}
|
||||
<span
|
||||
className={cn(
|
||||
'block rounded-full transition-all duration-200',
|
||||
i === currentStep
|
||||
? 'w-2.5 h-2.5 bg-primary ring-2 ring-primary/30 ring-offset-1 ring-offset-popover'
|
||||
: i < currentStep
|
||||
? 'w-2 h-2 bg-primary/60'
|
||||
: 'w-2 h-2 bg-muted-foreground/40'
|
||||
)}
|
||||
/>
|
||||
</button>
|
||||
))}
|
||||
</nav>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
{/* Description */}
|
||||
<p
|
||||
id={WIZARD_DESCRIPTION_ID}
|
||||
className="text-sm text-muted-foreground leading-relaxed mb-4"
|
||||
>
|
||||
{currentStepData.description}
|
||||
</p>
|
||||
|
||||
{/* Tip box */}
|
||||
{currentStepData.tip && (
|
||||
<div className="rounded-lg bg-primary/5 border border-primary/10 p-3 mb-4">
|
||||
<p className="text-xs text-muted-foreground">
|
||||
<span className="font-medium text-foreground">Tip: </span>
|
||||
{currentStepData.tip}
|
||||
</p>
|
||||
</div>
|
||||
)}
|
||||
|
||||
{/* Quick Start section - only on first step */}
|
||||
{isFirstStep && (
|
||||
<div className="rounded-lg bg-muted/30 border border-border/50 p-4 mb-4">
|
||||
<h4 className="text-sm font-medium text-foreground mb-2 flex items-center gap-2">
|
||||
<Sparkles className="w-4 h-4 text-primary" aria-hidden="true" />
|
||||
Quick Start
|
||||
</h4>
|
||||
<p className="text-xs text-muted-foreground mb-3">
|
||||
Want to see the board in action? We can add some sample tasks to demonstrate the
|
||||
workflow.
|
||||
</p>
|
||||
<div className="flex gap-2">
|
||||
<Button
|
||||
size="sm"
|
||||
variant="secondary"
|
||||
onClick={onQuickStart}
|
||||
disabled={hasSampleData || isQuickStartLoading}
|
||||
className={cn(
|
||||
'flex-1 min-h-[40px]', // Slightly larger touch target
|
||||
'focus-visible:ring-2 focus-visible:ring-primary'
|
||||
)}
|
||||
aria-busy={isQuickStartLoading}
|
||||
>
|
||||
{isQuickStartLoading ? (
|
||||
<>
|
||||
<Loader2 className="w-3.5 h-3.5 mr-1.5 animate-spin" aria-hidden="true" />
|
||||
<span>Adding tasks...</span>
|
||||
</>
|
||||
) : hasSampleData ? (
|
||||
<>
|
||||
<CheckCircle2
|
||||
className="w-3.5 h-3.5 mr-1.5 text-green-500"
|
||||
aria-hidden="true"
|
||||
/>
|
||||
<span>Sample Data Added</span>
|
||||
</>
|
||||
) : (
|
||||
<>
|
||||
<Sparkles className="w-3.5 h-3.5 mr-1.5" aria-hidden="true" />
|
||||
<span>Add Sample Tasks</span>
|
||||
</>
|
||||
)}
|
||||
</Button>
|
||||
{hasSampleData && (
|
||||
<Button
|
||||
size="sm"
|
||||
variant="ghost"
|
||||
onClick={onClearSampleData}
|
||||
className={cn(
|
||||
'min-w-[44px] min-h-[40px] px-3', // Accessible touch target
|
||||
'focus-visible:ring-2 focus-visible:ring-destructive'
|
||||
)}
|
||||
aria-label="Remove sample tasks"
|
||||
>
|
||||
<Trash2 className="w-4 h-4" aria-hidden="true" />
|
||||
</Button>
|
||||
)}
|
||||
</div>
|
||||
</div>
|
||||
)}
|
||||
|
||||
{/* Navigation buttons */}
|
||||
<div className="flex items-center justify-between gap-3 pt-2">
|
||||
<Button
|
||||
variant="ghost"
|
||||
size="sm"
|
||||
onClick={onPrevious}
|
||||
disabled={isFirstStep}
|
||||
className={cn(
|
||||
'text-muted-foreground min-h-[44px]',
|
||||
'focus-visible:ring-2 focus-visible:ring-primary',
|
||||
isFirstStep && 'invisible'
|
||||
)}
|
||||
aria-label="Go to previous step"
|
||||
>
|
||||
<ChevronLeft className="w-4 h-4 mr-1" aria-hidden="true" />
|
||||
<span>Previous</span>
|
||||
</Button>
|
||||
|
||||
<Button
|
||||
ref={nextButtonRef}
|
||||
size="sm"
|
||||
onClick={isLastStep ? handleComplete : onNext}
|
||||
disabled={showCompletionCelebration}
|
||||
className={cn(
|
||||
'bg-primary hover:bg-primary/90 text-primary-foreground',
|
||||
'min-w-[120px] min-h-[44px]', // Accessible touch target
|
||||
'focus-visible:ring-2 focus-visible:ring-primary focus-visible:ring-offset-2',
|
||||
'transition-all duration-200'
|
||||
)}
|
||||
aria-label={isLastStep ? 'Complete the tour and get started' : 'Go to next step'}
|
||||
>
|
||||
{isLastStep ? (
|
||||
<>
|
||||
<span>Get Started</span>
|
||||
<CheckCircle2 className="w-4 h-4 ml-1.5" aria-hidden="true" />
|
||||
</>
|
||||
) : (
|
||||
<>
|
||||
<span>Next</span>
|
||||
<ChevronRight className="w-4 h-4 ml-1" aria-hidden="true" />
|
||||
</>
|
||||
)}
|
||||
</Button>
|
||||
</div>
|
||||
|
||||
{/* Keyboard hints - hidden on touch devices for cleaner mobile UX */}
|
||||
{!isTouchDevice && (
|
||||
<div
|
||||
className="mt-4 pt-3 border-t border-border/50 flex items-center justify-center gap-4 text-xs text-muted-foreground/70"
|
||||
aria-hidden="true"
|
||||
>
|
||||
<span className="flex items-center gap-1.5">
|
||||
<kbd className="px-2 py-1 rounded bg-muted text-muted-foreground font-mono text-[11px] shadow-sm">
|
||||
ESC
|
||||
</kbd>
|
||||
<span>to skip</span>
|
||||
</span>
|
||||
<span className="flex items-center gap-1.5">
|
||||
<kbd className="px-2 py-1 rounded bg-muted text-muted-foreground font-mono text-[11px] shadow-sm">
|
||||
←
|
||||
</kbd>
|
||||
<kbd className="px-2 py-1 rounded bg-muted text-muted-foreground font-mono text-[11px] shadow-sm">
|
||||
→
|
||||
</kbd>
|
||||
<span>to navigate</span>
|
||||
</span>
|
||||
</div>
|
||||
)}
|
||||
</div>
|
||||
</div>
|
||||
);
|
||||
|
||||
// Render in a portal to ensure it's above everything
|
||||
return createPortal(content, document.body);
|
||||
}
|
||||
@@ -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';
|
||||
|
||||
@@ -89,3 +89,117 @@ export function getStepIdFromStatus(status: string): string | null {
|
||||
}
|
||||
return status.replace('pipeline_', '');
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// SAMPLE DATA FOR ONBOARDING WIZARD
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* Prefix used to identify sample/demo features in the board
|
||||
* This marker persists through the database and is used for cleanup
|
||||
*/
|
||||
export const SAMPLE_FEATURE_PREFIX = '[DEMO]';
|
||||
|
||||
/**
|
||||
* Sample feature template for Quick Start onboarding
|
||||
* These demonstrate a typical workflow progression across columns
|
||||
*/
|
||||
export interface SampleFeatureTemplate {
|
||||
title: string;
|
||||
description: string;
|
||||
category: string;
|
||||
status: Feature['status'];
|
||||
priority: number;
|
||||
isSampleData: true; // Marker to identify sample data
|
||||
}
|
||||
|
||||
/**
|
||||
* Sample features that demonstrate the workflow across all columns.
|
||||
* Each feature shows a realistic task at different stages.
|
||||
*/
|
||||
export const SAMPLE_FEATURES: SampleFeatureTemplate[] = [
|
||||
// Backlog items - awaiting work
|
||||
{
|
||||
title: '[DEMO] Add user profile page',
|
||||
description:
|
||||
'Create a user profile page where users can view and edit their account settings, change password, and manage preferences.\n\n---\n**This is sample data** - Click the trash icon in the wizard to remove all demo items.',
|
||||
category: 'Feature',
|
||||
status: 'backlog',
|
||||
priority: 1,
|
||||
isSampleData: true,
|
||||
},
|
||||
{
|
||||
title: '[DEMO] Implement dark mode toggle',
|
||||
description:
|
||||
'Add a toggle in the settings to switch between light and dark themes. Should persist the preference across sessions.\n\n---\n**This is sample data** - Click the trash icon in the wizard to remove all demo items.',
|
||||
category: 'Enhancement',
|
||||
status: 'backlog',
|
||||
priority: 2,
|
||||
isSampleData: true,
|
||||
},
|
||||
|
||||
// In Progress - currently being worked on
|
||||
{
|
||||
title: '[DEMO] Fix login timeout issue',
|
||||
description:
|
||||
'Users are being logged out after 5 minutes of inactivity. Investigate and increase the session timeout to 30 minutes.\n\n---\n**This is sample data** - Click the trash icon in the wizard to remove all demo items.',
|
||||
category: 'Bug Fix',
|
||||
status: 'in_progress',
|
||||
priority: 1,
|
||||
isSampleData: true,
|
||||
},
|
||||
|
||||
// Waiting Approval - completed and awaiting review
|
||||
{
|
||||
title: '[DEMO] Update API documentation',
|
||||
description:
|
||||
'Update the API documentation to reflect recent endpoint changes and add examples for new authentication flow.\n\n---\n**This is sample data** - Click the trash icon in the wizard to remove all demo items.',
|
||||
category: 'Documentation',
|
||||
status: 'waiting_approval',
|
||||
priority: 2,
|
||||
isSampleData: true,
|
||||
},
|
||||
|
||||
// Verified - approved and ready
|
||||
{
|
||||
title: '[DEMO] Add loading spinners',
|
||||
description:
|
||||
'Added loading spinner components to all async operations to improve user feedback during data fetching.\n\n---\n**This is sample data** - Click the trash icon in the wizard to remove all demo items.',
|
||||
category: 'Enhancement',
|
||||
status: 'verified',
|
||||
priority: 3,
|
||||
isSampleData: true,
|
||||
},
|
||||
];
|
||||
|
||||
/**
|
||||
* Check if a feature is sample data
|
||||
* Uses the SAMPLE_FEATURE_PREFIX in the title as the marker for sample data
|
||||
*/
|
||||
export function isSampleFeature(feature: Partial<Feature>): 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<Omit<Feature, 'id' | 'createdAt' | 'updatedAt'>> {
|
||||
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
|
||||
}));
|
||||
}
|
||||
|
||||
@@ -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';
|
||||
|
||||
@@ -0,0 +1,409 @@
|
||||
/**
|
||||
* Board Onboarding Hook
|
||||
*
|
||||
* Manages the state and logic for the interactive onboarding wizard
|
||||
* that guides new users through the Kanban board workflow.
|
||||
*
|
||||
* Features:
|
||||
* - Tracks wizard completion status per project
|
||||
* - Persists state to localStorage (per user, per board)
|
||||
* - Handles step navigation
|
||||
* - Provides analytics tracking
|
||||
*/
|
||||
|
||||
import { useState, useCallback, useEffect, useMemo } from 'react';
|
||||
import { createLogger } from '@automaker/utils/logger';
|
||||
import { getItem, setItem } from '@/lib/storage';
|
||||
|
||||
const logger = createLogger('BoardOnboarding');
|
||||
|
||||
// ============================================================================
|
||||
// CONSTANTS
|
||||
// ============================================================================
|
||||
|
||||
/** Storage key prefix for onboarding state */
|
||||
const ONBOARDING_STORAGE_KEY = 'automaker:board-onboarding';
|
||||
|
||||
/** Delay before auto-showing wizard to let the board render first (ms) */
|
||||
const WIZARD_AUTO_SHOW_DELAY_MS = 500;
|
||||
|
||||
/** Maximum length for project path hash in storage key */
|
||||
const PROJECT_PATH_HASH_MAX_LENGTH = 50;
|
||||
|
||||
// Analytics event names
|
||||
export const ONBOARDING_ANALYTICS = {
|
||||
STARTED: 'onboarding_started',
|
||||
COMPLETED: 'onboarding_completed',
|
||||
SKIPPED: 'onboarding_skipped',
|
||||
QUICK_START_USED: 'onboarding_quick_start_used',
|
||||
SAMPLE_DATA_CLEARED: 'onboarding_sample_data_cleared',
|
||||
STEP_VIEWED: 'onboarding_step_viewed',
|
||||
RETRIGGERED: 'onboarding_retriggered',
|
||||
} as const;
|
||||
|
||||
// Wizard step definitions
|
||||
export interface WizardStep {
|
||||
id: string;
|
||||
columnId: string;
|
||||
title: string;
|
||||
description: string;
|
||||
tip?: string;
|
||||
}
|
||||
|
||||
export const WIZARD_STEPS: WizardStep[] = [
|
||||
{
|
||||
id: 'backlog',
|
||||
columnId: '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.',
|
||||
},
|
||||
{
|
||||
id: 'in_progress',
|
||||
columnId: '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.',
|
||||
},
|
||||
{
|
||||
id: 'waiting_approval',
|
||||
columnId: '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.',
|
||||
},
|
||||
{
|
||||
id: 'verified',
|
||||
columnId: '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.',
|
||||
},
|
||||
{
|
||||
id: 'custom_columns',
|
||||
columnId: 'in_progress', // Highlight "In Progress" column to show the settings icon
|
||||
title: 'Custom Pipelines',
|
||||
description:
|
||||
'You can create custom columns (called pipelines) to build your own workflow! Click the settings icon in any column header to add, rename, or configure pipeline steps.',
|
||||
tip: 'Use pipelines to add code review, QA testing, or any custom stage to your workflow.',
|
||||
},
|
||||
];
|
||||
|
||||
// Persisted onboarding state structure
|
||||
interface OnboardingState {
|
||||
completed: boolean;
|
||||
completedAt?: string;
|
||||
skipped: boolean;
|
||||
skippedAt?: string;
|
||||
hasEverSeenWizard: boolean;
|
||||
hasSampleData: boolean;
|
||||
quickStartUsed: boolean;
|
||||
}
|
||||
|
||||
// Default state for new projects
|
||||
const DEFAULT_ONBOARDING_STATE: OnboardingState = {
|
||||
completed: false,
|
||||
skipped: false,
|
||||
hasEverSeenWizard: false,
|
||||
hasSampleData: false,
|
||||
quickStartUsed: false,
|
||||
};
|
||||
|
||||
/**
|
||||
* Get storage key for a specific project
|
||||
* Creates a sanitized key from the project path for localStorage
|
||||
*/
|
||||
function getStorageKey(projectPath: string): string {
|
||||
// Create a simple hash of the project path to use as key
|
||||
const hash = projectPath.replace(/[^a-zA-Z0-9]/g, '_').slice(0, PROJECT_PATH_HASH_MAX_LENGTH);
|
||||
return `${ONBOARDING_STORAGE_KEY}:${hash}`;
|
||||
}
|
||||
|
||||
// Load onboarding state from localStorage
|
||||
function loadOnboardingState(projectPath: string): OnboardingState {
|
||||
try {
|
||||
const key = getStorageKey(projectPath);
|
||||
const stored = getItem(key);
|
||||
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(projectPath: string, state: OnboardingState): void {
|
||||
try {
|
||||
const key = getStorageKey(projectPath);
|
||||
setItem(key, 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<string, unknown>): void {
|
||||
logger.debug(`[Analytics] ${event}`, data);
|
||||
// TODO: Integrate with actual analytics service (e.g., PostHog, Amplitude)
|
||||
// Example: posthog.capture(event, data);
|
||||
}
|
||||
|
||||
export interface UseBoardOnboardingOptions {
|
||||
projectPath: string | null;
|
||||
isEmpty: boolean; // Whether the board has no features
|
||||
totalFeatureCount: number; // Total number of features in the board
|
||||
/** Whether the spec generation dialog is currently open (prevents wizard from showing) */
|
||||
isSpecDialogOpen?: boolean;
|
||||
}
|
||||
|
||||
export interface UseBoardOnboardingResult {
|
||||
// Wizard visibility
|
||||
isWizardVisible: boolean;
|
||||
shouldShowWizard: boolean;
|
||||
|
||||
// Current step
|
||||
currentStep: number;
|
||||
currentStepData: WizardStep | null;
|
||||
totalSteps: number;
|
||||
|
||||
// Navigation
|
||||
goToNextStep: () => void;
|
||||
goToPreviousStep: () => void;
|
||||
goToStep: (step: number) => void;
|
||||
|
||||
// Actions
|
||||
startWizard: () => void;
|
||||
completeWizard: () => void;
|
||||
skipWizard: () => void;
|
||||
dismissWizard: () => void;
|
||||
|
||||
// Quick Start / Sample Data
|
||||
hasSampleData: boolean;
|
||||
setHasSampleData: (has: boolean) => void;
|
||||
markQuickStartUsed: () => void;
|
||||
|
||||
// Re-trigger
|
||||
canRetrigger: boolean;
|
||||
retriggerWizard: () => void;
|
||||
|
||||
// State
|
||||
isCompleted: boolean;
|
||||
isSkipped: boolean;
|
||||
}
|
||||
|
||||
export function useBoardOnboarding({
|
||||
projectPath,
|
||||
isEmpty,
|
||||
totalFeatureCount,
|
||||
isSpecDialogOpen = false,
|
||||
}: UseBoardOnboardingOptions): UseBoardOnboardingResult {
|
||||
// Local state
|
||||
const [currentStep, setCurrentStep] = useState(0);
|
||||
const [isWizardActive, setIsWizardActive] = useState(false);
|
||||
const [onboardingState, setOnboardingState] = useState<OnboardingState>(DEFAULT_ONBOARDING_STATE);
|
||||
|
||||
// Load persisted state when project changes
|
||||
useEffect(() => {
|
||||
if (!projectPath) {
|
||||
setOnboardingState(DEFAULT_ONBOARDING_STATE);
|
||||
return;
|
||||
}
|
||||
|
||||
const state = loadOnboardingState(projectPath);
|
||||
setOnboardingState(state);
|
||||
|
||||
// Auto-show wizard for empty boards that haven't seen it
|
||||
// Don't re-trigger if board became empty after having features (edge case)
|
||||
// Don't show if spec dialog is open (for new projects)
|
||||
if (
|
||||
isEmpty &&
|
||||
!state.hasEverSeenWizard &&
|
||||
!state.completed &&
|
||||
!state.skipped &&
|
||||
!isSpecDialogOpen
|
||||
) {
|
||||
// Small delay to let the board render first
|
||||
const timer = setTimeout(() => {
|
||||
setIsWizardActive(true);
|
||||
trackAnalytics(ONBOARDING_ANALYTICS.STARTED, { projectPath });
|
||||
}, WIZARD_AUTO_SHOW_DELAY_MS);
|
||||
return () => clearTimeout(timer);
|
||||
}
|
||||
}, [projectPath, isEmpty, isSpecDialogOpen]);
|
||||
|
||||
// Update persisted state helper
|
||||
const updateState = useCallback(
|
||||
(updates: Partial<OnboardingState>) => {
|
||||
if (!projectPath) return;
|
||||
|
||||
setOnboardingState((prev) => {
|
||||
const newState = { ...prev, ...updates };
|
||||
saveOnboardingState(projectPath, newState);
|
||||
return newState;
|
||||
});
|
||||
},
|
||||
[projectPath]
|
||||
);
|
||||
|
||||
// Determine if wizard should be visible
|
||||
// Don't show if:
|
||||
// - No project selected
|
||||
// - Already completed or skipped
|
||||
// - Board has features and user has seen wizard before (became empty after deletion)
|
||||
const shouldShowWizard = useMemo(() => {
|
||||
if (!projectPath) return false;
|
||||
if (onboardingState.completed || onboardingState.skipped) return false;
|
||||
if (!isEmpty && onboardingState.hasEverSeenWizard) return false;
|
||||
return isEmpty && !onboardingState.hasEverSeenWizard;
|
||||
}, [projectPath, isEmpty, onboardingState]);
|
||||
|
||||
// Current step data
|
||||
const currentStepData = WIZARD_STEPS[currentStep] || null;
|
||||
const totalSteps = WIZARD_STEPS.length;
|
||||
|
||||
// Navigation handlers
|
||||
const goToNextStep = useCallback(() => {
|
||||
if (currentStep < totalSteps - 1) {
|
||||
const nextStep = currentStep + 1;
|
||||
setCurrentStep(nextStep);
|
||||
trackAnalytics(ONBOARDING_ANALYTICS.STEP_VIEWED, {
|
||||
step: nextStep,
|
||||
stepId: WIZARD_STEPS[nextStep]?.id,
|
||||
projectPath,
|
||||
});
|
||||
}
|
||||
}, [currentStep, totalSteps, projectPath]);
|
||||
|
||||
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, {
|
||||
step,
|
||||
stepId: WIZARD_STEPS[step]?.id,
|
||||
projectPath,
|
||||
});
|
||||
}
|
||||
},
|
||||
[totalSteps, projectPath]
|
||||
);
|
||||
|
||||
// Wizard lifecycle handlers
|
||||
const startWizard = useCallback(() => {
|
||||
setCurrentStep(0);
|
||||
setIsWizardActive(true);
|
||||
updateState({ hasEverSeenWizard: true });
|
||||
trackAnalytics(ONBOARDING_ANALYTICS.STARTED, { projectPath });
|
||||
}, [projectPath, updateState]);
|
||||
|
||||
const completeWizard = useCallback(() => {
|
||||
setIsWizardActive(false);
|
||||
setCurrentStep(0);
|
||||
updateState({
|
||||
completed: true,
|
||||
completedAt: new Date().toISOString(),
|
||||
hasEverSeenWizard: true,
|
||||
});
|
||||
trackAnalytics(ONBOARDING_ANALYTICS.COMPLETED, {
|
||||
projectPath,
|
||||
quickStartUsed: onboardingState.quickStartUsed,
|
||||
totalFeatureCount,
|
||||
});
|
||||
}, [projectPath, updateState, onboardingState.quickStartUsed, totalFeatureCount]);
|
||||
|
||||
const skipWizard = useCallback(() => {
|
||||
setIsWizardActive(false);
|
||||
setCurrentStep(0);
|
||||
updateState({
|
||||
skipped: true,
|
||||
skippedAt: new Date().toISOString(),
|
||||
hasEverSeenWizard: true,
|
||||
});
|
||||
trackAnalytics(ONBOARDING_ANALYTICS.SKIPPED, {
|
||||
projectPath,
|
||||
skippedAtStep: currentStep,
|
||||
});
|
||||
}, [projectPath, currentStep, updateState]);
|
||||
|
||||
const dismissWizard = useCallback(() => {
|
||||
// Same as skip but doesn't mark as "skipped" - just closes the wizard
|
||||
setIsWizardActive(false);
|
||||
updateState({ hasEverSeenWizard: true });
|
||||
}, [updateState]);
|
||||
|
||||
// Quick Start / Sample Data
|
||||
const setHasSampleData = useCallback(
|
||||
(has: boolean) => {
|
||||
updateState({ hasSampleData: has });
|
||||
if (!has) {
|
||||
trackAnalytics(ONBOARDING_ANALYTICS.SAMPLE_DATA_CLEARED, { projectPath });
|
||||
}
|
||||
},
|
||||
[projectPath, updateState]
|
||||
);
|
||||
|
||||
const markQuickStartUsed = useCallback(() => {
|
||||
updateState({ quickStartUsed: true, hasSampleData: true });
|
||||
trackAnalytics(ONBOARDING_ANALYTICS.QUICK_START_USED, { projectPath });
|
||||
}, [projectPath, updateState]);
|
||||
|
||||
// Re-trigger wizard - memoized for stable reference
|
||||
const canRetrigger = useMemo(
|
||||
() => onboardingState.completed || onboardingState.skipped,
|
||||
[onboardingState.completed, onboardingState.skipped]
|
||||
);
|
||||
|
||||
const retriggerWizard = useCallback(() => {
|
||||
setCurrentStep(0);
|
||||
setIsWizardActive(true);
|
||||
// Don't reset completion status, just show wizard again
|
||||
trackAnalytics(ONBOARDING_ANALYTICS.RETRIGGERED, { projectPath });
|
||||
}, [projectPath]);
|
||||
|
||||
return {
|
||||
// Visibility
|
||||
isWizardVisible: isWizardActive,
|
||||
shouldShowWizard,
|
||||
|
||||
// Steps
|
||||
currentStep,
|
||||
currentStepData,
|
||||
totalSteps,
|
||||
|
||||
// Navigation
|
||||
goToNextStep,
|
||||
goToPreviousStep,
|
||||
goToStep,
|
||||
|
||||
// Actions
|
||||
startWizard,
|
||||
completeWizard,
|
||||
skipWizard,
|
||||
dismissWizard,
|
||||
|
||||
// Sample Data
|
||||
hasSampleData: onboardingState.hasSampleData,
|
||||
setHasSampleData,
|
||||
markQuickStartUsed,
|
||||
|
||||
// Re-trigger
|
||||
canRetrigger,
|
||||
retriggerWizard,
|
||||
|
||||
// State
|
||||
isCompleted: onboardingState.completed,
|
||||
isSkipped: onboardingState.skipped,
|
||||
};
|
||||
}
|
||||
Reference in New Issue
Block a user