@wakastellar/ui 2.0.0 → 2.1.1

package/src/components/waka-checklist/index.tsx

@@ -0,0 +1,1067 @@
+"use client"
+
+import * as React from "react"
+import { cn } from "../../utils/cn"
+import {
+  Check,
+  ChevronDown,
+  ChevronRight,
+  Gift,
+  X,
+  Sparkles,
+  Trophy,
+  PartyPopper,
+} from "lucide-react"
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type TaskStatus = "pending" | "completed" | "skipped"
+
+export interface ChecklistTask {
+  /** Unique identifier */
+  id: string
+  /** Task title */
+  title: string
+  /** Task description (shown when expanded) */
+  description?: string
+  /** Category/group the task belongs to */
+  category?: string
+  /** Action button label */
+  actionLabel?: string
+  /** Callback when action is triggered */
+  onAction?: () => void
+  /** Whether the task can be skipped */
+  skippable?: boolean
+  /** Custom icon */
+  icon?: React.ReactNode
+  /** Reward points for completing this task */
+  points?: number
+  /** Whether this task is required */
+  required?: boolean
+}
+
+export interface ChecklistCategory {
+  /** Category identifier */
+  id: string
+  /** Category label */
+  label: string
+  /** Category description */
+  description?: string
+  /** Custom icon */
+  icon?: React.ReactNode
+}
+
+export interface ChecklistState {
+  /** Map of task ID to status */
+  tasks: Record<string, TaskStatus>
+  /** Whether the checklist is collapsed */
+  collapsed: boolean
+  /** Set of expanded task IDs */
+  expandedTasks: Set<string>
+}
+
+export interface WakaChecklistProps {
+  /** Checklist identifier for localStorage persistence */
+  checklistId: string
+  /** List of tasks */
+  tasks: ChecklistTask[]
+  /** Category definitions */
+  categories?: ChecklistCategory[]
+  /** Title of the checklist */
+  title?: string
+  /** Subtitle/description */
+  subtitle?: string
+  /** Show progress bar */
+  showProgress?: boolean
+  /** Show completion percentage */
+  showPercentage?: boolean
+  /** Enable localStorage persistence */
+  persistent?: boolean
+  /** Show celebration on completion */
+  showCelebration?: boolean
+  /** Callback when all tasks are completed */
+  onComplete?: () => void
+  /** Callback when a task status changes */
+  onTaskChange?: (taskId: string, status: TaskStatus) => void
+  /** Initially collapsed */
+  defaultCollapsed?: boolean
+  /** Allow collapsing the checklist */
+  collapsible?: boolean
+  /** Size variant */
+  size?: "sm" | "default" | "lg"
+  /** Custom className */
+  className?: string
+}
+
+export interface UseChecklistOptions {
+  /** Checklist identifier for localStorage */
+  checklistId: string
+  /** List of tasks */
+  tasks: ChecklistTask[]
+  /** Enable localStorage persistence */
+  persistent?: boolean
+  /** Initially collapsed */
+  defaultCollapsed?: boolean
+  /** Callback when all tasks are completed */
+  onComplete?: () => void
+  /** Callback when a task status changes */
+  onTaskChange?: (taskId: string, status: TaskStatus) => void
+}
+
+export interface UseChecklistReturn {
+  /** Current state of all tasks */
+  taskStates: Record<string, TaskStatus>
+  /** Whether checklist is collapsed */
+  isCollapsed: boolean
+  /** Set of expanded task IDs */
+  expandedTasks: Set<string>
+  /** Mark a task as completed */
+  completeTask: (taskId: string) => void
+  /** Skip a task */
+  skipTask: (taskId: string) => void
+  /** Reset a task to pending */
+  resetTask: (taskId: string) => void
+  /** Toggle task expansion */
+  toggleTaskExpanded: (taskId: string) => void
+  /** Toggle checklist collapse */
+  toggleCollapsed: () => void
+  /** Reset entire checklist */
+  resetChecklist: () => void
+  /** Completion progress (0-100) */
+  progress: number
+  /** Number of completed tasks */
+  completedCount: number
+  /** Number of skipped tasks */
+  skippedCount: number
+  /** Total number of tasks */
+  totalCount: number
+  /** Whether all tasks are completed or skipped */
+  isComplete: boolean
+  /** Get status of a specific task */
+  getTaskStatus: (taskId: string) => TaskStatus
+}
+
+// ============================================================================
+// localStorage Helpers
+// ============================================================================
+
+const STORAGE_KEY_PREFIX = "waka-checklist-"
+
+function getStorageKey(checklistId: string): string {
+  return `${STORAGE_KEY_PREFIX}${checklistId}`
+}
+
+function loadFromStorage(checklistId: string): Partial<ChecklistState> | null {
+  if (typeof window === "undefined") return null
+  try {
+    const stored = localStorage.getItem(getStorageKey(checklistId))
+    if (stored) {
+      const parsed = JSON.parse(stored)
+      return {
+        ...parsed,
+        expandedTasks: new Set(parsed.expandedTasks || []),
+      }
+    }
+  } catch {
+    // Ignore storage errors
+  }
+  return null
+}
+
+function saveToStorage(checklistId: string, state: ChecklistState): void {
+  if (typeof window === "undefined") return
+  try {
+    localStorage.setItem(
+      getStorageKey(checklistId),
+      JSON.stringify({
+        ...state,
+        expandedTasks: Array.from(state.expandedTasks),
+      })
+    )
+  } catch {
+    // Ignore storage errors
+  }
+}
+
+// ============================================================================
+// useChecklist Hook
+// ============================================================================
+
+export function useChecklist({
+  checklistId,
+  tasks,
+  persistent = true,
+  defaultCollapsed = false,
+  onComplete,
+  onTaskChange,
+}: UseChecklistOptions): UseChecklistReturn {
+  // Initialize state from localStorage or defaults
+  const [state, setState] = React.useState<ChecklistState>(() => {
+    const stored = persistent ? loadFromStorage(checklistId) : null
+    return {
+      tasks: stored?.tasks || {},
+      collapsed: stored?.collapsed ?? defaultCollapsed,
+      expandedTasks: stored?.expandedTasks || new Set(),
+    }
+  })
+
+  const prevIsCompleteRef = React.useRef(false)
+
+  // Calculate derived values
+  const taskStates = state.tasks
+  const completedCount = Object.values(taskStates).filter(
+    (s) => s === "completed"
+  ).length
+  const skippedCount = Object.values(taskStates).filter(
+    (s) => s === "skipped"
+  ).length
+  const totalCount = tasks.length
+  const requiredTasks = tasks.filter((t) => t.required !== false)
+  const completedRequired = requiredTasks.filter(
+    (t) => taskStates[t.id] === "completed"
+  ).length
+  const skippedRequired = requiredTasks.filter(
+    (t) => taskStates[t.id] === "skipped"
+  ).length
+  const isComplete =
+    requiredTasks.length === 0 ||
+    completedRequired + skippedRequired >= requiredTasks.length
+  const progress = totalCount > 0 ? (completedCount / totalCount) * 100 : 0
+
+  // Persist state changes
+  React.useEffect(() => {
+    if (persistent) {
+      saveToStorage(checklistId, state)
+    }
+  }, [checklistId, persistent, state])
+
+  // Handle completion callback
+  React.useEffect(() => {
+    if (isComplete && !prevIsCompleteRef.current && completedCount > 0) {
+      onComplete?.()
+    }
+    prevIsCompleteRef.current = isComplete
+  }, [isComplete, completedCount, onComplete])
+
+  const completeTask = React.useCallback(
+    (taskId: string) => {
+      setState((prev) => ({
+        ...prev,
+        tasks: { ...prev.tasks, [taskId]: "completed" },
+      }))
+      onTaskChange?.(taskId, "completed")
+    },
+    [onTaskChange]
+  )
+
+  const skipTask = React.useCallback(
+    (taskId: string) => {
+      setState((prev) => ({
+        ...prev,
+        tasks: { ...prev.tasks, [taskId]: "skipped" },
+      }))
+      onTaskChange?.(taskId, "skipped")
+    },
+    [onTaskChange]
+  )
+
+  const resetTask = React.useCallback(
+    (taskId: string) => {
+      setState((prev) => {
+        const newTasks = { ...prev.tasks }
+        delete newTasks[taskId]
+        return { ...prev, tasks: newTasks }
+      })
+      onTaskChange?.(taskId, "pending")
+    },
+    [onTaskChange]
+  )
+
+  const toggleTaskExpanded = React.useCallback((taskId: string) => {
+    setState((prev) => {
+      const newExpanded = new Set(prev.expandedTasks)
+      if (newExpanded.has(taskId)) {
+        newExpanded.delete(taskId)
+      } else {
+        newExpanded.add(taskId)
+      }
+      return { ...prev, expandedTasks: newExpanded }
+    })
+  }, [])
+
+  const toggleCollapsed = React.useCallback(() => {
+    setState((prev) => ({ ...prev, collapsed: !prev.collapsed }))
+  }, [])
+
+  const resetChecklist = React.useCallback(() => {
+    setState({
+      tasks: {},
+      collapsed: defaultCollapsed,
+      expandedTasks: new Set(),
+    })
+    if (persistent) {
+      localStorage.removeItem(getStorageKey(checklistId))
+    }
+  }, [checklistId, defaultCollapsed, persistent])
+
+  const getTaskStatus = React.useCallback(
+    (taskId: string): TaskStatus => {
+      return taskStates[taskId] || "pending"
+    },
+    [taskStates]
+  )
+
+  return {
+    taskStates,
+    isCollapsed: state.collapsed,
+    expandedTasks: state.expandedTasks,
+    completeTask,
+    skipTask,
+    resetTask,
+    toggleTaskExpanded,
+    toggleCollapsed,
+    resetChecklist,
+    progress,
+    completedCount,
+    skippedCount,
+    totalCount,
+    isComplete,
+    getTaskStatus,
+  }
+}
+
+// ============================================================================
+// Celebration Effect Component
+// ============================================================================
+
+interface CelebrationEffectProps {
+  active: boolean
+  onComplete?: () => void
+}
+
+function CelebrationEffect({ active, onComplete }: CelebrationEffectProps) {
+  const [isVisible, setIsVisible] = React.useState(false)
+
+  React.useEffect(() => {
+    if (active) {
+      setIsVisible(true)
+      const timer = setTimeout(() => {
+        setIsVisible(false)
+        onComplete?.()
+      }, 4000)
+      return () => clearTimeout(timer)
+    }
+  }, [active, onComplete])
+
+  if (!isVisible) return null
+
+  const confettiColors = [
+    "#fbbf24",
+    "#f59e0b",
+    "#ef4444",
+    "#8b5cf6",
+    "#06b6d4",
+    "#22c55e",
+    "#ec4899",
+  ]
+
+  return (
+    <div className="pointer-events-none fixed inset-0 z-50 overflow-hidden">
+      {/* Confetti burst */}
+      {[...Array(80)].map((_, i) => {
+        const angle = (i / 80) * 360
+        const distance = 150 + Math.random() * 250
+        const size = 6 + Math.random() * 10
+        const duration = 1.2 + Math.random() * 0.6
+
+        return (
+          <div
+            key={i}
+            className="absolute left-1/2 top-1/2 animate-confetti"
+            style={
+              {
+                width: size,
+                height: size,
+                backgroundColor:
+                  confettiColors[
+                    Math.floor(Math.random() * confettiColors.length)
+                  ],
+                borderRadius: Math.random() > 0.5 ? "50%" : "2px",
+                "--angle": `${angle}deg`,
+                "--distance": `${distance}px`,
+                animationDuration: `${duration}s`,
+                animationDelay: `${Math.random() * 0.3}s`,
+              } as React.CSSProperties
+            }
+          />
+        )
+      })}
+
+      {/* Celebration message */}
+      <div className="absolute left-1/2 top-1/2 -translate-x-1/2 -translate-y-1/2 animate-celebration-popup">
+        <div className="flex flex-col items-center gap-4 rounded-2xl bg-gradient-to-br from-yellow-400 via-orange-500 to-pink-500 px-12 py-8 text-white shadow-2xl">
+          <div className="flex items-center gap-3">
+            <PartyPopper className="h-10 w-10 animate-bounce" />
+            <Trophy className="h-12 w-12 animate-pulse" />
+            <PartyPopper className="h-10 w-10 animate-bounce" />
+          </div>
+          <div className="text-center">
+            <h3 className="text-3xl font-bold">All Done!</h3>
+            <p className="mt-1 text-lg opacity-90">
+              You completed all the tasks
+            </p>
+          </div>
+          <Gift className="h-8 w-8 animate-bounce" />
+        </div>
+      </div>
+
+      {/* Sparkles */}
+      {[...Array(20)].map((_, i) => (
+        <Sparkles
+          key={`sparkle-${i}`}
+          className="absolute animate-sparkle text-yellow-400"
+          style={{
+            left: `${Math.random() * 100}%`,
+            top: `${Math.random() * 100}%`,
+            animationDelay: `${Math.random() * 2}s`,
+            fontSize: `${20 + Math.random() * 20}px`,
+          }}
+        />
+      ))}
+
+      <style>{`
+        @keyframes confetti {
+          0% {
+            transform: translate(-50%, -50%) rotate(var(--angle)) translateX(0) scale(1);
+            opacity: 1;
+          }
+          100% {
+            transform: translate(-50%, -50%) rotate(var(--angle)) translateX(var(--distance)) scale(0) rotate(720deg);
+            opacity: 0;
+          }
+        }
+        @keyframes celebration-popup {
+          0% { transform: translate(-50%, -50%) scale(0); opacity: 0; }
+          20% { transform: translate(-50%, -50%) scale(1.1); opacity: 1; }
+          30% { transform: translate(-50%, -50%) scale(1); }
+          80% { transform: translate(-50%, -50%) scale(1); opacity: 1; }
+          100% { transform: translate(-50%, -50%) scale(0.8); opacity: 0; }
+        }
+        @keyframes sparkle {
+          0%, 100% { transform: scale(0) rotate(0deg); opacity: 0; }
+          50% { transform: scale(1) rotate(180deg); opacity: 1; }
+        }
+        .animate-confetti {
+          animation: confetti 1.5s ease-out forwards;
+        }
+        .animate-celebration-popup {
+          animation: celebration-popup 4s ease-out forwards;
+        }
+        .animate-sparkle {
+          animation: sparkle 2s ease-in-out infinite;
+        }
+      `}</style>
+    </div>
+  )
+}
+
+// ============================================================================
+// Progress Bar Component
+// ============================================================================
+
+interface ProgressBarProps {
+  progress: number
+  showPercentage?: boolean
+  size?: "sm" | "default" | "lg"
+}
+
+function ProgressBar({
+  progress,
+  showPercentage = true,
+  size = "default",
+}: ProgressBarProps) {
+  const [displayProgress, setDisplayProgress] = React.useState(0)
+
+  React.useEffect(() => {
+    const timer = setTimeout(() => setDisplayProgress(progress), 100)
+    return () => clearTimeout(timer)
+  }, [progress])
+
+  const sizeClasses = {
+    sm: "h-1.5",
+    default: "h-2",
+    lg: "h-3",
+  }
+
+  const isComplete = progress >= 100
+
+  return (
+    <div className="w-full">
+      <div
+        className={cn(
+          "relative w-full overflow-hidden rounded-full bg-muted",
+          sizeClasses[size]
+        )}
+      >
+        <div
+          className={cn(
+            "h-full rounded-full transition-all duration-700 ease-out",
+            isComplete
+              ? "bg-gradient-to-r from-green-500 to-emerald-500"
+              : "bg-gradient-to-r from-blue-500 to-purple-500"
+          )}
+          style={{ width: `${displayProgress}%` }}
+        />
+        {/* Shine effect */}
+        <div
+          className="absolute inset-0 animate-progress-shine"
+          style={{ width: `${displayProgress}%` }}
+        />
+      </div>
+      {showPercentage && (
+        <div className="mt-1 flex items-center justify-between text-xs text-muted-foreground">
+          <span>{Math.round(displayProgress)}% complete</span>
+          {isComplete && (
+            <span className="flex items-center gap-1 text-green-600">
+              <Check className="h-3 w-3" />
+              Complete
+            </span>
+          )}
+        </div>
+      )}
+      <style>{`
+        @keyframes progress-shine {
+          0% { background: linear-gradient(90deg, transparent 0%, rgba(255,255,255,0.3) 50%, transparent 100%); background-position: -100% 0; }
+          100% { background: linear-gradient(90deg, transparent 0%, rgba(255,255,255,0.3) 50%, transparent 100%); background-position: 200% 0; }
+        }
+        .animate-progress-shine {
+          animation: progress-shine 2s ease-in-out infinite;
+        }
+      `}</style>
+    </div>
+  )
+}
+
+// ============================================================================
+// Task Item Component
+// ============================================================================
+
+interface TaskItemProps {
+  task: ChecklistTask
+  status: TaskStatus
+  isExpanded: boolean
+  onToggleExpand: () => void
+  onComplete: () => void
+  onSkip: () => void
+  onReset: () => void
+  size?: "sm" | "default" | "lg"
+}
+
+function TaskItem({
+  task,
+  status,
+  isExpanded,
+  onToggleExpand,
+  onComplete,
+  onSkip,
+  onReset,
+  size = "default",
+}: TaskItemProps) {
+  const isCompleted = status === "completed"
+  const isSkipped = status === "skipped"
+  const isPending = status === "pending"
+
+  const sizeClasses = {
+    sm: {
+      container: "px-3 py-2",
+      icon: "h-4 w-4",
+      checkIcon: "h-3 w-3",
+      title: "text-sm",
+      description: "text-xs",
+      button: "px-2 py-1 text-xs",
+    },
+    default: {
+      container: "px-4 py-3",
+      icon: "h-5 w-5",
+      checkIcon: "h-3.5 w-3.5",
+      title: "text-base",
+      description: "text-sm",
+      button: "px-3 py-1.5 text-sm",
+    },
+    lg: {
+      container: "px-5 py-4",
+      icon: "h-6 w-6",
+      checkIcon: "h-4 w-4",
+      title: "text-lg",
+      description: "text-base",
+      button: "px-4 py-2 text-base",
+    },
+  }
+
+  const sizes = sizeClasses[size]
+
+  return (
+    <div
+      className={cn(
+        "group rounded-lg border transition-all duration-200",
+        isCompleted && "border-green-200 bg-green-50 dark:border-green-900 dark:bg-green-950/30",
+        isSkipped && "border-muted bg-muted/30 opacity-60",
+        isPending && "border-border bg-card hover:border-primary/50 hover:shadow-sm"
+      )}
+    >
+      {/* Task header */}
+      <div className={cn("flex items-center gap-3", sizes.container)}>
+        {/* Status icon */}
+        <button
+          type="button"
+          onClick={isPending ? onComplete : onReset}
+          className={cn(
+            "flex-shrink-0 rounded-full border-2 transition-all duration-200",
+            sizes.icon,
+            "flex items-center justify-center",
+            isCompleted && "border-green-500 bg-green-500 text-white",
+            isSkipped && "border-muted-foreground/30 bg-muted",
+            isPending && "border-muted-foreground/30 hover:border-primary hover:bg-primary/10"
+          )}
+          aria-label={isPending ? "Complete task" : "Reset task"}
+        >
+          {isCompleted && <Check className={sizes.checkIcon} />}
+          {isSkipped && <X className={cn(sizes.checkIcon, "text-muted-foreground")} />}
+        </button>
+
+        {/* Task info */}
+        <div className="flex-1 min-w-0">
+          <div className="flex items-center gap-2">
+            {task.icon && (
+              <span className="text-muted-foreground">{task.icon}</span>
+            )}
+            <span
+              className={cn(
+                "font-medium transition-all duration-200",
+                sizes.title,
+                isCompleted && "text-green-700 line-through dark:text-green-400",
+                isSkipped && "text-muted-foreground line-through"
+              )}
+            >
+              {task.title}
+            </span>
+            {task.required === false && (
+              <span className="text-xs text-muted-foreground">(optional)</span>
+            )}
+            {task.points && isPending && (
+              <span className="inline-flex items-center gap-0.5 rounded-full bg-yellow-100 px-2 py-0.5 text-xs font-medium text-yellow-700 dark:bg-yellow-900/50 dark:text-yellow-400">
+                +{task.points}
+              </span>
+            )}
+          </div>
+        </div>
+
+        {/* Expand/Action buttons */}
+        <div className="flex items-center gap-2">
+          {/* Skip button */}
+          {isPending && task.skippable && (
+            <button
+              type="button"
+              onClick={onSkip}
+              className="text-xs text-muted-foreground hover:text-foreground transition-colors"
+            >
+              Skip
+            </button>
+          )}
+
+          {/* Action button */}
+          {isPending && task.actionLabel && task.onAction && (
+            <button
+              type="button"
+              onClick={(e) => {
+                e.stopPropagation()
+                task.onAction?.()
+              }}
+              className={cn(
+                "rounded-md bg-primary text-primary-foreground font-medium transition-colors hover:bg-primary/90",
+                sizes.button
+              )}
+            >
+              {task.actionLabel}
+            </button>
+          )}
+
+          {/* Expand toggle */}
+          {task.description && (
+            <button
+              type="button"
+              onClick={onToggleExpand}
+              className="rounded-md p-1 text-muted-foreground hover:bg-muted hover:text-foreground transition-colors"
+              aria-label={isExpanded ? "Collapse details" : "Expand details"}
+            >
+              {isExpanded ? (
+                <ChevronDown className={sizes.icon} />
+              ) : (
+                <ChevronRight className={sizes.icon} />
+              )}
+            </button>
+          )}
+        </div>
+      </div>
+
+      {/* Expanded description */}
+      {task.description && (
+        <div
+          className={cn(
+            "overflow-hidden transition-all duration-200",
+            isExpanded ? "max-h-40 opacity-100" : "max-h-0 opacity-0"
+          )}
+        >
+          <div
+            className={cn(
+              "border-t pt-2 pb-3 px-4 ml-8",
+              sizes.description,
+              "text-muted-foreground"
+            )}
+          >
+            {task.description}
+          </div>
+        </div>
+      )}
+    </div>
+  )
+}
+
+// ============================================================================
+// Category Group Component
+// ============================================================================
+
+interface CategoryGroupProps {
+  category: ChecklistCategory
+  tasks: ChecklistTask[]
+  taskStates: Record<string, TaskStatus>
+  expandedTasks: Set<string>
+  onCompleteTask: (taskId: string) => void
+  onSkipTask: (taskId: string) => void
+  onResetTask: (taskId: string) => void
+  onToggleTaskExpanded: (taskId: string) => void
+  size?: "sm" | "default" | "lg"
+}
+
+function CategoryGroup({
+  category,
+  tasks,
+  taskStates,
+  expandedTasks,
+  onCompleteTask,
+  onSkipTask,
+  onResetTask,
+  onToggleTaskExpanded,
+  size = "default",
+}: CategoryGroupProps) {
+  const [isExpanded, setIsExpanded] = React.useState(true)
+
+  const completedCount = tasks.filter(
+    (t) => taskStates[t.id] === "completed"
+  ).length
+  const totalCount = tasks.length
+
+  return (
+    <div className="space-y-2">
+      {/* Category header */}
+      <button
+        type="button"
+        onClick={() => setIsExpanded((prev) => !prev)}
+        className="flex w-full items-center gap-2 rounded-lg px-2 py-1.5 hover:bg-muted/50 transition-colors"
+      >
+        {isExpanded ? (
+          <ChevronDown className="h-4 w-4 text-muted-foreground" />
+        ) : (
+          <ChevronRight className="h-4 w-4 text-muted-foreground" />
+        )}
+        {category.icon && (
+          <span className="text-muted-foreground">{category.icon}</span>
+        )}
+        <span className="font-medium">{category.label}</span>
+        <span className="ml-auto text-sm text-muted-foreground">
+          {completedCount}/{totalCount}
+        </span>
+      </button>
+
+      {/* Category tasks */}
+      {isExpanded && (
+        <div className="ml-4 space-y-2">
+          {tasks.map((task) => (
+            <TaskItem
+              key={task.id}
+              task={task}
+              status={taskStates[task.id] || "pending"}
+              isExpanded={expandedTasks.has(task.id)}
+              onToggleExpand={() => onToggleTaskExpanded(task.id)}
+              onComplete={() => onCompleteTask(task.id)}
+              onSkip={() => onSkipTask(task.id)}
+              onReset={() => onResetTask(task.id)}
+              size={size}
+            />
+          ))}
+        </div>
+      )}
+    </div>
+  )
+}
+
+// ============================================================================
+// Main WakaChecklist Component
+// ============================================================================
+
+export function WakaChecklist({
+  checklistId,
+  tasks,
+  categories,
+  title = "Getting Started",
+  subtitle,
+  showProgress = true,
+  showPercentage = true,
+  persistent = true,
+  showCelebration = true,
+  onComplete,
+  onTaskChange,
+  defaultCollapsed = false,
+  collapsible = true,
+  size = "default",
+  className,
+}: WakaChecklistProps) {
+  const [showCelebrationEffect, setShowCelebrationEffect] = React.useState(false)
+  const prevIsCompleteRef = React.useRef(false)
+
+  const checklist = useChecklist({
+    checklistId,
+    tasks,
+    persistent,
+    defaultCollapsed,
+    onComplete: () => {
+      if (showCelebration) {
+        setShowCelebrationEffect(true)
+      }
+      onComplete?.()
+    },
+    onTaskChange,
+  })
+
+  // Track completion for celebration
+  React.useEffect(() => {
+    if (checklist.isComplete && !prevIsCompleteRef.current && checklist.completedCount > 0) {
+      if (showCelebration) {
+        setShowCelebrationEffect(true)
+      }
+    }
+    prevIsCompleteRef.current = checklist.isComplete
+  }, [checklist.isComplete, checklist.completedCount, showCelebration])
+
+  // Group tasks by category
+  const groupedTasks = React.useMemo(() => {
+    if (!categories || categories.length === 0) {
+      return null
+    }
+
+    const groups: Record<string, ChecklistTask[]> = {}
+    const uncategorized: ChecklistTask[] = []
+
+    for (const task of tasks) {
+      if (task.category && categories.find((c) => c.id === task.category)) {
+        if (!groups[task.category]) {
+          groups[task.category] = []
+        }
+        groups[task.category].push(task)
+      } else {
+        uncategorized.push(task)
+      }
+    }
+
+    return { groups, uncategorized }
+  }, [tasks, categories])
+
+  const sizeClasses = {
+    sm: {
+      container: "p-3",
+      header: "gap-2",
+      title: "text-base",
+      subtitle: "text-xs",
+    },
+    default: {
+      container: "p-4",
+      header: "gap-3",
+      title: "text-lg",
+      subtitle: "text-sm",
+    },
+    lg: {
+      container: "p-6",
+      header: "gap-4",
+      title: "text-xl",
+      subtitle: "text-base",
+    },
+  }
+
+  const sizes = sizeClasses[size]
+
+  return (
+    <div
+      className={cn(
+        "rounded-xl border bg-card shadow-sm",
+        sizes.container,
+        className
+      )}
+    >
+      <CelebrationEffect
+        active={showCelebrationEffect}
+        onComplete={() => setShowCelebrationEffect(false)}
+      />
+
+      {/* Header */}
+      <div className={cn("flex items-start justify-between", sizes.header)}>
+        <div className="flex-1">
+          <div className="flex items-center gap-2">
+            {collapsible && (
+              <button
+                type="button"
+                onClick={checklist.toggleCollapsed}
+                className="rounded-md p-1 hover:bg-muted transition-colors"
+                aria-label={
+                  checklist.isCollapsed ? "Expand checklist" : "Collapse checklist"
+                }
+              >
+                {checklist.isCollapsed ? (
+                  <ChevronRight className="h-5 w-5" />
+                ) : (
+                  <ChevronDown className="h-5 w-5" />
+                )}
+              </button>
+            )}
+            <h2 className={cn("font-semibold", sizes.title)}>{title}</h2>
+            {checklist.isComplete && (
+              <span className="inline-flex items-center gap-1 rounded-full bg-green-100 px-2 py-0.5 text-xs font-medium text-green-700 dark:bg-green-900/50 dark:text-green-400">
+                <Check className="h-3 w-3" />
+                Complete
+              </span>
+            )}
+          </div>
+          {subtitle && !checklist.isCollapsed && (
+            <p className={cn("text-muted-foreground mt-1", sizes.subtitle)}>
+              {subtitle}
+            </p>
+          )}
+        </div>
+
+        {/* Stats */}
+        <div className="text-right text-sm text-muted-foreground">
+          <span className="font-medium text-foreground">
+            {checklist.completedCount}
+          </span>
+          /{checklist.totalCount} tasks
+        </div>
+      </div>
+
+      {/* Progress bar */}
+      {showProgress && !checklist.isCollapsed && (
+        <div className="mt-3">
+          <ProgressBar
+            progress={checklist.progress}
+            showPercentage={showPercentage}
+            size={size}
+          />
+        </div>
+      )}
+
+      {/* Task list */}
+      {!checklist.isCollapsed && (
+        <div className="mt-4 space-y-3">
+          {groupedTasks ? (
+            <>
+              {/* Categorized tasks */}
+              {categories?.map((category) => {
+                const categoryTasks = groupedTasks.groups[category.id] || []
+                if (categoryTasks.length === 0) return null
+
+                return (
+                  <CategoryGroup
+                    key={category.id}
+                    category={category}
+                    tasks={categoryTasks}
+                    taskStates={checklist.taskStates}
+                    expandedTasks={checklist.expandedTasks}
+                    onCompleteTask={checklist.completeTask}
+                    onSkipTask={checklist.skipTask}
+                    onResetTask={checklist.resetTask}
+                    onToggleTaskExpanded={checklist.toggleTaskExpanded}
+                    size={size}
+                  />
+                )
+              })}
+
+              {/* Uncategorized tasks */}
+              {groupedTasks.uncategorized.length > 0 && (
+                <div className="space-y-2">
+                  {groupedTasks.uncategorized.map((task) => (
+                    <TaskItem
+                      key={task.id}
+                      task={task}
+                      status={checklist.getTaskStatus(task.id)}
+                      isExpanded={checklist.expandedTasks.has(task.id)}
+                      onToggleExpand={() =>
+                        checklist.toggleTaskExpanded(task.id)
+                      }
+                      onComplete={() => checklist.completeTask(task.id)}
+                      onSkip={() => checklist.skipTask(task.id)}
+                      onReset={() => checklist.resetTask(task.id)}
+                      size={size}
+                    />
+                  ))}
+                </div>
+              )}
+            </>
+          ) : (
+            /* Flat task list */
+            <div className="space-y-2">
+              {tasks.map((task) => (
+                <TaskItem
+                  key={task.id}
+                  task={task}
+                  status={checklist.getTaskStatus(task.id)}
+                  isExpanded={checklist.expandedTasks.has(task.id)}
+                  onToggleExpand={() => checklist.toggleTaskExpanded(task.id)}
+                  onComplete={() => checklist.completeTask(task.id)}
+                  onSkip={() => checklist.skipTask(task.id)}
+                  onReset={() => checklist.resetTask(task.id)}
+                  size={size}
+                />
+              ))}
+            </div>
+          )}
+        </div>
+      )}
+
+      {/* Completed state with reward */}
+      {checklist.isComplete && !checklist.isCollapsed && (
+        <div className="mt-4 rounded-lg bg-gradient-to-r from-green-50 to-emerald-50 p-4 dark:from-green-950/30 dark:to-emerald-950/30">
+          <div className="flex items-center gap-3">
+            <div className="rounded-full bg-green-500 p-2 text-white">
+              <Trophy className="h-5 w-5" />
+            </div>
+            <div>
+              <p className="font-medium text-green-700 dark:text-green-400">
+                Great job!
+              </p>
+              <p className="text-sm text-green-600 dark:text-green-500">
+                You have completed the onboarding checklist
+              </p>
+            </div>
+            <Gift className="ml-auto h-8 w-8 text-green-500" />
+          </div>
+        </div>
+      )}
+    </div>
+  )
+}
+
+// ============================================================================
+// Export
+// ============================================================================
+
+export default WakaChecklist